Add readme for shmk

1 files changed, 121 insertions, 0 deletions

diff --git a/src/util/shmk.README b/src/util/shmk.README
new file mode 100644
index 0000000..a359fbc
--- /dev/null
+++ b/src/util/shmk.README
@@ -0,0 +1,121 @@
+# shmk
+
+shmk is a simple utility to build complicated shell projects
+
+## Usage
+
+### single file
+
+shmk can be invoked on a single sh file to "build" it:
+
+```sh
+$ shmk myprog.sh file_output.sh
+```
+
+### in a wider project
+
+shmk can also serve as a "make" tool, building libraries and executables, running tests (checks) and installing your project to a path.
+
+see [shmk project](#shmk project) for more info
+
+## Directives
+
+Shmk will take each file and parse it before making an output. Most of the file will remain unchanged, however some directives will be parsed:
+
+
+### `#include file`
+
+Will include a file 'in place'. Will not include a file more than once within the output
+
+The first file with the given name will be used. The search path by default follows this order:
+
+```
+./
+$DIST/
+/usr/lib/
+/usr/local/lib/
+/usr/share/shmk/
+```
+
+Using the `-I` option will prepend a file to this list. If no `.sh` extension is given, both the `filenanme` and the `filename.sh` will be checked
+
+# shmk project
+
+A shmk project is typically built using a `build.shmk` file
+
+An example build shmk file could like this (chek this project's shmk file for more examples):
+
+```sh
+#!/usr/bin/env shmk
+
+LIBS="
+    src/lib/mylibrary.sh
+    src/lib/second_library.sh
+"
+
+PROGS="
+    src/myutil.sh
+"
+
+CHECKS="
+    tests/test_myutil.sh
+"
+```
+
+By making this file executable, shmk will be invoked via its shebang and it will parse this file as a project fille.
+
+The difference between a lib and a prog (library and program) is functionally only in where the files get installed. Programs should be intsalled to a `bin/` directory and are inteded to be run directly. Libraries, even though they are functionally shell programs, are intended to be included by other shell programs and provide variables and functions that are to be used.
+
+## stages
+
+When shmk builds a project, it is able to execute the following steps: (by default in the given order)
+
+- **clean**
+    - cleans the project files
+    - removes outputted files, executables etc
+- **build**
+    - builds all libraries and programs using shmk 
+- **check**
+    - run all the available tests
+- **install**
+    - install binaries and libraries
+    - by default will install progs to `/usr/local/bin/` and libraries to `/usr/local/lib/`
+    - `/usr/local/` can be changed using the env var `$PREFIX`
+    - instead of installing to system, package maintainers may use `$DESTDIR` to choose where to install shmk
+- **uninstall**
+    - this stage is not run by default
+    - opposite of install, will follow the same install path and remove any libraries or programs it would have installed
+
+## custom build stages
+
+If desired, a custom build stage can be created:
+
+```sh
+
+prog_mycprog () {
+    gcc -o ${DIST}/myprog src/myprog.c
+}
+
+```
+
+Any function prefixed with `prog_` or `lib_` will be treated as an extra program or library to be built, and said function will be run after handling all of the files mentioned in `LIBS` and `PROGS` variables. This will not override anything from these lists.
+These 
+
+As per the example, this can be useful for incorporating non-shmk build stages. As shmk is interpreted like a normal shell file, the syntax should be the same as a shell allowing for extensible configuration of build stages.
+
+The prefix `check_` can also be used for custom check stages. These will not override the exsiting checks
+
+### Checks and tests
+
+A test in shmk is called a `check` (since test is already a shell command). The testing framework is rather rudimentary, and currenty can only be used with custom `check_` prefixed fucntions in the shmk build. Alternatively binaries from the `$CHECKS` variable will also be run. These are not to be confused with other build stages where the programs are never executed themselves: checks are run as-is.
+
+Checks are run consecutively until either all checks reutrn 0 (success) or a single check returns 1.
+
+This feature is intended to be used with the `shtests` tool.
+
+
+## Syntax and formatting
+
+shmk is intended to be as portable as possible, following exclusively POSIX shell syntax. This means that unlike in bash or csh, there is no formal structure for lists, instead whitespace separated strings are used. New lines or spaces both work, however for the sake of simplicity, newlines are prefered. The "standard" shmk syntax for a list is as follows
+
+`