FuelLabs · bvrooman · Aug 22, 2023 · Aug 16, 2023 · Aug 16, 2023 · Aug 16, 2023
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,4 @@ version-compatibility/Cargo.lock
 benches/benches-outputs/Cargo.lock
 benches/benches-outputs/src/test_gas_costs_output.rs
 .idea
+.env
@@ -10,6 +10,8 @@ Description of the upcoming release here.
 
 ### Added
 
+- [#1309](https://github.com/FuelLabs/fuel-core/pull/1309): Add documentation for running debug builds with CLion and Visual Studio Code.  
+- [#1308](https://github.com/FuelLabs/fuel-core/pull/1308): Add support for loading .env files when compiling with the `env` feature. This allows users to conveniently supply CLI arguments in a secure and IDE-agnostic way. 
 - [#1263](https://github.com/FuelLabs/fuel-core/pull/1263): Add gas benchmarks for `ED19` and `ECR1` instructions.
 - [#1286](https://github.com/FuelLabs/fuel-core/pull/1286): Include readable names for test cases where missing.
 - [#1304](https://github.com/FuelLabs/fuel-core/pull/1304): Implemented `submit_and_await_commit_with_receipts` method for `FuelClient`.

diff --git a/Cargo.lock b/Cargo.lock
@@ -142,6 +142,10 @@ The service relies on the environment variable `RUST_LOG`. For more information,
 
 Human logging can be disabled with the environment variable `HUMAN_LOGGING=false`
 
+## Debugging
+
+See the guide on [debugging](docs/developers/debugging.md) for an overview on running a debug build of a local node.
+
 ## Docker & Kubernetes
 
 ```sh

diff --git a/bin/fuel-core/Cargo.toml b/bin/fuel-core/Cargo.toml
@@ -20,6 +20,7 @@ anyhow = { workspace = true }
 clap = { workspace = true, features = ["derive", "env"] }
 const_format = { version = "0.2", optional = true }
 dirs = "4.0"
+dotenvy = { version = "0.15", optional = true }
 fuel-core = { workspace = true }
 humantime = "2.1"
 lazy_static = { workspace = true }
@@ -40,6 +41,7 @@ test-case = { workspace = true }
 [features]
 debug = ["fuel-core/debug"]
 default = ["debug", "metrics", "relayer", "rocksdb"]
+env = ["dep:dotenvy"]
 metrics = ["fuel-core/metrics"]
 p2p = ["fuel-core/p2p", "const_format"]
 relayer = ["fuel-core/relayer", "dep:url", "dep:serde_json"]

diff --git a/bin/fuel-core/src/cli.rs b/bin/fuel-core/src/cli.rs
@@ -4,14 +4,20 @@ use std::{
     path::PathBuf,
     str::FromStr,
 };
-use tracing::warn;
+use tracing::{
+    info,
+    warn,
+};
 use tracing_subscriber::{
     filter::EnvFilter,
     layer::SubscriberExt,
     registry,
     Layer,
 };
 
+#[cfg(feature = "env")]
+use dotenvy::dotenv;
+
 lazy_static::lazy_static! {
     pub static ref DEFAULT_DB_PATH: PathBuf = dirs::home_dir().unwrap().join(".fuel").join("db");
 }
@@ -41,6 +47,16 @@ pub enum Fuel {
 pub const LOG_FILTER: &str = "RUST_LOG";
 pub const HUMAN_LOGGING: &str = "HUMAN_LOGGING";
 
+#[cfg(feature = "env")]
+fn init_environment() -> Option<PathBuf> {
+    dotenv().ok()
+}
+
+#[cfg(not(feature = "env"))]
+fn init_environment() -> Option<PathBuf> {
+    None
+}
+
 pub async fn init_logging() -> anyhow::Result<()> {
     let filter = match env::var_os(LOG_FILTER) {
         Some(_) => {
@@ -87,6 +103,11 @@ pub async fn init_logging() -> anyhow::Result<()> {
 }
 
 pub async fn run_cli() -> anyhow::Result<()> {
+    init_logging().await?;
+    if let Some(path) = init_environment() {
+        let path = path.display();
+        info!("Loading environment variables from {path}");
+    }
     let opt = Opt::try_parse();
     if opt.is_err() {
         let command = run::Command::try_parse();

diff --git a/bin/fuel-core/src/cli/run.rs b/bin/fuel-core/src/cli/run.rs
@@ -1,7 +1,6 @@
 #![allow(unused_variables)]
 use crate::{
     cli::{
-        init_logging,
         run::consensus::PoATriggerArgs,
         DEFAULT_DB_PATH,
     },
@@ -333,7 +332,6 @@ impl Command {
 }
 
 pub async fn exec(command: Command) -> anyhow::Result<()> {
-    init_logging().await?;
     let config = command.get_config()?;
     let network_name = {
         #[cfg(feature = "p2p")]

diff --git a/bin/fuel-core/src/cli/run/relayer.rs b/bin/fuel-core/src/cli/run/relayer.rs
@@ -25,7 +25,7 @@ pub struct RelayerArgs {
     #[arg(long = "relayer", env)]
     #[arg(required_if_eq("enable_relayer", "true"))]
     #[arg(requires_if(IsPresent, "enable_relayer"))]
-    pub eth_client: Option<url::Url>,
+    pub relayer: Option<url::Url>,
 
     /// Ethereum contract address. Create EthAddress into fuel_types
     #[arg(long = "relayer-v2-listening-contracts", value_parser = parse_h160, env)]
@@ -71,7 +71,7 @@ impl RelayerArgs {
         let config = Config {
             da_deploy_height: DaBlockHeight(self.da_deploy_height),
             da_finalization: DaBlockHeight(self.da_finalization),
-            eth_client: self.eth_client,
+            relayer: self.relayer,
             eth_v2_listening_contracts: self.eth_v2_listening_contracts,
             log_page_size: self.log_page_size,
             sync_minimum_duration: Duration::from_secs(self.sync_minimum_duration_secs),

diff --git a/bin/fuel-core/src/cli/snapshot.rs b/bin/fuel-core/src/cli/snapshot.rs
@@ -51,7 +51,6 @@ pub async fn exec(command: Command) -> anyhow::Result<()> {
 
 #[cfg(any(feature = "rocksdb", feature = "rocksdb-production"))]
 pub async fn exec(command: Command) -> anyhow::Result<()> {
-    use crate::cli::init_logging;
     use anyhow::Context;
     use fuel_core::{
         chain_config::{
@@ -60,7 +59,6 @@ pub async fn exec(command: Command) -> anyhow::Result<()> {
         },
         database::Database,
     };
-    init_logging().await?;
     let path = command.database_path;
     let data_source =
         fuel_core::state::rocks_db::RocksDb::default_open(&path, None).context(

diff --git a/crates/services/relayer/src/config.rs b/crates/services/relayer/src/config.rs
@@ -22,7 +22,7 @@ pub struct Config {
     /// Number of da blocks after which messages/stakes/validators become finalized.
     pub da_finalization: DaBlockHeight,
     /// Uri address to ethereum client.
-    pub eth_client: Option<url::Url>,
+    pub relayer: Option<url::Url>,
     // TODO: Create `EthAddress` into `fuel_core_types`.
     /// Ethereum contract address.
     pub eth_v2_listening_contracts: Vec<H160>,
@@ -58,7 +58,7 @@ impl Default for Config {
         Self {
             da_deploy_height: DaBlockHeight::from(Self::DEFAULT_DA_DEPLOY_HEIGHT),
             da_finalization: DaBlockHeight::from(Self::DEFAULT_DA_FINALIZATION),
-            eth_client: None,
+            relayer: None,
             eth_v2_listening_contracts: vec![H160::from_str(
                 "0x03E4538018285e1c03CCce2F92C9538c87606911",
             )

diff --git a/crates/services/relayer/src/service.rs b/crates/services/relayer/src/service.rs
@@ -348,7 +348,7 @@ pub fn new_service<D>(database: D, config: Config) -> anyhow::Result<Service<D>>
 where
     D: RelayerDb + Clone + 'static,
 {
-    let url = config.eth_client.clone().ok_or_else(|| {
+    let url = config.relayer.clone().ok_or_else(|| {
         anyhow::anyhow!(
             "Tried to start Relayer without setting an eth_client in the config"
         )

diff --git a/docs/developers/assets/vs_code_configuration.png b/docs/developers/assets/vs_code_configuration.png
@@ -0,0 +1,131 @@
+# Debugging
+
+## Setup Requirements
+
+Building Fuel is supported on macOS and Linux.
+
+The Fuel client is written in Rust. For developers who wish to build the Fuel client locally, it is recommended to use the latest version of Rust. The build process uses the stable Rust toolchain.
+
+See the [Fuel Client system requirements](../../README.md#system-requirements).
+
+## Building and Running
+
+Building and running debug builds of the Fuel client is done using Cargo.
+
+By default, when using the `cargo build` or `cargo run` commands, Cargo generates a debug build. This build is optimized for debugging and development purposes, including debug symbols and minimal optimizations. IDEs rely on debug builds to provide robust debugging features.
+
+The `cargo run` command will compile and execute the Fuel client application directly from source code. When running `cargo run`, Cargo compiles the Fuel client, and runs the resulting binary. During development and debugging, this should be used instead of installing the client (`cargo install`) or running the executable directly.
+
+When building or running the Fuel client, it is recommended to pass the  `--all-features` flag to Cargo. This will instruct Cargo to compile the client with features such as P2P and the Relayer service.
+
+To run the Fuel client, the following command can be used:
+
+```bash
+cargo run --all-features --bin fuel-core -- run <ARGUMENTS>
+```
+
+where `<ARGUMENTS>` is the desired set of arguments.
+
+The list of arguments can be found by running the `help` command:
+
+```bash
+cargo run --bin fuel-core run --help
+```
+
+It is suggested to run the client with the P2P and Relayer services enabled. This is communicated to the CLI with the flags `--enable-p2p` and `--enable-relayer` respectively. Enabling these services requires that the client is compiled with the relevant features (`p2p` and `relayer`). These features are specified implicitly when the `--all-features` flag is specified.
+
+
+## Environment
+
+Users can supply CLI arguments to their node indirectly by populating the relevant environment variables. The list of CLI arguments and their environment variables can be found by running the `help` command.
+
+Users can define environment variables by configuring their shell or setting them inside the current terminal.
+
+Additionally, users can add a `.env` file to the root directory of their local copy of their Fuel node (or wherever the working directory is). Using a `.env` file requires compiling the client with the `env` feature. This can be accomplished by including `env` in the list of features or by passing the `--all-features` flag. 
+
+Using environment variables for CLI arguments allows these values to be reused across IDEs and IDE configurations seamlessly.
+
+
+## P2P Network
+
+When running the client with the P2P service enabled, i.e., building the binary with the `p2p` feature and supplying the runtime argument `--enable-p2p`, the client will connect to a Fuel network. This requires additional CLI arguments, including the `--keypair` and `--network` arguments.
+
+A key pair can be generated by running the utility binary `fuel-core-keygen`:
+
+```bash
+cargo run --bin fuel-core-keygen new
+```
+
+The resulting key pair printed to the console contains an address and secret. The `address` can be provided to the `--keypair` argument when running the node.
+
+The `--network` argument identifies the name of the network to join. The network name is used during peer discovery. For example, users can specify `--network beta3-prod` to join the Beta 3 Production network. Similarly, setting the environment variable `NETWORK="beta3-prod"` will produce the same result.
+
+## Recommended IDEs
+
+During development, it is recommended to delegate the execution of Cargo instructions to an IDE and connect the application to the IDE's debugger, instead of running these instructions manually.
+
+Recommended IDEs include:
+- CLion
+- Visual Studio Code
+
+## CLion
+
+### Prerequisites
+
+Running Fuel Core with CLion requires the official JetBrains Rust plugin. Find the Rust plugin by navigating to CLion's Plugin menu, entering "Rust" in the search. Install it by clicking "Install".
+
+### Create A Run Configuration
+
+1. In the top-right corner of the CLion window, click on the configurations dropdown menu and select "Edit Configurations..."
+2. In the "Run/Debug Configurations" window, click on the "+" button and select "Cargo"
+3. In the "Name" field, give your configuration a descriptive name, such as "Run Beta 3"
-3. In the "Name" field, give your configuration a descriptive name, such as "Run Beta 3"
+3. In the "Name" field, give your configuration a descriptive name, such as "Run Fuel Client"
-3. In the "Name" field, give your configuration a descriptive name, such as "Run Beta 3"
+3. In the "Name" field, give your configuration a descriptive name, such as "Run Fuel Client"
+4. In the "Command" field, enter `run --all-features --bin fuel-core -- run <ARGUMENTS>`, where `<ARGUMENTS>` represents the desired CLI arguments. Refer to the CLI documentation for guidance on which options and arguments to use.
+5. If you use environment variables for configuration (as indicated in the CLI documentation), you can set them in the "Environment variables" section. Enter the variables and their values as needed. It is recommended to set the `RUST_LOG` environment variable to either `info` or `debug`.
+6. Click "Apply" or "OK" to save your run configuration.
+
+### Example Configuration
+
+![clion_configuration.png](assets/clion_configuration.png)
+
+### Running and Debugging
+
+1. With your configuration selected in the dropdown menu, click on the Run button to start running your Fuel client node.
+2. Alternatively, click on the Debug button to start your client node in debug mode.
+3. Set breakpoints in the code where inspections are necessary. CLion will halt execution at these breakpoints, allowing variable inspection and step-by-step code execution.
+
+## Visual Studio Code
+
+### Prerequisites
+
+Running Fuel Core with Visual Studio Code requires the CodeLLDB extension. Find the CodeLLDB extension by navigating to the "Extensions" tab and searching "CodeLLDB". Install it by clicking "Install".
+
+### Create A Run Configuration
+
+1. In VS Code, click on the "Run and Debug" icon in the left sidebar.
+2. VS Code will offer to create a `launch.json` file to configure how your client node is run. Clicking this will prompt you to select a debugger. Select the CodeLLDB debugger to proceed. VS Code will generate a `launch.json` file for you.
+3. In the "Run and Debug" menu, click the dropdown menu and select "Add Configuration..."
+4. In the `"type"` field, enter `"lldb"`. In the `"request"` field, enter `"launch"`.
+5. In the `"name"` field, give your configuration a descriptive name, such as `"Run Beta 3"`
-5. In the `"name"` field, give your configuration a descriptive name, such as `"Run Beta 3"`
+5. In the `"name"` field, give your configuration a descriptive name, such as `"Run Fuel Client"`
-5. In the `"name"` field, give your configuration a descriptive name, such as `"Run Beta 3"`
+5. In the `"name"` field, give your configuration a descriptive name, such as `"Run Fuel Client"`
+6. In the `"args"` array nested under `"cargo"`, enter the following arguments: `"run"`, `"--all-features"`, `"--bin"`, `"fuel-core"`, `"--"`, `"run"`, `<ARGUMENTS>`, where `<ARGUMENTS>` is a list of CLI values and arguments encapsulated by quotes. Refer to the CLI documentation for guidance on which options and arguments to use.
+7. Save these changes made to your `launch.json` file.
+
+### Example Configuration
+
+![vs_code_configuration.png](assets/vs_code_configuration.png)
+
+### Running and Debugging
+
+1. Navigate to the "Run and Debug" tab. With your configuration selected in the configuration dropdown menu, click on the Run button to start running your Fuel client node.
+2. Set breakpoints in the code where inspections are necessary. VS Code will halt execution at these breakpoints, allowing variable inspection and step-by-step code execution.
+
+## Alternative Configurations
+
+Developers can create additional configurations with alternative CLI arguments to experiment with different setups or debug specific features. For example, omitting the `--enable-p2p` flag (and related P2P arguments) will start the node without the P2P service. Similarly, omitting the `--enable-relayer` (and related relayer arguments) will start the node without the relayer service. Developers can create additional configurations to save specific combinations of CLI arguments and to conveniently switch between them.
+
+Developers can also configure builds by selecting the desired compile-time features. For example, developers can omit the `p2p` service from compilation by explicitly passing a custom feature set to Cargo:
+
+```bash
+cargo run --features "relayer" --bin fuel-core -- run --enable-relayer <ARGUMENTS>
+```
+
+
diff --git a/tests/tests/relayer.rs b/tests/tests/relayer.rs
@@ -95,7 +95,7 @@ async fn relayer_can_download_logs() {
     let eth_node = Arc::new(eth_node);
     let eth_node_handle = spawn_eth_node(eth_node).await;
 
-    relayer_config.eth_client = Some(
+    relayer_config.relayer = Some(
         format!("http://{}", eth_node_handle.address)
             .as_str()
             .try_into()
@@ -153,7 +153,7 @@ async fn messages_are_spendable_after_relayer_is_synced() {
     let eth_node = Arc::new(eth_node);
     let eth_node_handle = spawn_eth_node(eth_node).await;
 
-    relayer_config.eth_client = Some(
+    relayer_config.relayer = Some(
         format!("http://{}", eth_node_handle.address)
             .as_str()
             .try_into()
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,3 +12,4 @@ version-compatibility/Cargo.lock @@
     benches/benches-outputs/Cargo.lock
     benches/benches-outputs/src/test_gas_costs_output.rs
     .idea
+    .env