README.md

   1 # pp (prepend)
   2
   3 The **pp** (prepend) utility takes the content of the file named by the *source* operand and inserts or prepends it
   4 above the first line of the file named by the *target* operand. The file operands are processed in command-line order.
   5 If the *source* file is a single dash ('-') or absent, **pp** reads from the standard input.
   6
   7 So, essentially, if I have a CSV file without a header and I want to quickly insert the header from a file, I
   8 would run:
   9
  10 ```
  11  pp header.txt spreadsheet.csv
  12 ```
  13
  14 and it would be functionally equivalent to
  15
  16 ```
  17 cat header.txt spreadsheet.csv > temp
  18 mv temp spreadsheet.csv
  19 ```
  20
  21 ## Features
  22 * Quality
  23     * Compiled with security hardening flags
  24     * Static analysis integrated using clang's `scan-build` using checkers `alpha.security`, `alpha.core.CastSize`,
  25     `alpha.core.CastToStruct`, `alpha.core.IdenticalExpr`, `alpha.core.PointerArithm`, `alpha.core.PointerSub`,
  26     `alpha.core.SizeofPtr`, `alpha.core.TestAfterDivZero`, `alpha.unix`
  27     * Test harness
  28     * Fuzzing using clang's `libFuzzer`
  29     * Follows [FreeBSD coding style](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9)
  30 * Portable
  31     * C99 compliant
  32     * Self-contained, no external dependencies
  33     * Easy to compile (needs clang >= 11.0) and uses POSIX make
  34
  35 ## Build dependencies
  36 The only dependency is the toolchain needed to build the program using the Makefile, which is `clang` >= 11.0. That's
  37 because the security flags used to build the executable are specific to clang.
  38
  39 If you want to build it with GCC and have equivalent security flags you can change the `CFLAGS` and `LDFLAGS` to the
  40 following
  41
  42 ```
  43 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic \
  44     -Wformat=2 -Wformat-overflow=2 -Wformat-truncation=2 -Wformat-security \
  45     -Wnull-dereference -Wstack-protector -Wtrampolines -Walloca -Wvla \
  46     -Warray-bounds=2 -Wimplicit-fallthrough=3 -Wtraditional-conversion \
  47     -Wshift-overflow=2 -Wcast-qual -Wstringop-overflow=4 -Wconversion \
  48     -Warith-conversion -Wlogical-op -Wduplicated-cond -Wduplicated-branches \
  49     -Wformat-signedness -Wshadow -Wstrict-overflow=4 -Wundef \
  50     -Wstrict-prototypes -Wswitch-default -Wswitch-enum -Wstack-usage=1000000 \
  51     -Wcast-align=strict \
  52     -D_FORTIFY_SOURCE=2 \
  53     -fstack-protector-strong -fstack-clash-protection -fPIE
  54
  55 LDFLAGS = -Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack \
  56     -Wl,-z,separate-code
  57 ```
  58
  59 ## Installation
  60 Clone this repository then
  61
  62 ```sh
  63 $ make PREFIX=/usr install
  64 ```
  65
  66 This will install the compiled binary under `PREFIX` (`/usr/bin`) in this case, if not specified `PREFIX` will default
  67 to `/usr/local`. For staged installs, `DESTDIR` is also supported. As the binary does not have any dependency it does
  68 not have to be installed before use.
  69
  70 ## Usage
  71
  72 ## Compilation
  73 In order to build on any Unix-like system, simply run `make`. Since the binary does not have any dependencies, it can
  74 just be copied into your `PATH`.