diff options
Diffstat (limited to 'automake.txt')
| -rw-r--r-- | automake.txt | 131 |
1 files changed, 74 insertions, 57 deletions
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 |