Merge pull request #2050 from rivy/update.readme

README update revising initial build instructions

README.md

@@ -1,5 +1,4 @@
-uutils coreutils
+# uutils coreutils
-================
 
 [![Crates.io](https://img.shields.io/crates/v/coreutils.svg)](https://crates.io/crates/coreutils)
 [![Discord](https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat)](https://discord.gg/wQVJbvJ)
@@ -9,285 +8,322 @@ uutils coreutils
 
 [![Build Status](https://api.travis-ci.org/uutils/coreutils.svg?branch=master)](https://travis-ci.org/uutils/coreutils)
 [![Build Status (FreeBSD)](https://api.cirrus-ci.com/github/uutils/coreutils.svg)](https://cirrus-ci.com/github/uutils/coreutils/master)
-[![codecov](https://codecov.io/gh/uutils/coreutils/branch/master/graph/badge.svg)](https://codecov.io/gh/uutils/coreutils)
+[![CodeCov](https://codecov.io/gh/uutils/coreutils/branch/master/graph/badge.svg)](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,
+There are currently two methods to build the uutils binaries: either Cargo
-while there may be two methods, both systems are required to build on Unix
+or GNU Make.
-(only Cargo is required on Windows).
+
+> 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
+This command builds the most portable common core set of uutils into a multicall
-Unix-like platforms at the moment, to build on Windows, you must do the
+(BusyBox-type) binary, named 'coreutils', on most Rust-supported platforms.
-following:
+
+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 --features macos
-$ cargo build --release --no-default-features --features windows
+# 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
+final binary, you can also specify which ones you want to build manually.
-you want to build manually.  For example:
+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
+If you don't want to build the multicall binary and would prefer to build
-build the utilities as individual binaries, that is possible too.  For example:
+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:
 
-```
+```shell
-nix-env -iA nixos.uutils-coreutils
+$ 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