uutils/findutils
0
0
Fork 0
mirror of https://github.com/uutils/findutils.git synced 2026-06-10 15:48:30 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: initial version of mdbook (#347)

Browse Source 
* docs: initial version of mdbook

* docs: fix typo in CONTRIBUTING.md

---------

Co-authored-by: Daniel Hofstetter <daniel.hofstetter@42dh.com>
This commit is contained in:
Terts Diepraam
2024-04-03 07:50:24 +02:00
committed by GitHub
parent 274d749f8d
commit ef9c382464
14 changed files with 695 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CODE_OF_CONDUCT.md
+128
View File
@@ -0,0 +1,128 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socioeconomic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
sylvestre@debian.org.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
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).
[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>.
CONTRIBUTING.md
+264
View File
@@ -0,0 +1,264 @@
<!-- spell-checker:ignore reimplementing toybox RUNTEST CARGOFLAGS nextest embeddable Rustonomicon rustdoc's -->
# Contributing to findutils
Hi! Welcome to uutils/findutils!
Thanks for wanting to contribute to this project! This document explains
everything you need to know to contribute. Before you start make sure to also
check out these documents:
- Our community's [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
- [DEVELOPMENT.md](./DEVELOPMENT.md) for setting up your development
environment.
Now follows a very important warning:
> [!WARNING]
> uutils is original code and cannot contain any code from GNU or
> other implementations. This means that **we cannot accept any changes based on
> the GNU source code**. To make sure that cannot happen, **you cannot link to
> the GNU source code** either. It is however possible to look at other implementations
> under a BSD or MIT license like [Apple's implementation](https://opensource.apple.com/source/file_cmds/)
> or [OpenBSD](https://github.com/openbsd/src/tree/master/bin).
Finally, feel free to join our [Discord](https://discord.gg/wQVJbvJ)!
<!-- TODO: Getting Oriented -->
## Design Goals
We have the following goals with our development:
- **Compatible**: The utilities should be a drop-in replacement for the GNU
coreutils.
- **Cross-platform**: All utilities should run on as many of the supported
platforms as possible.
- **Reliable**: The utilities should never unexpectedly fail.
- **Performant**: Our utilities should be written in fast idiomatic Rust. We aim
to match or exceed the performance of the GNU utilities.
- **Well-tested**: We should have a lot of tests to be able to guarantee
reliability and compatibility.
## How to Help
There are several ways to help and writing code is just one of them. Reporting
issues and writing documentation are just as important as writing code.
### Reporting Issues
We can't fix bugs we don't know about, so good issues are super helpful! Here
are some tips for writing good issues:
- If you find a bug, make sure it's still a problem on the `main` branch.
- Search through the existing issues to see whether it has already been
reported.
- Make sure to include all relevant information, such as:
- Which version of uutils did you check?
- Which version of GNU coreutils are you comparing with?
- What platform are you on?
- Provide a way to reliably reproduce the issue.
- Be as specific as possible!
### Writing Documentation
There's never enough documentation. If you come across any documentation that
could be improved, feel free to submit a PR for it!
### Writing Code
If you want to submit a PR, make sure that you've discussed the solution with
the maintainers beforehand. We want to avoid situations where you put a lot of
work into a fix that we can't merge! If there's no issue for what you're trying
to fix yet, make one _before_ you start working on the PR.
Generally, we try to follow what GNU is doing in terms of options and behavior.
It is recommended to look at the GNU findtils manual
([on the web](https://www.gnu.org/software/findutils/manual/html_node/index.html),
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. But remember, you cannot look at the GNU source code!
Also remember that we can only merge PRs which pass our test suite, follow
rustfmt, and do not have any warnings from clippy. See
[DEVELOPMENT.md](./DEVELOPMENT.md) for more information. Be sure to also read
about our [Rust style](#our-rust-style).
## Our Rust Style
We want uutils to be written in idiomatic Rust, so here are some guidelines to
follow. Some of these are aspirational, meaning that we don't do them correctly
everywhere in the code. If you find violations of the advice below, feel free to
submit a patch!
### Don't `panic!`
The coreutils should be very reliable. This means that we should never `panic!`.
Therefore, you should avoid using `.unwrap()` and `panic!`. Sometimes the use of
`unreachable!` can be justified with a comment explaining why that code is
unreachable.
### Don't `exit`
We want uutils to be embeddable in other programs. This means that no function
in uutils should exit the program. Doing so would also lead to code with more
confusing control flow. Avoid therefore `std::process::exit` and similar
functions which exit the program early.
### `unsafe`
uutils cannot be entirely safe, because we have to call out to `libc` and do
syscalls. However, we still want to limit our use of `unsafe`. We generally only
accept `unsafe` for FFI, with very few exceptions. Note that performance is very
rarely a valid argument for using `unsafe`.
If you still need to write code with `unsafe`, make sure to read the
[Rustonomicon](https://doc.rust-lang.org/nomicon/intro.html) and annotate the
calls with `// SAFETY:` comments explaining why the use of `unsafe` is sound.
### Macros
Macros can be a great tool, but they are also usually hard to understand. They
should be used sparingly. Make sure to explore simpler options before you reach
for a solution involving macros.
### `str`, `OsStr` & `Path`
Rust has many string-like types, and sometimes it's hard to choose the right
one. It's tempting to use `str` (and `String`) for everything, but that is not
always the right choice for uutils, because we need to support invalid UTF-8,
just like the GNU coreutils. For example, paths on Linux might not be valid
UTF-8! Whenever we are dealing with paths, we should therefore stick with
`OsStr` and `Path`. Make sure that you only convert to `str`/`String` if you
know that something is always valid UTF-8. If you need more operations on
`OsStr`, you can use the [`bstr`](https://docs.rs/bstr/latest/bstr/) crate.
### Doc-comments
We use rustdoc for our documentation, so it's best to follow
[rustdoc's guidelines](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components).
Make sure that your documentation is not just repeating the name of the
function, but actually giving more useful information. Rustdoc recommends the
following structure:
```
[short sentence explaining what it is]
[more detailed explanation]
[at least one code example that users can copy/paste to try it]
[even more advanced explanations if necessary]
```
### Other comments
Comments should be written to _explain_ the code, not to _describe_ the code.
Try to focus on explaining _why_ the code is the way it is. If you feel like you
have to describe the code, that's usually a sign that you could improve the
naming of variables and functions.
If you edit a piece of code, make sure to update any comments that need to
change as a result. The only thing worse than having no comments is having
outdated comments!
## Git Etiquette
To ensure easy collaboration, we have guidelines for using Git and GitHub.
### Commits
- Make small and atomic commits.
- Keep a clean history of commits.
- Write informative commit messages.
- Annotate your commit message with the component you're editing. For example:
`cp: do not overwrite on with -i` or `uucore: add support for FreeBSD`.
- Do not unnecessarily move items around in the code. This makes the changes
much harder to review. If you do need to move things around, do that in a
separate commit.
### Commit messages
You can read this section in the Git book to learn how to write good commit
messages: https://git-scm.com/book/ch5-2.html.
In addition, here are a few examples for a summary line when committing to
uutils:
- 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
```
### PRs
- Make the titles of PRs descriptive.
- This means describing the problem you solve. For example, do not write
`Fix #1234`, but `ls: fix version sort order`.
- You can prefix the title with the utility the PR concerns.
- Keep PRs small and self-contained. A set of small PRs is much more likely to
get merged quickly than one large PR.
- Make sure the CI passes (up to intermittently failing tests).
- You know your code best, that's why it's best if you can solve merge conflicts
on your branch yourself.
- It's up to you whether you want to use `git merge main` or
`git rebase main`.
- Feel free to ask for help with merge conflicts.
- You do not need to ping maintainers to request a review, but it's fine to do
so if you don't get a response within a few days.
## Platforms
We take pride in supporting many operating systems and architectures. Any code
you contribute must at least compile without warnings for all platforms in the
CI. However, you can use `#[cfg(...)]` attributes to create platform dependent
features.
**Tip:** For Windows, Microsoft provides some images (VMWare, Hyper-V,
VirtualBox and Parallels) for development:
<https://developer.microsoft.com/windows/downloads/virtual-machines/>
## 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.
DEVELOPMENT.md
+156
View File
@@ -0,0 +1,156 @@
<!-- spell-checker:ignore (flags) Ccodegen Coverflow Cpanic Zinstrument Zpanic reimplementing toybox RUNTEST CARGOFLAGS nextest prereq autopoint gettext texinfo automake findutils shellenv libexec gnubin toolchains gsed -->
# Setting up your local development environment
For contributing rules and best practices please refer to [CONTRIBUTING.md](CONTRIBUTING.md)
## Before you start
For this guide we assume that you already have a GitHub account and have `git` and your favorite code editor or IDE installed and configured.
Before you start working on findutils, please follow these steps:
1. Fork the [findutils repository](https://github.com/uutils/findutils) to your GitHub account.
***Tip:*** See [this GitHub guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more information on this step.
2. Clone that fork to your local development environment:
```shell
git clone https://github.com/YOUR-GITHUB-ACCOUNT/findutils
cd findutils
```
## Tools
You will need the tools mentioned in this section to build and test your code changes locally.
This section will explain how to install and configure these tools.
We also have an extensive CI that uses these tools and will check your code before it can be merged.
The next section [Testing](#testing) will explain how to run those checks locally to avoid waiting for the CI.
### Rust toolchain
[Install Rust](https://www.rust-lang.org/tools/install)
If you're using rustup to install and manage your Rust toolchains, `clippy` and `rustfmt` are usually already installed. If you are using one of the alternative methods, please make sure to install them manually. See following sub-sections for their usage: [clippy](#clippy) [rustfmt](#rustfmt).
***Tip*** You might also need to add 'llvm-tools' component if you are going to [generate code coverage reports locally](#code-coverage-report):
```shell
rustup component add llvm-tools-preview
```
### 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)
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.
**NOTE: On MacOS** the pre-commit hooks are currently broken. There are workarounds involving switching to unstable nightly Rust and components.
### clippy
```shell
cargo clippy --all-targets --all-features
```
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).
### rustfmt
```shell
cargo fmt --all
```
### cargo-deny
This project uses [cargo-deny](https://github.com/EmbarkStudios/cargo-deny/) to
detect duplicate dependencies, checks licenses, etc. To run it locally, first
install it and then run with:
```shell
cargo deny --all-features check all
```
### Markdown linter
We use [markdownlint](https://github.com/DavidAnson/markdownlint) to lint the
Markdown files in the repository.
### Spell checker
We use `cspell` as spell checker for all files in the project. If you are using
VS Code, you can install the
[code spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
extension to enable spell checking within your editor. Otherwise, you can
install [cspell](https://cspell.org/) separately.
If you want to make the spell checker ignore a word, you can add
```rust
// spell-checker:ignore word_to_ignore
```
at the top of the file.
## Testing
Just like with building, we follow the standard procedure for testing using
Cargo:
```shell
cargo test
```
## Code coverage report
Code coverage report can be generated using [grcov](https://github.com/mozilla/grcov).
### Using Nightly Rust
To generate [gcov-based](https://github.com/mozilla/grcov#example-how-to-generate-gcda-files-for-a-rust-project) coverage report
```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 <options...>
cargo test <options...>
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.
### Using Stable Rust
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.
## Tips for setting up on Mac
### C Compiler and linker
On MacOS you'll need to install C compiler & linker:
```shell
xcode-select --install
```
## Tips for setting up on Windows
### MSVC build tools
On Windows you'll need the MSVC build tools for Visual Studio 2013 or later.
If you are using `rustup-init.exe` to install Rust toolchain, it will guide you through the process of downloading and installing these prerequisites.
Otherwise please follow [this guide](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup).
docs/book.toml
+10
View File
@@ -0,0 +1,10 @@
[book]
authors = ["Terts Diepraam"]
language = "en"
multilingual = false
src = "src"
title = "findutils"
[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]
docs/src/SUMMARY.md
+9
View File
@@ -0,0 +1,9 @@
# Summary
[Introduction](index.md)
* [Installation](installation.md)
* [Build from source](build.md)
* [Platform support](platforms.md)
* [Contributing](contributing.md)
* [GNU test coverage](test_coverage.md)
* [Extensions](extensions.md)
docs/src/build.md
+3
View File
@@ -0,0 +1,3 @@
# Build from source
TODO
docs/src/contributing.md
+3
View File
@@ -0,0 +1,3 @@
<!-- markdownlint-disable MD041 -->
{{ #include ../../CONTRIBUTING.md }}
docs/src/extensions.md
+3
View File
@@ -0,0 +1,3 @@
# Extensions
TODO
docs/src/index.md
+49
View File
@@ -0,0 +1,49 @@
<!-- markdownlint-disable MD041 -->
{{#include logo.svg}}
<!-- markdownlint-disable MD033 -->
<style>
/* Make the logo a bit bigger and center */
#logo {
height: 200px;
width: 100%;
}
/* This is necessary to get the <use> tags to obey the CSS styles below */
g, polygon {
fill: inherit;
stroke: inherit;
}
/* Set the circle to the foreground color of the theme */
#gear circle {
stroke: var(--fg);
}
/* Set the stroke of polygons and the copies (via use) */
#gear polygon,
#gear use {
fill: var(--fg);
stroke: var(--fg);
}
</style>
# uutils findutils Documentation
The uutils findutils project reimplements the GNU findutils in Rust. It is available for Linux, Windows, Mac
and other platforms.
uutils is licensed under the
[MIT License](https://github.com/uutils/findutils/blob/main/LICENSE).
## Useful links
- [Releases](https://github.com/uutils/findutils/releases)
- [Source Code](https://github.com/uutils/findutils)
- [Issues](https://github.com/uutils/findutils/issues)
- [Discord](https://discord.gg/wQVJbvJ)
> Note: This manual is automatically generated from the source code and is a
> work in progress.
docs/src/installation.md
+64
View File
@@ -0,0 +1,64 @@
<!-- spell-checker:ignore pacman pamac nixpkgs openmandriva conda winget openembedded yocto bblayers bitbake -->
# Installation
This is a list of uutils packages in various distributions and package managers.
Note that these are packaged by third-parties and the packages might contain
patches.
You can also [build findutils from source](build.md).
<!-- toc -->
## Cargo
[![crates.io package](https://repology.org/badge/version-for-repo/crates_io/rust:findutils.svg)](https://crates.io/crates/findutils)
```shell
cargo install findutils
```
## Linux
### Debian
[![Debian 13 package](https://repology.org/badge/version-for-repo/debian_13/rust:findutils.svg)](https://packages.debian.org/trixie/source/rust-findutils)
[![Debian Unstable package](https://repology.org/badge/version-for-repo/debian_unstable/rust:findutils.svg)](https://packages.debian.org/sid/source/rust-findutils)
```shell
apt install rust-findutils
# To use it:
export PATH=/usr/lib/cargo/bin/findutils:$PATH
```
### Gentoo
[![Gentoo package](https://repology.org/badge/version-for-repo/gentoo/uutils-findutils.svg)](https://packages.gentoo.org/packages/sys-apps/uutils-findutils)
```shell
emerge -pv sys-apps/uutils-findutils
```
## MacOS
### Homebrew
[![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/uutils-findutils.svg)](https://formulae.brew.sh/formula/uutils-findutils)
```shell
brew install uutils-findutils
```
## FreeBSD
[![FreeBSD port](https://repology.org/badge/version-for-repo/freebsd/rust-findutils.svg)](https://repology.org/project/rust-findutils/versions)
```sh
pkg install rust-findutils
```
## Windows
As far as we are aware, `findutils` has not been packaged for any package managers on Windows yet.
docs/src/oranda.css
-4
View File
@@ -1,4 +0,0 @@
.logo {
display: block;
height: 170px;
}
docs/src/platforms.md
+3
View File
@@ -0,0 +1,3 @@
# Platform support
TODO
docs/src/test_coverage.md
+3
View File
@@ -0,0 +1,3 @@
# GNU test coverage
TODO
oranda.json
-18
View File
@@ -1,18 +0,0 @@
{
"project": {
"name": "uutils findutils"
},
"build": {
"path_prefix": "findutils"
},
"components": {
"changelog": {
"read_changelog_file": false
}
},
"styles": {
"theme": "light",
"logo": "docs/src/logo.svg",
"additional_css": ["docs/src/oranda.css"]
}
}