summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@sbcglobal.net>2016-03-01 19:15:29 -0500
committerLuke Shumaker <lukeshu@sbcglobal.net>2016-03-01 19:15:29 -0500
commita2718bfbd5dee3b5a69fcdb4361748ef84cbd06c (patch)
tree4b973ee446a68c11e0d2a4d3351fa0beece9bef4
parentbce7ec06c4234cb5713bb20350b3aff9010e3703 (diff)
(libretools) improve HACKING documentation
-rw-r--r--automake.head.mk2
-rw-r--r--automake.txt131
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