| # Contributing to Netstack3 | |
| Netstack3 is a networking stack being developed from scratch in Rust. It is | |
| under active development, and we encourage everyone to contribute! Most of | |
| Netstack3 - roughly 90% by lines of code - is platform-agnostic, meaning you can | |
| build and test on your development machine without needing to build all of | |
| Fuchsia or run it in a virtual machine. You can just use your normal `cargo` | |
| development workflow (`cargo check`, `cargo test`, etc). | |
| <!-- TODO(https://fxbug.dev/42149513): Make shortlinks for these Monorail search | |
| URLs --> | |
| You can find a list of good bugs to get started with in our [good first bugs | |
| list][good-first-bugs], and a list of good bugs to tackle next in our [good | |
| second bugs list][good-second-bugs]. | |
| This document is designed to get you started with the basics of contributing to | |
| Netstack3. It will get you from zero to building, testing, and contributing to | |
| Netstack3's platform-agnostic core. | |
| If you're interested in contributing and would like to chat with the Netstack3 | |
| developers, don't hesitate to reach out! We hang out on the | |
| <connectivity-dev@fuchsia.dev> mailing list. | |
| ## Getting set up | |
| * [Get the source code](/docs/get-started/get_fuchsia_source.md) | |
| * [Configure and build Fuchsia](/docs/get-started/build_fuchsia.md) | |
| * Your `fx set` command will need to enable Netstack3 development using Cargo | |
| by including the flags `--with //src/connectivity/network/netstack3:bin | |
| --cargo-toml-gen`. Assuming you're developing on an x86 machine, use `fx set | |
| core.x64 --with //src/connectivity/network/netstack3:bin --cargo-toml-gen`. | |
| * The source code for Netstack3's platform-agnostic core lives in | |
| `src/connectivity/network/netstack3/core`. | |
| * Build the Netstack3 core by running `fx build | |
| src/connectivity/network/netstack3/core:netstack3-core`. | |
| * Generate a `Cargo.toml` file to enable development with `cargo` by running `fx | |
| build build/rust:cargo_toml_gen` followed by `fx gen-cargo | |
| //src/connectivity/network/netstack3/core:netstack3-core`. | |
| * Add the following lines to your `~/.cargo/config.toml` file, replacing the | |
| absolute path to your Fuchsia directory and replacing the target if your local | |
| development target is different than `x86_64-unknown-linux-gnu`: | |
| ```toml | |
| [target.x86_64-unknown-linux-gnu] | |
| rustflags = ["-L", "absolute_path_to_fuchsia_directory/out/default/host_x64/obj/third_party/boringssl"] | |
| ``` | |
| If you don't have a config file, you can create one with just these contents. | |
| If you're not sure what your development target is, run `rustup show`. These | |
| config lines instruct `cargo` where to find the build artifacts for BoringSSL, | |
| which we use for some cryptographic operations. | |
| * Configure `rustup` to use the Fuchsia Rust toolchain by running: | |
| ```shell | |
| rustup toolchain link fuchsia $($FUCHSIA_DIR/scripts/youcompleteme/paths.py VSCODE_RUST_TOOLCHAIN) | |
| rustup default fuchsia | |
| ``` | |
| * Run a `cargo` command like `cargo check` or `cargo test` to see it in action! | |
| From now on, you will mostly be able to just use `cargo` for development. | |
| Sometimes, major changes to Netstack3's dependencies may cause your build setup | |
| to break. See the [Troubleshooting](#Troubleshooting) section for advice on | |
| fixing your build if this happens. | |
| ### Troubleshooting | |
| * If you can't run `cargo` correctly after pulling the latest changes with `jiri | |
| update`, try the following: | |
| * Remove the `Cargo.lock` file, run `cargo clean`, and try again | |
| * If `cargo` still doesn't work correctly, try a full clean build: | |
| * `fx clean` - this cleans out the build output, and prepares you to do a | |
| full clean build | |
| * Run the same `fx set` command you ran in the beginning (probably `fx set | |
| core.x64 --with //src/connectivity/network/netstack3:bin | |
| --cargo-toml-gen`). | |
| * `fx build src/connectivity/network/netstack3/core:netstack3-core` | |
| * `fx build build/rust:cargo_toml_gen` | |
| ## Contributing changes | |
| Interested in contributing to Netstack3? We'd love to have you! If you're not | |
| sure where to start, try our [good first bugs list][good-first-bugs] or our | |
| [good second bugs list][good-second-bugs]. If you're still a bit lost, don't | |
| hesitate to reach out to us at <connectivity-dev@fuchsia.dev>. | |
| If you have ideas for changes which aren't already tracked on our issue tracker, | |
| that's great! Bug fixes and documentation improvements are especially welcome. | |
| Just reach out to us first to make sure we're on the same page so you don't | |
| spend time doing work that we won't end up accepting. | |
| Once you're ready to contribute, just follow these simple steps: | |
| * Read the general instructions for [Contributing to Fuchsia](/CONTRIBUTING.md) | |
| * Read our [Fuchsia Networking Contributor Guide] | |
| ## Understanding | |
| If you're interested in diving deeper to understand Netstack3's design and | |
| architecture, check out [our docs](/src/connectivity/network/netstack3/docs). | |
| [Fuchsia Networking Contributor Guide]: /docs/contribute/contributing-to-netstack | |
| [good-first-bugs]: https://bugs.fuchsia.dev/p/fuchsia/issues/list?q=%28component%3Anetworkstack%3Enetstack3+OR+component%3AConnectivity%3ELibraries%3Enet_types+OR+component%3AConnectivity%3ELibraries%3Einternet_checksum+OR+component%3AConnectivity%3ELibraries%3Epacket%29+label%3AGoodFirstBug&can=2 | |
| [good-second-bugs]: https://bugs.fuchsia.dev/p/fuchsia/issues/list?q=%28component%3Anetworkstack%3Enetstack3+OR+component%3AConnectivity%3ELibraries%3Enet_types+OR+component%3AConnectivity%3ELibraries%3Einternet_checksum+OR+component%3AConnectivity%3ELibraries%3Epacket%29+label%3AGoodSecondBug&can=2 |