(libretools) improve HACKING documentation

2 files changed, 75 insertions, 58 deletions

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