Luke's AutoMake
===============

Yo, this document is incomplete.  It describes the magical
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.

High-level overview
-------------------

In each source directory, you write a `Makefile`, very similarly to if
you were writing for plain GNU Make, with

    # adjust the number of `../` segments as appropriate
    include $(dir $(lastword $(MAKEFILE_LIST)))/../../config.mk
    include $(topsrcdir)/automake.head.mk

    # your makefile
    
    include $(topsrcdir)/automake.tail.mk

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                                   |
|------+------------------+--------------------------------------------------------|
| 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

This documentation file is placed into the public domain.  If that is
not possible in your legal system, I grant you permission to use it in
absolutely every way that I can legally do so.