This document describes how to set up your development environment to build and test Iroh, and
explains the basic mechanics of using cargo run and cargo test.
Before you can build Iroh, you must install and configure the following dependencies on your machine:
-
Git: The Github Guide to Installing Git is a good source of information.
-
The Rust Programming Language: see https://www.rust-lang.org/learn/get-started to get started
Protobuf compiler: Download it from the Protobuf Releases page
You need to get the protoc- release for your platform (they can be found at the very bottom of the list of release binaries). To install, make sure the protoc compiler is on your path. If you get errors during build about experimental_allow_proto3_optional or inability to import /google/protobuf/empty.proto you're likely using a version of the compiler that's too old.
It may be that Rust Analyzer does not find the protobuf compiler even after installation. You can point it in the right direction using a configuration like this:
"rust-analyzer.cargo.extraEnv": {
"PROTOC": "/path/to/protoc"
}
This works in VSCode settings, for instance.
RocksDb requires libclang to be built successfully. On Linux you can make this available by installing the clang package.
To contribute code to Iroh, you must have a GitHub account so you can push code to your own fork of Iroh and open Pull Requests in the GitHub Repository.
Use cargo commands to build and run the various Iroh binaries.
For example:
# run each command in a different terminal to simulate running iroh as
# microservices on different boxes:
$ cargo run -p iroh-p2p
$ cargo run -p iroh-gateway
$ cargo run -p iroh-store
$ cargo run -p iroh -- status --watchIf you want to use the iroh binary to start and stop the services, you can
use xtask to move previously built binaries to the correct bin:
# build the binaries
$ cargo build
# or build the binaries for release:
$ cargo build --release
# move the binaries to the correct location
$ cargo xtask dev-installWhen you push your branch to github and open up a pull request, it will automatically trigger CircleCI to lint and test your code.
In order to catch linting and testing errors before pushing the code to github, be sure to run:
$ cargo clippy --workspace --all-features --all-targets
$ cargo test --workspace --all-features --all-targetsSetting up a git hook to run these commands can save you many headaches:
#!/bin/sh
cargo clippy --workspace --all-features --all-targets && cargo test --workspace --all-features --all-targetsAny crate added to iroh will need to use a license compatible with ours. Any PR that introduces a new crate will require additional review time to audit the crate being introduced, including rationale on why you chose this crate, and what alternatives you considered willl speed up the review process.
Crate lists in Cargo.toml files must be kept alphabetically sorted.
The tests must pass and you must get an approval from someone on the Iroh team before you can merge your PR.
Depending on your permissions in the iroh repo, you may not have the the ability to "request a review". Instead, please tag your selected reviewers in the PR itself (using the @) and specify that you would like them to review. If you are a member of our discord community, you can and should ping your reviewer(s) there as well.
If you don't know who to tag for review, here are some good guidelines. For any markdown documentations changes, tag ramfox or b5. If your PR solves an issue that someone else created, tag that person in review. If it's an issue you have created, tag team members who have been discussing the issue. Otherwise, create the PR and note that you aren't sure who to tag! Someone will drop in to give you guidance. If you are apart of our discord community, ask who should be tagged in the iroh channel.
The MacOS testing infrastructure currently does not work on forked branches of iroh. If you are working on a forked branch, you will notice that the MacOS tests on your PRs will always fail (because they will not run). This is the only case where you may have a "failing" test and still merge your PR.
Please "squash and merge" your commits, combining the commit message into something that will properly summarize all the changes you have made, the bugs you have fixed, and/or the features you have implemented. Use the commit guidelines outlined in the following sections.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the Iroh change log.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
If the commit reverts a previous commit, it should begin with revert: , followed by the header
of the reverted commit.
In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit
being reverted.
A commit with this format is automatically created by the git revert command.
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing or correcting existing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
The scope could be anything specifying place of the commit change. For example, if I am refactoring something in the iroh package, I may start my commit with "refactor(iroh)".
You can use * when the change affects more than a single scope.
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes.
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines.
The rest of the commit message is then used for this.
A detailed explanation can be found in this document.
If, while running Iroh, you get errors concerning "too many open files", you will need to adjust the number of files your shell process is willing to open. This is particularly common with any p2p work.
Often this is caused by having too low a file limit for your shell. You can use the ulimit command to check out or change the limits. Try the following command to set the shell limit to unlimited open files:
ulimit -S -n unlimited