mirror of
https://github.com/RGBCube/uutils-coreutils
synced 2025-07-28 03:27:44 +00:00
Merge pull request #2050 from rivy/update.readme
README update revising initial build instructions
This commit is contained in:
Sylvestre Ledru
GitHub
commit
b26e12eaa4
1 changed files with 87 additions and 53 deletions
140
README.md
140
README.md
|
|
@ -1,5 +1,4 @@
|
|||
uutils coreutils
|
||||
================
|
||||
# uutils coreutils
|
||||
|
||||
[](https://crates.io/crates/coreutils)
|
||||
[](https://discord.gg/wQVJbvJ)
|
||||
|
|
@ -9,285 +8,322 @@ uutils coreutils
|
|||
|
||||
[](https://travis-ci.org/uutils/coreutils)
|
||||
[](https://cirrus-ci.com/github/uutils/coreutils/master)
|
||||
[](https://codecov.io/gh/uutils/coreutils)
|
||||
[](https://codecov.io/gh/uutils/coreutils)
|
||||
|
||||
-----------------------------------------------
|
||||
|
||||
<!-- markdownlint-disable commands-show-output no-duplicate-heading -->
|
||||
<!-- spell-checker:ignore markdownlint ; (jargon) multicall ; (misc) aarch riscv uutil uutils ; (names/acronyms) BusyBox BusyBox's BusyTest MSVC NixOS PowerPC WASI WASM ; (options) DESTDIR RUNTEST UTILNAME -->
|
||||
|
||||
uutils is an attempt at writing universal (as in cross-platform) CLI
|
||||
utilities in [Rust](http://www.rust-lang.org). This repository is intended to
|
||||
aggregate GNU coreutils rewrites.
|
||||
|
||||
Why?
|
||||
----
|
||||
## Why?
|
||||
|
||||
Many GNU, Linux and other utilities are useful, and obviously
|
||||
[some](http://gnuwin32.sourceforge.net) [effort](http://unxutils.sourceforge.net)
|
||||
has been spent in the past to port them to Windows. However, those projects
|
||||
are written in platform-specific C, a language considered unsafe compared to Rust, and
|
||||
are written in platform-specific C, a language considered unsafe compared to Rust, and
|
||||
have other issues.
|
||||
|
||||
Rust provides a good, platform-agnostic way of writing systems utilities that are easy
|
||||
to compile anywhere, and this is as good a way as any to try and learn it.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
## Requirements
|
||||
|
||||
* Rust (`cargo`, `rustc`)
|
||||
* GNU Make (required to build documentation)
|
||||
* [Sphinx](http://www.sphinx-doc.org/) (for documentation)
|
||||
* gzip (for installing documentation)
|
||||
|
||||
### Rust Version ###
|
||||
### 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.40.0`.
|
||||
|
||||
On both Windows and Redox, only the nightly version is tested currently.
|
||||
|
||||
Build Instructions
|
||||
------------------
|
||||
## Build Instructions
|
||||
|
||||
There are currently two methods to build uutils: GNU Make and Cargo. However,
|
||||
while there may be two methods, both systems are required to build on Unix
|
||||
(only Cargo is required on Windows).
|
||||
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:
|
||||
|
||||
First, for both methods, we need to fetch the repository:
|
||||
```bash
|
||||
$ git clone https://github.com/uutils/coreutils
|
||||
$ cd coreutils
|
||||
```
|
||||
|
||||
### Cargo ###
|
||||
### Cargo
|
||||
|
||||
Building uutils using Cargo is easy because the process is the same as for
|
||||
every other Rust program:
|
||||
|
||||
```bash
|
||||
# to keep debug information, compile without --release
|
||||
$ cargo build --release
|
||||
```
|
||||
|
||||
Because the above command attempts to build utilities that only work on
|
||||
Unix-like platforms at the moment, to build on Windows, you must do the
|
||||
following:
|
||||
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:
|
||||
|
||||
```bash
|
||||
# to keep debug information, compile without --release
|
||||
$ cargo build --release --no-default-features --features windows
|
||||
$ 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
|
||||
multicall binary (the Busybox-esque binary), you can also specify which ones
|
||||
you want to build manually. For example:
|
||||
final binary, you can also specify which ones you want to build manually.
|
||||
For example:
|
||||
|
||||
```bash
|
||||
$ cargo build --features "base32 cat echo rm" --no-default-features
|
||||
```
|
||||
|
||||
If you don't even want to build the multicall binary and would prefer to just
|
||||
build the utilities as individual binaries, that is possible too. For example:
|
||||
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 it's 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:
|
||||
|
||||
```bash
|
||||
$ cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm
|
||||
```
|
||||
|
||||
### GNU Make ###
|
||||
### GNU Make
|
||||
|
||||
Building using `make` is a simple process as well.
|
||||
|
||||
To simply build all available utilities:
|
||||
|
||||
```bash
|
||||
$ make
|
||||
```
|
||||
|
||||
To build all but a few of the available utilities:
|
||||
|
||||
```bash
|
||||
$ make SKIP_UTILS='UTILITY_1 UTILITY_2'
|
||||
```
|
||||
|
||||
To build only a few of the available utilities:
|
||||
|
||||
```bash
|
||||
$ make UTILS='UTILITY_1 UTILITY_2'
|
||||
```
|
||||
|
||||
Installation Instructions
|
||||
-------------------------
|
||||
## Installation Instructions
|
||||
|
||||
### Cargo ###
|
||||
### Cargo
|
||||
|
||||
Likewise, installing can simply be done using:
|
||||
|
||||
```bash
|
||||
$ cargo install --path .
|
||||
```
|
||||
|
||||
This command will install uutils into Cargo's *bin* folder (*e.g.* `$HOME/.cargo/bin`).
|
||||
|
||||
### GNU Make ###
|
||||
### GNU Make
|
||||
|
||||
To install all available utilities:
|
||||
|
||||
```bash
|
||||
$ make install
|
||||
```
|
||||
|
||||
To install using `sudo` switch `-E` must be used:
|
||||
|
||||
```bash
|
||||
$ sudo -E make install
|
||||
```
|
||||
|
||||
To install all but a few of the available utilities:
|
||||
|
||||
```bash
|
||||
$ make SKIP_UTILS='UTILITY_1 UTILITY_2' install
|
||||
```
|
||||
|
||||
To install only a few of the available utilities:
|
||||
|
||||
```bash
|
||||
$ make UTILS='UTILITY_1 UTILITY_2' install
|
||||
```
|
||||
|
||||
To install every program with a prefix (e.g. uu-echo uu-cat):
|
||||
|
||||
```bash
|
||||
$ make PROG_PREFIX=PREFIX_GOES_HERE install
|
||||
```
|
||||
|
||||
To install the multicall binary:
|
||||
|
||||
```bash
|
||||
$ make MULTICALL=y install
|
||||
```
|
||||
|
||||
Set install parent directory (default value is /usr/local):
|
||||
|
||||
```bash
|
||||
# DESTDIR is also supported
|
||||
$ make PREFIX=/my/path install
|
||||
```
|
||||
|
||||
### NixOS ###
|
||||
### NixOS
|
||||
|
||||
The [standard package set](https://nixos.org/nixpkgs/manual/) of [NixOS](https://nixos.org/)
|
||||
provides this package out of the box since 18.03:
|
||||
|
||||
```
|
||||
nix-env -iA nixos.uutils-coreutils
|
||||
```shell
|
||||
$ nix-env -iA nixos.uutils-coreutils
|
||||
```
|
||||
|
||||
Uninstallation Instructions
|
||||
---------------------------
|
||||
## Un-installation Instructions
|
||||
|
||||
Uninstallation differs depending on how you have installed uutils. If you used
|
||||
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 ###
|
||||
### Cargo
|
||||
|
||||
To uninstall uutils:
|
||||
|
||||
```bash
|
||||
$ cargo uninstall uutils
|
||||
```
|
||||
|
||||
### GNU Make ###
|
||||
### GNU Make
|
||||
|
||||
To uninstall all utilities:
|
||||
|
||||
```bash
|
||||
$ make uninstall
|
||||
```
|
||||
|
||||
To uninstall every program with a set prefix:
|
||||
|
||||
```bash
|
||||
$ make PROG_PREFIX=PREFIX_GOES_HERE uninstall
|
||||
```
|
||||
|
||||
To uninstall the multicall binary:
|
||||
|
||||
```bash
|
||||
$ make MULTICALL=y uninstall
|
||||
```
|
||||
|
||||
To uninstall from a custom parent directory:
|
||||
|
||||
```bash
|
||||
# DESTDIR is also supported
|
||||
$ make PREFIX=/my/path uninstall
|
||||
```
|
||||
|
||||
Test Instructions
|
||||
-----------------
|
||||
## Test Instructions
|
||||
|
||||
Testing can be done using either Cargo or `make`.
|
||||
|
||||
### Cargo ###
|
||||
### Cargo
|
||||
|
||||
Just like with building, we follow the standard procedure for testing using
|
||||
Cargo:
|
||||
|
||||
```bash
|
||||
$ cargo test
|
||||
```
|
||||
|
||||
By default, `cargo test` only runs the common programs. To run also platform
|
||||
specific tests, run:
|
||||
|
||||
```bash
|
||||
$ cargo test --features unix
|
||||
```
|
||||
|
||||
If you would prefer to test a select few utilities:
|
||||
|
||||
```bash
|
||||
$ cargo test --features "chmod mv tail" --no-default-features
|
||||
```
|
||||
|
||||
If you also want to test the core utilities:
|
||||
|
||||
```bash
|
||||
$ cargo test -p uucore -p coreutils
|
||||
```
|
||||
|
||||
To debug:
|
||||
|
||||
```bash
|
||||
$ gdb --args target/debug/coreutils ls
|
||||
(gdb) b ls.rs:79
|
||||
(gdb) run
|
||||
```
|
||||
|
||||
### GNU Make ###
|
||||
### GNU Make
|
||||
|
||||
To simply test all available utilities:
|
||||
|
||||
```bash
|
||||
$ make test
|
||||
```
|
||||
|
||||
To test all but a few of the available utilities:
|
||||
|
||||
```bash
|
||||
$ make SKIP_UTILS='UTILITY_1 UTILITY_2' test
|
||||
```
|
||||
|
||||
To test only a few of the available utilities:
|
||||
|
||||
```bash
|
||||
$ make UTILS='UTILITY_1 UTILITY_2' test
|
||||
```
|
||||
|
||||
To include tests for unimplemented behavior:
|
||||
|
||||
```bash
|
||||
$ make UTILS='UTILITY_1 UTILITY_2' SPEC=y test
|
||||
```
|
||||
|
||||
Run Busybox Tests
|
||||
-----------------
|
||||
## Run Busybox Tests
|
||||
|
||||
This testing functionality is only available on *nix operating systems and
|
||||
requires `make`.
|
||||
|
||||
To run busybox's tests for all utilities for which busybox has tests
|
||||
|
||||
```bash
|
||||
$ make busytest
|
||||
```
|
||||
|
||||
To run busybox's tests for a few of the available utilities
|
||||
|
||||
```bash
|
||||
$ make UTILS='UTILITY_1 UTILITY_2' busytest
|
||||
```
|
||||
|
||||
To pass an argument like "-v" to the busybox test runtime
|
||||
|
||||
```bash
|
||||
$ make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest
|
||||
```
|
||||
|
||||
Contribute
|
||||
----------
|
||||
## Contribute
|
||||
|
||||
To contribute to uutils, please see [CONTRIBUTING](CONTRIBUTING.md).
|
||||
|
||||
Utilities
|
||||
---------
|
||||
## Utilities
|
||||
|
||||
| Done | Semi-Done | To Do |
|
||||
|-----------|-----------|--------|
|
||||
|
|
@ -377,8 +413,7 @@ Utilities
|
|||
| whoami | | |
|
||||
| yes | | |
|
||||
|
||||
Targets that compile
|
||||
-------
|
||||
## Targets that compile
|
||||
|
||||
This is an auto-generated table showing which binaries compile for each target-triple. Note that this **does not** indicate that they are fully implemented, or that the tests pass.
|
||||
|
||||
|
|
@ -405,8 +440,7 @@ This is an auto-generated table showing which binaries compile for each target-t
|
|||
|fuchsia|aarch64| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
|
||||
|fuchsia|x86_64| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
|
||||
|
||||
License
|
||||
-------
|
||||
## License
|
||||
|
||||
uutils is licensed under the MIT License - see the `LICENSE` file for details
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue