Extend README

This commit is contained in:
Nathan Fisher 2024-04-17 14:05:03 -04:00
parent e6d1ce57f1
commit cc3c43bf43

View file

@ -1,6 +1,7 @@
Contents
========
- [Rationale](#rationale)
- [Requirements](#requirements)
- [Usage](#usage)
- [Writing Tests](#writing_tests)
@ -11,12 +12,29 @@ as well as the use of simple tools. As such, the **Roadrunner** test runner cons
of a test runner written in a single file of highly portable C, totaling 43 lines,
and a simple, POSIX compatible Makefile which works with both GNU and BSD make.
Most "modern" programming languages have a built in testing framework and this is
often a selling point, as **C** just leaves it to the programmer to pick from the
thousands of different ways to not only build but also test their code, or roll
their own. In this guy's opinion, 99.99% of all modern build systems are overkill
and the vast majority actually introduce corner cases and bugs into the process,
making things like cross compilation a *serious* PITA. If you stick with **make**,
without any wrappers around it, you can pretty easily build even complex software
in a way that doesn't require 15k line configure scripts, keeping up to date with
changes in Python (WTF, why use *Python* to build *C*?) and that will be friendly
to cross compilation. This simplistic test harness is a natural outgrowth of that
mental model of building software (at least for software written in C or Fortran).
The original version of this project was written entirely in POSIX make, but due to
the variations in POSIX shell behavior, especially in regards to the variety of ways
that both the built in *echo* command and */bin/echo* screw up sending terminal escape
sequences, something more robust and portable was desirable. There were simply too
many corner cases to be bothered to find them all.
## Requirements
- a functional C compiler
- a **POSIX** compatible *make* program (GNU and BSD make are both fine)
- your code built as a static library
## Usage
The best way to use this is to stuff it into a `test` subdirectory and call it via
`make -C test`, or invoke it from your project's `Makefile` as a sub-make. If you
@ -41,6 +59,11 @@ Your library will have to be built as a static library and statically linked to
test program. All you have to do (after building the static library) is add it to
the `$(LDLIBS)` array in the Makefile.
### Cross compilation
It would be entirely *possible* to extend this harness to work for cross compilation,
substituting `$(HOSTCC)` for `$(CC)` when building *runner.c* and calling qemu in
user mode to run the binary tests. However, this is out of scope for **Roadrunner**.
## Writing Tests
### Return values
The return values for each test shouuld follow these conventions.