This README.dev file describes the development environment.

  Copyright (C) 2025 GCK.

  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.

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: --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 --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 --debug
  bear -- make
  ./bin/yait --version

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.