Skip to content

Latest commit

 

History

History
230 lines (164 loc) · 7.48 KB

CONTRIBUTING.md

File metadata and controls

230 lines (164 loc) · 7.48 KB
Raw

Contributing Guide

Building & Testing

macOS

The simplest way to develop this app is to build the dynamically-linked Darwin (macOS) target.

macOS Install

First you need to install Rust. The easiest way is to use rustup.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

If you don't want to install to the default locations, just set the variables correctly.

# You need to set $RUSTUP_HOME and $CARGO_HOME in your rc file and add $CARGO_HOME/bin to your path.
RUSTUP_HOME="$XDG_DATA_HOME"/rustup CARGO_HOME="$XDG_DATA_HOME"/cargo \
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs           \
  | sh -s -- -y --no-modify-path

macOS Build

You can then build and run this project with:

cargo build                          # Debug   binary in target/debug/up
cargo build --release                # Release binary in target/release/up

cargo run --release -- <args>        # Build the release binary and run it with <args>.

./target/release/up --help # Run release binary directly.

The compiled binary can be copied anywhere.

macOS Test

cargo test                    # Run tests in debug mode.
cargo test --release          # Run tests in release mode.
cargo test --release          # Run all tests in release mode (what CI runs).
cargo test --no-fail-fast     # Don't stop at first error.

cargo test --test test_module # Only run tests in <test_module> (e.g. file in tests/).
cargo test -- test_name       # Only test functions containing <test_name>.

Linux

The binary that is used in Rio is a statically-linked Linux binary.

Docker Linux Build

The easiest way to build is with docker.

Run this script to build and test locally.

meta/cargo-docker

Cross-Compiled Linux Build

See this blog post for more info.

brew install FiloSottile/musl-cross/musl-cross
rustup target install x86_64-unknown-linux-musl
grep -q 'linker = "x86_64-linux-musl-gcc"' "${CARGO_HOME}"/config \
  || echo -e '[target.x87_64-unknown-linux-musl]
  linker = "x86_64-linux-musl-gcc"' >> "${CARGO_HOME:-~/.cargo}"/config
TARGET_CC=x86_64-linux-musl-gcc cargo build --release --target=x86_64-unknown-linux-musl

Development

Helpful tools:

You probably want to install some extra rust components to make life easier:

  • rls: the Rust Language Server. Provides IDE capabilities for anything with Language Server Protocol support.
  • clippy: warns about unidiomatic or dangerous code.
  • rustfmt: use cargo fmt to auto-format code in this repo
  • rust-docs: offline rust docs, open with rustup doc.
  • cargo-edit: Provides cargo add, cargo rm, and cargo upgrade for dependency management.
  • cargo-watch: Run commands when files change (are saved).
# Use the latest stable rust by default.
cargo default stable

# Add useful rust components.
rustup component add rls rust-analysis rust-src clippy rustfmt rust-docs

cargo install cargo-edit cargo-watch

Updating

You can keep your build tools up to date with:

# Updates rustup and installed toolchains + components.
rustup update

# Updates everything installed globally with `cargo install`.
cargo install-update --all

Debugging

Rust code can be debugged with either gdb or lldb. VS Code or CLion should both work.

See these links for more info:

Show docs

You can show the Rust documentation for the current version of Rust with:

rustup doc

You can show the docs for the current versions of this tool and all its dependencies with:

# Use --document-private-items to see doc comments for private functions/items/modules.
cargo doc --open --document-private-items

Run on save

cargo watch -x test                # Run `cargo test` when files change.
cargo watch -x 'run -- --some-arg' # Run `cargo run -- --some-arg` when files change.

You can also run arbitrary commands on your own system as you develop, for example with:

# Run on file change.
fd | entr -s 'cargo +nightly fmt && RUST_BACKTRACE=1 cargo +nightly r -- --log-level=trace'

# In another window, replace with your command logging output.
less ~/tmp/dot-tmp.log

Command Aliases

You can also define command aliases as in git, for an example see my dotfiles.

Managing Dependencies

To add a prod dependency (compiled into the final binary) use:

# `cargo add --help` for more info.
cargo add <dependency>    # Add a dependency (compiled into the binary).
cargo add -D <dependency> # Add a dev dependency (only used in tests).

To update the ranges in the Cargo.toml:

cargo upgrade

Update pinned versions in Cargo.lock to the latest versions matching the ranges in Cargo.toml:

cargo update

Writing doc comments

Useful links:

Commit Messages

This project uses Conventional Commit messages, with the following categories:

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • chore: (updating grunt tasks etc; no production code change)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: revert of a previous commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests