uutils Coreutils Documentation

uutils is an attempt at writing universal (as in cross-platform) CLI utilities in Rust. It is available for Linux, Windows, Mac and other platforms.

The API reference for uucore, the library of functions shared between various utils, is hosted at at docs.rs.

uutils is licensed under the MIT License.

Useful links

Note: This manual is automatically generated from the source code and is a work in progress.

Installation

Requirements

Rust (cargo, rustc)
GNU Make (required to build documentation)
Sphinx (for documentation)
gzip (for installing documentation)

Rust Version

uutils follows Rust's release channels and is tested against stable, beta and nightly. The current oldest supported version of the Rust compiler is 1.54.

On both Windows and Redox, only the nightly version is tested currently.

Build Instructions

There are currently two methods to build the uutils binaries: either Cargo or GNU Make.

Building the full package, including all documentation, requires both Cargo and Gnu Make on a Unix platform.

For either method, we first need to fetch the repository:

$ git clone https://github.com/uutils/coreutils
$ cd coreutils

Cargo

Building uutils using Cargo is easy because the process is the same as for every other Rust program:

$ cargo build --release

This command builds the most portable common core set of uutils into a multicall (BusyBox-type) binary, named 'coreutils', on most Rust-supported platforms.

Additional platform-specific uutils are often available. Building these expanded sets of uutils for a platform (on that platform) is as simple as specifying it as a feature:

$ cargo build --release --features macos
# or ...
$ cargo build --release --features windows
# or ...
$ cargo build --release --features unix

If you don't want to build every utility available on your platform into the final binary, you can also specify which ones you want to build manually. For example:

$ cargo build --features "base32 cat echo rm" --no-default-features

If you don't want to build the multicall binary and would prefer to build the utilities as individual binaries, that is also possible. Each utility is contained in its own package within the main repository, named "uu_UTILNAME". To build individual utilities, use cargo to build just the specific packages (using the --package [aka -p] option). For example:

$ cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm

GNU Make

Building using make is a simple process as well.

To simply build all available utilities:

$ make

To build all but a few of the available utilities:

$ make SKIP_UTILS='UTILITY_1 UTILITY_2'

To build only a few of the available utilities:

$ make UTILS='UTILITY_1 UTILITY_2'

Installation Instructions

Cargo

Likewise, installing can simply be done using:

$ cargo install --path .

This command will install uutils into Cargo's bin folder (e.g. $HOME/.cargo/bin).

This does not install files necessary for shell completion. For shell completion to work, use GNU Make or see Manually install shell completions.

GNU Make

To install all available utilities:

$ make install

To install using sudo switch -E must be used:

$ sudo -E make install

To install all but a few of the available utilities:

$ make SKIP_UTILS='UTILITY_1 UTILITY_2' install

To install only a few of the available utilities:

$ make UTILS='UTILITY_1 UTILITY_2' install

To install every program with a prefix (e.g. uu-echo uu-cat):

$ make PROG_PREFIX=PREFIX_GOES_HERE install

To install the multicall binary:

$ make MULTICALL=y install

Set install parent directory (default value is /usr/local):

# DESTDIR is also supported
$ make PREFIX=/my/path install

Installing with make installs shell completions for all installed utilities for bash, fish and zsh. Completions for elvish and powershell can also be generated; See Manually install shell completions.

NixOS

The standard package set of NixOS provides this package out of the box since 18.03:

$ nix-env -iA nixos.uutils-coreutils

Manually install shell completions

The coreutils binary can generate completions for the bash, elvish, fish, powershell and zsh shells. It prints the result to stdout.

The syntax is:

cargo run completion <utility> <shell>

So, to install completions for ls on bash to /usr/local/share/bash-completion/completions/ls, run:

cargo run completion ls bash > /usr/local/share/bash-completion/completions/ls

Un-installation Instructions

Un-installation differs depending on how you have installed uutils. If you used Cargo to install, use Cargo to uninstall. If you used GNU Make to install, use Make to uninstall.

Cargo

To uninstall uutils:

$ cargo uninstall uutils

GNU Make

To uninstall all utilities:

$ make uninstall

To uninstall every program with a set prefix:

$ make PROG_PREFIX=PREFIX_GOES_HERE uninstall

To uninstall the multicall binary:

$ make MULTICALL=y uninstall

To uninstall from a custom parent directory:

# DESTDIR is also supported
$ make PREFIX=/my/path uninstall

Contributing to coreutils

Contributions are very welcome, and should target Rust's master branch until the standard libraries are stabilized. You may claim an item on the to-do list by following these steps:

Open an issue named "Implement [the utility of your choice]", e.g. "Implement ls".
State that you are working on this utility.
Develop the utility.
Add integration tests.
Add the reference to your utility into Cargo.toml and Makefile.
Remove utility from the to-do list in the README.
Submit a pull request and close the issue.

The steps above imply that, before starting to work on a utility, you should search the issues to make sure no one else is working on it.

Best practices

Follow what GNU is doing in terms of options and behavior. It is recommended to look at the GNU Coreutils manual (on the web, or locally using info <utility>). It is more in depth than the man pages and provides a good description of available features and their implementation details.
If possible, look at the GNU test suite execution in the CI and make the test work if failing.
Use clap for argument management.
Make sure that the code coverage is covering all of the cases, including errors.
The code must be clippy-warning-free and rustfmt-compliant.
Don't hesitate to move common functions into uucore if they can be reused by other binaries.
Unsafe code should be documented with Safety comments.
uutils is original code. It cannot contain code from existing GNU or Unix-like utilities, nor should it link to or reference GNU libraries.

Commit messages

To help the project maintainers review pull requests from contributors across numerous utilities, the team has settled on conventions for commit messages.

From http://git-scm.com/book/ch5-2.html:

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

  - Bullet points are okay, too

  - Typically a hyphen or asterisk is used for the bullet, preceded by a
    single space, with blank lines in between, but conventions vary here

Furthermore, here are a few examples for a summary line:

commit for a single utility

nohup: cleanup and refactor

commit for a utility's tests

tests/rm: test new feature

Beyond changes to an individual utility or its tests, other summary lines for non-utility modules include:

README: add help

uucore: add new modules

uutils: add new utility

gitignore: add temporary files

Licensing

uutils is distributed under the terms of the MIT License; see the LICENSE file for details. This is a permissive license, which allows the software to be used with few restrictions.

Copyrights in the uutils project are retained by their contributors, and no copyright assignment is required to contribute.

If you wish to add or change dependencies as part of a contribution to the project, a tool like cargo-license can be used to show their license details. The following types of license are acceptable:

MIT License
Dual- or tri-license with an MIT License option ("Apache-2.0 or MIT" is a popular combination)
"MIT equivalent" license (2-clause BSD, 3-clause BSD, ISC)
License less restrictive than the MIT License (CC0 1.0 Universal)
Apache License version 2.0

Licenses we will not use:

An ambiguous license, or no license
Strongly reciprocal licenses (GNU GPL, GNU LGPL)

If you wish to add a reference but it doesn't meet these requirements, please raise an issue to describe the dependency.

Multi-call binary

uutils includes a multi-call binary from which the utils can be invoked. This reduces the binary size of the binary and can be useful for portability.

The first argument of the multi-call binary is the util to run, after which the regular arguments to the util can be passed.

coreutils [util] [util options]

The --help flag will print a list of available utils.

Example

coreutils ls -l

arch

version: 0.0.12

arch

Display machine architecture

uutils Documentation