From 2d33bd2f34f011c4f025a073b50d536f6a66a4db Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Mon, 16 Jan 2017 19:27:20 -0500 Subject: Improve documentation. --- README.md | 115 +------------------------------------------------------------- 1 file changed, 1 insertion(+), 114 deletions(-) mode change 100644 => 120000 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index ac5ff61..0000000 --- a/README.md +++ /dev/null @@ -1,114 +0,0 @@ -Autothing 3: The smart way to write GNU Makefiles -================================================= - -Autothing is a thing that does things automatically. - -Ok, more helpfully: Autothing is a pair of .mk Makefile fragments that -you can `include` from your Makefiles to make them easier to write; -specifically, it makes it _easy_ to write non-recursive Makefiles--and -ones that are similar to plain recursive Makefiles, at that! - -Sample ------- - -Write your makefiles of the form: - - topsrcdir ?= ... - topoutdir ?= ... - at.Makefile ?= Makefile # Optional - include $(topsrcdir)/build-aux/Makefile.head.mk - - $(outdir)/%.o: $(srcdir)/%.c: - $(CC) -c -o $@ $< - - $(outdir)/hello: $(outdir)/hello.o - - at.subdirs = ... - at.targets = ... - - include $(topsrcdir)/build-aux/Makefile.tail.mk - -This is similar to, but not quite, the comfortable way that you probably -already write your Makefiles. - -What's where? -------------- - -There are three things that Autothing provides: - - 1. Variable namespacing - 2. Tools for dealing with paths - 3. A module (plugin) system. - -This repository contains both Autothing itself, and several modules. - -Autothing itself is described in `build-aux/Makefile.README.txt`. -That file is the core documentation. - -There is a "mod" module that adds self-documenting capabilities to the -module system; adding Make targets that print documentation about the -modules used in a project. For convenience, in the top level of this -repository, there is a Makefile allowing you to use these targets to -get documentation on the modules in this repository. - -Running `make at-modules` will produce a list of modules, and short -descriptions of them: - - $ make at-modules - Autothing modules used in this project: - - dist `dist` target for distribution tarballs (more) - - files Keeping track of groups of files (more) - - gitfiles Automatically populate files.src.src from git (more) - - gnuconf GNU standard configuration variables (more) - - mod Display information about Autothing modules (more) - - nested Easy nested .PHONY targets (more) - - quote Macros to quote tricky strings (more) - - texinfo The GNU documentation system (more) - - var Depend on the values of variables (more) - - write-atomic `write-atomic` auxiliary build script (more) - - write-ifchanged `write-ifchanged` auxiliary build script (more) - -The "(more)" at the end of a line indicates that there is further -documentation for that module, which can be produced by running the -command `make at-modules/MODULE_NAME`. - -Further development -------------------- - -The raison d'être of GNU Automake is that targeting multiple -implementations of Make is hard; the different dialects have diverged -significantly. - -But GNU's requirement of supporting multiple implementations of Make -is relaxing. With GNU Emacs 25, it GNU Make is explicitly required. -We can finally rise up from our Automake shackles! - -... But we soon discover that the GNU Coding Standards require many -things of our Makefiles, which Automake took care of for us. - -So, several of the modules in this repository combine to attempt to -provide the things that the GNU Coding Standards require. Between -`gnuconf`, `dist`, `files`, and `texinfo`; the GNU Coding Standards -for Makefiles are nearly entirely satisfied. However, there are a few -targets that are required, but aren't implemented by a module (yet!): - - - `install-strip` - - `TAGS` - - `check` - - `installcheck` (optional, but recommended) - -Further, none of the standard modules actually provide rules for -installing files; they merely define the standard install targets with -dependencies on the files they need to install. This is because -actual rules for installing them can be project-specific, but also -depend on classes of files that none of the modules are aware of; -binary executables might need a strip flag passed to INSTALL, but we -need to avoid that flag for scripts; some parts might need libtool -install commands, others not. - ----- -Copyright (C) 2016-2017 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. diff --git a/README.md b/README.md new file mode 120000 index 0000000..5e5ea4a --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +build-aux/Makefile.README.txt \ No newline at end of file -- cgit v1.2.3