The GNU Autotools autoconf, automake, (libtool) by ccf65261

VIEWS: 28 PAGES: 28

									         The GNU Autotools:
     autoconf, automake, (libtool)
                       Dr. Robert P. Goddard
                    Applied Physics Laboratory
                      University of Washington
                Robert_Goddard@apl.washington.edu

           Presentation for the Northwest C++ Users‟ Group
                          8 September 2004




9/1/2010                     GNU Autotools                   1
                    Outline
•   Who needs Autotools?
•   Open Source Software
•   Roles of software users
•   Files in a source distribution
•   The configure script
•   Autoconf, configure.ac
•   Automake, Makefile.am

9/1/2010              GNU Autotools   2
                        Who needs GNU
                          Autotools?
• Use GNU Autotools if you develop software satisfying several of
  these attributes:
     –     Distributed as source code, built and installed by others
     –     Must be portable to multiple platforms
     –     Developed by a team
     –     Complex enough to require multiple Makefiles in multiple directories
     –     Written in multiple languages
     –     Long lived, requiring many update cycles
• Alternatives:
     –     Hand-crafted Makefiles
     –     Multiple Makefiles, one per target platform
     –     Configuration header files (config.h) and/or –D switches
     –     #ifdef, #if
     –     Integrated development environments
     –     IMake


9/1/2010                             GNU Autotools                                3
           (Open) Source Software
• Distributed to (some) users as source code
• Portable, at least multiple Unix and Windows
• Can be modified by (some) users
• Documented, at least for end users
• Maintained, at least bug fixes
• Easy to build from source and install
• (Licensed for redistribution:
  www.opensource.org)
• Examples: OSF (GNU), Linux, X Windows,
  Boost, PVM, LAM/MPI, ACE, Loki, NEdit,
  SourceForge, TeX, FFFTW, (SST), …
9/1/2010             GNU Autotools               4
           Roles of Software Users
•   End User                     • Differ by:
•   Installer                            –   Expectations
•   Porter                               –   Expertise
                                         –   Tasks to accomplish
•   Distributor
                                         –   Services needed
•   Developer                            –   Tools available
•   Configuration Guru                   –   Operating system
                                         –   Patience
                                         –   Willingness to learn
                                         –   Tolerance of
                                             inconvenience
9/1/2010                 GNU Autotools                              5
           Development Use Cases




9/1/2010           GNU Autotools   6
                            End User
• Expects:
     –     Executables on path
     –     Dynamic libraries where executables expect them
     –     Documentation findable and complete
     –     Software works on his or her platform
• Plus, for libraries:
     – Header files where compilers expect them
     – Libraries where linkers expect them
• Platform Requirements:
     – For libraries, compilers and linker
     – Otherwise, only basic OS services
     – Some packages may require more, e.g. a third-party library

9/1/2010                         GNU Autotools                      7
               Installer (from source)
• Expects simple, standard                   • Platform requirements:
  procedure:                                         –   Network connection
     – Download source package                       –   Gzip and tar
     – Unpack, normally with                         –   Compilers & Linker
       gunzip and tar                                –   GNU make
     – configure                                     –   Bourne-compatible shell
     – make                                          –   Maybe test tools etc.
     – make check                            • Skill requirements
     – make install
                                                     – How to run make
• Expects some flexibility:                          – What compiler options do
     –     Where installed                           – Platform software
     –     Which compilers                             installation requirements
     –     Compiler/linker options
     –     Optional features

9/1/2010                             GNU Autotools                                 8
                              Developer
• Expectations:                              • Platform Requirements:
     – Multiple configurations, single               –   Automake, autoconf, (libtool)
       code base                                     –   GNU m4, Perl 5
           • Implies: Separate source and            –   Source code control (CVS)
             build directories                       –   Probably many other tools
     – Complete set of standard              • Skills Required
       make targets (without writing                 – Software design,
       them!)                                          programming, testing,
     – Support for multiple                            debugging, source control,
           • Source directories
                                                       teamwork, planning, etc.
           • Make targets                            – Simple modifications to
                                                       Autotools input files
           • Languages
                                                     – Simple make
     – Support for non-standard tools                – Documentation
       (e.g. code generators, scripts)
                                             • Skills Not Required:
     – Automatic updating of
       #include dependencies                         – Configuration subtleties


9/1/2010                             GNU Autotools                                       9
                Autotools Overview (no libtool)
                 Under source control
Starting,             Source
occasional             files            [autoscan]     [configure.scan]     configure.ac

                  configure.ac                   autoconf             configure
Developer,
on




                                                                                        distribute
                 [acinclude.m4]                [autoheader]           [config.h.in]
development
system
                 Makefile.am                     automake
                                                                      Makefile.in

                   configure                                              Source
Installer, on                                 config.cache
                                                                           files
target             [config.h.in]               config.log
system                                                            [config.h]
                 Makefile.in                                                          make
                                            config.status        Makefile

End User                                Executables, libraries, documents, etc.
  9/1/2010                                 GNU Autotools                                         10
                        Source Distribution
                            Package
•   Makefile.in
     – Makefile with special @XX@ variables
     – One per source directory
     – Generated by automake
•   configure
     –     Bourne shell script. Substantial.
     –     One at top of directory tree
     –     Tests for platform capabilities, sets macro values, generates files (right)
     –     Generated by autoconf
•   README, AUTHORS, COPYING
     – Specific instructions for your package. You must write these!
•   aclocal.m4, config.guess, config.h.in, depcomp, install-sh, missing,
    mkinstalldirs, etc.
     – Generated automatically. Ignore them.
•   INSTALL
     – Standard instructions for building standard software. Always the same.
•   Your source files, in directory tree

9/1/2010                                  GNU Autotools                                  11
                       configure
• Bourne shell script
• Generated by autoconf, distributed with source, run on
  target computer
• Performs tests for working compilers, options, programs,
  libraries, headers, structures, functions, etc. on the target
  computer.
• Sets “output variables” and C preprocessor macro
  definitions based on tests, options, configure.am.
• Transforms input files (usually Makefile.in to Makefile) by
  substituting output variables for @XX@ placeholders.
• Writes the C macro definitions into either:
     – a header file (usually config.h) as “#define XX value”, or
     – a @DEFS@ output variable as “–DXX=value” for the Makefiles.

9/1/2010                     GNU Autotools                       12
              Files Generated by
           configure script on target computer
  • Build Tree
       – Subdirectory for each one in source tree
       – If configure is run in a separate build directory
  • Makefile from each Makefile.in
       – By substituting macro values for @XX@ variables
       – Include all GNU targets and a lot more. Huge!
  • config.h
       – Include file defining C preprocessing macros
       – Optional; macros may be defined on command lines instead
  • Config.log, config.status, maybe others
       – Ignore these unless something goes wrong during
         configuration

9/1/2010                        GNU Autotools                       13
              Running configure
• $SSTSRC/configure --help
     – Prints generic instructions, plus options added by
       developer
• mkdir sst_gcc_gpg
  cd sst_gcc_gpg
  $SSTSRC/configure CXX=g++ \
      CFLAGS=„-g -pg‟ \
      --prefix=/usr/local/sst
• Actually, I put the configure invocation into a
  config.local script, with instructions to copy it into
  each new build directory and edit it.
9/1/2010                   GNU Autotools                    14
                                       configure output
                                        (example from SST under Cygwin)
•   checking for a BSD-compatible install... /usr/bin/install -c               •   configure: creating ./config.status
•   checking whether build environment is sane... yes                          •   config.status: creating Makefile
•   checking for gawk... gawk                                                  •   config.status: creating src/Makefile
•   checking whether make sets $(MAKE)... yes                                  •   config.status: creating src/tools/Makefile
•   checking build system type... i686-pc-cygwin                               •   config.status: creating src/dsp/Makefile
•   checking host system type... i686-pc-cygwin                                •   config.status: creating src/sigproc/Makefile
•   checking for /usr/local/include/cppunit/Asserter.h... yes                  •   config.status: creating src/math/Makefile
•   checking for pdflatex... yes                                               •   config.status: creating src/sonar/Makefile
•   checking for gcc... gcc                                                    •   config.status: creating src/ocean/Makefile
•   checking for C compiler default output... a.exe                                    –    … et cetera
•   checking whether the C compiler works... yes                               •   config.status: creating src/main/Makefile
•   checking whether we are cross compiling... no                              •   config.status: creating support/Makefile
•   checking for suffix of executables... .exe                                 •   config.status: creating support/examples/Makefile
•   checking for suffix of object files... o                                   •   config.status: creating support/examples/tarmod/Makefile
•   checking whether we are using the GNU C compiler... yes                    •   config.status: creating support/JUA_Paper/Makefile
•   checking whether gcc accepts -g... yes                                     •   config.status: creating support/scripts/Makefile
•   checking for gcc option to accept ANSI C... none needed                    •   config.status: creating support/scripts/certifySST.sh
•   checking for style of include used by make... GNU                          •   config.status: creating support/scripts/webzip.sh
•   checking dependency style of gcc... gcc3                                   •   config.status: creating support/sioplot/Makefile
•   checking for gcc option to accept ANSI C... none needed                    •   config.status: creating test/Makefile
•   checking for g++... g++                                                    •   config.status: creating test/basic/Makefile
•   checking whether we are using the GNU C++ compiler... yes                  •   config.status: creating test/sim/Makefile
•   checking whether g++ accepts -g... yes                                     •   config.status: creating test/cass/Makefile
•   checking dependency style of g++... gcc3                                   •   config.status: creating test/math/Makefile
•   checking for g77... g77                                                    •   config.status: creating test/ocean/Makefile
•   checking whether we are using the GNU Fortran 77 compiler... yes           •   config.status: creating test/describe/Makefile
•   checking whether g77 accepts -g... yes                                     •   config.status: creating test/raysig/Makefile
•   checking for flex... flex                                                  •   config.status: creating config.h
•   checking for yywrap in -lfl... yes                                         •   config.status: config.h is unchanged
•   checking lex output file root... lex.yy                                    •   config.status: executing depfiles commands
•   checking whether yytext is a pointer... yes
•   checking for bison... bison -y
•   checking whether ln -s works... yes
•   checking for a BSD-compatible install... /usr/bin/install –c
      –     … and lots more like those



9/1/2010                                                               GNU Autotools                                                          15
           autoconf, autoreconf
• Input: configure.ac, which contains m4 macro
  invocations and shell commands
• Output: configure script, consisting of macro expansions
  and your shell commands
• Autoreconf runs extras too: aclocal, autoheader,
  automake, etc.
• General pattern: Each macro generates shell code to
  test whether some tool, library, or header is present and
  working. If so, it sets “output variables” and/or C macros
  to record facts needed by Makefiles etc.
• AC_OUTPUT generates code to substitute output
  variable XX for @XX@ in YY.in, generating YY

9/1/2010                  GNU Autotools                    16
            Simple configure.ac
     AC_INIT
     AC_CONFIG_SRCDIR([main/foonly.cc])
     AM_INIT_AUTOMAKE(foonly, 1.0)
     AC_PROG_CC
     AC_PROG_CXX
     AM_PROG_LEX
     AC_PROG_YACC
     AC_CONFIG_FILES([Makefile lib/Makefile \
       main/Makefile])
     AC_OUTPUT
9/1/2010                 GNU Autotools          17
                           Example configure.ac
AC_INIT                                                                           AC_LANG_PUSH(C++)
AC_CONFIG_SRCDIR([src/main/sst.cc])
AM_INIT_AUTOMAKE(sst, 2004.4)                                                     AC_HEADER_TIME
                                                                                  AC_CHECK_HEADERS(pwd.h unistd.h sys/times.h)
dnl Put the preprocessor macros in a header, not on command line
AM_CONFIG_HEADER(config.h)                                                        dnl Checks for types
                                                                                  AC_TYPE_SIZE_T
dnl Put the executables in a subdirectory of SSTHOME
AC_PREFIX_DEFAULT("${SSTHOME=/usr/local/sst}")                                    dnl Checks for structures
AC_CANONICAL_HOST                                                                 AC_STRUCT_TM
exec_prefix="${prefix}/${host}${HOST_SUFFIX}"                                     dnl SST_STRUCT_TMS defines TMS_IN_SYS_TIMES
                                                                                  dnl if struct tms is in sys/times.h
dnl data_suffix is used in share/Makefile to plant local symbolic links.          SST_STRUCT_TMS
data_suffix=`echo ${datadir} | sed 's,${prefix}/,,'`
AC_SUBST(data_suffix)                                                             AC_LANG_POP(C++)

dnl Set FLIBS to link flags enabling C++ linker to find Fortran library           dnl Checks for library functions.
AC_F77_LIBRARY_LDFLAGS                                                            AC_FUNC_MEMCMP
                                                                                  AC_FUNC_STRCOLL
dnl If the Fortran library must be initialized, pass the call and                 AC_FUNC_VPRINTF
dnl declaration from user-defined environment variables to C DEFINE's.            AC_CHECK_FUNCS(getpwnam)
if test -n "${FCINIT}"; then
         AC_DEFINE_UNQUOTED(FCINIT,${FCINIT},                                     AC_CONFIG_FILES([Makefile src/Makefile src/math/Makefile \
                     [Fortran library initialization call])                           src/ocean/Makefile src/signal/Makefile src/main/Makefile \
fi                                                                                    support/Makefile support/scripts/Makefile \
if test -n "${FCINIT_DECL}"; then                                                     support/scripts/certifySST.sh \
         AC_DEFINE_UNQUOTED(FCINIT_DECL,${FCINIT_DECL},                               test/Makefile test/basic/Makefile test/math/Makefile])
                     [Fortran library declaration])                               AC_OUTPUT
fi

dnl Checks for header files.
AC_HEADER_STDC



9/1/2010                                                                  GNU Autotools                                                            18
                                Automake
•   Inputs: configure.ac and                    •   Main program example:
    srcdir/Makefile.am                                  bin_PROGRAMS = sst
•   Output: srcdir/Makefile.in                          sst_SOURCES = sst.cc
                                                        sst_DEPENDENCIES =
     – which is later used by configure to                  ../math/libSSTmath.a
       generate objdir/Makefile                         sst_LDADD = $(sst_DEPENDENCIES)
•   Makefile.am is a Makefile …                             $(FLIBS) –lm
    except:
     – Supports include, conditionals, +=       •   Library example:
     – Special macro names are                          noinst_LIBRARIES = libSSTmath.a
       recognized                                       libSSTmath_a_SOURCES = chebyshev.c
     – Makefile.in variables: @XX@                          clairy.cc clairy.hh
     – Most of the meat is missing
•   automake creates a zillion Make
    macros and rules to do the actual
    work of building your software
     – and installing, uninstalling, testing,
       distributing, cleaning, etc.



9/1/2010                                GNU Autotools                                     19
                      Makefile.am Syntax
•   Special names per install directory:                •   Main program example:
     –     Form: dir_PRIMARY                                    bin_PROGRAMS = sst
     –     Primaries: PROGRAMS, LIBRARIES,                      sst_SOURCES = sst.cc
           LTLIBRARIES, DATA, HEADERS,                          sst_DEPENDENCIES = ../math/libSSTmath.a
           SCRIPTS, MANS, TEXINFOS                              sst_LDADD = $(sst_DEPENDENCIES) $(FLIBS)
                                                                    –lm
     –     Directories: bin, lib, include, man1, etc.
     –     Pseudo-directories: noinst check
•   Special names per target                            •   Library example:
                                                                noinst_LIBRARIES = libSSTmath.a
     –     Form: target_PRIMARY                                 libSSTmath_a_SOURCES = chebyshev.c
     –     Primaries: SOURCES,                                      clairy.cc clairy.hh
           DEPENDENCIES, LDADD, LDFLAGS,
           LIBADD
     –     Targets: Names from PROGRAMS etc.
     –     Absent target means all targets              •   Non-special Make macros and rules
•   Global special name:                                    simply pass through.
     –     AUTOMAKE_OPTIONS
•   Make macros used in rules:
     –     SUBDIRS, EXTRA_DIST, lots more




9/1/2010                                        GNU Autotools                                         20
           GNU Makefile Standards
                              http://www.fsf.org
• Targets                                   • Variables
     – all                                          – AR, BISON, CC, FLEX,
     – install, uninstall, install-strip              INSTALL, LD, LDCONFIG,
     – clean, distclean, mostlyclean,                 LEX, MAKE, MAKEINFO,
       maintainer-clean                               RANLIB, TEXI2DVI, YACC
     – TAGS                                         – INSTALL,
                                                      INSTALL_PROGRAM,
     – info, dvi                                      INSTALL_DATA
     – dist                                         – prefix, exec_prefix, bindir,
     – check, installcheck, installdirs               sbindir, libexecdir, datadir,
                                                      sysconfdir, sharedstatedir,
                                                      localstatedir, libdir, infodir,
• Most projects need others too                       lispdir, includedir,
                                                      oldincludedir, mandir, man1dir
                                                      (etc.)
                                                    – manext, man1ext (etc.)
                                                    – srcdir


9/1/2010                            GNU Autotools                                  21
             Makefile.am: Top level
AUTOMAKE_OPTIONS = foreign no-installman no-installinfo

SUBDIRS = src support test
EXTRA_DIST = arwrap config.local mdwrap sstDoxy.config

# Use doxygen to document source code in these directories
DOXY_SUBDIRS = src

# This target builds the html doxygen files and leaves
# each generated tree (named html) under each leaf subdirectory
doxy: doxy-recursive

doxy-recursive:
   list='$(DOXY_SUBDIRS)'; for subdir in $$list; do \
     test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) doxy); \
   done



9/1/2010                            GNU Autotools                              22
                 Makefile.am: Library
AUTOMAKE_OPTIONS = foreign \                   # Look here to find include files
   no-installman no-installinfo                INCLUDES = -I$(srcdir)/..

noinst_LIBRARIES = libSSTmath.a                EXTRA_PROGRAMS = clairy_test
                                               clairy_test_SOURCES = clairy_test.cc
libSSTmath_a_SOURCES = \                       clairy_test_DEPENDENCIES = clairy.o
clairy.cc \                                    clairy_test_LDADD = clairy.o
clairy.hh \
Function2.cc \                                 # Remove Sun Forte's template database
Function2.hh                                   clean-local:
# … et cetera                                      -rm -fr SunWS_cache

# These are included only if they are in       # Generate the Doxygen documentation
# MATHOBJS, where configure put them if they   DOCNAME = math
# aren't in the system math library.           DOCSRC = $(libSSTmath_a_SOURCES)
EXTRA_libSSTmath_a_SOURCES = \                 DOCDEPS = sigproc describe sim
    erf.c j1.c lgamma.c
libSSTmath_a_LIBADD = @MATHOBJS@               include $(srcdir)/../tools/doxy.make
libSSTmath_a_DEPENDENCIES= \
    @MATHOBJS@


9/1/2010                               GNU Autotools                                    23
           Makefile.am: Main program
AUTOMAKE_OPTIONS = foreign \                 track2traj_SOURCES = track2traj.cc
   no-installman no-installinfo              track2traj_LDADD = -lm

bin_PROGRAMS = sst track2traj                # Look here to find include files
                                             INCLUDES = -I$(top_srcdir)/src/
sst_SOURCES = sst.cc
                                             # Remove Sun Forte's template database
sst_DEPENDENCIES = \                         clean-local:
    ../symbol/libSSTsymbol.a \                   -rm -fr SunWS_cache
    ../language/libSSTlanguage.a \
    ../describe/libSSTdescribe.a \           # Generate the Doxygen documentation
    ../signal/libSSTsignal.a \               DOCNAME = sst
    @CASS_LIB@ \                             DOCSRC = $(sst_SOURCES)
    @GSM_LIB@ \                              DOCDEPS = symbol cass gsm ocean \
    ../ocean/libSSTocean.a \                     sonar signal math language describe
    ../sonar/libSSTsonar.a \
    ../math/libSSTmath.a                     include $(srcdir)/../tools/doxy.make

sst_LDADD = $(sst_DEPENDENCIES) $(FLIBS)



9/1/2010                             GNU Autotools                                     24
                            Libtool
• Problem: Dynamic libraries differ by system
     –     Naming conventions
     –     Versioning
     –     Commands for creating them
     –     Compiler options required (e.g. position-independent
           code)
• Solution:
     – Wrap platform-specific tools in a script
     – Generate the script as output from configure
     – Modify generated Makefiles to call the script
9/1/2010                      GNU Autotools                       25
           configure.ac for libtool
• Required:
     – AC_PROG_LIBTOOL
• Optional:
     – AC_DISABLE_SHARED
     – AC_DISABLE_STATIC
     – AC_DISABLE_FAST_INSTALL




9/1/2010            GNU Autotools     26
            Makefile.am for libtool
• Building a static library without libtool:
     – lib_LIBRARIES = libshell.a
     – libshell_a_SOURCES = object.c subr.c symbol.c
• Building a library with libtool:
     – lib_LTLIBRARIES = libshell.la
     – libshell_la_SOURCES = object.c subr.c symbol.c
• Linking an executable with libtool:
     – bin_PROGRAMS = shell
     – shell_SOURCES = shell.c token.l
     – shell_LDADD = libshell.la
• Static vs. dynamic controlled by LDFLAGS macro


9/1/2010                     GNU Autotools              27
                          Advice
• If your project is sufficiently simple, it‟s not worth it! Stop
  here! (See “Who Needs Autotools” slide.)
• Start with the simplest possible configure.ac and
  Makefile.am. Make it work on one primary system.
• Run autoscan for hints only. Look up the macros that it
  suggests. Add them one at a time if they seem relevant.
• Add complications only if portability problems arise.
• The documentation is essential! Fortunately, it‟s also
  pretty good.
• Iterate and persevere. For complex projects, you will be
  glad you did.

9/1/2010                    GNU Autotools                       28

								
To top