summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--README.md283
-rw-r--r--build-aux/Makefile.README.txt164
2 files changed, 283 insertions, 164 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e7606eb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,283 @@
+Autothing
+=========
+
+Autothing is a set of Makefile fragments that you can `include` in
+your GNU Makefiles to provide two core things:
+
+ 1. Make it _easy_ to write non-recursive Makefiles. (search for the
+ paper "Recursive Make Considered Harmful")
+ 2. Provide boilerplate for standard features people expect to be
+ implemented in Makefiles.
+
+Between these two, it should largely obviate GNU Automake in your
+projects.
+
+The recommended including Autothing into your project is to add the
+autothing repository as a `git` remote, and merge the `core` branch,
+and whichever `mod-*` module branches you want into your project's
+branch.
+
+| module name | dependencies | description |
+|-------------+--------------+--------------------------------------------------------------------------------------------------|
+| at | | The core of Autothing |
+|-------------+--------------+--------------------------------------------------------------------------------------------------|
+| std | at | Provide .PHONY targets: all/build/install/uninstall/mostlyclean/clean/distclean/maintainer-clean |
+| dist | std | Provide .PHONY target: dist |
+| gnuconf | dist | Provide default values for user-variables from the GNU Coding Standards' Makefile Conventions |
+| gnustuff | gnuconf | Provide remaining stuff from the GNU Coding Standards' Makefile Conventions |
+
+Core (psuedo-module: at)
+------------------------
+
+As harmful as recursive make is, it's historically been difficult to
+to write non-recursive Makefiles. The goal of the core of Autothing
+is to make it easy.
+
+In each source directory, you write a `Makefile`, very similarly to if
+you were writing for plain GNU Make, with the form:
+
+ topoutdir ?= ...
+ topsrcdir ?= ...
+ include $(topsrcdir)/build-aux/Makefile.head.mk
+
+ # your makefile
+
+ include $(topsrcdir)/build-aux/Makefile.tail.mk
+
+| at.path | Use $(call at.path,FILENAME1 FILENAME2...) sanitize filenames that are not in the current Makefile's directory or its children |
+| at.nl | A newline, for convenience, since it is difficult to type a newline in GNU Make expressions |
+
+| at.dirlocal | Which variables to apply the namespacing mechanism to |
+| at.phony | Which targets to mark as .PHONY, and have automatic recursive dependencies |
+| at.subdirs | Which directories to consider as children of this one |
+| at.depdirs | Which directories are't subdirs, but may contain dependencies of targets in this directory |
+
+outdir
+srcdir
+
+Module: std
+-----------
+
+| Variable | Create Command | Delete Command | Description | Relative to |
+|---------------+----------------+-----------------------------+-----------------------------------+-------------|
+| std.src_files | emacs | rm -rf . | Files that the developer writes | srcdir |
+| std.gen_files | ??? | make maintainer-clean | Files the developer compiles | srcdir |
+| std.cfg_files | ./configure | make distclean | Users' compile-time configuration | outdir |
+| std.out_files | make all | make mostlyclean/make clean | Files the user compiles | outdir |
+| std.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 |
+|-----------------+------------------+------------------------------------------------+-------------|
+| std.clean_files | make clean | A list of things to `rm` in addition to the | outdir |
+| | | files in `$(std.out_files)`. (Example: `*.o`) | |
+|-----------------+------------------+------------------------------------------------+-------------|
+| std.slow_files | make mostlyclean | A list of things that (as an exception) should | outdir |
+| | | _not_ be deleted. (otherwise, `mostlyclean` | |
+| | | is the same as `clean`) | |
+
+| Variable | Default | Description |
+|----------+----------+-------------|
+| DESTDIR | | |
+|----------+----------+-------------|
+| RM | rm -f | |
+| RMDIR_P | rmdir -p | |
+| TRUE | true | |
+
+Module: dist
+------------
+
+The `dist` module produces distribution tarballs
+
+| Variable | Default | Description |
+|--------------+------------+-------------|
+| dist.exts | .tar.gz | |
+| dist.pkgname | $(PACKAGE) | |
+| dist.version | $(VERSION) | |
+
+| Variable | Default | Description |
+|-----------+-------------+----------------------------------------------------|
+| CP | cp | |
+| GZIP | gzip | |
+| MKDIR | mkdir | |
+| MKDIR_P | mkdir -p | |
+| MV | mv | |
+| RM | rm -f | |
+| TAR | tar | |
+|-----------+-------------+----------------------------------------------------|
+| GZIPFLAGS | $(GZIP_ENV) | |
+| GZIP_ENV | --best | Because of GNU Automake, users expect this to work |
+
+Module: gnuconf
+---------------
+
+The `gnuconf` module provides default values for user-facing toggles
+required by the GNU Coding Standards.
+
+There is only one developer configuration option:
+
+| Variable | Default | Description |
+|-----------------+------------+-----------------------------------------------|
+| gnuconf.pkgname | $(PACKAGE) | The package name to use in the default docdir |
+
+There is an extensive list of user configuration options:
+
+| Variable | Default | Description |
+|-----------------+---------------------------------------+-------------------------------------------|
+| AWK | awk | |
+| CAT | cat | |
+| CMP | cmp | |
+| CP | cp | |
+| DIFF | diff | |
+| ECHO | echo | |
+| EGREP | egrep | |
+| EXPR | expr | |
+| FALSE | false | |
+| GREP | grep | |
+| INSTALL_INFO | install-info | |
+| LN | ln | |
+| LS | ls | |
+| MKDIR | mkdir | |
+| MV | mv | |
+| PRINTF | printf | |
+| PWD | pwd | |
+| RM | rm | |
+| RMDIR | rmdir | |
+| SED | sed | |
+| SLEEP | sleep | |
+| SORT | sort | |
+| TAR | tar | |
+| TEST | test | |
+| TOUCH | touch | |
+| TR | tr | |
+| TRUE | true | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| AR | ar | |
+| ARFLAGS | | |
+| BISON | bison | |
+| BISONFLAGS | | |
+| CC | cc | |
+| CCFLAGS | $(CFLAGS) | |
+| FLEX | flex | |
+| FLEXFLAGS | | |
+| INSTALL | install | |
+| INSTALLFLAGS | | |
+| LD | ld | |
+| LDFLAGS | | |
+| LDCONFIG | ldconfig | TODO: detect absence, fall back to `true` |
+| LDCONFIGFLAGS | | |
+| LEX | lex | |
+| LEXFLAGS | $(LFLAGS) | |
+| MAKEINFO | makeinfo | |
+| MAKEINFOFLAGS | | |
+| RANLIB | ranlib | TODO: detect absence, fall back to `true` |
+| RANLIBFLAGS | | |
+| TEXI2DVI | texi2dvi | |
+| TEXI2DVIFLAGS | | |
+| YACC | yacc | |
+| YACCFLAGS | $(YFLAGS) | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| CFLAGS | | |
+| LFLAGS | | |
+| YFLAGS | | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| LN_S | ln -s | TODO: detect when to fall back to `cp` |
+|-----------------+---------------------------------------+-------------------------------------------|
+| CHGRP | chgrp | |
+| CHMOD | chmod | |
+| CHOWN | chown | |
+| MKNOD | mknod | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| INSTALL_PROGRAM | $(INSTALL) | |
+| INSTALL_DATA | ${INSTALL} -m 644 | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| prefix | /usr/local | |
+| exec_prefix | $(prefix) | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| bindir | $(exec_prefix)/bin | |
+| sbindir | $(exec_prefix)/sbin | |
+| libexecdir | $(exec_prefix)/libexec | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| datadir | $(datarootdir) | |
+| sysconfdir | $(prefix)/etc | |
+| sharedstatedir | $(prefix)/com | |
+| localstatedir | $(prefix)/var | |
+| runstatedir | $(localstatedir)/run | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| includedir | $(prefix)/include | |
+| oldincludedir | /usr/include | |
+| docdir | $(datarootdir)/doc/$(gnuconf.pkgname) | |
+| infodir | $(datarootdir)/info | |
+| htmldir | $(docdir) | |
+| dvidir | $(docdir) | |
+| pdfdir | $(docdir) | |
+| psdir | $(docdir) | |
+| libdir | $(exec_prefix)/lib | |
+| lispdir | $(datarootdir)/emacs/site-lisp | |
+| localedir | $(datarootdir)/locale | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| mandir | $(datarootdir)/man | |
+| man1dir | $(mandir)/man1 | |
+| man2dir | $(mandir)/man2 | |
+| man3dir | $(mandir)/man3 | |
+| man4dir | $(mandir)/man4 | |
+| man5dir | $(mandir)/man5 | |
+| man6dir | $(mandir)/man6 | |
+| man7dir | $(mandir)/man7 | |
+| man8dir | $(mandir)/man8 | |
+|-----------------+---------------------------------------+-------------------------------------------|
+| manext | .1 | |
+| man1ext | .1 | |
+| man2ext | .2 | |
+| man3ext | .3 | |
+| man4ext | .4 | |
+| man5ext | .5 | |
+| man6ext | .6 | |
+| man7ext | .7 | |
+| man8ext | .8 | |
+
+Module: gnustuff
+----------------
+
+This is a poorly-thought-out module implementing remaining things from
+the GNU Coding Standards.
+
+This is poorly thought out and poorly tested because it's basically
+the part of the GNU Coding Standards that I don't use.
+
+Developer configuration options:
+
+| Variable | Default | Description |
+|-----------------------+-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------|
+| gnustuff.info_docs | | The list of texinfo documents in the current directory, without the `.texi` suffix. |
+| gnustuff.program_dirs | $(bindir) $(sbindir) $(libexecdir) | Directories to use $(INSTALL_PROGRAM) for inserting files into. |
+| gnustuff.data_dirs | <every variable from gnuconf ending in `dir` that isn't bindir, sbindir, or libexecdir> | Directories to use $(INSTALL_DATA) for inserting files into. |
+| gnustuff.dirs | $(gnustuff.program_dirs) $(gnustuff.data_dirs) | Directories to create |
+
+User configuration options:
+
+| Variable | Default | Description |
+|-----------+-----------------+-------------|
+| STRIP | strip | |
+| TEXI2HTML | makeinfo --html | |
+| TEXI2PDF | texi2pdf | |
+| TEXI2PS | texi2dvi --ps | |
+| MKDIR_P | mkdir -p | |
+
+It provides several `.phony` targets:
+ - install-{html,dvi,pdf,ps}
+ - install-strip
+ - {info,html,dvi,pdf,ps}
+ - TAGS
+ - check
+ - installcheck
+
+It also augments the `std` `install` rule to run $(INSTALL_INFO) as
+necessary.
+
+And several real rules:
+ - How to install files into any of the $(gnustuff.program_dirs) or
+ $(gnustuff.data_dirs).
+ - How to generate info, dvi, html, pdf, and ps files from texi files.
diff --git a/build-aux/Makefile.README.txt b/build-aux/Makefile.README.txt
deleted file mode 100644
index 935af5f..0000000
--- a/build-aux/Makefile.README.txt
+++ /dev/null
@@ -1,164 +0,0 @@
-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
--------------------
-
-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
-
- topoutdir ?= ...
- topsrcdir ?= ...
- include $(topsrcdir)/automake.head.mk
-
- # your makefile
-
- include $(topsrcdir)/automake.tail.mk
-
-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
-
-The `common.*.mk` makefiles are nice for including generic pattern
-rules and variables that aren't specific to a directory.
-
-You're probably thinking that this sounds too good to be true!
-Unfortunately, there are two major deviations from writing a plain
-recursive Makefile:
-
- 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)`. Further, that path must NOT contain
- a `..` segment; if you need to refer to a sibling directory, do it
- relative to `$(topoutdir)` or `$(topsrcdir)`.
-
-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`.
-
-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:
-
-| 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. |
-
-Tips, notes
------------
-
-I like to have the first (non-comment) line in a Makefile be:
-
- include $(dir $(lastword $(MAKEFILE_LIST)))/../../config.mk
-
-(adjusting the number of `../` sequences as nescessary). Then, my
-(user-editable) `config.mk` is of the form:
-
- ifeq ($(topsrcdir),)
- topoutdir := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
- topsrcdir := $(topoutdir)
-
- # your configuration
-
- endif
-
-If the package has a `./configure` script, then I have it modifiy
-topsrcdir as necessary, as well as modifying whatever other parts of
-the configuration. All of the configuration lives in `config.mk`;
-`./configure` doesn't modify any `Makefile`s, it just generates
-`config.mk`, and copies (or (sym?)link?) every `$(srcdir)/Makefile` to
-`$(outdir)/Makefile`.
-
-----
-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 grant to you.
generated by cgit v1.2.3-54-g00ecf (git 2.45.2) at 2024-11-22 00:55:41 +0000