diff --git a/.github/workflows/CICD.yml b/.github/workflows/CICD.yml index cf12ee2d7..9e48eb804 100644 --- a/.github/workflows/CICD.yml +++ b/.github/workflows/CICD.yml @@ -291,7 +291,13 @@ jobs: shell: bash run: | RUSTDOCFLAGS="-Dwarnings" cargo doc ${{ steps.vars.outputs.CARGO_FEATURES_OPTION }} --no-deps --workspace --document-private-items - + - uses: DavidAnson/markdownlint-cli2-action@v9 + with: + command: fix + globs: | + *.md + docs/src/*.md + src/uu/*/*.md min_version: name: MinRustV # Minimum supported rust version (aka, MinSRV or MSRV) @@ -408,6 +414,16 @@ jobs: make test env: RUST_BACKTRACE: "1" + - name: "`make install`" + shell: bash + run: | + DESTDIR=/tmp/ make PROFILE=release install + # Check that the manpage is present + test -f /tmp/usr/local/share/man/man1/whoami.1 + # Check that the completion is present + test -f /tmp/usr/local/share/zsh/site-functions/_install + env: + RUST_BACKTRACE: "1" build_rust_stable: diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 000000000..11b733e0b --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,6 @@ +# Disable 'Line length'. Doesn't provide much values +MD013: false +# Disable 'Fenced code blocks should have a language specified' +# Doesn't provide much in src/ to enforce it +MD040: false + 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/Cargo.lock b/Cargo.lock index 89d67bf81..e4f489eae 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -267,6 +267,16 @@ dependencies = [ "os_str_bytes", ] +[[package]] +name = "clap_mangen" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb0f09a0ca8f0dd8ac92c546b426f466ef19828185c6d504c80c48c9c2768ed9" +dependencies = [ + "clap", + "roff", +] + [[package]] name = "codespan-reporting" version = "0.11.1" @@ -324,6 +334,7 @@ dependencies = [ "chrono", "clap", "clap_complete", + "clap_mangen", "conv", "filetime", "glob", @@ -1874,6 +1885,12 @@ dependencies = [ "libc", ] +[[package]] +name = "roff" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b833d8d034ea094b1ea68aa6d5c740e0d04bad9d16568d08ba6f76823a114316" + [[package]] name = "rstest" version = "0.16.0" diff --git a/Cargo.toml b/Cargo.toml index 61a461deb..d8d43b252 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ # coreutils (uutils) # * see the repository LICENSE, README, and CONTRIBUTING files for more information -# spell-checker:ignore (libs) libselinux gethostid procfs bigdecimal kqueue fundu +# spell-checker:ignore (libs) libselinux gethostid procfs bigdecimal kqueue fundu mangen [package] name = "coreutils" @@ -271,6 +271,7 @@ byteorder = "1.3.2" chrono = { version="^0.4.23", default-features=false, features=["std", "alloc", "clock"]} clap = { version = "4.0", features = ["wrap_help", "cargo"] } clap_complete = "4.0" +clap_mangen = "0.2" compare = "0.1.0" coz = { version = "0.1.3" } crossterm = ">=0.19" @@ -352,6 +353,7 @@ clap = { workspace=true } once_cell = { workspace=true } uucore = { workspace=true } clap_complete = { workspace=true } +clap_mangen = { workspace=true } phf = { workspace=true } selinux = { workspace=true, optional = true } textwrap = { workspace=true } diff --git a/DEVELOPER_INSTRUCTIONS.md b/DEVELOPER_INSTRUCTIONS.md index 28deb2677..3641f57b9 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 @@ -35,14 +31,14 @@ 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 +```shell +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,21 @@ 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`. + +## Markdown linter + +We use to lint the Markdown files. diff --git a/GNUmakefile b/GNUmakefile index b242bc8ce..81b90d32f 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -349,10 +349,12 @@ endif mkdir -p $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions mkdir -p $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions mkdir -p $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d + mkdir -p $(DESTDIR)$(DATAROOTDIR)/man/man1 $(foreach prog, $(INSTALLEES), \ $(BUILDDIR)/coreutils completion $(prog) zsh > $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions/_$(PROG_PREFIX)$(prog); \ $(BUILDDIR)/coreutils completion $(prog) bash > $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions/$(PROG_PREFIX)$(prog); \ $(BUILDDIR)/coreutils completion $(prog) fish > $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d/$(PROG_PREFIX)$(prog).fish; \ + $(BUILDDIR)/coreutils manpage $(prog) > $(DESTDIR)$(DATAROOTDIR)/man/man1/$(PROG_PREFIX)$(prog).1; \ ) uninstall: diff --git a/README.md b/README.md index 66a0395e9..4bf12ccf5 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ----------------------------------------------- - + uutils is an attempt at writing universal (as in cross-platform) CLI utilities in [Rust](http://www.rust-lang.org). @@ -21,11 +21,12 @@ or different behavior might be experienced. To install it: -``` -$ cargo install coreutils -$ ~/.cargo/bin/coreutils +```shell +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 @@ -64,9 +66,9 @@ or GNU Make. For either method, we first need to fetch the repository: -```bash -$ git clone https://github.com/uutils/coreutils -$ cd coreutils +```shell +git clone https://github.com/uutils/coreutils +cd coreutils ``` ### Cargo @@ -74,8 +76,8 @@ $ cd coreutils Building uutils using Cargo is easy because the process is the same as for every other Rust program: -```bash -$ cargo build --release +```shell +cargo build --release ``` This command builds the most portable common core set of uutils into a multicall @@ -85,20 +87,20 @@ 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 -$ cargo build --release --features macos +```shell +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 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 +```shell +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 @@ -107,8 +109,8 @@ 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: -```bash -$ cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm +```shell +cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm ``` ### GNU Make @@ -117,80 +119,86 @@ Building using `make` is a simple process as well. To simply build all available utilities: -```bash -$ make +```shell +make +``` + +In release mode: + +```shell +make PROFILE=release ``` To build all but a few of the available utilities: -```bash -$ make SKIP_UTILS='UTILITY_1 UTILITY_2' +```shell +make SKIP_UTILS='UTILITY_1 UTILITY_2' ``` To build only a few of the available utilities: -```bash -$ make UTILS='UTILITY_1 UTILITY_2' +```shell +make UTILS='UTILITY_1 UTILITY_2' ``` ## Installation -### Cargo +### Install with Cargo Likewise, installing can simply be done using: -```bash -$ cargo install --path . +```shell +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`. +This does not install files necessary for shell completion or manpages. +For manpages or shell completion to work, use `GNU Make` or see `Manually install shell completions`/`Manually install manpages`. -### GNU Make +### Install with GNU Make To install all available utilities: -```bash -$ make install +```shell +make install ``` To install using `sudo` switch `-E` must be used: -```bash -$ sudo -E make install +```shell +sudo -E make install ``` To install all but a few of the available utilities: -```bash -$ make SKIP_UTILS='UTILITY_1 UTILITY_2' install +```shell +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 +```shell +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 +```shell +make PROG_PREFIX=PREFIX_GOES_HERE install ``` To install the multicall binary: -```bash -$ make MULTICALL=y install +```shell +make MULTICALL=y install ``` Set install parent directory (default value is /usr/local): -```bash +```shell # 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,123 +211,139 @@ The `coreutils` binary can generate completions for the `bash`, `elvish`, `fish` and `zsh` shells. It prints the result to stdout. The syntax is: -```bash + +```shell cargo run completion ``` So, to install completions for `ls` on `bash` to `/usr/local/share/bash-completion/completions/ls`, run: -```bash +```shell cargo run completion ls bash > /usr/local/share/bash-completion/completions/ls ``` +### Manually install manpages + +To generate manpages, the syntax is: +```bash +cargo run manpage +``` + +So, to install the manpage for `ls` to `/usr/local/share/man/man1/ls.1` +run: + +```bash +cargo run manpage ls > /usr/local/share/man/man1/ls.1 +``` + ## Un-installation 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 +```shell +cargo uninstall uutils ``` -### GNU Make +### Uninstall with GNU Make To uninstall all utilities: -```bash -$ make uninstall +```shell +make uninstall ``` To uninstall every program with a set prefix: -```bash -$ make PROG_PREFIX=PREFIX_GOES_HERE uninstall +```shell +make PROG_PREFIX=PREFIX_GOES_HERE uninstall ``` To uninstall the multicall binary: -```bash -$ make MULTICALL=y uninstall +```shell +make MULTICALL=y uninstall ``` To uninstall from a custom parent directory: -```bash +```shell # 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 +```shell +cargo test ``` By default, `cargo test` only runs the common programs. To run also platform specific tests, run: -```bash -$ cargo test --features unix +```shell +cargo test --features unix ``` If you would prefer to test a select few utilities: -```bash -$ cargo test --features "chmod mv tail" --no-default-features +```shell +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 +```shell +cargo test -p uucore -p coreutils ``` To debug: -```bash -$ gdb --args target/debug/coreutils ls +```shell +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 +```shell +make test ``` To test all but a few of the available utilities: -```bash -$ make SKIP_UTILS='UTILITY_1 UTILITY_2' test +```shell +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 +```shell +make UTILS='UTILITY_1 UTILITY_2' test ``` To include tests for unimplemented behavior: -```bash -$ make UTILS='UTILITY_1 UTILITY_2' SPEC=y test +```shell +make UTILS='UTILITY_1 UTILITY_2' SPEC=y test ``` ### Run Busybox Tests @@ -329,20 +353,20 @@ requires `make`. To run busybox tests for all utilities for which busybox has tests -```bash -$ make busytest +```shell +make busytest ``` To run busybox tests for a few of the available utilities -```bash -$ make UTILS='UTILITY_1 UTILITY_2' busytest +```shell +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 +```shell +make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest ``` ### Comparing with GNU @@ -355,15 +379,15 @@ 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 +```shell +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 +411,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 +418,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}} + +