logo

utils-std

Collection of commonly available Unix tools git clone https://anongit.hacktivis.me/git/utils-std.git/

README.md (5062B)

    

  1. # utils-std: Collection of commonly available Unix tools
  2. <!--
  3. Licensing of README file:
  4. Copyright 2017 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
  5. SPDX-License-Identifier: MPL-2.0
  6. -->
  8. Project homepage: <https://hacktivis.me/projects/utils-std>
  10. This is my own collection of commonly available Unix utilities, most of them implemented by me.
  11. POSIX is used as a guide, but current Unix systems are the biggest inspiration and compatibility with portable scripts is intended.
  13. Developed on Linux+musl, automatically tested on FreeBSD, NetBSD and ArchLinux thanks to [SourceHut](https://builds.sr.ht/~lanodan/utils-std).
  15. ## Dependencies
  16. - C99 Compiler + POSIX.1-2017 C Library (POSIX.1-2024 recommended)
  17. - POSIX yacc(1) implementation
  18. - POSIX Shell
  19. - POSIX.1-2024 Make
  20. - POSIX m4 utility
  21. - (optional, test) [prysk](https://www.prysk.net/) (or [cram](https://bitheap.org/cram/) but it got abandoned)
  22. - (optional, lint) mandoc: <https://mdocml.bsd.lv/> For linting the manual pages
  24. For bootstrapping reasons, this list should not get any bigger.
  25. For example utilities depending on a library must be split, and dependencies on other utilities shall be kept to a minimum.
  27. ## Packaging
  28. - The `./configure` script isn't auto*hell based, you can pass it arguments via key-value arguments or environment variables
  29. - You can define the `NO_BWRAP` environment variable to skip the bwrap-based tests which can cause issues in some environments like Gentoo `sandbox`
  30. - If you want statically linked executables, pass `LDSTATIC=-static` to configure (environment or argument)
  31. - `make -f bootstrap.mk` will compile the few utilities used by `./configure` for you
  33. ## Cross-compiling
  34. Set the `CC` and `CFLAGS` environment variables for your target, the usual `CROSS_COMPILE` is also supported as a fallback.  
  35. To compile the test binaries without running them, run `make build-checks`
  37. ## Building
  38. 0. (Optional, for when you don't already have utilities on the host): ``make -f bootstrap.mk && export PATH=$PWD/cmd:$PATH``
  39. 1. ``sh ./configure``
  40. 2. ``make``
  41. 3. (optional, runs the tests) ``make check``
  42. 4. (supports DESTDIR) ``make install``
  44. ## Licensing
  46. The default license for new original works is the `MPL-2.0`, except when they should be broadly distributed and proprietary extensions aren't a concern (so `BSD-3-Clause`), or are considered under the copyright threshold (so `0BSD`).
  48. When works are imported from other codebases they should be either under a permissive license or `MPL-2.0` and their licensing is kept to allow the original authors to use modifications made if any (copyleft in spirit).
  50. ## Design differences
  51. - Whenever possible programs prefix their messages with their name. This way you don't end up with context-less messages.
  52. - Error messages contain "error:", warning messages contain "warning:". To allow to easily find what went wrong in logs.
  53. - When the output is structured data, a terminal gets human-oriented output, others like piped programs get machine-oriented output (no padding, line separation, CSV, JSON, …). Prior art: most `ls(1)` implementations, i3/sway, FreeBSD utils via `libxo`, …
  54. - As the `utmp` and `wtmp` files are considered broken by design, utilities dependent on them like `who` and `lastlog` won't be implemented. Proper authentication logs shouldn't be writable into by multiple programs, some of them third-party (like SSH and Display Managers typically are).
  55. - Minimal dependencies, allowing to bootstrap utils-std with barely having unix utilities.
  56. - No binary blobs, even in the testsuite. Output of generated code is itself auditable.
  58. ### Difference with coreutils
  60. Much more straightforward code. Similarly to glibc, coreutils codebase often has it's actual code hidden under layers of macros and wrapper functions.
  62. ### Difference with BusyBox/ToyBox
  63. Instead of minimalism as a constraint, here it is seen as a virtue of good design and as such as a process/long-term-goal.
  64. But being a near drop-in replacement is utils-std reason for existing.
  66. Also Toybox is stuck with reimplementing everything free of copyright issues due to it's choice of 0BSD.  
  67. utils-std default license is the MPL-2.0 to be able to take code and design back without legal issues, but also is able to take code from other implementations.
  69. ## Goals
  70. - (long-run) Effectively serve as one of the blocks to get base utilities, replacing GNU coreutils and part of BusyBox/ToyBox
  71. - Code readability and hackability
  72. - Portability, should run on modern libre POSIX systems as to not introduce vendor-locking
  73. - Efficiency, but not without sacrificing the other goals
  75. ## Non-Goals
  76. - Reimplementing complex utilities that are typically maintained separately (such as sh, awk, yacc, tar/pax, …)
  77. - Implementing utilities which aren't in your usual base system. This is covered by [utils-extra](https://hacktivis.me/git/utils-extra), and I'd also recommend checking out [moreutils](https://joeyh.name/code/moreutils/)
  78. - Reimplementing OS-specific utilities like [util-linux](https://www.kernel.org/pub/linux/utils/util-linux/)