improve HACKING documentation

9 files changed, 226 insertions, 179 deletions

diff --git a/COPYING b/COPYING
index def2dff..0cca3f1 100644
--- a/COPYING
+++ b/COPYING
@@ -6,4 +6,4 @@ and license statement, each file contains a "License:" line to make
 searching easy.
 
 Full copies of the GNU General Public License versions 2 and 3 are
-included as `COPYING-GPLv2` and `COPYING-GPLv3`, respectively.
\ No newline at end of file
+included as `COPYING-GPLv2` and `COPYING-GPLv3`, respectively.
diff --git a/HACKING/build-system.md b/HACKING/build-system.md
new file mode 100644
index 0000000..93770cc
--- /dev/null
+++ b/HACKING/build-system.md
@@ -0,0 +1,24 @@
+The build system is built around an automake-like system for GNU Make
+that I wrote.  It is documented in `automake.txt`.  It provides all of
+the standard targets and such; you tell it what to do by setting a
+series of `am_whatever` variables.  I'm just going to call it
+"automake" here.
+
+I also hook into non-exposed parts of automake with a couple of
+`_am_whatever` variables.  Hopefully I will come up with good ways to
+expose the needed functionality in the future.
+
+There are a couple of variables that get automatically set from git.
+This happens by `include`ing a hidden makefile that sets them; if
+`$(topsrcdir)/.git` exists, it knows to use git to generate it;
+otherwise it expects the file to exist:
+
+| variable           | file                                   |
+|--------------------+----------------------------------------|
+| srcfiles           | $(srcdir)/.srcfiles.mk                 |
+| LIBRETOOLS_VERSION | $(topsrcdir)/.srcversion-libretools.mk |
+| LIBRETOOLS_COMMIT  | $(topsrcdir)/.srcversion-libretools.mk |
+| DEVTOOLS_VERSION   | $(topsrcdir)/.srcversion-devtools.mk   |
+| DEVTOOLS_COMMIT    | $(topsrcdir)/.srcversion-devtools.mk   |
+
+`srcfiles` basically becomes `am_src_files`.
diff --git a/HACKING.md b/HACKING/code-quality.md
index ee5cd65..a520ce5 100644
--- a/HACKING.md
+++ b/HACKING/code-quality.md
@@ -1,56 +1,10 @@
-This document is a little all over the place--I've been working on it
-for a while, but I keep refactoring it as I move pieces of it into man
-pages and whatnot.  It's mostly a brain dump, sorry.
-
-There are three parts to this; procedures, "content" guidelines and
-"style" guidelines.  The style guidelines are less strict; as long as
-things are consistent at the file-level, I'm pretty happy.
-
-Contributing
-============
-
-I'd love to have your patches!  Code should be hackable; if you want
-to modify something, but can't figure out how: 1) ping me for help, 2)
-it probably means the code was too complicated in the first place.
-
-Patches should be sent to <dev@lists.parabolagnulinux.org>; please put
-"[PATCH]" and "libretools" in the subject line.  If you have commit
-access, but want me to look over it first, feel free to create a new
-branch in git, and I will notice it.  Try to avoid pushing to the
-"master" branch unless it's a trivial change; it makes it easier to
-review things; though I *will* look over every commit before I do a
-release, so don't think you can sneak something in :)
-
-I'd love to discuss possible changes on IRC (I'm lukeshu), either on
-irc.freenode.net#parabola or in personal messages.  My account may be
-online even if I'm not; I will eventually see your it, I do a search
-for mentions of "luke" on #parabola every time I get on.
-
-Testing
-=======
-
-Please write unit tests for new things.  Tests can be run with `make
-check`, which just runs `./testenv roundup` in the `test/` directory.
-Relatedly, you need the `roundup` tool to run the tests.  `./testenv`
-can be given `--no-network` and/or `--no-sudo` to dissable tests that
-require those things.  Make can be made to pass those things in by
-setting `TESTENVFLAGS`.  If you don't dissable either, I *strongly*
-recommend setting TMPDIR to somewhere on a btrfs partition before
-running the tests; otherwise the chroot tests will take forever.  I
-mean, they already take long on btrfs, but without it... _dang_.
-
-I also recommend having the `haveged` daemon running.  That's good
-general advice, but also: some of the tests make GPG keys, this
-"should" take on the order of 1 second, but can take several minutes
-if you don't have `haveged` running.
-
 Code content
 ============
 
 Be aware of the `librelib(7)` library suite, which lives `src/lib`.
 It is a suite of Bash libraries that will help you out.  Most of the
 people looking at the libretools code are familiar with the `messages`
-part of it, which actually contains a much of utility routines, not
+part of it, which actually contains a bunch of utility routines, not
 just message printing.  There is also a library for dealing with
 `blacklist.txt`, and one for loading configuration files and
 PKGBUILDs.  These are common tasks, but are tricky to handle
@@ -178,76 +132,3 @@ My brief rules of thumb:
 	while read line; do
 		...
 	done < <(prog)
-
-
-Style guidelines
-================
-
-Unless you have a good reason, use `[[ ... ]]` instead of `[ ... ]`;
-they work similarly, but `[[ ... ]]` is sometimes more readable (fine,
-rarely, but never less), and is harder to make mistakes with quoting,
-because it is syntactic magic, as opposed to `[ ... ]` which is an
-executable which just happens to be implemented as a builtin.
-
-Use a litteral tab for indent.  When indenting line-wrapped text, such
-as that for `prose`, do it like this:  (» indicates tab, · indicates
-space)
-
-	func() {
-	»   prose "This is the first line. This paragraph is going to be
-	»   ·······wrapped."
-	}
-
-The `; then` and `; do` should go on the same line as
-`if`/`elif`/`for`/`while`.  Also, there is no space before the `;`.
-
-Prefer the `for VAR in LIST` syntax over the `for ((init; cond; inc))`
-syntax, when possible.  For example (heh, `for` example):
-
-	local i
-	for (( i = 1 ; i <= 10 ; i++ )); do
-
-should be
-
-	local i
-	for i in {1..10}; do
-
-Of course, if the upper bound is a variable, the C-like syntax is
-the better option, as otherwise you would have to use `seq` (calling
-an external), or `eval` (gross, easy to mess up royally).
-
-Indent comments like you would code; don't leave them at the beginning
-of the line.  Example:
-
-	for item in "${list[@]}"; do
-		if [[ $item == foo ]]; then
-	# BAD
-			foobar
-		fi
-		if [[ $item == bar ]]; then
-			# GOOD
-			barbaz
-		fi
-	done
-
-Fauno, I'm sorry.  But I don't know how you can read your own code :P.
-
-Some people argue in favor of the useless use of cat, because data
-should flow from left to right.  However, the input redirection
-doesn't have to go on the right side of a command:
-
-	cat file | program  # useless use of cat
-	program < file      # data flows right to left
-	< file program      # just right
-
-Copyright statements should look like
-
-	# Copyright (C) YEARS NAME <EMAIL>
-
-for most code, for 3rd-party code that has been imported, indent it a
-bit:
-
-	#   Copyright (C) YEARS NAME <EMAIL>
-
-Always put a line with `# License:` specifying the license of that
-file.
diff --git a/HACKING/code-style.md b/HACKING/code-style.md
new file mode 100644
index 0000000..077bc49
--- /dev/null
+++ b/HACKING/code-style.md
@@ -0,0 +1,62 @@
+The style guidelines aren't terribly strict.  As long as things are
+consistent per-file, I'm pretty happy.
+
+Style guidelines
+================
+
+Unless you have a good reason, use `[[ ... ]]` instead of `[ ... ]`;
+they work similarly, but `[[ ... ]]` is sometimes more readable (fine,
+rarely, but never less), and is harder to make mistakes with quoting,
+because it is syntactic magic, as opposed to `[ ... ]` which is an
+executable which just happens to be implemented as a builtin.
+
+Use a litteral tab for indent.  When indenting line-wrapped text, such
+as that for `prose`, do it like this:  (» indicates tab, · indicates
+space)
+
+	func() {
+	»   prose "This is the first line. This paragraph is going to be
+	»   ·······wrapped."
+	}
+
+The `; then` and `; do` should go on the same line as
+`if`/`elif`/`for`/`while`.  Also, there is no space before the `;`.
+
+Prefer the `for VAR in LIST` syntax over the `for ((init; cond; inc))`
+syntax, when possible.  For example (heh, `for` example):
+
+	local i
+	for (( i = 1 ; i <= 10 ; i++ )); do
+
+should be
+
+	local i
+	for i in {1..10}; do
+
+Of course, if the upper bound is a variable, the C-like syntax is
+the better option, as otherwise you would have to use `seq` (calling
+an external), or `eval` (gross, easy to mess up royally).
+
+Indent comments like you would code; don't leave them at the beginning
+of the line.  Example:
+
+	for item in "${list[@]}"; do
+		if [[ $item == foo ]]; then
+	# BAD
+			foobar
+		fi
+		if [[ $item == bar ]]; then
+			# GOOD
+			barbaz
+		fi
+	done
+
+Fauno, I'm sorry.  But I don't know how you can read your own code :P.
+
+Some people argue in favor of the useless use of cat, because data
+should flow from left to right.  However, the input redirection
+doesn't have to go on the right side of a command:
+
+	cat file | program  # useless use of cat
+	program < file      # data flows right to left
+	< file program      # just right
diff --git a/HACKING/contributing.md b/HACKING/contributing.md
new file mode 100644
index 0000000..65066b5
--- /dev/null
+++ b/HACKING/contributing.md
@@ -0,0 +1,26 @@
+Contributing
+============
+
+I'd love to have your patches!  Code should be hackable; if you want
+to modify something, but can't figure out how: 1) ping me for help, 2)
+it probably means the code was too complicated in the first place.
+
+Patches should be sent to <dev@lists.parabolagnulinux.org>; please put
+"[PATCH]" and "libretools" in the subject line.  If you have commit
+access, but want me to look over it first, feel free to create a new
+branch in git, and I will notice it.  Try to avoid pushing to the
+"master" branch unless it's a trivial change; it makes it easier to
+review things; though I *will* look over every commit before I do a
+release, so don't think you can sneak something in :)
+
+Be sure to make sure to follow the licensing requirements in
+`HACKING/licensing.md`
+
+I'd love to discuss possible changes on IRC (I'm lukeshu), either on
+irc.freenode.net#parabola or in personal messages.  My account may be
+online even if I'm not; I will eventually see your message, I do a
+search for mentions of "luke" on #parabola every time I get on.
+
+Please write unit tests for new functionality.  Or old functionality.
+Please write unit tests!  See `HACKING/testing.md` for details on
+testing.
diff --git a/HACKING/licensing.md b/HACKING/licensing.md
new file mode 100644
index 0000000..6d17e31
--- /dev/null
+++ b/HACKING/licensing.md
@@ -0,0 +1,19 @@
+We don't require copyright assignment or any fancy paperwork!  Just
+make sure you specify the license and include a copyright statement
+with your name and the current year.
+
+New code should (please) be licensed GPLv2+.  I say v2 instead of v3
+because some code from Arch is GPLv2 (no "or any later version"), and
+having to worry about which programs can be combined is a huge pain.
+
+Copyright statements should look like
+
+	# Copyright (C) YEARS NAME <EMAIL>
+
+for most code, for 3rd-party code that has been imported, indent it a
+bit:
+
+	#   Copyright (C) YEARS NAME <EMAIL>
+
+Always put a line with `# License:` specifying the license of that
+file.
diff --git a/HACKING/testing.md b/HACKING/testing.md
new file mode 100644
index 0000000..8dee485
--- /dev/null
+++ b/HACKING/testing.md
@@ -0,0 +1,18 @@
+Testing
+=======
+
+Please write unit tests for new things.  Tests can be run with `make
+check`, which just runs `./testenv roundup` in the `test/` directory.
+Relatedly, you need the `roundup` (the `sh-roundup` package on
+Parabola) tool to run the tests.  `./testenv` can be given
+`--no-network` and/or `--no-sudo` to dissable tests that require those
+things.  Make can be made to pass those things in by setting
+`TESTENVFLAGS`.  If you don't dissable either, I *strongly* recommend
+setting TMPDIR to somewhere on a btrfs partition before running the
+tests; otherwise the chroot tests will take forever.  I mean, they
+already take long on btrfs, but without it... _dang_.
+
+I also recommend having the `haveged` daemon running.  That's good
+general advice, but also: some of the tests make GPG keys, this
+"should" take on the order of 1 second, but can take several minutes
+if you don't have `haveged` running.
diff --git a/automake.head.mk b/automake.head.mk
index a3c90fd..ad7154c 100644
--- a/automake.head.mk
+++ b/automake.head.mk
@@ -39,7 +39,7 @@ endif
 
 _am_included_makefiles := $(_am_included_makefiles) $(call _am_path,$(outdir)/Makefile)
 
-## Empty variables for use by the module
+## Empty variables for use by each Makefile
 $(_am)subdirs =
 $(_am)depdirs =
 
diff --git a/automake.txt b/automake.txt
index 307b321..22a0b84 100644
--- a/automake.txt
+++ b/automake.txt
@@ -7,14 +7,13 @@ automake.{head,tail}.mk Makefiles and how to use them, kinda.
 I wrote a "clone" of automake.  I say clone, because it works
 differently.  Yeah, I need a new name for it.
 
-Anyway, how to use it:
+High-level overview
+-------------------
 
 In each source directory, you write a `Makefile`, very similarly to if
 you were writing for plain GNU Make, with
 
-_am_phony = build install uninstall mostlyclean clean distclean maintainer-clean check
-
-
+    # adjust the number of `../` segments as appropriate
     include $(dir $(lastword $(MAKEFILE_LIST)))/../../config.mk
     include $(topsrcdir)/automake.head.mk
 
@@ -22,63 +21,81 @@ _am_phony = build install uninstall mostlyclean clean distclean maintainer-clean
     
     include $(topsrcdir)/automake.tail.mk
 
-Write your own `common.each.mk` that gets included after the body of
-your Makefile for each Makefile.
-
-Write your own `common.once.mk` that gets included once after
-everything else has been parsed.
-
-There are several commands that generate files; simply record what
-they the list of files in their output to the following variables:
-
-| Variable  | Command      | Description                       | Relative to |
-|-----------+--------------+-----------------------------------+-------------|
-| src_files | emacs        | Files that the developer writes   | srcdir      |
-| gen_files | ???          | Files the developer compiles      | srcdir      |
-| cfg_files | ./configure  | Users' compile-time configuration | outdir      |
-| out_files | make all     | Files the user compiles           | outdir      |
-| sys_files | make install | Files the user installs           | DESTDIR     |
-
-In addition, there are
-
-    subdirs   : A list of other directories containing Makefiles that
-                contain or generate files that are dependencies of
-                targets in this directory.  They are not necesarily
-                actually subdirectories of this directory in the
-                filesystem.
-    
-    clean_files : A list of things to `rm` in addition to
-                  `$(out_files)` when you run `make clean`. (Example:
-                  `*.o`).
-    
-    slow_files : A list of things in `$(out_files)` that (as an
-                 exception) should _not_ be deleted when you run `make
-                 mostlyclean`.
-
-Each directory containing a Makefile is a "module".  The module name
-is one of 4 things (with / replaced with _ in all cases):
- - `all`
- - $(realpath --relative-to=. $dir_name)
- - dep-top
- - dep-$(realpath --relative-to=$(topoutdir) $dir_name)
-
-The dep-* options are only used if that directory is not a child of
-the current directory.
+Write your own `common.{each,once}.{head,tail}.mk` files that get
+included:
+ - `common.once.head.mk`: before parsing any of your Makefiles
+ - `common.each.head.mk`: before parsing each of your Makefiles
+ - `common.each.tail.mk`: after parsing each of your Makefiles
+ - `common.each.tail.mk`: after parsing all of your Makefiles
 
 Here is a table of all of the .PHONY targets that automake takes care
 of for you:
 
-| this | and this         | are aliases for this | which is just a case of this |
-|------+------------------+----------------------+------------------------------|
-| all  | build            | build-all            | build-$(module)              |
-|      | install          | install-all          | install-$(module)            |
-|      | uninstall        | uninstall-all        | uninstall-$(module)          |
-|      | mostlyclean      | mostlyclean-all      | mostlyclean-$(module)        |
-|      | clean            | clean-all            | clean-$(module)              |
-|      | distclean        | distclean-all        | distclean-$(module)          |
-|      | maintainer-clean | maintainer-clean-all | maintainer-clean-$(module)   |
-|      | check            | check-all            | check-$(module)              |
-|      |                  |                      | dist                         |
+| this | and this         | are aliases for this                                   |
+|------+------------------+--------------------------------------------------------|
+| all  | build            | $(outdir)/build                                        |
+|      | install          | $(outdir)/install                                      |
+|      | uninstall        | $(outdir)/uninstall                                    |
+|      | mostlyclean      | $(outdir)/mostlyclean                                  |
+|      | clean            | $(outdir)/clean                                        |
+|      | distclean        | $(outdir)/distclean                                    |
+|      | maintainer-clean | $(outdir)/maintainer-clean                             |
+|      | check            | $(outdir)/check (not implemented for you)              |
+|      | dist             | $(topoutdir)/$(PACKAGE)-$(VERSION).tar.gz (not .PHONY) |
+
+You are responsible for implementing the `$(outdir)/check` target in
+each of your Makefiles.
+
+Telling automake about your program
+-----------------------------------
+
+You tell automake what to do for you by setting some variables.  They
+are all prefixed with `am_`; this prefix may be changed by editing the
+`_am` variable at the top of `automake.head.mk`.
+
+There are several commands that generate files; simply record the list
+of files that each command generates as the following variable
+variables:
+
+| Variable     | Create Command | Delete Command              | Description                       | Relative to |
+|--------------+----------------+-----------------------------+-----------------------------------+-------------|
+| am_src_files | emacs          | rm -rf .                    | Files that the developer writes   | srcdir      |
+| am_gen_files | ???            | make maintainer-clean       | Files the developer compiles      | srcdir      |
+| am_cfg_files | ./configure    | make distclean              | Users' compile-time configuration | outdir      |
+| am_out_files | make all       | make mostlyclean/make clean | Files the user compiles           | outdir      |
+| am_sys_files | make install   | make uninstall              | Files the user installs           | DESTDIR     |
+
+In addition, there are two more variables that control not how files
+are created, but how they are deleted:
+
+| Variable       | Affected command | Description                                    | Relative to |
+|----------------+------------------+------------------------------------------------+-------------|
+| am_clean_files | make clean       | A list of things to `rm` in addition to the    | outdir      |
+|                |                  | files in `$(am_out_files)`.  (Example: `*.o`)  |             |
+|----------------+------------------+------------------------------------------------+-------------|
+| am_slow_files  | make mostlyclean | A list of things that (as an exception) should | outdir      |
+|                |                  | _not_ be deleted.  (otherwise, `mostlyclean`   |             |
+|                |                  | is the same as `clean`)                        |             |
+
+Finally, there are two variables that express the relationships
+between directories:
+
+| Variable   | Description                                             |
+|------------+---------------------------------------------------------|
+| am_subdirs | A list of other directories (containing Makefiles) that |
+|            | may be considered "children" of this                    |
+|            | directory/Makefile; building a phony target in this     |
+|            | directory should also build it in the subdirectory.     |
+|            | They are not necesarily actually subdirectories of this |
+|            | directory in the filesystem.                            |
+|------------+---------------------------------------------------------|
+| am_depdirs | A list of other directories (containing Makefiles) that |
+|            | contain or generate files that are dependencies of      |
+|            | targets in this directory.  They are not necesarily     |
+|            | actually subdirectories of this directory in the        |
+|            | filesystem.  Except for files that are dependencies of  |
+|            | files in this directory, things in the dependency       |
+|            | directory will not be built.                            |
 
 ----
 Copyright (C) 2016  Luke Shumaker