From cc3c43bf433cfabc330e1ff90c6051afc9e13b2d Mon Sep 17 00:00:00 2001 From: Nathan Fisher Date: Wed, 17 Apr 2024 14:05:03 -0400 Subject: [PATCH] Extend README --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index 2b253f9..9bd59a5 100644 --- a/README.md +++ b/README.md @@ -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.