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).

You can find a list of good bugs to get started with in our good first bugs list, and a list of good bugs to tackle next in our good second bugs list.

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
  • Configure and build Fuchsia
    • 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:

    [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:

    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 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 or our good second bugs list. 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:

Understanding

If you're interested in diving deeper to understand Netstack3's design and architecture, check out our docs.