build - the correct tool for the job™

Thank you for taking an interest in my software. This file should help you get
it up and running to either use it on your machine, or mess around with the code
if you feel so inclined. Please read everything before continuing for a greatly
increased chance of success.

 - Michael Smith <[email protected]>

NOTE: read LICENCE (or LICENSE) for copyright and permission information!!!

== COMPATIBILITY ==

The code is known to compile and run on modern Linux with glibc or musl using
either Clang or GCC, as well as on FreeBSD 12.2, NetBSD 9.1, OpenBSD 6.8 and
DragonFly 5.8.3 with their default compilers, and illumos (OpenIndiana) with GCC
10. If any of these platforms don't work, it's a bug. Hardware-wise, only x86_64
has been tested so far, but there is nothing that should fundamentally cause
issues on other reasonable architectures.  Reports of any issues (or successes!)
are welcome.

NOTE: macOS is *unsupported* because 1) it's terrible 2) I can't test it. Ports
to macOS and other terrible and/or untestable platforms (including old
enterprise Unixes like HP/UX, AIX, and so on) are left to third parties.

Windows is unsupported because it is fundamentally incompatible with almost
every aspect of how this code works. However, now that we have WSL2, that ought
to be an adequate way to use build (and other Unix tools) if you're stuck in a
Windows environment. There's also MSYS2 and Cygwin, but they're really slow and
currently untested.

== HOW TO BUILD THE SOFTWARE ==

build builds build. If you've built and installed build, just type `build`.
If you haven't done that yet, use ./strap to bootstrap it. The build scripts
don't require much more than a POSIX shell and standard Unix utilities, and of
course a C compiler.

This project relies on libc functions and declarations that you probably don't
have because your OS is bad. These are provided by libcpoly, my
browser-polyfill-except-not-for-browsers:

  https://gitlab.com/mikesmiffy128/libcpoly

This provides a very convenient way to write portable software without worrying
about as many of the various quirks and omissions unfortunately found in all
Unix operating systems. It is recommended that you grab the up-to-date
repository from the link above and install the shared library and configuration
tool on your system before building build.

However, for the sake of convenience, build also bundles its own copy of
libcpoly. If it's missing from the system, the bundled wrapper headers will
probably still work, and any required functions will simply be statically linked
on platforms that lack them.

NOTE: If the bundled library is used, the build system will print a warning
indicating that this is not the recommended configuration! Anyone producing
distribution packages is advised to *please* package up the library as well,
since it's intended to be used by various different software.

Bindings to scripting languages will be built assuming the appropriate libraries
and headers exist to build against. If they don't, the build system will warn
about it, but won't fail!

== HOW TO INSTALL THE SOFTWARE ==

In an attempt to facilitate cross-compiling one day, installable files
will end up in build/your_os-your_architecture-your_compiler-its_version/out/,
unless a different build directory is specified (see Buildfile).

It's your choice to plonk the installation into /usr/local or /usr/pkg, stage it
into a proper package for your OS, or use something to install it into your home
directory (setting PATH, LD_LIBRARY_PATH, LIBRARY_PATH, C_INCLUDE_PATH and
MANPATH appropriately in a shell profile or .pam_environment file or something).

Tools and techniques for installing to your home directory include:

  Crude personal package managers:
    https://gitlab.com/mikesmiffy128/lpkg *
    https://nullprogram.com/blog/2018/03/27/

  Existing package managers like pkgsrc or Homebrew, in a custom prefix:
    https://web.nmsu.edu/~brook/pkgsrc/
    https://docs.brew.sh/Installation
  [but of course you'd need to actually create a package for build, and if
  someone did that, you'd probably just install it that way, right?]

  FUSE bindfs‽

* lpkg now also supports installing into (and uninstalling from) /usr/local.

You can also just use the "runbuild" script in this directory to run your
freshly-compiled copy without having to install it anywhere, but this may be
unreliable when building build itself for various reasons. It is recommended
that you install and use a known working, stable version for general usage.

NOTE: Lua bindings will be a pain to make work anywhere other than the
system-wide directories since LUA_CPATH isn't additive and also varies depending
on Lua version. It is recommended to install system-wide if you want to use Lua.
./runbuild will just assume Lua 5.4, which ought to be enough to be able to try
out Lua build scripts, but is no good if you're fussy about using a specific
version.

Do also keep in mind that many Linux distributions, such as the one I'm using,
are made by incompetent people so they don't actually look for libraries under
/usr/local/lib even though it's a standard place to put them. In fact, FreeBSD
doesn't either even though packages are actually supposed to go there! If you
get errors about missing shared libraries you'll need to add an entry in
/etc/ld.so.conf.d and probably also add /usr/local/lib to your LIBRARY_PATH
environment variable to tell the linker how to do its job. I assume packaging
people must just set RPATHs or something, but that's not really something that
can be done for upstream software (ie this) since build doesn't care where it is
installed (nor where anything else is installed).

If you're using something really stupid like NixOS or Gobo, you're on your own.

== MAN PAGES ==

build has full man page documentation, like any reasonable Unix thing.

HOWEVER, currently the build system does *NOT* install man pages as part of the
build, because it's not entirely clear where they should go. Base system man
pages pretty universally go in /usr/share/man, but OpenBSD uses /usr/local/man
for package man pages, so you can't simply do something like $PREFIX/share/man
and have it work everywhere. Similarly, NetBSD uses /usr/pkg/man. man-db on
Linux appears to not mind either /usr/local/share/man or /usr/local/man, but
again, we can't just use "/man" as a universal directory name because then
installing it to /usr would be definitely wrong everywhere.

To make matters more awkward, plenty of Linux distributions compress man pages
with gzip, as does FreeBSD, but OpenBSD and NetBSD do not. Chances are a few
Linux distributions probably don't either.

Oh, and section directories exist too.

Coming up with a way to automate man page installation/staging for every
conceivable environment is a sufficiently annoying task that I don't want to do
it, so it is up to you (and/or your OS packager one day) to figure that one out.

== PROJECT STRUCTURE ==

This should be self-explanatory, but for the sake of maximum clarity, here's a
quick tour:

src/      - implementation source code
test/     - automated tests: sanity checks and regression coverage
include/  - public headers, to be installed along with the software
cbits/    - an incomplete helper library, with a few working parts used
            extensively in build; changing or reusing this is not recommended
libcpoly/ - compatibility wrappers for libc to make porting easier (see above)
man/      - manual pages to be installed along with the software (see above)
DevDocs/  - notes, rants, random information that might come in handy
TODO/     - issue tracking, see below
scripts/  - build scripts for the build system that builds build
tools/    - scripts and snippets to support the development of the project
build/    - default compile output directory
junk/     - doesn't exist, but is ignored by Git so you can dump stuff there

Oh, also: this project is set up for use with a Language Server such as ccls or
clangd: `tools/mkcompdb` will generate an appropriate compile_commands.json.

== DEVELOPMENT PROCESS ==

So this program is a personal project of mine that I've wanted to make anyway,
but it's also my university project.

I've been told that if I don't have some sort of development process and project
management system in place then I'm doing it wrong and the resulting project
might not be as good or whatever. It's therefore unfortunate that the entire
software development industry is built on complicated cargo-cult tooling that
wastes time and causes immense sadness - indeed, sadness that this new build
system is part of an effort to avoid. So here's what I've come up with to
convince people that I do in fact keep track of what I'm doing, without creating
too much unnecessary development friction for myself.

You could call it a Unix filesystem-backed Kanban board, if you wanted to. I'm
not sure if I want to. That sounds pretty pretentious.

Start by loading the `todo` function:

  . tools/todo.sh

OR (if you want to use this system elsewhere, I guess):

  cat tools/todo.sh >> ~/.your_shell_rc

Then type one of these commands:

  todo
    (prints a list of issues)
  todo issue-identifier
    (lists a particular issue in detail and lists cross-references in code)

(It is also possible to just run tools/todo as its own binary, or put tools/ in
$PATH. Do whatever is easiest!)

To actually create/edit issues, create a text file named TODO/issue-identifier,
in the following format:

  Title
  [lines reserved for some sort of headers later]
  ====
  Body (extended description, comments, etc)

To reference issues from inside code:

  // TODO(issue-identifier): additional contextual information if you want

There is also Vim quickfix integration for those who use Vim/Neovim:

  :so tools/todo.vim

or copy tools/todo.vim into your plugins directory if you want to.

Then you can use :Todo <item> to get a list of source locations and jump to
them! You can also use :TodoEdit issue-identifier to create or edit a TODO file
in a new tab.

To close an issue, move it to TODO/.issue-identifier. This hides it, but
maintains its documentation for reference.

For really urgent issues with specific bits of code, use FIXME comments with
inline explanation. A stable release shouldn't have any FIXMEs - this will
prevent accumulation of bugs. XXX can also be used for stuff that's just vaguely
bad but not an outright bug and can get cleaned up "later" (i.e. might never
get cleaned up, but who cares, cleaning it up is merely a bonus).

"bUt wHAt aBOuT cLOseS iDs In COmMIt MeSsAGeS?!"
... just move the file as part of the commit. Stop overcomplicating things.