README.md

   1 # Cursed Utils
   2 A collection of **cursed** core tools for a POSIX-compatible operating system.
   3
   4 ## Goal
   5 The goal of the project is to provide cursed/corrupted versions of the POSIX.1 core tools and utilities. This project
   6 is meant as a joke and *should not* be used in production.
   7
   8 ## Features
   9 * Quality
  10     * Compiled with security hardening flags.
  11     * Static analysis integrated using clang's `scan-build` using checkers `alpha.security`, `alpha.core.CastSize`,
  12     `alpha.core.CastToStruct`, `alpha.core.IdenticalExpr`, `alpha.core.PointerArithm`, `alpha.core.PointerSub`,
  13     `alpha.core.SizeofPtr`, `alpha.core.TestAfterDivZero`, `alpha.unix`.
  14     * Test harness
  15     * Follows [FreeBSD coding style](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9).
  16 * Portable
  17     * C99 compliant *and* may be built in an environment which provides POSIX.1-2008 system interfaces.
  18     * Self-contained, no external dependencies.
  19     * Easy to compile and uses POSIX make.
  20
  21 ## Limitations
  22
  23 ## Build dependencies
  24 The only dependency is a toolchain supporting the following flags:
  25
  26 ```
  27 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic \
  28         -Walloca -Wcast-qual -Wconversion -Wformat=2 -Wformat-security \
  29         -Wnull-dereference -Wstack-protector -Wvla -Warray-bounds \
  30         -Wbad-function-cast -Wconversion -Wshadow -Wstrict-overflow=4 -Wundef \
  31         -Wstrict-prototypes -Wswitch-default -Wfloat-equal -Wimplicit-fallthrough \
  32         -Wpointer-arith -Wswitch-enum \
  33         -D_FORTIFY_SOURCE=2 \
  34         -fstack-protector-strong -fPIE -fstack-clash-protection
  35
  36 LDFLAGS = -Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack -Wl,-z,separate-code
  37 ```
  38
  39 Otherwise you can just remove the security flags and compile it with
  40 ```
  41 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic
  42 LDFLAGS =
  43 ```
  44
  45 or pass your own flags to make
  46 ```sh
  47 make CC=gcc CFLAGS=... LDFLAGS=...
  48 ```
  49
  50 ## Compilation
  51 Each tool can be compiled individually with the following:
  52 ```sh
  53 cd src/$tool
  54 make
  55 ```
  56 Alternatively, you can compile all of the tools from the top level directory with:
  57 ```sh
  58 make
  59 ```
  60
  61 ## Installation
  62 Clone this repository then
  63
  64 ```sh
  65 $ make PREFIX=/usr install
  66 ```
  67
  68 This will install the compiled binary under `PREFIX` (`/usr/bin`) in this case, if not specified `PREFIX` will default
  69 to `/usr/local`. For staged installs, `DESTDIR` is also supported. As the binary does not have any dependency it does
  70 not have to be installed before use.
  71
  72 ### Test suite
  73 The test suite consists of a POSIX shell script called `harness.sh` contained in the `test` folder. It's output is
  74 similar to [googletest](https://github.com/google/googletest)'s and it can be invoked with `make test` which, if
  75 everything is working should output something similar to
  76 ```
  77 (cd test && ./harness.sh)
  78 [----------] Test environment set-up.
  79 [==========] Running 2 test cases.
  80 [ RUN      ] false_should_return_zero
  81 [       OK ] false_should_return_zero
  82 [ RUN      ] true_should_return_nonzero
  83 [       OK ] true_should_return_nonzero
  84 [==========] 2 test cases ran.
  85 [  PASSED  ] 2 tests.
  86 [  FAILED  ] 0 tests.
  87 [----------] Test environment teardown.
  88 ```
  89
  90 ### Static analysis
  91 Static analysis on the code base is done by using clang's static analyzer run through `scan-build.sh` which wraps the
  92 `scan-build` utility. The checkers used are part of the
  93 [Experimental Checkers](https://releases.llvm.org/12.0.0/tools/clang/docs/analyzer/checkers.html#alpha-checkers)
  94 (aka *alpha* checkers):
  95
  96 * `alpha.security`
  97 * `alpha.core.CastSize`
  98 * `alpha.core.CastToStruct`
  99 * `alpha.core.IdenticalExpr`
 100 * `alpha.core.PointerArithm`
 101 * `alpha.core.PointerSub`
 102 * `alpha.core.SizeofPtr`
 103 * `alpha.core.TestAfterDivZero`
 104 * `alpha.unix`
 105
 106 ## Scope
 107 **cursedutils** contains some of the POSIX.1-2017 base utilities, but does not support any POSIX.1-2017
 108 [option groups](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap02.html#tag_02_01_06_02). The utilities
 109 are not POSIX.1-2017 conformant nor compliant since they (obviously) don't follow the specification. However, when
 110 applicable, the utilities will try to adhere to the standard.
 111
 112 ## Contributing
 113 Send patches on the [mailing list](https://www.freelists.org/list/cursedutils-dev), report bugs using [git-bug](https://github.com/MichaelMure/git-bug).
 114
 115 ## License
 116 BSD 2-Clause FreeBSD License, see LICENSE.