diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index d196c6e95..39474f7ab 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -116,7 +116,7 @@ the community. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). @@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. +. Translations are available at +. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a749ebac..f2e5763a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,20 +38,19 @@ search the issues to make sure no one else is working on it. ## Platforms -We take pride in supporting many operating systems and architectures. +We take pride in supporting many operating systems and architectures. **Tip:** -For Windows, Microsoft provides some images (VMWare, Hyper-V, VirtualBox and Parallels) +For Windows, Microsoft provides some images (VMWare, Hyper-V, VirtualBox and Parallels) for development: -https://developer.microsoft.com/windows/downloads/virtual-machines/ - + ## 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: +From : ``` Short (50 chars or less) summary of changes diff --git a/DEVELOPER_INSTRUCTIONS.md b/DEVELOPER_INSTRUCTIONS.md index 28deb2677..f7dfc689e 100644 --- a/DEVELOPER_INSTRUCTIONS.md +++ b/DEVELOPER_INSTRUCTIONS.md @@ -1,21 +1,19 @@ -Documentation -------------- +# Documentation The source of the documentation is available on: -https://uutils.github.io/dev/coreutils/ + The documentation is updated everyday on this repository: -https://github.com/uutils/uutils.github.io/ + -Running GNU tests ------------------ +## Running GNU tests -- Check out https://github.com/coreutils/coreutils next to your fork as gnu -- Check out https://github.com/coreutils/gnulib next to your fork as gnulib +- Check out next to your fork as gnu +- Check out next to your fork as gnulib - Rename the checkout of your fork to uutils At the end you should have uutils, gnu and gnulib checked out next to each other. @@ -23,9 +21,7 @@ At the end you should have uutils, gnu and gnulib checked out next to each other - Run `cd uutils && ./util/build-gnu.sh && cd ..` to get everything ready (this may take a while) - Finally, you can run tests with `bash uutils/util/run-gnu-test.sh `. Instead of `` insert the tests you want to run, e.g. `tests/misc/wc-proc.sh`. - -Code Coverage Report Generation ---------------------------------- +## Code Coverage Report Generation @@ -36,13 +32,13 @@ Code coverage report can be generated using [grcov](https://github.com/mozilla/g To generate [gcov-based](https://github.com/mozilla/grcov#example-how-to-generate-gcda-files-for-a-rust-project) coverage report ```bash -$ export CARGO_INCREMENTAL=0 -$ export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort" -$ export RUSTDOCFLAGS="-Cpanic=abort" -$ cargo build # e.g., --features feat_os_unix -$ cargo test # e.g., --features feat_os_unix test_pathchk -$ grcov . -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 +export CARGO_INCREMENTAL=0 +export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort" +export RUSTDOCFLAGS="-Cpanic=abort" +cargo build # e.g., --features feat_os_unix +cargo test # e.g., --features feat_os_unix test_pathchk +grcov . -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 run `cargo clean` and run the above commands. @@ -52,19 +48,17 @@ if changes are not reflected in the report then run `cargo clean` and run the ab If you are using stable version of Rust that doesn't enable code coverage instrumentation by default then add `-Z-Zinstrument-coverage` flag to `RUSTFLAGS` env variable specified above. - -pre-commit hooks ----------------- +## pre-commit hooks A configuration for `pre-commit` is provided in the repository. It allows automatically checking every git commit you make to ensure it compiles, and passes `clippy` and `rustfmt` without warnings. To use the provided hook: 1. [Install `pre-commit`](https://pre-commit.com/#install) -2. Run `pre-commit install` while in the repository directory +1. Run `pre-commit install` while in the repository directory Your git commits will then automatically be checked. If a check fails, an error message will explain why, and your commit will be canceled. You can then make the suggested changes, and run `git commit ...` again. -### Using Clippy +## Using Clippy The `msrv` key in the clippy configuration file `clippy.toml` is used to disable lints pertaining to newer features by specifying the minimum supported Rust version (MSRV). However, this key is only supported on `nightly`. To invoke clippy without errors, use `cargo +nightly clippy`. In order to also check tests and non-default crate features, use `cargo +nightly clippy --all-targets --all-features`. diff --git a/README.md b/README.md index 66a0395e9..1bd87401c 100644 --- a/README.md +++ b/README.md @@ -21,11 +21,12 @@ or different behavior might be experienced. To install it: -``` -$ cargo install coreutils -$ ~/.cargo/bin/coreutils +```bash +cargo install coreutils +~/.cargo/bin/coreutils ``` + ## Why? uutils aims to work on as many platforms as possible, to be able to use the @@ -35,6 +36,7 @@ chosen not only because it is fast and safe, but is also excellent for writing cross-platform code. ## Documentation + uutils has both user and developer documentation available: - [User Manual](https://uutils.github.io/user/) @@ -46,8 +48,8 @@ Both can also be generated locally, the instructions for that can be found in th ## Requirements -* Rust (`cargo`, `rustc`) -* GNU Make (optional) +- Rust (`cargo`, `rustc`) +- GNU Make (optional) ### Rust Version @@ -65,8 +67,8 @@ or GNU Make. For either method, we first need to fetch the repository: ```bash -$ git clone https://github.com/uutils/coreutils -$ cd coreutils +git clone https://github.com/uutils/coreutils +cd coreutils ``` ### Cargo @@ -75,7 +77,7 @@ Building uutils using Cargo is easy because the process is the same as for every other Rust program: ```bash -$ cargo build --release +cargo build --release ``` This command builds the most portable common core set of uutils into a multicall @@ -86,11 +88,11 @@ expanded sets of uutils for a platform (on that platform) is as simple as specifying it as a feature: ```bash -$ cargo build --release --features macos +cargo build --release --features macos # or ... -$ cargo build --release --features windows +cargo build --release --features windows # or ... -$ cargo build --release --features unix +cargo build --release --features unix ``` If you don't want to build every utility available on your platform into the @@ -98,7 +100,7 @@ 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 +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 @@ -108,7 +110,7 @@ is contained in its own package within the main repository, named 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 +cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm ``` ### GNU Make @@ -118,29 +120,29 @@ Building using `make` is a simple process as well. To simply build all available utilities: ```bash -$ make +make ``` To build all but a few of the available utilities: ```bash -$ make SKIP_UTILS='UTILITY_1 UTILITY_2' +make SKIP_UTILS='UTILITY_1 UTILITY_2' ``` To build only a few of the available utilities: ```bash -$ make UTILS='UTILITY_1 UTILITY_2' +make UTILS='UTILITY_1 UTILITY_2' ``` ## Installation -### Cargo +### Install with Cargo Likewise, installing can simply be done using: ```bash -$ cargo install --path . +cargo install --path . ``` This command will install uutils into Cargo's *bin* folder (*e.g.* `$HOME/.cargo/bin`). @@ -148,49 +150,49 @@ This command will install uutils into Cargo's *bin* folder (*e.g.* `$HOME/.cargo 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 +### Install with GNU Make To install all available utilities: ```bash -$ make install +make install ``` To install using `sudo` switch `-E` must be used: ```bash -$ sudo -E make install +sudo -E make install ``` To install all but a few of the available utilities: ```bash -$ make SKIP_UTILS='UTILITY_1 UTILITY_2' install +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 +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 +make PROG_PREFIX=PREFIX_GOES_HERE install ``` To install the multicall binary: ```bash -$ make MULTICALL=y install +make MULTICALL=y install ``` Set install parent directory (default value is /usr/local): ```bash # DESTDIR is also supported -$ make PREFIX=/my/path install +make PREFIX=/my/path install ``` Installing with `make` installs shell completions for all installed utilities @@ -203,6 +205,7 @@ The `coreutils` binary can generate completions for the `bash`, `elvish`, `fish` and `zsh` shells. It prints the result to stdout. The syntax is: + ```bash cargo run completion ``` @@ -220,106 +223,107 @@ 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 +### Uninstall with Cargo To uninstall uutils: ```bash -$ cargo uninstall uutils +cargo uninstall uutils ``` -### GNU Make +### Uninstall with GNU Make To uninstall all utilities: ```bash -$ make uninstall +make uninstall ``` To uninstall every program with a set prefix: ```bash -$ make PROG_PREFIX=PREFIX_GOES_HERE uninstall +make PROG_PREFIX=PREFIX_GOES_HERE uninstall ``` To uninstall the multicall binary: ```bash -$ make MULTICALL=y uninstall +make MULTICALL=y uninstall ``` To uninstall from a custom parent directory: ```bash # DESTDIR is also supported -$ make PREFIX=/my/path uninstall +make PREFIX=/my/path uninstall ``` + ## Testing Testing can be done using either Cargo or `make`. -### Cargo +### Testing with Cargo Just like with building, we follow the standard procedure for testing using Cargo: ```bash -$ cargo test +cargo test ``` By default, `cargo test` only runs the common programs. To run also platform specific tests, run: ```bash -$ cargo test --features unix +cargo test --features unix ``` If you would prefer to test a select few utilities: ```bash -$ cargo test --features "chmod mv tail" --no-default-features +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 +cargo test -p uucore -p coreutils ``` To debug: ```bash -$ gdb --args target/debug/coreutils ls +gdb --args target/debug/coreutils ls (gdb) b ls.rs:79 (gdb) run ``` -### GNU Make +### Testing with GNU Make To simply test all available utilities: ```bash -$ make test +make test ``` To test all but a few of the available utilities: ```bash -$ make SKIP_UTILS='UTILITY_1 UTILITY_2' test +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 +make UTILS='UTILITY_1 UTILITY_2' test ``` To include tests for unimplemented behavior: ```bash -$ make UTILS='UTILITY_1 UTILITY_2' SPEC=y test +make UTILS='UTILITY_1 UTILITY_2' SPEC=y test ``` ### Run Busybox Tests @@ -330,19 +334,19 @@ requires `make`. To run busybox tests for all utilities for which busybox has tests ```bash -$ make busytest +make busytest ``` To run busybox tests for a few of the available utilities ```bash -$ make UTILS='UTILITY_1 UTILITY_2' busytest +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 +make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest ``` ### Comparing with GNU @@ -356,14 +360,14 @@ breakdown of the GNU test results of the main branch can be found To run locally: ```bash -$ bash util/build-gnu.sh -$ bash util/run-gnu-test.sh +bash util/build-gnu.sh +bash util/run-gnu-test.sh # To run a single test: -$ bash util/run-gnu-test.sh tests/touch/not-owner.sh # for example +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 +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 +DEBUG=1 bash util/run-gnu-test.sh tests/misc/sm3sum.pl ``` Note that it relies on individual utilities (not the multicall binary). @@ -387,7 +391,6 @@ To improve the GNU compatibility, the following process is recommended: 1. Start to modify the Rust implementation to match the expected behavior 1. Add a test to make sure that we don't regress (our test suite is super quick) - ## Contributing To contribute to uutils, please see [CONTRIBUTING](CONTRIBUTING.md). @@ -395,11 +398,12 @@ To contribute to uutils, please see [CONTRIBUTING](CONTRIBUTING.md). ## Utilities Please note that this is not fully accurate: -* Some new options can be added / removed in the GNU implementation; -* Some error management might be missing; -* Some behaviors might be different. -See https://github.com/uutils/coreutils/issues/3336 for the main meta bugs +- Some new options can be added / removed in the GNU implementation; +- Some error management might be missing; +- Some behaviors might be different. + +See for the main meta bugs (many are missing). | Done | WIP | diff --git a/docs/src/build.md b/docs/src/build.md index 6505b5b6e..e35b0ebe8 100644 --- a/docs/src/build.md +++ b/docs/src/build.md @@ -1,3 +1,3 @@ # Build from source -{{#include ../../README.md:build }} \ No newline at end of file +{{#include ../../README.md:build }} diff --git a/docs/src/contributing.md b/docs/src/contributing.md index 79ef4d13b..f69e1b377 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -1 +1,3 @@ -{{ #include ../../CONTRIBUTING.md }} \ No newline at end of file + + +{{ #include ../../CONTRIBUTING.md }} diff --git a/docs/src/index.md b/docs/src/index.md index 7bac8b816..0212b7526 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,5 +1,9 @@ + + {{#include logo.svg}} + +