Setting up your local development environment

For contributing rules and best practices please refer toCONTRIBUTING.md

Before you start

For this guide we assume that you already have a GitHub account and havegit and your favorite code editor or IDE installed and configured.Before you start working on coreutils, please follow these steps:

1. Fork thecoreutils repository to your GitHub account.Tip: Seethis GitHub guide for more information on this step.
2. Clone that fork to your local development environment:

git clone https://github.com/YOUR-GITHUB-ACCOUNT/coreutilscd coreutils

Tools

You will need the tools mentioned in this section to build and test your code changes locally.This section will explain how to install and configure these tools.We also have an extensive CI that uses these tools and will check your code before it can be merged.The next sectionTesting will explain how to run those checks locally to avoid waiting for the CI.

Rust toolchain

Install Rust

If you're using rustup to install and manage your Rust toolchains,clippy andrustfmt are usually already installed. If you are using one of the alternative methods, please make sure to install them manually. See following sub-sections for their usage:clippyrustfmt.

Tip You might also need to add 'llvm-tools' component if you are going togenerate code coverage reports locally:

rustup component add llvm-tools-preview

GNU utils and prerequisites

If you are developing on Linux, most likely you already have all/most GNU utilities and prerequisites installed.

To make sure, please check GNU coreutilsREADME-prereq.

You will need these torun uutils against the GNU test suite locally.

For MacOS and Windows platform specific setup please checkMacOS GNU utils andWindows GNU utils sections respectfully.

pre-commit hooks

A configuration forpre-commit is provided in the repository. It allowsautomatically checking every git commit you make to ensure it compiles, andpassesclippy andrustfmt without warnings.

To use the provided hook:

1. Installpre-commit
2. Runpre-commit install while in the repository directory

Your git commits will then automatically be checked. If a check fails, an errormessage will explain why, and your commit will be canceled. You can then makethe suggested changes, and rungit commit ... again.

NOTE: On MacOS the pre-commit hooks are currently broken. There are workarounds involving switching to unstable nightly Rust and components.

clippy

cargo clippy --all-targets --all-features

Themsrv key in the clippy configuration fileclippy.toml is used to disablelints pertaining to newer features by specifying the minimum supported Rustversion (MSRV).

rustfmt

cargo fmt --all

cargo-deny

This project usescargo-deny todetect duplicate dependencies, checks licenses, etc. To run it locally, firstinstall it and then run with:

cargo deny --all-features check all

Markdown linter

We usemarkdownlint to lint theMarkdown files in the repository.

Spell checker

We usecspell as spell checker for all files in the project. If you are usingVS Code, you can install thecode spell checkerextension to enable spell checking within your editor. Otherwise, you caninstallcspell separately.

If you want to make the spell checker ignore a word, you can add

#![allow(unused)]fn main() {// spell-checker:ignore word_to_ignore}

at the top of the file.

Testing

This section explains how to run our CI checks locally.Testing can be done using either Cargo ormake.

Testing with Cargo

Just like with building, we follow the standard procedure for testing usingCargo:

cargo test

By default,cargo test only runs the common programs. To run also platformspecific tests, run:

cargo test --features unix

If you would prefer to test a select few utilities:

cargo test --features "chmod mv tail" --no-default-features

If you also want to test the core utilities:

cargo test  -p uucore -p coreutils# orcargo test --all-features -p uucore

Running the complete test suite might take a while. We usenextest inthe CI and you might want to try it out locally. It can speed up the execution time of the wholetest run significantly if the cpu has multiple cores.

cargo nextest run --features unix --no-fail-fast

To debug:

rust-gdb --args target/debug/coreutils ls(gdb) b ls.rs:79(gdb) run

Testing with GNU Make

To simply test all available utilities:

make test

To test all but a few of the available utilities:

make SKIP_UTILS='UTILITY_1 UTILITY_2' test

To test only a few of the available utilities:

make UTILS='UTILITY_1 UTILITY_2' test

To include tests for unimplemented behavior:

make UTILS='UTILITY_1 UTILITY_2' SPEC=y test

To run tests withnextest just use the nextest target. Note you'll need toinstallnextest first. Thenextest target accepts thesame arguments like the defaulttest target, so it's possible to pass arguments tonextest runviaCARGOFLAGS:

make CARGOFLAGS='--no-fail-fast' UTILS='UTILITY_1 UTILITY_2' nextest

Run Busybox Tests

This testing functionality is only available on *nix operating systems andrequiresmake.

To run busybox tests for all utilities for which busybox has tests

make busytest

To run busybox tests for a few of the available utilities

make UTILS='UTILITY_1 UTILITY_2' busytest

To pass an argument like "-v" to the busybox test runtime

make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest

Comparing with GNU

To run uutils against the GNU test suite locally, run the following commands:

bash util/build-gnu.sh# Build uutils with release optimizationsbash util/build-gnu.sh --release-buildbash util/run-gnu-test.sh# To run a single test:bash util/run-gnu-test.sh tests/touch/not-owner.sh # for example# To run several tests:bash util/run-gnu-test.sh tests/touch/not-owner.sh tests/rm/no-give-up.sh # for example# If this is a perl (.pl) test, to run in debug:DEBUG=1 bash util/run-gnu-test.sh tests/misc/sm3sum.pl

Tip: First time you runbash util/build-gnu.sh command, it will provide instructions on how to checkout GNU coreutils repository at the correct release tag. Please follow those instructions and when done, runbash util/build-gnu.sh command again.

Note that GNU test suite relies on individual utilities (not the multicall binary).

You also need to installquilt, a tool used to manage a stack of patches for modifying GNU tests.

On FreeBSD, you need to install packages for GNU coreutils and sed (used in shell scripts instead of system commands):

pkg install coreutils gsed

Code coverage report

Code coverage report can be generated usinggrcov.

To generategcov-based coverage report

export CARGO_INCREMENTAL=0export RUSTFLAGS="-Cinstrument-coverage -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"export RUSTDOCFLAGS="-Cpanic=abort"cargo build <options...> # e.g., --features feat_os_unixcargo test <options...> # e.g., --features feat_os_unix test_pathchkgrcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing --ignore build.rs --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?\#\[derive\()" -o ./target/debug/coverage/# open target/debug/coverage/index.html in browser

if changes are not reflected in the report then runcargo clean and run the above commands.

Tips for setting up on Mac

C Compiler and linker

On MacOS you'll need to install C compiler & linker:

xcode-select --install

MacOS GNU utils

On MacOS you will need to installHomebrew and use it to install the following Homebrew formulas:

brew install \  coreutils \  autoconf \  gettext \  wget \  texinfo \  xz \  automake \  gnu-sed \  m4 \  bison \  pre-commit \  findutils

After installing these Homebrew formulas, please make sure to add the following lines to yourzsh orbash rc file, i.e.~/.profile or~/.zshrc or~/.bashrc ...(assuming Homebrew is installed at default location/opt/homebrew):

eval "$(/opt/homebrew/bin/brew shellenv)"export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"export PATH="/opt/homebrew/opt/bison/bin:$PATH"export PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"

Last step is to link Homebrew coreutils version oftimeout to/usr/local/bin (as admin user):

sudo ln -s /opt/homebrew/bin/timeout /usr/local/bin/timeout

Do not forget to either source updated rc file or restart you terminal session to update environment variables.

Tips for setting up on Windows

MSVC build tools

On Windows you'll need the MSVC build tools for Visual Studio 2013 or later.

If you are usingrustup-init.exe to install Rust toolchain, it will guide you through the process of downloading and installing these prerequisites.

Otherwise please followthis guide.

Windows GNU utils

If you have usedGit for Windows to installgit on you Windows system you might already have some GNU core utilities installed as part of "GNU Bash" included in Git for Windows package, but it is not a complete package.This article provides instruction on how to add more to it.

Alternatively you can installCygwin and/or useWSL2 to get access to all GNU core utilities on Windows.

Preparing a new release

1. Modifyutil/update-version.sh (FROM & TO) and run it
2. Submit a new PR with these changes and wait for it to be merged
3. Tag the new releasegit tag -a X.Y.Z andgit push --tags
4. Once the CI is green, a new release will be automatically created in draft mode.Reuse this release and make sure that assets have been added.
5. Write the release notes (it takes time) following previous examples
6. Runutil/publish.sh --do-it to publish the new release to crates.io