From bb8c597ec232212a056a5171c847972e51f02ce7 Mon Sep 17 00:00:00 2001
From: BodgeMaster <>
Date: Wed, 6 Jul 2022 13:33:10 +0200
Subject: [PATCH] Documentation: add detailed build system documentation, add
 documentation for some files in resources

---
 README.md           | 14 +++--------
 doc/build_system.md | 60 +++++++++++++++++++++++++++++++++++++++++++++
 resources/README.md | 26 ++++++++++++++++++++
 3 files changed, 89 insertions(+), 11 deletions(-)
 create mode 100644 doc/build_system.md

diff --git a/README.md b/README.md
index e5105a1..83ea166 100644
--- a/README.md
+++ b/README.md
@@ -52,18 +52,10 @@ This will download the following dependenceis:
 
 ### Building
 
-To build the project, just use the `build` alias or invoke the `build.sh`
-script from the project's base directory.
-
-`build` and `build.sh` accept the environment variables `CXX`, `CXXFLAGS`, and `SINGLE`.
-
-- `CXXFLAGS` must at least specify the C++ version.
-- Set `SINGLE` to `yes` to run the build script in single-threaded mode.
-
-To clean out the build or dependency directories, use `clean` and
-`clean_dependencies` or their corresponding scripts respectively.
-`setup_project` will clean out both before doing its thing.
+To build the project, just use the `build` alias or invoke `scripts/build.sh`
+from the project's base directory.
 
+For more details, have a look at [the build system documentation](doc/build_system.md).
 
 ## Copyright / License
 
diff --git a/doc/build_system.md b/doc/build_system.md
new file mode 100644
index 0000000..cdb2ea3
--- /dev/null
+++ b/doc/build_system.md
@@ -0,0 +1,60 @@
+# FOSS-VG Buils System
+
+Yeah, I was annoyed at make. Sorry. -BodgeMaster
+
+## Aliases
+
+The shell environment provided in the project's base directory contains
+aliases that can be invoked from anywhere.
+This is useful if you, for example, `cd src/lib` and want to do a quick
+rebuild, you can just run `build` and it will take care of switching
+directories back and forth.
+
+Where necessary, the "aliases" are shell functions instead of literal aliases
+to accommodate for inline environment variables.
+
+Provided aliases:
+- `setup_project` runs `scripts/setup_project.sh`
+- `build` runs `scripts/build.sh`
+- `run_tests` runs `scripts/test.sh` (we can't alias `test` because that's an
+   actual POSIX command and it would break a lot of things)
+- `clean` runs `scripts/clean.sh`
+- `clean_dependencies` runs `scripts/clean_dependencies.sh`
+
+
+## setup_project
+
+Cleans the project and its dependencies first, ensuring the project is in a known state, then downloads and extracts dependencies.
+
+This will probably do more in the future (for example compile dependencies that need to be compiled).
+
+
+# build
+
+Builds the project. This will compile all the things in `src/` except for what is in `src/test/`.
+
+Checks for endianness if endianness header is missing. Builds the endianness check if that is missing as well.
+
+Accepted environment variables:
+- `CXX`: override the default compiler
+- `CXXFLAGS`: override the default compiler flags, must at least specify the C++ version
+- `SINGLE`: if set to `yes`, causes the build script to run in single-threaded mode
+
+
+# test / run_tests
+
+Builds and runs the unit tests.
+
+Accepted environment variables:
+- `CXX`: override the default compiler
+- `CXXFLAGS`: override the default compiler flags, must at least specify the C++ version
+
+
+# clean
+
+Removes and re-creates `bin/`. Also removes the endianness header and the endianness check.
+
+
+# clean_dependencies
+
+Removes and re-created `dependencies/`.
diff --git a/resources/README.md b/resources/README.md
index e663e4f..3d1527c 100644
--- a/resources/README.md
+++ b/resources/README.md
@@ -1,7 +1,33 @@
 # Tests
 
+## unicode_data/
+
+This directory contains two files with unicode data. One is in Java format, the other is normal UTF-8.
+
+
+## check_endianness.cpp
+
+A simple tool to determine the endianness of the system and write the endianness header for FOSS-VG
+
+Supports: Little Endian, Big Endian, PDP Endian, Honeywell Endian
+
+Note that, while it can detect PDP and Honeywell endianness, the FOSS-VG project itself does not support these.
+
+Usage example: `check_endianness > header_file`
+
+
+## JavaStringGenerator.java
+
+A simple tool written in Java that takes an input as UTF-8 and outputs it in Java-style UTF-8.
+
+Usage example: `echo -ne "\x00" | java JavaStringGenerator > output_file`
+
+
 ## servers.dat
+
 My current servers.dat as pulled from my Minecraft installation. Used for testing the NBT library until we have something better.
 
+
 ## servers.dat_nbt_decoded.txt
+
 The same file manually decoded. I did this to get a better understanding how NBT works, might come in handy in the future.