automake: amhello's Makefile.am Setup Explained

1 
1 2.4.3 ‘amhello’’s ‘Makefile.am’ Setup Explained
1 -----------------------------------------------
1 
1 We now turn to ‘src/Makefile.am’.  This file contains Automake
1 instructions to build and install ‘hello’.
1 
1      bin_PROGRAMS = hello
1      hello_SOURCES = main.c
1 
1    A ‘Makefile.am’ has the same syntax as an ordinary ‘Makefile’.  When
1 ‘automake’ processes a ‘Makefile.am’ it copies the entire file into the
1 output ‘Makefile.in’ (that will be later turned into ‘Makefile’ by
1 ‘configure’) but will react to certain variable definitions by
1 generating some build rules and other variables.  Often ‘Makefile.am’s
1 contain only a list of variable definitions as above, but they can also
1 contain other variable and rule definitions that ‘automake’ will pass
1 along without interpretation.
1 
1    Variables that end with ‘_PROGRAMS’ are special variables that list
1 programs that the resulting ‘Makefile’ should build.  In Automake speak,
1 this ‘_PROGRAMS’ suffix is called a “primary”; Automake recognizes other
1 primaries such as ‘_SCRIPTS’, ‘_DATA’, ‘_LIBRARIES’, etc. corresponding
1 to different types of files.
1 
1    The ‘bin’ part of the ‘bin_PROGRAMS’ tells ‘automake’ that the
1 resulting programs should be installed in BINDIR.  Recall that the GNU
1 Build System uses a set of variables to denote destination directories
11 and allow users to customize these locations (⇒Standard Directory
 Variables).  Any such directory variable can be put in front of a
1 primary (omitting the ‘dir’ suffix) to tell ‘automake’ where to install
1 the listed files.
1 
1    Programs need to be built from source files, so for each program
1 ‘PROG’ listed in a ‘_PROGRAMS’ variable, ‘automake’ will look for
1 another variable named ‘PROG_SOURCES’ listing its source files.  There
1 may be more than one source file: they will all be compiled and linked
1 together.
1 
1    Automake also knows that source files need to be distributed when
1 creating a tarball (unlike built programs).  So a side-effect of this
1 ‘hello_SOURCES’ declaration is that ‘main.c’ will be part of the tarball
1 created by ‘make dist’.
1 
1    Finally here are some explanations regarding the top-level
1 ‘Makefile.am’.
1 
1      SUBDIRS = src
1      dist_doc_DATA = README
1 
1    ‘SUBDIRS’ is a special variable listing all directories that ‘make’
1 should recurse into before processing the current directory.  So this
1 line is responsible for ‘make’ building ‘src/hello’ even though we run
1 it from the top-level.  This line also causes ‘make install’ to install
1 ‘src/hello’ before installing ‘README’ (not that this order matters).
1 
1    The line ‘dist_doc_DATA = README’ causes ‘README’ to be distributed
1 and installed in DOCDIR.  Files listed with the ‘_DATA’ primary are not
1 automatically part of the tarball built with ‘make dist’, so we add the
1 ‘dist_’ prefix so they get distributed.  However, for ‘README’ it would
1 not have been necessary: ‘automake’ automatically distributes any
1 ‘README’ file it encounters (the list of other files automatically
1 distributed is presented by ‘automake --help’).  The only important
1 effect of this second line is therefore to install ‘README’ during ‘make
1 install’.
1 
1    One thing not covered in this example is accessing the installation
1 directory values (⇒Standard Directory Variables) from your
1 program code, that is, converting them into defined macros.  For this,
1 ⇒(autoconf)Defining Directories.
1