Skip to content

Latest commit

 

History

History
250 lines (203 loc) · 6.74 KB

README.md

File metadata and controls

250 lines (203 loc) · 6.74 KB
Raw

posixutils-rs

This is a suite of Rust-native core command line utilities (cp, mv, awk, make, vi, ...) using POSIX.2024 as the baseline specification.

Goals

The goal is to create clean, race-free userland utilities that are POSIX compliant, maximizing compatibility with existing shell scripts while minimizing bloat.

Implementation goals include clean, safe Rust code and maximal use of small Rust community crates. This project's utilities should "look like normal Rust programs."

Core POSIX specification: https://pubs.opengroup.org/onlinepubs/9699919799/ (Old, free edition. POSIX.2024 was just released.)

WANTED: Volunteers!

Contributions are welcome. Developers and non-developers alike, please read CONTRIBUTING for details, and WANTED for recommended coding tasks for newcomers.

Non-goals

It is not a goal to be compatible with GNU utilities, which are sometimes viewed as bloated and overloaded with rarely-used options.

Popular GNU options will be supported by virtue of the "don't break scripts" rule. Unpopular options will not be implemented, to prevent bloat.

Similar projects

A similar project from the author, written in C++, is https://github.com/jgarzik/posixutils

A project with more narrow scope, with the aim of GNU coreutils compatibility, is uutils: https://github.com/uutils/coreutils

Because it is a FAQ, the major differences between this project and uutils are:

  1. Wider scope: posixutils is far more ambitious than uutils from a breadth standpoint: posixutils will include bc, m4, c99 compiler, a cron daemon etc. uutils is far more limited in the scope of programs covered, mimicing GNU coreutils.
  2. More minimalist: Each posixutils utility implementation is intentionally more minimalist, intending to avoid the bloat of supporting rarely-used, non-POSIX features. Our common denominator and baseline is the POSIX spec, then add non-POSIX features that users cannot live without.
  3. Transportable: Each posixutils utility should look like normal Rust code, easily stand alone with little-or-no deps, and be used in another project. This project is MIT-licensed, not GPL licensed, to aid in that transportability goal.

Utility status

Stage 6 - Audited

(none)

Stage 5 - Fully Translated to 2+ languages

(none)

Stage 4 - Code coverage

(none)

Stage 3 - Test coverage

  • ar (Development)
  • awk
  • basename
  • bc
  • cksum
  • cmp
  • comm
  • compress (compress cat.)
  • cp
  • csplit
  • cut
  • diff
  • dirname
  • expand
  • expr
  • false
  • file
  • find
  • fold
  • fuser
  • gencat (i18n)
  • grep
  • head
  • iconv (i18n)
  • join
  • link
  • ls
  • make
  • m4
  • mkdir
  • mv
  • nl
  • nm (Development)
  • od
  • paste
  • pr
  • readlink
  • realpath
  • rm
  • rmdir
  • sort
  • split
  • strings
  • strip (Development)
  • tail
  • time
  • timeout
  • tr
  • true
  • uncompress (compress cat.)
  • uudecode (uue)
  • uuencode (uue)
  • unexpand
  • uniq
  • unlink
  • wc
  • what (SCCS)
  • zcat (compress cat.)

Stage 2 - Feature-complete and POSIX compliant

  • cat
  • chgrp
  • chmod
  • chown
  • date
  • env
  • ipcrm (IPC)
  • ln
  • logname
  • mesg
  • mkfifo
  • newgrp
  • nice
  • nohup
  • pathchk
  • pwd
  • renice
  • sleep
  • talk
  • tee
  • touch
  • tty
  • uname
  • write

Stage 1 - Rough draft

  • asa
  • cal
  • df
  • du
  • echo
  • dd
  • getconf
  • id
  • ipcs (IPC)
  • kill
  • logger
  • printf
  • ps
  • stty
  • tabs
  • test
  • tput
  • tsort
  • who
  • xargs

Stage 0 - Not started

Cron category

  • at (cron cat.)
  • batch (cron cat.)
  • crontab (cron cat.)

Development category

SCCS category

  • admin (SCCS)
  • delta (SCCS)
  • get (SCCS)
  • prs (SCCS)
  • rmdel (SCCS)
  • sact (SCCS)
  • sccs (SCCS)
  • unget (SCCS)
  • val (SCCS)

i18n category

  • gettext (i18n)
  • locale (i18n) -- status: in progress
  • localedef (i18n)
  • msgfmt (i18n)
  • ngettext (i18n)
  • xgettext (i18n) -- status: in progress

UUCP category

  • uucp (UUCP)
  • uustat (UUCP)
  • uux (UUCP)

Editors category

Misc. category

  • lp
  • mailx
  • man (status: in progress)
  • more
  • patch (status: in progress)
  • pax
  • sed
  • sh (status: in progress)

Installation

These are "core" utilities of any operating system. Production packaging in the future will be done on a per-distro basis in a distro-specific way.

As such, Dockerfiles, rpm and deb packaging are welcome, but currently considered a secondary priority to finishing, bugfixing and tuning the utilities. Packaging contributions are welcome... if done right.

The standard cargo install should work, for those interested in testing. Care should be taken with PATH to point to the correct cp or awk, when mixing with standard system utilities on an already-shipped operating system.

Testing

A few tests require additional setup such as a case-insensitive filesystem or the use of another command like script. They are locked under the posixutils_test_all feature flag to exclude them from GitHub CI. These tests can be run by passing the feature flag to cargo:

cargo test --release --features posixutils_test_all

A further subset of posixutils_test_all tests are marked as requires_root. Running as root would override Unix permissions and thus give false failures on tests where such permissions are expected to be upheld so it is recommended to run these tests individually. There are currently 4 such tests:

  • test_cp_special_bits
  • test_mv_sticky_to_xpart
  • test_rm_fail_2eperm
  • test_rm_no_give_up
sudo -E cargo test --release --features posixutils_test_all,requires_root <test_name>

Integration tests may generate test data under CARGO_TARGET_TMPDIR (usually resolves to target/tmp) and /dev/shm (Linux only).