uutils/uutils.github.io
0
0
Fork 0
mirror of https://github.com/uutils/uutils.github.io.git synced 2026-06-10 16:12:28 -07:00
Code Issues Packages Projects Releases Wiki Activity
Files
88883bf41ebcfc1604618648016abc841f091543
uutils.github.io/user/contributing.html
T
sylvestre 1ae6ac9650 deploy: f0e8d44e6e
2023-04-27 02:42:53 +00:00

502 lines
40 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Contributing - uutils Documentation</title>
<!-- Custom HTML head -->
<style>
dd {
margin-bottom: 1em;
}
main {
position: relative;
}
.additional {
position: absolute;
top: 0.5em;
right: 0;
display: flex;
gap: 5px;
align-items: center;
font-size: 1.3em;
}
.platforms {
font-size: 2rem;
}
dd > p {
margin-top: 0.2em;
}
</style>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var html = document.querySelector('html');
var sidebar = null;
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html">Introduction</a></li><li class="chapter-item expanded "><a href="installation.html"><strong aria-hidden="true">1.</strong> Installation</a></li><li class="chapter-item expanded "><a href="build.html"><strong aria-hidden="true">2.</strong> Build from source</a></li><li class="chapter-item expanded "><a href="contributing.html" class="active"><strong aria-hidden="true">3.</strong> Contributing</a></li><li class="chapter-item expanded "><a href="test_coverage.html"><strong aria-hidden="true">4.</strong> GNU test coverage</a></li><li class="chapter-item expanded "><a href="extensions.html"><strong aria-hidden="true">5.</strong> Extensions</a></li><li class="chapter-item expanded affix "><li class="part-title">Reference</li><li class="chapter-item expanded "><a href="multicall.html"><strong aria-hidden="true">6.</strong> Multi-call binary</a></li><li class="chapter-item expanded "><a href="utils/arch.html"><strong aria-hidden="true">7.</strong> arch</a></li><li class="chapter-item expanded "><a href="utils/b2sum.html"><strong aria-hidden="true">8.</strong> b2sum</a></li><li class="chapter-item expanded "><a href="utils/b3sum.html"><strong aria-hidden="true">9.</strong> b3sum</a></li><li class="chapter-item expanded "><a href="utils/base32.html"><strong aria-hidden="true">10.</strong> base32</a></li><li class="chapter-item expanded "><a href="utils/base64.html"><strong aria-hidden="true">11.</strong> base64</a></li><li class="chapter-item expanded "><a href="utils/basename.html"><strong aria-hidden="true">12.</strong> basename</a></li><li class="chapter-item expanded "><a href="utils/basenc.html"><strong aria-hidden="true">13.</strong> basenc</a></li><li class="chapter-item expanded "><a href="utils/cat.html"><strong aria-hidden="true">14.</strong> cat</a></li><li class="chapter-item expanded "><a href="utils/chcon.html"><strong aria-hidden="true">15.</strong> chcon</a></li><li class="chapter-item expanded "><a href="utils/chgrp.html"><strong aria-hidden="true">16.</strong> chgrp</a></li><li class="chapter-item expanded "><a href="utils/chmod.html"><strong aria-hidden="true">17.</strong> chmod</a></li><li class="chapter-item expanded "><a href="utils/chown.html"><strong aria-hidden="true">18.</strong> chown</a></li><li class="chapter-item expanded "><a href="utils/chroot.html"><strong aria-hidden="true">19.</strong> chroot</a></li><li class="chapter-item expanded "><a href="utils/cksum.html"><strong aria-hidden="true">20.</strong> cksum</a></li><li class="chapter-item expanded "><a href="utils/comm.html"><strong aria-hidden="true">21.</strong> comm</a></li><li class="chapter-item expanded "><a href="utils/cp.html"><strong aria-hidden="true">22.</strong> cp</a></li><li class="chapter-item expanded "><a href="utils/csplit.html"><strong aria-hidden="true">23.</strong> csplit</a></li><li class="chapter-item expanded "><a href="utils/cut.html"><strong aria-hidden="true">24.</strong> cut</a></li><li class="chapter-item expanded "><a href="utils/date.html"><strong aria-hidden="true">25.</strong> date</a></li><li class="chapter-item expanded "><a href="utils/dd.html"><strong aria-hidden="true">26.</strong> dd</a></li><li class="chapter-item expanded "><a href="utils/df.html"><strong aria-hidden="true">27.</strong> df</a></li><li class="chapter-item expanded "><a href="utils/dir.html"><strong aria-hidden="true">28.</strong> dir</a></li><li class="chapter-item expanded "><a href="utils/dircolors.html"><strong aria-hidden="true">29.</strong> dircolors</a></li><li class="chapter-item expanded "><a href="utils/dirname.html"><strong aria-hidden="true">30.</strong> dirname</a></li><li class="chapter-item expanded "><a href="utils/du.html"><strong aria-hidden="true">31.</strong> du</a></li><li class="chapter-item expanded "><a href="utils/echo.html"><strong aria-hidden="true">32.</strong> echo</a></li><li class="chapter-item expanded "><a href="utils/env.html"><strong aria-hidden="true">33.</strong> env</a></li><li class="chapter-item expanded "><a href="utils/expand.html"><strong aria-hidden="true">34.</strong> expand</a></li><li class="chapter-item expanded "><a href="utils/expr.html"><strong aria-hidden="true">35.</strong> expr</a></li><li class="chapter-item expanded "><a href="utils/factor.html"><strong aria-hidden="true">36.</strong> factor</a></li><li class="chapter-item expanded "><a href="utils/false.html"><strong aria-hidden="true">37.</strong> false</a></li><li class="chapter-item expanded "><a href="utils/fmt.html"><strong aria-hidden="true">38.</strong> fmt</a></li><li class="chapter-item expanded "><a href="utils/fold.html"><strong aria-hidden="true">39.</strong> fold</a></li><li class="chapter-item expanded "><a href="utils/groups.html"><strong aria-hidden="true">40.</strong> groups</a></li><li class="chapter-item expanded "><a href="utils/hashsum.html"><strong aria-hidden="true">41.</strong> hashsum</a></li><li class="chapter-item expanded "><a href="utils/head.html"><strong aria-hidden="true">42.</strong> head</a></li><li class="chapter-item expanded "><a href="utils/hostid.html"><strong aria-hidden="true">43.</strong> hostid</a></li><li class="chapter-item expanded "><a href="utils/hostname.html"><strong aria-hidden="true">44.</strong> hostname</a></li><li class="chapter-item expanded "><a href="utils/id.html"><strong aria-hidden="true">45.</strong> id</a></li><li class="chapter-item expanded "><a href="utils/install.html"><strong aria-hidden="true">46.</strong> install</a></li><li class="chapter-item expanded "><a href="utils/join.html"><strong aria-hidden="true">47.</strong> join</a></li><li class="chapter-item expanded "><a href="utils/kill.html"><strong aria-hidden="true">48.</strong> kill</a></li><li class="chapter-item expanded "><a href="utils/link.html"><strong aria-hidden="true">49.</strong> link</a></li><li class="chapter-item expanded "><a href="utils/ln.html"><strong aria-hidden="true">50.</strong> ln</a></li><li class="chapter-item expanded "><a href="utils/logname.html"><strong aria-hidden="true">51.</strong> logname</a></li><li class="chapter-item expanded "><a href="utils/ls.html"><strong aria-hidden="true">52.</strong> ls</a></li><li class="chapter-item expanded "><a href="utils/md5sum.html"><strong aria-hidden="true">53.</strong> md5sum</a></li><li class="chapter-item expanded "><a href="utils/mkdir.html"><strong aria-hidden="true">54.</strong> mkdir</a></li><li class="chapter-item expanded "><a href="utils/mkfifo.html"><strong aria-hidden="true">55.</strong> mkfifo</a></li><li class="chapter-item expanded "><a href="utils/mknod.html"><strong aria-hidden="true">56.</strong> mknod</a></li><li class="chapter-item expanded "><a href="utils/mktemp.html"><strong aria-hidden="true">57.</strong> mktemp</a></li><li class="chapter-item expanded "><a href="utils/more.html"><strong aria-hidden="true">58.</strong> more</a></li><li class="chapter-item expanded "><a href="utils/mv.html"><strong aria-hidden="true">59.</strong> mv</a></li><li class="chapter-item expanded "><a href="utils/nice.html"><strong aria-hidden="true">60.</strong> nice</a></li><li class="chapter-item expanded "><a href="utils/nl.html"><strong aria-hidden="true">61.</strong> nl</a></li><li class="chapter-item expanded "><a href="utils/nohup.html"><strong aria-hidden="true">62.</strong> nohup</a></li><li class="chapter-item expanded "><a href="utils/nproc.html"><strong aria-hidden="true">63.</strong> nproc</a></li><li class="chapter-item expanded "><a href="utils/numfmt.html"><strong aria-hidden="true">64.</strong> numfmt</a></li><li class="chapter-item expanded "><a href="utils/od.html"><strong aria-hidden="true">65.</strong> od</a></li><li class="chapter-item expanded "><a href="utils/paste.html"><strong aria-hidden="true">66.</strong> paste</a></li><li class="chapter-item expanded "><a href="utils/pathchk.html"><strong aria-hidden="true">67.</strong> pathchk</a></li><li class="chapter-item expanded "><a href="utils/pinky.html"><strong aria-hidden="true">68.</strong> pinky</a></li><li class="chapter-item expanded "><a href="utils/pr.html"><strong aria-hidden="true">69.</strong> pr</a></li><li class="chapter-item expanded "><a href="utils/printenv.html"><strong aria-hidden="true">70.</strong> printenv</a></li><li class="chapter-item expanded "><a href="utils/printf.html"><strong aria-hidden="true">71.</strong> printf</a></li><li class="chapter-item expanded "><a href="utils/ptx.html"><strong aria-hidden="true">72.</strong> ptx</a></li><li class="chapter-item expanded "><a href="utils/pwd.html"><strong aria-hidden="true">73.</strong> pwd</a></li><li class="chapter-item expanded "><a href="utils/readlink.html"><strong aria-hidden="true">74.</strong> readlink</a></li><li class="chapter-item expanded "><a href="utils/realpath.html"><strong aria-hidden="true">75.</strong> realpath</a></li><li class="chapter-item expanded "><a href="utils/relpath.html"><strong aria-hidden="true">76.</strong> relpath</a></li><li class="chapter-item expanded "><a href="utils/rm.html"><strong aria-hidden="true">77.</strong> rm</a></li><li class="chapter-item expanded "><a href="utils/rmdir.html"><strong aria-hidden="true">78.</strong> rmdir</a></li><li class="chapter-item expanded "><a href="utils/runcon.html"><strong aria-hidden="true">79.</strong> runcon</a></li><li class="chapter-item expanded "><a href="utils/seq.html"><strong aria-hidden="true">80.</strong> seq</a></li><li class="chapter-item expanded "><a href="utils/sha1sum.html"><strong aria-hidden="true">81.</strong> sha1sum</a></li><li class="chapter-item expanded "><a href="utils/sha224sum.html"><strong aria-hidden="true">82.</strong> sha224sum</a></li><li class="chapter-item expanded "><a href="utils/sha256sum.html"><strong aria-hidden="true">83.</strong> sha256sum</a></li><li class="chapter-item expanded "><a href="utils/sha3-224sum.html"><strong aria-hidden="true">84.</strong> sha3-224sum</a></li><li class="chapter-item expanded "><a href="utils/sha3-256sum.html"><strong aria-hidden="true">85.</strong> sha3-256sum</a></li><li class="chapter-item expanded "><a href="utils/sha3-384sum.html"><strong aria-hidden="true">86.</strong> sha3-384sum</a></li><li class="chapter-item expanded "><a href="utils/sha3-512sum.html"><strong aria-hidden="true">87.</strong> sha3-512sum</a></li><li class="chapter-item expanded "><a href="utils/sha384sum.html"><strong aria-hidden="true">88.</strong> sha384sum</a></li><li class="chapter-item expanded "><a href="utils/sha3sum.html"><strong aria-hidden="true">89.</strong> sha3sum</a></li><li class="chapter-item expanded "><a href="utils/sha512sum.html"><strong aria-hidden="true">90.</strong> sha512sum</a></li><li class="chapter-item expanded "><a href="utils/shake128sum.html"><strong aria-hidden="true">91.</strong> shake128sum</a></li><li class="chapter-item expanded "><a href="utils/shake256sum.html"><strong aria-hidden="true">92.</strong> shake256sum</a></li><li class="chapter-item expanded "><a href="utils/shred.html"><strong aria-hidden="true">93.</strong> shred</a></li><li class="chapter-item expanded "><a href="utils/shuf.html"><strong aria-hidden="true">94.</strong> shuf</a></li><li class="chapter-item expanded "><a href="utils/sleep.html"><strong aria-hidden="true">95.</strong> sleep</a></li><li class="chapter-item expanded "><a href="utils/sort.html"><strong aria-hidden="true">96.</strong> sort</a></li><li class="chapter-item expanded "><a href="utils/split.html"><strong aria-hidden="true">97.</strong> split</a></li><li class="chapter-item expanded "><a href="utils/stat.html"><strong aria-hidden="true">98.</strong> stat</a></li><li class="chapter-item expanded "><a href="utils/stdbuf.html"><strong aria-hidden="true">99.</strong> stdbuf</a></li><li class="chapter-item expanded "><a href="utils/stty.html"><strong aria-hidden="true">100.</strong> stty</a></li><li class="chapter-item expanded "><a href="utils/sum.html"><strong aria-hidden="true">101.</strong> sum</a></li><li class="chapter-item expanded "><a href="utils/sync.html"><strong aria-hidden="true">102.</strong> sync</a></li><li class="chapter-item expanded "><a href="utils/tac.html"><strong aria-hidden="true">103.</strong> tac</a></li><li class="chapter-item expanded "><a href="utils/tail.html"><strong aria-hidden="true">104.</strong> tail</a></li><li class="chapter-item expanded "><a href="utils/tee.html"><strong aria-hidden="true">105.</strong> tee</a></li><li class="chapter-item expanded "><a href="utils/test.html"><strong aria-hidden="true">106.</strong> test</a></li><li class="chapter-item expanded "><a href="utils/timeout.html"><strong aria-hidden="true">107.</strong> timeout</a></li><li class="chapter-item expanded "><a href="utils/touch.html"><strong aria-hidden="true">108.</strong> touch</a></li><li class="chapter-item expanded "><a href="utils/tr.html"><strong aria-hidden="true">109.</strong> tr</a></li><li class="chapter-item expanded "><a href="utils/true.html"><strong aria-hidden="true">110.</strong> true</a></li><li class="chapter-item expanded "><a href="utils/truncate.html"><strong aria-hidden="true">111.</strong> truncate</a></li><li class="chapter-item expanded "><a href="utils/tsort.html"><strong aria-hidden="true">112.</strong> tsort</a></li><li class="chapter-item expanded "><a href="utils/tty.html"><strong aria-hidden="true">113.</strong> tty</a></li><li class="chapter-item expanded "><a href="utils/uname.html"><strong aria-hidden="true">114.</strong> uname</a></li><li class="chapter-item expanded "><a href="utils/unexpand.html"><strong aria-hidden="true">115.</strong> unexpand</a></li><li class="chapter-item expanded "><a href="utils/uniq.html"><strong aria-hidden="true">116.</strong> uniq</a></li><li class="chapter-item expanded "><a href="utils/unlink.html"><strong aria-hidden="true">117.</strong> unlink</a></li><li class="chapter-item expanded "><a href="utils/uptime.html"><strong aria-hidden="true">118.</strong> uptime</a></li><li class="chapter-item expanded "><a href="utils/users.html"><strong aria-hidden="true">119.</strong> users</a></li><li class="chapter-item expanded "><a href="utils/vdir.html"><strong aria-hidden="true">120.</strong> vdir</a></li><li class="chapter-item expanded "><a href="utils/wc.html"><strong aria-hidden="true">121.</strong> wc</a></li><li class="chapter-item expanded "><a href="utils/who.html"><strong aria-hidden="true">122.</strong> who</a></li><li class="chapter-item expanded "><a href="utils/whoami.html"><strong aria-hidden="true">123.</strong> whoami</a></li><li class="chapter-item expanded "><a href="utils/yes.html"><strong aria-hidden="true">124.</strong> yes</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">uutils Documentation</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/rust-lang/cargo/tree/master/src/doc/src" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<!-- markdownlint-disable MD041 -->
<!-- spell-checker:ignore reimplementing toybox RUNTEST CARGOFLAGS nextest -->
<h1 id="contributing-to-coreutils"><a class="header" href="#contributing-to-coreutils">Contributing to coreutils</a></h1>
<p>Contributions are very welcome via Pull Requests. If you don't know where to
start, take a look at the
<a href="https://github.com/uutils/coreutils/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22"><code>good-first-issues</code></a>.
If you have any questions, feel free to ask them in the issues or on
<a href="https://discord.gg/wQVJbvJ">Discord</a>.</p>
<h2 id="best-practices"><a class="header" href="#best-practices">Best practices</a></h2>
<ol>
<li>Follow what GNU is doing in terms of options and behavior. It is recommended
to look at the GNU Coreutils manual (<a href="https://www.gnu.org/software/coreutils/manual/html_node/index.html">on the
web</a>, or
locally using <code>info &lt;utility&gt;</code>). It is more in depth than the man pages and
provides a good description of available features and their implementation
details.</li>
<li>If possible, look at the GNU test suite execution in the CI and make the test
work if failing.</li>
<li>Use clap for argument management.</li>
<li>Make sure that the code coverage is covering all of the cases, including
errors.</li>
<li>The code must be clippy-warning-free and rustfmt-compliant.</li>
<li>Don't hesitate to move common functions into uucore if they can be reused by
other binaries.</li>
<li>Unsafe code should be documented with Safety comments.</li>
<li>uutils is original code. It cannot contain code from existing GNU or Unix-like
utilities, nor should it link to or reference GNU libraries.</li>
</ol>
<h2 id="platforms"><a class="header" href="#platforms">Platforms</a></h2>
<p>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 <code>#[cfg(...)]</code> attributes to create platform dependent features.</p>
<p><strong>Tip:</strong> For Windows, Microsoft provides some images (VMWare, Hyper-V,
VirtualBox and Parallels) for development:
<a href="https://developer.microsoft.com/windows/downloads/virtual-machines/">https://developer.microsoft.com/windows/downloads/virtual-machines/</a></p>
<h2 id="tools"><a class="header" href="#tools">Tools</a></h2>
<p>We have an extensive CI that will check your code before it can be merged. This
section explains how to run those checks locally to avoid waiting for the CI.</p>
<h3 id="pre-commit-hooks"><a class="header" href="#pre-commit-hooks">pre-commit hooks</a></h3>
<p>A configuration for <code>pre-commit</code> is provided in the repository. It allows
automatically checking every git commit you make to ensure it compiles, and
passes <code>clippy</code> and <code>rustfmt</code> without warnings.</p>
<p>To use the provided hook:</p>
<ol>
<li><a href="https://pre-commit.com/#install">Install <code>pre-commit</code></a></li>
<li>Run <code>pre-commit install</code> while in the repository directory</li>
</ol>
<p>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 <code>git commit ...</code> again.</p>
<h3 id="clippy"><a class="header" href="#clippy">clippy</a></h3>
<pre><code class="language-shell">cargo clippy --all-targets --all-features
</code></pre>
<p>The <code>msrv</code> key in the clippy configuration file <code>clippy.toml</code> is used to disable
lints pertaining to newer features by specifying the minimum supported Rust
version (MSRV).</p>
<h3 id="rustfmt"><a class="header" href="#rustfmt">rustfmt</a></h3>
<pre><code class="language-shell">cargo fmt --all
</code></pre>
<h3 id="cargo-deny"><a class="header" href="#cargo-deny">cargo-deny</a></h3>
<p>This project uses <a href="https://github.com/EmbarkStudios/cargo-deny/">cargo-deny</a> to
detect duplicate dependencies, checks licenses, etc. To run it locally, first
install it and then run with:</p>
<pre><code>cargo deny --all-features check all
</code></pre>
<h3 id="markdown-linter"><a class="header" href="#markdown-linter">Markdown linter</a></h3>
<p>We use <a href="https://github.com/DavidAnson/markdownlint">markdownlint</a> to lint the
Markdown files in the repository.</p>
<h3 id="spell-checker"><a class="header" href="#spell-checker">Spell checker</a></h3>
<p>We use <code>cspell</code> as spell checker for all files in the project. If you are using
VS Code, you can install the
<a href="https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker">code spell checker</a>
extension to enable spell checking within your editor. Otherwise, you can
install <a href="https://cspell.org/">cspell</a> separately.</p>
<p>If you want to make the spell checker ignore a word, you can add</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>// spell-checker:ignore word_to_ignore
<span class="boring">}</span></code></pre></pre>
<p>at the top of the file.</p>
<h2 id="testing"><a class="header" href="#testing">Testing</a></h2>
<p>Testing can be done using either Cargo or <code>make</code>.</p>
<h3 id="testing-with-cargo"><a class="header" href="#testing-with-cargo">Testing with Cargo</a></h3>
<p>Just like with building, we follow the standard procedure for testing using
Cargo:</p>
<pre><code class="language-shell">cargo test
</code></pre>
<p>By default, <code>cargo test</code> only runs the common programs. To run also platform
specific tests, run:</p>
<pre><code class="language-shell">cargo test --features unix
</code></pre>
<p>If you would prefer to test a select few utilities:</p>
<pre><code class="language-shell">cargo test --features &quot;chmod mv tail&quot; --no-default-features
</code></pre>
<p>If you also want to test the core utilities:</p>
<pre><code class="language-shell">cargo test -p uucore -p coreutils
</code></pre>
<p>Running the complete test suite might take a while. We use <a href="https://nexte.st/index.html">nextest</a> in
the CI and you might want to try it out locally. It can speed up the execution time of the whole
test run significantly if the cpu has multiple cores.</p>
<pre><code class="language-shell">cargo nextest run --features unix --no-fail-fast
</code></pre>
<p>To debug:</p>
<pre><code class="language-shell">gdb --args target/debug/coreutils ls
(gdb) b ls.rs:79
(gdb) run
</code></pre>
<h3 id="testing-with-gnu-make"><a class="header" href="#testing-with-gnu-make">Testing with GNU Make</a></h3>
<p>To simply test all available utilities:</p>
<pre><code class="language-shell">make test
</code></pre>
<p>To test all but a few of the available utilities:</p>
<pre><code class="language-shell">make SKIP_UTILS='UTILITY_1 UTILITY_2' test
</code></pre>
<p>To test only a few of the available utilities:</p>
<pre><code class="language-shell">make UTILS='UTILITY_1 UTILITY_2' test
</code></pre>
<p>To include tests for unimplemented behavior:</p>
<pre><code class="language-shell">make UTILS='UTILITY_1 UTILITY_2' SPEC=y test
</code></pre>
<p>To run tests with <code>nextest</code> just use the nextest target. Note you'll need to
<a href="https://nexte.st/book/installation.html">install</a> <code>nextest</code> first. The <code>nextest</code> target accepts the
same arguments like the default <code>test</code> target, so it's possible to pass arguments to <code>nextest run</code>
via <code>CARGOFLAGS</code>:</p>
<pre><code class="language-shell">make CARGOFLAGS='--no-fail-fast' UTILS='UTILITY_1 UTILITY_2' nextest
</code></pre>
<h3 id="run-busybox-tests"><a class="header" href="#run-busybox-tests">Run Busybox Tests</a></h3>
<p>This testing functionality is only available on *nix operating systems and
requires <code>make</code>.</p>
<p>To run busybox tests for all utilities for which busybox has tests</p>
<pre><code class="language-shell">make busytest
</code></pre>
<p>To run busybox tests for a few of the available utilities</p>
<pre><code class="language-shell">make UTILS='UTILITY_1 UTILITY_2' busytest
</code></pre>
<p>To pass an argument like &quot;-v&quot; to the busybox test runtime</p>
<pre><code class="language-shell">make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest
</code></pre>
<h3 id="comparing-with-gnu"><a class="header" href="#comparing-with-gnu">Comparing with GNU</a></h3>
<p>To run uutils against the GNU test suite locally, run the following commands:</p>
<pre><code class="language-shell">bash util/build-gnu.sh
# Build uutils without release optimizations
UU_MAKE_PROFILE=debug 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
# To run several tests:
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
</code></pre>
<p>Note that it relies on individual utilities (not the multicall binary).</p>
<h3 id="improving-the-gnu-compatibility"><a class="header" href="#improving-the-gnu-compatibility">Improving the GNU compatibility</a></h3>
<p>The Python script <code>./util/remaining-gnu-error.py</code> shows the list of failing
tests in the CI.</p>
<p>To improve the GNU compatibility, the following process is recommended:</p>
<ol>
<li>Identify a test (the smaller, the better) on a program that you understand or
is easy to understand. You can use the <code>./util/remaining-gnu-error.py</code> script
to help with this decision.</li>
<li>Build both the GNU and Rust coreutils using: <code>bash util/build-gnu.sh</code></li>
<li>Run the test with <code>bash util/run-gnu-test.sh &lt;your test&gt;</code></li>
<li>Start to modify <code>&lt;your test&gt;</code> to understand what is wrong. Examples:
<ol>
<li>Add <code>set -v</code> to have the bash verbose mode</li>
<li>Add <code>echo $?</code> where needed</li>
<li>When the variable <code>fail</code> is used in the test, <code>echo $fail</code> to see when the
test started to fail</li>
<li>Bump the content of the output (ex: <code>cat err</code>)</li>
<li>...</li>
</ol>
</li>
<li>Or, if the test is simple, extract the relevant information to create a new
test case running both GNU &amp; Rust implementation</li>
<li>Start to modify the Rust implementation to match the expected behavior</li>
<li>Add a test to make sure that we don't regress (our test suite is super quick)</li>
</ol>
<h2 id="commit-messages"><a class="header" href="#commit-messages">Commit messages</a></h2>
<p>To help the project maintainers review pull requests from contributors across
numerous utilities, the team has settled on conventions for commit messages.</p>
<p>From <a href="https://git-scm.com/book/ch5-2.html">https://git-scm.com/book/ch5-2.html</a>:</p>
<pre><code>Capitalized, short (50 chars or less) summary
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase will confuse you if you run the
two together.
Write your commit message in the imperative: &quot;Fix bug&quot; and not &quot;Fixed bug&quot;
or &quot;Fixes bug.&quot; This convention matches up with commit messages generated
by commands like git merge and git revert.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, followed by a
single space, with blank lines in between, but conventions vary here
- Use a hanging indent
</code></pre>
<p>Furthermore, here are a few examples for a summary line:</p>
<ul>
<li>commit for a single utility</li>
</ul>
<pre><code>nohup: cleanup and refactor
</code></pre>
<ul>
<li>commit for a utility's tests</li>
</ul>
<pre><code>tests/rm: test new feature
</code></pre>
<p>Beyond changes to an individual utility or its tests, other summary
lines for non-utility modules include:</p>
<pre><code>README: add help
</code></pre>
<pre><code>uucore: add new modules
</code></pre>
<pre><code>uutils: add new utility
</code></pre>
<pre><code>gitignore: add temporary files
</code></pre>
<h2 id="code-coverage"><a class="header" href="#code-coverage">Code coverage</a></h2>
<!-- spell-checker:ignore (flags) Ccodegen Coverflow Cpanic Zinstrument Zpanic -->
<p>Code coverage report can be generated using <a href="https://github.com/mozilla/grcov">grcov</a>.</p>
<h3 id="using-nightly-rust"><a class="header" href="#using-nightly-rust">Using Nightly Rust</a></h3>
<p>To generate <a href="https://github.com/mozilla/grcov#example-how-to-generate-gcda-files-for-a-rust-project">gcov-based</a> coverage report</p>
<pre><code class="language-shell">export CARGO_INCREMENTAL=0
export RUSTFLAGS=&quot;-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort&quot;
export RUSTDOCFLAGS=&quot;-Cpanic=abort&quot;
cargo build &lt;options...&gt; # e.g., --features feat_os_unix
cargo test &lt;options...&gt; # 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 &quot;^\s*((debug_)?assert(_eq|_ne)?\#\[derive\()&quot; -o ./target/debug/coverage/
# open target/debug/coverage/index.html in browser
</code></pre>
<p>if changes are not reflected in the report then run <code>cargo clean</code> and run the above commands.</p>
<h3 id="using-stable-rust"><a class="header" href="#using-stable-rust">Using Stable Rust</a></h3>
<p>If you are using stable version of Rust that doesn't enable code coverage instrumentation by default
then add <code>-Z-Zinstrument-coverage</code> flag to <code>RUSTFLAGS</code> env variable specified above.</p>
<h2 id="other-implementations"><a class="header" href="#other-implementations">Other implementations</a></h2>
<p>The Coreutils have different implementations, with different levels of completions:</p>
<ul>
<li><a href="https://git.savannah.gnu.org/gitweb/?p=coreutils.git">GNU's</a></li>
<li><a href="https://github.com/openbsd/src/tree/master/bin">OpenBSD</a></li>
<li><a href="https://github.com/mirror/busybox/tree/master/coreutils">Busybox</a></li>
<li><a href="https://github.com/landley/toybox/tree/master/toys/posix">Toybox (Android)</a></li>
<li><a href="https://github.com/vlang/coreutils">V lang</a></li>
<li><a href="https://github.com/SerenityOS/serenity/tree/master/Userland/Utilities">SerenityOS</a></li>
<li><a href="https://github.com/dspinellis/unix-history-repo">Initial Unix</a></li>
</ul>
<p>However, when reimplementing the tools/options in Rust, don't read their source codes
when they are using reciprocal licenses (ex: GNU GPL, GNU LGPL, etc).</p>
<h2 id="licensing"><a class="header" href="#licensing">Licensing</a></h2>
<p>uutils is distributed under the terms of the MIT License; see the <code>LICENSE</code> file
for details. This is a permissive license, which allows the software to be used
with few restrictions.</p>
<p>Copyrights in the uutils project are retained by their contributors, and no
copyright assignment is required to contribute.</p>
<p>If you wish to add or change dependencies as part of a contribution to the
project, a tool like <code>cargo-license</code> can be used to show their license details.
The following types of license are acceptable:</p>
<ul>
<li>MIT License</li>
<li>Dual- or tri-license with an MIT License option (&quot;Apache-2.0 or MIT&quot; is a
popular combination)</li>
<li>&quot;MIT equivalent&quot; license (2-clause BSD, 3-clause BSD, ISC)</li>
<li>License less restrictive than the MIT License (CC0 1.0 Universal)</li>
<li>Apache License version 2.0</li>
</ul>
<p>Licenses we will not use:</p>
<ul>
<li>An ambiguous license, or no license</li>
<li>Strongly reciprocal licenses (GNU GPL, GNU LGPL)</li>
</ul>
<p>If you wish to add a reference but it doesn't meet these requirements, please
raise an issue to describe the dependency.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="build.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="test_coverage.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="build.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="test_coverage.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js"></script>
<script src="mark.min.js"></script>
<script src="searcher.js"></script>
<script src="clipboard.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink