Working on Cargo
This chapter gives an overview of how to build Cargo, make a change, and submit a Pull Request.
- Before hacking on Cargo.
- Check out the Cargo source.
- Building Cargo.
- Making a change.
- Writing and running tests.
- Submitting a Pull Request.
- The merging process.
Before hacking on Cargo
We encourage people to discuss their design before hacking on code. This gives the Cargo team a chance to know your idea more. Sometimes after a discussion, we even find a way to solve the problem without coding! Typically, you file an issue or start a thread on the internals forum before submitting a pull request. Please read the process of how features and bugs are managed in Cargo.
Checkout out the source
We use the “fork and pull” model described here, where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository. Cargo uses git and GitHub for all development.
- Fork the
rust-lang/cargorepository on GitHub to your personal account (see GitHub docs).
- Clone your fork to your local machine using
git clone(see GitHub docs)
- It is recommended to start a new branch for the change you want to make. All Pull Requests are made against the master branch.
Cargo is built by…running
cargo! There are a few prerequisites that you
need to have installed:
cargoneed to be installed. Cargo is expected to build and test with the current stable, beta, and nightly releases. It is your choice which to use. Nightly is recommended, since some nightly-specific tests are disabled when using the stable release. But using stable is fine if you aren’t working on those.
- A C compiler (typically gcc, clang, or MSVC).
- OpenSSL (
- OpenSSL (homebrew is recommended to install the
- OpenSSL (homebrew is recommended to install the
If you can successfully run
cargo build, you should be good to go!
You can use
cargo run to run cargo itself, or you can use the path directly
to the cargo binary, such as
If you are using
rustup, beware that running the binary directly can cause
issues with rustup overrides. Usually, when
cargo is executed as part of
rustup, the toolchain becomes sticky (via an environment variable), and all
rustc will use the same toolchain. But when
cargo is not run via
rustup, the toolchain may change based on the directory. Since Cargo changes
the directory for each compilation, this can cause different calls to
to use different versions. There are a few workarounds:
- Don’t use rustup overrides.
rustup run target/debug/cargoto execute
- Set the
RUSTCenvironment variable to a specific
rustcexecutable (not the rustup wrapper).
- Create a custom toolchain. This is a bit of a hack, but you can create a
directory in the rustup
toolchainsdirectory, and create symlinks for all the files and directories in there to your toolchain of choice (such as nightly), except for the
cargobinary, which you can symlink to your
target/debug/cargobinary in your project directory.
Normally, all development is done by running Cargo’s test suite, so running it directly usually isn’t required. But it can be useful for testing Cargo on more complex projects.
Making a change
Some guidelines on working on a change:
- All code changes are expected to comply with the formatting suggested by
rustfmt. You can use
rustup component add rustfmtto install
cargo fmtto automatically format your code.
- Include tests that cover all non-trivial code. See the Testing chapter for more about writing and running tests.
- All code should be warning-free. This is checked during tests.
Submitting a Pull Request
After you have committed your work, and pushed it to GitHub, you can open a Pull Request
- Push your commits to GitHub and create a pull request against Cargo’s
- Include a clear description of what the change is and why it is being made.
- Use GitHub’s keywords in the description to automatically link to an issue
if the PR resolves the issue. For example
Closes #1234will link issue #1234 to the PR. When the PR is merged, GitHub will automatically close the issue.
@rustbot will automatically assign a reviewer for the PR. It
may take at least a few days for someone to respond. If you don’t get a
response in over a week, feel free to ping the assigned reviewer.
When your PR is submitted, GitHub automatically runs all tests. The GitHub interface will show a green checkmark if it passes, or a red X if it fails. There are links to the logs on the PR page to diagnose any issues. The tests typically finish in under 30 minutes.
The reviewer might point out changes deemed necessary. Large or tricky changes may require several passes of review and changes.
PRs will get marked with labels like
S-waiting-on-author to indicate their status.
@rustbot bot can be used by anyone to adjust the labels.
If a PR gets marked as
S-waiting-on-author, and you have pushed new changes that you would like to be reviewed, you can write a comment on the PR with the text
The bot will switch the labels on the PR.
More information about these commands can be found at the shortcuts documentation.
The merging process
After a reviewer has approved your PR, they will issue a command to the bors
bot (also known as “Homu”, the software that powers
@bors). Bors will
create a temporary branch with your PR, and run all tests. Only if all tests
pass will it merge the PR to master. If it fails, the bot will leave a comment
on the PR. This system ensures that the master branch is always in a good
state, and that merges are processed one at a time. The Homu queue
dashboard shows the current merge queue. Cargo’s queue is rarely
busy, but a busy project like the rust repo is constantly full.
Assuming everything works, congratulations! It may take at least a week for the changes to arrive on the nightly channel. See the release chapter for more information on how Cargo releases are made.