wip: large changes

t/README-dev.x

@@ -0,0 +1,113 @@
+Format_Index: y, a
+This README.dev file describes the development environment.
+
+  Copyright (C) %d %s.
+
+  Copying and distribution of this file, with or without modification,
+  are permitted in any medium without royalty provided the copyright
+  notice and this notice are preserved.
+
+Notice
+------
+
+This documentation is standard across all GCK package and is not specified per
+package; however, this is the defacto standard for most packages. The only
+place where this commonly differs is in non-binary or library packages.
+
+
+Build system
+------------
+
+This distribution uses a GNU autotools-like build system. This is made up of a
+configure script, and a Makefile. The configure script detects a C23 compiler
+on the system and sets any program flags: debug, release, custom. The Makefile
+builds the binary based on the output [config.mak] of the configure script.
+
+
+Building
+--------
+
+To build this distribution you first must run the configure script. This
+outputs a config.mak file that will be used in the Make step. Then run make;
+this builds the objects into build/ and the binary into bin/.
+
+
+Configuration
+-------------
+
+The configuration script is used to generate a build intermediate step called
+the config.mak. This file is used by the Makefile to figure out C compiler to
+use, what CFLAGS and LDFLAGS to use, and where to install the binary if
+requested. By default these values are gcc, the release flag set, and
+/usr/local/. The configuration script supports the following flags that control
+CFLAGS: --enable-debug and CFLAGS="". By default, the script uses flags for a release
+build. Debug is for in-development programming and is the strictest when it
+comes to warnings and other compiler output. CFLAGS="" is for custom flag
+definition. For the development environment is it recommended to use the
+--debug flag. Some examples of how you can run the configure script:
+
+For default behavior:
+
+  ./configure
+
+For debug use:
+
+  ./configure --enable-debug
+
+For help text:
+
+  ./configure --help
+
+The help text is a more useage specific and up-to-date reference for
+the configure script.
+
+
+Makefile
+--------
+
+The GNU Makefile is used to build the final executable, clean up build
+artifacts, and install the program. It checks for the config.mak which is
+generated by the configure script. For a regular build, once you have the
+configure script with desired flags, run:
+
+  make
+
+This builds the executable to bin/ and build objects to build/
+
+
+Suggested enviroment setup
+--------------------------
+It is suggested that you run do the following things to prepare you environment
+for development. This is not a strict enforcement, but due to the project
+structure it is a good starting point.
+
+  git pull
+  ./tools/Cleanup
+  ./configure --enable-debug
+  ./build-aux/generate-artifacts
+  make test
+
+This is to ensure that you have the most up-to-date source code, and that there
+are no major problems with the source control version.
+
+The git pull is used to sync with the repository and prevent conflicts. The
+cleanup is to ensure their are no lingering build artifacts. The configure with
+debug enabled is for strict build flags and -ggdb. Bear is used to generated
+compile_commands.json for the clang suite of tooling. Finally, run the program
+to ensure the chain works.
+
+
+Pre-commit checks
+-----------------
+
+Before you commit to source control ensure that done the following:
+
+  * Run the cleanup scripts
+
+    ./tools/Cleanup
+
+  * Ensure that all changes were atomic
+
+  * If you compted a TODO list item check it off.
+
+  * Based on complexity, test the feature accordingly.