Changes between Initial Version and Version 1 of pm-automake-intro

Jun 1, 2006 1:35:34 AM (15 years ago)

started first draft


  • pm-automake-intro

    v1 v1  
     1= Introduction of Automake Concepts =
     3The format of the Automake {{{}}} input files is essentially that of a usual Makefile:  One can have comments (everything in a line following a "{{{#}}}"), set Makefile variables, and write rules.
     5Some of the Makefile variables in a {{{}}} file have special meaning.  For example, the {{{SUBDIRS}}} variable can be set to the list of directories, into which the generated Makefile should recurse.
     7The things that should be built, are listed in variable names that have a '''primary''', and possibly a '''prefix'''.  Typical examples are
     10bin_PROGRAMS = super_solver
     11super_solver_SOURCES = super_solver.cpp super_solver.hpp
     13lib_LTLIBRARIES =
     14libgreatlib_la_SOURCES = greatlib1.cpp greatlib1.hpp greatlib2.cpp greatlib2.hpp
     15libgreatlib_la_LDFLAGS = $(LT_LDFLAGS)
     17include_HEADERS = ../inc/config_supersolver.h greatlib1.hpp
     20The primaries in this example are the parts of the Makefile variables that are capitalized, and the prexifes are the strings before the primaries.
     22Those are the primaries that are important for a COIN project:
     24 * '''PROGRAMS''':  This primary is used to specify programs that are to be compiled.  The prefix '''bin_''' indicates that the program should be installed into the {{{bin}}} directory by a {{{make install}}}.  If the prefix '''noinst_''' is used, it indicates that the program should not be installed (e.g., the unit test program).
     26 * '''LTLIBRARIES''':  This primary is used to tell Automake the name(s) of libraries that should be build.  (Since we are using Libtool in COIN, we don't use the {{{LIBRARIES}}} primary.)  The extension should be libtool's {{{.la}}} (not {{{.a}}} or {{{.so}}}). The prefix again indicates, where the library (or libraries, if both static libraries and shared objects are compiled) are to be installed.  Usually, this is '''lib_''' to have them installed in the {{{lib}}} directory, or '''noinst_''', if they should not be installed.
     28  * '''SOURCES''': This primary is used to list all the source files that should be compiled in order to generate a program or a library.  Depending on the extension of the source file, Automake will figure out how the file should be compiled and generate automatically the requires rules.  One also includes all header files, so that a {{{make dist}}} will know, what to include in a distribution.  (In COIN, we generate the tarballs not by this feature, but it is still a good idea to follow the common scheme.)
     30  The prefix for {{{SOURCES}}} is the name of the program or library, including extension, where any dash ("{{{-}}}") and any period ("{{{.}}}") is replaced by an underscore ("{{{_}}}").
     32 * '''HEADERS''': This is usually used with the '''include_''' prefix, and one lists here all the header files that should be installed in the {{{include}}} directory.  Note that not all header files in the source code directory might be required by a user in order to link her/his code to the library, and it is good practice to only install required header files.
     34 * There are a number of additional primaries, such as '''LDFLAGS''' in the above example.  In this case, this lists additional flags that should be used when the library is "linked" (a Libtool term).  The prefix specifies, for which program or library this applies.
     37Automake provides the following features:
     39 * All '''Autoconf output variables''' are automatically available as Makefile variables.  In the above example, {{{LT_LDFLAGS}}} is actually an output variable defined in one of the custom {{{AC_COIN_}}} autoconf macros, and as you can see, it is here use as a Makefile variable.
     41 * '''Variables can be added up''', using a "{{{+=}}}" assignment.  In general, only a few {{{make}}} programs understand this in a Makefile.  Therefore, {{{automake}}} will convert a statement like
     42 {{{
     43  SUBDIRS += ForgottenSubdirectory
     44 }}}
     45 into something that all {{{make}}} programs understand.  Note that a "{{{+=}}}" can only be specified, if the Makefile variable has already been assigned with a "{{{=}}}" earlier (an empty assignment suffices).
     47 * Lines in the final Makefile can be activated depending on the outcome of a test in the {{{configure}}} script, using '''Automake conditionals'''.  An Automake conditional must have been defined in the {{{}}} file, using the '''AM_CONDITIONAL''' macro.  An invocation of this macro in the {{{}}} file looks like this:
     48 {{{
     49  AM_CONDITIONAL([COIN_IS_GREAT], [test x$is_open_source = xyes])
     50 }}}
     51 The name of the Automake conditional that is defined by that line is "{{{COIN_IS_GREAT}}}", and it attains the value "true", if the shell command, specifies in the second argument, returns true.  In this example, the conditional is set to "true", if the shell variable {{{is_open_source}}} in the final {{{configure}}} script has the value "yes" at this point.
     53 To use an Automake conditional in a {{{}}} file, one uses '''if''', '''else''' (optionally), and '''endif''', as demonstrated in the following example:
     54 {{{
     55  if COIN_IS_GREAT
     56  tellme:
     57          echo "We agree that coin is great"
     58  else
     59  tellme:
     60          echo "Something must have gone wrong with the configure test"
     61  endif
     62 }}}
     63 If the conditional {{{COIN_IS_GREAT}}} is true, then the {{{tellme}}} target will output the first line, otherwise the second.  (In the final Makefile, the inactive lines are simply commented out.)
     65 * The {{{}}} file can {{{include other input files}}}.  For example, in
     66 {{{
     67 include BuildTools/
     68 }}}
     69 the file {{{BuildTools/}}} is included (with the path relative to the location of the file that has the above line in it), when {{{automake}}} processes the input file.  It does not translate in an "{{{include}}}" in the generated Makefile, since this is not supported by all {{{make}}} programs.
     71 * If the compiler supports it, the generated Makefiles will automatically generate rules to derive '''depencendy rules for C or C++ header files'''.
     73Some more important Automake Makefile variables are the following:
     75 * '''CXXFLAGS''':  This contains the C++ compiler flags, as {{{configure}}} has determined them.
     77 * '''DEFS''':  This is the list of preprocessor
     79 * '''INCLUDES'''