Skip to content

Latest commit

 

History

History
207 lines (161 loc) · 6.35 KB

CONTRIBUTING.adoc

File metadata and controls

207 lines (161 loc) · 6.35 KB
Raw

Contributing to DFX

Developing dfx

Run nix-shell in the root directory of this repo to bring the right version of rustc and cargo into scope.

Inside the shell use cargo to build and test the Rust packages (crates).

sdk $ nix-shell
[nix-shell:~/d/sdk]$ cargo build
[nix-shell:~/d/sdk]$ cargo test

Open a second window to run dfx, since we usually run it in a different subdirectory and running it does not require a nix-shell.

sdk $ alias dfx=$(pwd)/target/debug/dfx
sdk $ dfx --version
dfx 0.5.7-1-gad81116

Other Development Workflows

Running End-to-End Tests Locally

sdk $ nix-shell -A e2e-tests.shell .
[nix-shell:~/d/sdk]$ cd e2e
[nix-shell:~/d/sdk]$ bats tests-dfx/*.bash

Running End-to-End Tests Locally Against Reference IC

This runs the end-to-end tests against the reference implementation of the Internet Computer.

sdk $ nix-shell -A e2e-tests-ic-ref.shell .
[nix-shell:~/d/sdk]$ cd e2e
[nix-shell:~/d/sdk]$ bats tests-dfx/*.bash

Running dfx in a Debugger

While there are many OS/IDE variants where this can work, this document provides a specific example in order to make the instructions easier to follow.

The key is to use a nix-shell to provide the DFX_ASSETS environment variable for dfx.

This example assumes that your git workspaces are under ~/d and your dfx workspaces are under ~/w, but they can be anywhere.

Debugging dfx in JetBrains IDEs on OSX

  1. Install Rust

  2. Switch to the version of the rust toolchain from the common repo

    $ rustup toolchain install 1.41.1
$ rustup default 1.41.1

  3. Install IDEA Ultimate or CLion, and the Rust plugin.

  4. Install Homebrew and required packages:

    $ brew install openssl cmake

  5. Start a nix-shell and obtain DFX_ASSETS.

    Leave this nix-shell open.

    sdk $ nix-shell
[nix-shell:~/d/sdk]$ echo $DFX_ASSETS
/nix/store/g419n569py1gas7642q9jf5vh19xzp3y-dfx-assets

  6. Launch your IDE and then File | Open…​ | ~/d/sdk/Cargo.toml You should briefly see a small popup that says Using rustup.

  7. In the Project window, navigate to src/dfx/src/main.rs and right-click Run 'Run dfx'

    It will build, but fail to run with an error like this:

    thread 'main' panicked at 'Cannot find DFX_ASSETS: NotPresent', src/libcore/result.rs:1188:5

  8. Fix the Run/Debug Configuration

    By default, it will be set up to run dfx without parameters in the sdk workspace directory.

    We’ll set up a configuration to run dfx new <project>, which we can duplicate and alter for other commands, by making these changes:

    • Change the Name field to indicate which command we are running

    • Specify the --manifest-path for cargo run

    • Add command-line arguments for dfx

    • Provide the DFX_ASSETS environment variable

    • Change the working directory to where we want to run dfx

      Before:

      Name: Run dfx
Command: run --package dfx --bin dfx
Environment variables:
Working directory: <home>/d/sdk

      After:

      Name: dfx new dfxdebug
Command: run --manifest-path <home>/d/sdk/Cargo.toml --package dfx --bin dfx new someproject
Environment variables: DFX_ASSETS=<DFX_ASSETS path from nix-shell>
Working directory: <home>/w

  9. Run or set breakpoints and debug.

Conventional Commits

We use a squash & merge PR strategy, which means that each PR will result in exactly one commit in master. When releasing, we are using the history to know which commits and what messages make into the release notes (and what needs to be documented).

That means we enforce conventional commits to help us distinguish those commits. When creating a PR, we have a special check that validate the PR title and will fail if it doesn’t follow the conventional commit standard (see https://www.conventionalcommits.org/).

What that means is your PR title should start with one of the following prefix:

  • feat:. Your PR implement a new feature and should be documented. If version numbers were following semver, this would mean that we need to put the PR in the next minor.

  • fix:. Your PR fixes an issue. There should be a link to the issue being fixed. In SemVer, this would be merged in both minor and patch branches.

  • refactor:, chore:, build:, docs:, test: does not affect the release notes and will be ignored.

  • release:. Your PR is for tagging a release and should be ignored, but will be a break point for the log history when doing release notes.

Documentation

Building without Nix

The build script in this repo requires an environment variable to point to the asset directory that is to be bundled. That asset directory is normally built as a nix dependency to building DFX.

If you aren’t changing the assets themselves (ie. you’re just fixing a bug in dfx), and you already have the latest DFX installed, it’s probably safe (but not always) to use the cache folder installed on your computer as the asset directory.

You can do this with the follow command:

export DFX_ASSETS=$(dfx cache show)
cargo build

Please note that this will work, but result in a bigger output (dfx itself is part of the cache but not the asset), and that if the installed cache is out of sync with your branch it might result in incompatibilities. This is normally enough to run unit tests and compilation though.

CI

To run the CI job manually run either:

nix-build ci/ci.nix -A dfx[.x86_64-linux|.x86_64-darwin]

Dependencies

Updating the Replica

To update the replica to a given $SHA from the dfinity repo, execute the following:

niv update ic-starter-x86_64-darwin -a rev=$SHA
niv update ic-starter-x86_64-linux -a rev=$SHA
niv update replica-x86_64-darwin -a rev=$SHA
niv update replica-x86_64-linux -a rev=$SHA