From c8c1b794b51ef20646cb6d30702cb79dee3248ea Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Mon, 30 May 2016 20:26:00 -0400 Subject: Turn the master branch into just a README --- README.md | 283 ++++++++++++++++++++++++++++++++++++++++++ build-aux/Makefile.README.txt | 164 ------------------------ 2 files changed, 283 insertions(+), 164 deletions(-) create mode 100644 README.md delete mode 100644 build-aux/Makefile.README.txt 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 | | 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. -- cgit v1.1-4-g5e80