summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@sbcglobal.net>2016-03-03 17:55:39 -0500
committerLuke Shumaker <lukeshu@sbcglobal.net>2016-03-03 17:55:39 -0500
commit8b4ed19938c1314ea15eb0b507dcc5aadeb3d9e6 (patch)
treeaa210642cb233b6ec79655244afc82fb400fa378
parent592eded56c45cdecb9ec9b6fc269d6c3e60f4c4c (diff)
make a public `am_path`, more docs
-rw-r--r--automake.head.mk3
-rw-r--r--automake.txt96
-rw-r--r--config.mk.in47
3 files changed, 80 insertions, 66 deletions
diff --git a/automake.head.mk b/automake.head.mk
index ad7154c..c79da83 100644
--- a/automake.head.mk
+++ b/automake.head.mk
@@ -17,13 +17,14 @@ _am = am_
_am_noslash = $(patsubst %/.,%,$(patsubst %/,%,$1))
# These are all $(call _am_func,parent,child)
-#_am_relto = $(if $2,$(shell realpath -s --relative-to='$1' $2))
+#_am_relto = $(if $2,$(shell realpath -sm --relative-to='$1' $2))
_am_is_subdir = $(filter $(abspath $1)/%,$(abspath $2)/.)
_am_relto_helper = $(if $(call _am_is_subdir,$1,$2),$(patsubst $1/%,%,$(addsuffix /.,$2)),$(addprefix ../,$(call _am_relto_helper,$(patsubst %/,%,$(dir $1)),$2)))
_am_relto = $(call _am_noslash,$(call _am_relto_helper,$(call _am_noslash,$(abspath $1)),$(call _am_noslash,$(abspath $2))))
# Note that _am_is_subdir says that a directory is a subdirectory of
# itself.
_am_path = $(call _am_relto,.,$1)
+am_path = $(foreach p,$1,$(call _am_relto,$p))
## Declare the default target
all: build
diff --git a/automake.txt b/automake.txt
index 22a0b84..b6b9184 100644
--- a/automake.txt
+++ b/automake.txt
@@ -10,6 +10,34 @@ differently. Yeah, I need a new name for it.
High-level overview
-------------------
+Now, what this does for you is:
+
+It makes it _easy_ to write non-recursive Makefiles--and ones that are
+similar to plain recursive Makefiles, at that! (search for the paper
+"Recursive Make Considered Harmful") As harmful as recursive make is,
+it's historically been difficult to to write non-recursive Makefiles.
+This makes it easy.
+
+It also makes it easy to follow the GNU standards for your makefiles:
+it takes care of this entire table of .PHONY targets 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 still responsible for implementing the `$(outdir)/check`
+target in each of your Makefiles.)
+
+What you have to do is:
+
In each source directory, you write a `Makefile`, very similarly to if
you were writing for plain GNU Make, with
@@ -21,30 +49,40 @@ you were writing for plain GNU Make, with
include $(topsrcdir)/automake.tail.mk
-Write your own `common.{each,once}.{head,tail}.mk` files that get
-included:
+And in the top-level output directory, you write a `config.mk` with:
+
+ ifeq ($(topsrcdir),)
+ # have your ./configure script adjust topsrcdir if doing an
+ # out-of-tree build
+ topsrcdir := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
+
+ # your configuration
+
+ endif
+
+And in the top-level source directory, Write your own helper makefiles
+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:
+The `common.*.mk` makefiles are nice for including generic pattern
+rules and variables that aren't specific to a directory.
-| 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're probably thinking that this sounds too good to be true!
+Unfortunately, there are two major deviations from writing a plain
+recursive Makefile:
-You are responsible for implementing the `$(outdir)/check` target in
-each of your Makefiles.
+ 1. all targets and prerequisites (including .PHONY targets!) need to
+ be prefixed with
+ `$(srcdir)`/`$(outdir)`/`$(topsrcdir)`/`$(topoutdir)`.
+ * sub-gotcha: this means that if a pattern rule has a
+ prerequisite that may be in srcdir or outdir, then it must be
+ specified twice, once for each case.
+ 2. if a prerequisite is in a directory "owned" by another Makefile,
+ you must filter the pathname through `am_path`:
+ `$(call am_path,YOUR_PATH)`.
Telling automake about your program
-----------------------------------
@@ -53,6 +91,11 @@ 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`.
+The exception to this is the `am_path` variable, which is a macro that
+is used to make a list of filenames relative to the appropriate
+directory, because unlike normal GNU (Auto)Make, $(outdir) isn't
+nescessarily equal to '.'. See above.
+
There are several commands that generate files; simply record the list
of files that each command generates as the following variable
variables:
@@ -97,9 +140,26 @@ between directories:
| | files in this directory, things in the dependency |
| | directory will not be built. |
+Tips, notes
+-----------
+
+If you have a `./configure` script, don't have it modify the
+`Makefile`s; have everything you need modified be in
+`$(topoutdir)/config.mk` and have it generate that; then have it copy
+(or (sym?)link?) every `$(srcdir)/Makefile` into `$(outdir)/Makefile`.
+
+If you're wondering, `am_path` is defined equivalently to:
+
+ am_path = $(if $1,$(shell realpath -sm -- $1))`
+
+though it is implemented purely in Make, instead of calling out to
+another program. Besides that older versions of coreutils don't have
+`realpath`, calling to an external program like that can have a
+_substantial_ slowdown on the parse time.
+
----
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.
+absolutely every way that I can legally grant to you.
diff --git a/config.mk.in b/config.mk.in
deleted file mode 100644
index ca8fa7f..0000000
--- a/config.mk.in
+++ /dev/null
@@ -1,47 +0,0 @@
-ifeq ($(topsrcdir),)
-topsrcdir := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
-
-PACKAGE = rvs
-VERSION = 0.10
-pkgtextdomain = $(PACKAGE)
-
-DESTDIR =
-prefix = /usr/local
-exec_prefix = $(prefix)
-
-bindir = $(exec_prefix)/bin
-sbindir = $(exec_prefix)/sbin
-libexecdir = $(exec_prefix)/libexec
-datarootdir = $(prefix)/share
-datadir = $(datarootdir)
-sysconfdir = $(prefix)/etc
-sharedstatedir = $(prefix)/com
-localstatedir = $(prefix)/var
-runstatedir = $(localstatedir)/run
-localedir = $(datarootdir)/locale
-
-pkgdatadir = $(datadir)/$(PACKAGE)
-pkglibexecdir = $(libexecdir)/$(PACKAGE)
-
-CFLAGS = -std=c99 -Werror -Wall -Wextra -pedantic -O2
-CPPFLAGS = -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=2 -D_GNU_SOURCE
-
-CC = cc
-M4 = m4
-MKDIR = mkdir
-MKDIRS = mkdir -p
-RMDIRS = rmdir -p
-INSTALL_DATA = install -m644
-INSTALL_PROGRAM = install -m755
-CP = cp
-MV = mv
-RM = rm -f
-SED = sed
-SORT = sort
-TAR = tar
-TRUE = true
-PRINTF = printf
-
-AUTODEPS = t
-
-endif