Embedded Linux Conference 2016

GNU Autotools: a tutorial

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 1/99
 Thomas Petazzoni

I CTO and Embedded Linux engineer at Free Electrons

I Embedded Linux specialists.
I Development, consulting and training.
I [Link]
I Contributions
I Kernel support for the Marvell Armada ARM SoCs
from Marvell
I Major contributor to Buildroot, an open-source, simple
and fast embedded Linux build system
I Living in Toulouse, south west of France

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 2/99
 When talking about autotools, most people think:

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 3/99
 When talking about autotools, most people think:

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 3/99
 When talking about autotools, most people think:

But this is a German book, really about the autotools!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 3/99
 Autotools, why?

I Yes, the autotools are old

I Yes, they have their pain points
I Yes, people hate them
I Due to this, people tend to roll-their-own, and roll-their-own build systems tend to
be even worse than the autotools
I But
I They bring a number of very useful benefits
I They are not that complicated when you take the time to get back to the basics

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 4/99
 Autotools: benefits

I Standardized build procedure and behavior: users know how to build things that
use the autotools
I Good for human users, but also for build systems
I Proper handling for diverted installation
I I.e. build with prefix=/usr, but divert the installation to another directory. Needed
for cross-compilation.
I Built-in support for out-of-tree build
I Built-in handling of dependencies on header files
I Support for cross-compilation aspects
I Somewhat esoteric, but standardized languages used
I Learn once, use for many projects
I New contributors are more likely to know the autotools than your own custom thing
I Of course, there are alternatives, CMake being the most interesting and widely
used.
Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 5/99
 Disclaimer

I I am not an autotools expert

I I don’t know the internals of autotools, only their usage
I This tutorial will only cover the basics aspects
I Sufficient to understand the autoconf/automake documentation
I Sufficient to understand most existing build systems
I Won’t cover many advanced aspects

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 6/99
 Autotools tutorial: agenda

1. User point of view

2. autoconf basics
3. automake basics
4. autoconf advanced
5. automake advanced

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 7/99
 User point of view

Free Electrons

User point of view Embedded Linux

Developers

Thomas Petazzoni

© Copyright 2004-2016, Free Electrons.

Creative Commons BY-SA 3.0 license.
Corrections, suggestions, contributions and translations are welcome!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 8/99
 Using autotools based packages

I The basic steps to build an autotools based software component are:

1. Configuration
./configure
Will look at the available build environment, verify required dependencies, generate
Makefiles and a config.h
2. Compilation
make
Actually builds the software component, using the generated Makefiles.
3. Installation
make install
Installs what has been built.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 9/99
 What is configure doing?

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 10/99
 Standard Makefile targets

I all, builds everything. The default target.

I install, installs everything that should be installed.
I install-strip, same as install, but then strips debugging symbols
I uninstall
I clean, remove what was built
I distclean, same as clean, but also removes the generated autotools files
I check, run the test suite
I installcheck, check the installation
I dist, create a tarball

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 11/99
 Standard filesystem hierarchy

I prefix, defaults to /usr/local

I exec-prefix, defaults to prefix
I bindir, for programs, defaults to exec-prefix/bin
I libdir, for libraries, defaults to exec-prefix/lib
I includedir, for headers, defaults to prefix/include
I datarootdir, defaults to prefix/share
I datadir, defaults to datarootdir
I mandir, for man pages, defaults to datarootdir/man
I infodir, for info documents, defaults to datarootdir/info
I sysconfdir, for configuration files, defaults to prefix/etc
I --<option> available for each of them
I E.g: ./configure --prefix=~/sys/

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 12/99
 Standard configuration variables

I CC, C compiler command

I CFLAGS, C compiler flags
I CXX, C++ compiler command
I CXXFLAGS, C++ compiler flags
I LDFLAGS, linker flags
I CPPFLAGS, C/C++ preprocessor flags
I and many more, see ./configure --help
I E.g: ./configure CC=arm-linux-gcc

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 13/99
 System types: build, host, target

I autotools identify three system types:

I build, which is the system where the build takes place
I host, which is the system where the execution of the compiled code will take place
I target, which is the system for which the program will generate code. This is only
used for compilers, assemblers, linkers, etc.
I Corresponding --build, --host and --target configure options.
I They are all automatically guessed to the current machine by default
I --build, generally does not need to be changed
I --host, must be overridden to do cross-compilation
I --target, needs to be overridden if needed (to generate a cross-compiler, for
example)
I Arguments to these options are configuration names, also called system tuples

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 14/99
 System type: native compilation example

Demo
(based on the kmod source code)

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 15/99
 Cross-compilation

I By default, autotools will guess the host machine as being the current machine
I To cross-compile, it must be overridden by passing the --host option with the
appropriate configuration name
I By default, autotools will try to use the cross-compilation tools that use the
configuration name as their prefix.
I If not, the variables CC, CXX, LD, AR, etc. can be used to point to the
cross-compilation tools.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 16/99
 Out of tree build

I autotools support out of tree compilation by default

I Consists in doing the build in a directory separate from the source directory
I Allows to:
I Build different configurations without having to rebuild from scratch each time.
I Not clutter the source directory with build related files
I To use out of tree compilation, simply run the configure script from another
empty directory
I This directory will become the build directory

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 17/99
 Out of tree build: example

Demo

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 18/99
 Diverted installation with DESTDIR

I By default, make install installs to the directories given in --prefix and

related options.
I In some situations, it is useful to divert the installation to another directory
I Cross-compilation, where the build machine is not the machine where applications
will be executed.
I Packaging, where the installation needs to be done in a temporary directory.
I Achieved using the DESTDIR variable.
Demo!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 19/99
 --prefix or DESTDIR ?

I --prefix and DESTDIR are often misunderstood

I --prefix is the location where the programs/libraries will be placed when
executed on the host machine
I DESTDIR is a way of temporarily diverting the installation to a different location.
I For example, if you use --prefix=/home/<foo>/sys/usr, then binaries/libraries
will look for icons in /home/<foo>/sys/usr/share/icons
I Good for native installation in /home/<foo>/sys
I Bad for cross-compilation where the binaries will ultimately be in /usr

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 20/99
 --prefix or DESTDIR use cases

I Native compilation, install system-wide in /usr

$ ./configure --prefix=/usr
$ make
$ sudo make install

I Native compilation, install in a user-specific directory:

$ ./configure --prefix=/home/<foo>/sys/
$ make
$ make install

I Cross-compilation, install in /usr, diverted to a temporary directory where the

system for the target is built
$ ./configure --prefix=/usr
$ make
$ make DESTDIR=/home/<foo>/target-rootfs/ install

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 21/99
 Analyzing issues

I autoconf keeps a log of all the tests it runs in a file called [Link]
I Very useful for analysis of autoconf issues
I It contains several sections: Platform, Core tests, Running [Link], Cache
variables, Output variables, confdefs.h
I The end of the Core tests section is usually the most interesting part
I This is where you would get more details about the reason of the configure script
failure
I At the beginning of [Link] you can also see the ./configure line that was
used, with all options and environment variables.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 22/99
 autotools: autoconf and automake

I The configure script is a shell script generated from [Link] by a

program called autoconf
I [Link] used to be named [Link] but this name is now deprecated
I Written in shell script, augmented with numerous m4 macros
I The [Link] are generated from [Link] files by a program called
automake
I Uses special make variables that are expanded in standard make constructs
I Some auxilliary tools like autoheader or aclocal are also used
I autoheader is responsible for generating the configuration header template,
[Link]
I Generated files (configure, [Link], Makefile) should not be modified.
I Reading them is also very difficult. Read the real source instead!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 23/99
 Overall organization

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 24/99
 Cache variables

I Each test done by a [Link] script is associated with a cache variable

I The list of such variables and their values is visible in [Link]:
## ---------------- ##
## Cache variables. ##
## ---------------- ##
ac_cv_build=x86_64-unknown-linux-gnu
ac_cv_c_compiler_gnu=yes
[...]
ac_cv_path_SED=/bin/sed

I If the autodetected value is not correct for some reason, you can override any of
these variables in the environment:
$ ac_cv_path_SED=/path/to/sed ./configure

I This is sometimes useful when cross-compiling, since some tests are not always
cross-compilation friendly.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 25/99
 Distribution

I In general:
I When a software is published as a tarball, the configure script and [Link]
files are already generated and part of the tarball.
I When a software is published through version control system, only the real sources
[Link] and [Link] are available.
I There are some exceptions (like tarballs not having pre-generated
configure/[Link])
I Do not version control generated files!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 26/99
 Regenerating autotools files: autoreconf

I To generate all the files used by autotools, you could call automake, autoconf,
aclocal, autoheader, etc. manually.
I But it is not very easy and efficient.
I A tool called autoreconf automates this process
I Useful option: -i or --install, to ask autoreconf to copy missing auxiliary files
I Always use autoreconf!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 27/99
 autoconf basics

Free Electrons

autoconf basics Embedded Linux

Developers

Thomas Petazzoni

© Copyright 2004-2016, Free Electrons.

Creative Commons BY-SA 3.0 license.
Corrections, suggestions, contributions and translations are welcome!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 28/99
 [Link] language

I Really a shell script

I Processed through the m4 preprocessor
I Shell script augmented with special constructs for portability:
I AS_IF instead of shell if ... then .. fi
I AS_CASE instead of shell case ... esac
I etc.
I autoconf provides a large set of m4 macros to perform most of the usual tests
I Make sure to quote macro arguments with []

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 29/99
 Minimal [Link]

[Link]
AC_INIT([hello], [1.0])
AC_OUTPUT

I AC_INIT
I Every configure script must call AC_INIT before doing anything else that produces
output.
I Process any command-line arguments and perform initialization and verification.
I Prototype:
AC_INIT (package, version, [bug-report], [tarname], [url])
I AC_OUTPUT
I Every [Link], should finish by calling AC_OUTPUT.
I Generates and runs [Link], which in turn creates the makefiles and any
other files resulting from configuration.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 30/99
 Minimal [Link] example

Demo 01

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 31/99
 Additional basic macros

I AC_PREREQ
I Verifies that a recent enough version of autoconf is used
I AC_PREREQ([2.68])
I AC_CONFIG_SRCDIR
I Gives the path to one source file in your project
I Allows autoconf to check that it is really where it should be
I AC_CONFIG_SRCDIR([hello.c])
I AC_CONFIG_AUX_DIR
I Tells autoconf to put the auxiliary build tools it requires in a different directory,
rather than the one of [Link]
I Useful to keep cleaner build directory

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 32/99
 Additional basic macros

Demo 02

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 33/99
 Checking for basic programs

I AC_PROG_CC, makes sure a C compiler is available

I AC_PROG_CXX, makes sure a C++ compiler is available
I AC_PROG_AWK, AC_PROG_GREP, AC_PROG_LEX, AC_PROG_YACC, etc.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 34/99
 Checking for basic programs: example

Demo 03

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 35/99
 AC CONFIG FILES

I AC_CONFIG_FILES (file..., [cmds], [init-cmds])

I Make AC_OUTPUT create each file by copying an input file (by default [Link]),
substituting the output variable values.
I Typically used to turn the Makefile templates [Link] files into final
Makefile.
I Example:
AC_CONFIG_FILES([Makefile src/Makefile])
I cmds and init-cmds are rarely used, see the autoconf documentation for details.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 36/99
 Output variables

I autoconf will replace @variable@ constructs by the appropriate values in files

listed in AC_CONFIG_FILES
I Long list of standard variables replaced by autoconf
I Additional shell variables declared in [Link] can be replaced using
AC_SUBST
I The following three examples are equivalent:

AC_SUBST([FOO], [42])

FOO=42
AC_SUBST([FOO])

AC_SUBST([FOO])
FOO=42
Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 37/99
 AC CONFIG FILES example

Demo 04

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 38/99
 [Link]: a shell script

I It is possible to include normal shell constructs in [Link]

I Beware to not use bashisms: use only POSIX compatible constructs
I Most configure scripts use directly shell constructs, but AS_ECHO, AS_IF, etc. are
available.

Demo 05 and 05b

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 39/99
 Writing [Link]?

I At this point, we have seen the very basics of autoconf to perform the
configuration side of our software
I We could use AC_CONFIG_FILES to generate Makefile from [Link]
I However, writing a [Link] properly is not easy, especially if you want to:
I be portable
I automatically handle dependencies
I support conditional compilation, out-of-tree build, diverted installation,
cross-compilation, etc.
I For these reasons, [Link] are typically not written manually, but generated
by automake from a [Link] file

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 40/99
 automake basics

Free Electrons

automake basics Embedded Linux

Developers

Thomas Petazzoni

© Copyright 2004-2016, Free Electrons.

Creative Commons BY-SA 3.0 license.
Corrections, suggestions, contributions and translations are welcome!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 41/99
 [Link] language

I Really just a Makefile

I You can include regular make code
I Augmented with automake specific constructs that are expanded into regular
make code
I For most situations, the automake constructs are sufficient to express what needs
to be built

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 42/99
 [Link] minimal example

I The minimal example of [Link] to build just one C file into a program is
only two lines:

[Link]
bin_PROGRAMS = hello
hello_SOURCES = main.c

I Will compile main.c to main.o

I And link hello.o into the hello executable
I Which will be installed in $prefix/bin

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 43/99
 Enabling automake in [Link]

I To enable automake usage in [Link], you need:

I A call to AM_INIT_AUTOMAKE
I Generate the Makefile using AC_CONFIG_FILES
I automake will generate the [Link] at autoreconf time, and configure will
generate the final Makefile

[Link]
AC_INIT([hello], [1.0])
AM_INIT_AUTOMAKE([foreign 1.13])
AC_PROG_CC
AC_CONFIG_FILES([Makefile])
AC_OUTPUT

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 44/99
 First automake demo

Demo 06

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 45/99
 AM INIT AUTOMAKE

I AM_INIT_AUTOMAKE([OPTIONS])
I Interesting options:
I foreign, tells automake to not require all the GNU Coding Style files such as NEWS,
README, AUTHORS, etc.
I dist-bzip2, dist-xz, etc. tell automake which tarball format should be generated
by make dist
I subdir-objects tells automake that the objects are placed into the subdirectory of
the build directory corresponding to the subdirectory of the source file
I version, e.g 1.14.1, tells the minimal automake version that is expected

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 46/99
 [Link] syntax

I An automake parsable [Link] is composed of product list variables:

bin_PROGRAMS = hello
I And product source variables:

hello_SOURCES = main.c

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 47/99
 Product list variables

[modifier-list]prefix_PRIMARY = product1 product2 ...

I prefix is the installation prefix, i.e. where it should be installed

I All *dir variables from autoconf can be used, without their dir suffix: use bin for
bindir
I E.g.: bindir, libdir, includedir, datadir, etc.
I PRIMARY describes what type of things should be built:
I PROGRAMS, for executables
I LIBRARIES, LTLIBRARIES, for libraries
I HEADERS, for publicly installed header files
I DATA, arbitrary data files
I PYTHON, JAVA, SCRIPTS
I MANS, TEXINFOS, for documentation
I After the = sign, list of products to be generated

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 48/99
 Product source variables

[modifier-list]product_SOURCES = file1 file2 ...

I The product is the normalized name of the product, as listed in a product list
variable
I The normalization consists in replacing special characters such as . or + by _. For
example, libfoo+.a in a product list variable gives the libfoo__a_SOURCES
product source variable.
I _SOURCES is always used, it’s not like a configurable primary.
I Contains the list of files containing the source code for the product to be built.
I Both source files and header files should be listed.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 49/99
 More complicated automake example

Demo 07

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 50/99
 autoconf advanced

Free Electrons

autoconf advanced Embedded Linux

Developers

Thomas Petazzoni

© Copyright 2004-2016, Free Electrons.

Creative Commons BY-SA 3.0 license.
Corrections, suggestions, contributions and translations are welcome!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 51/99
 Configuration header

I Very often, C/C++ code needs to know the result of certain tests done by the
configure script.
I A template C header file can be automatically generated by autoheader,
generally named [Link]
I The final header file is generated by configure, generally named config.h
I Declared using AC_CONFIG_HEADERS
[Link] extract
AC_CONFIG_HEADERS([config.h])

Example config.h
/* Define if the complete vga libraries (vga, vgagl) are installed */
/* #undef HAVE_LIBVGA */

/* Define to 1 if you have the <limits.h> header file. */

#define HAVE_LIMITS_H 1

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 52/99
 AC DEFINE

I AC_DEFINE allows to create C definitions in the configuration header

I AC_DEFINE (variable, value, description)

[Link]
AC_DEFINE([FOOBAR], [42], [This is the foobar value])

Demo 08

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 53/99
 Checking for functions

I You may need to check if certain functions are available and/or meet certain
characteristics
I Family of AC_FUNC_* macros
I AC_FUNC_FORK, AC_FUNC_GETLOADAVG, AC_FUNC_MALLOC, etc.
I See autoconf manual for details
I AC_CHECK_FUNC[S] to check for generic functions
I AC_CHECK_FUNC (function, [action-if-found], [action-if-not-found])
I AC_CHECK_FUNCS (function..., [action-if-found], [action-if-not-
found])
I Results available
I ac_cv_func_<function> variable in [Link]
I HAVE_<FUNCTION> defines in configuration headers

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 54/99
 AC CHECK FUNCS() example

Demo 09

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 55/99
 Checking for headers

I Much like AC_FUNC_* and AC_CHECK_FUNC[S], but for headers

I Variety of AC_HEADER_* macros
I Check the autoconf manual for details
I AC_CHECK_HEADER[S] for generic headers checking
I AC_CHECK_HEADER (header-file, [action-if-found], [action-if-not-
found], [includes])
I AC_CHECK_HEADERS (header-file..., [action-if-found], [action-if-
not-found], [includes])
I Results available in:
I ac_cv_header_<header-file> variable in [Link]
I HAVE_<HEADER>_H define in config.h

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 56/99
 AC CHECK HEADERS example

[Link]
[...]
AC_CHECK_HEADERS([spawn.h],
[echo "Header spawn.h was found"; has_spawn=yes],
[echo "Header spawn.h was not found"])
echo ${has_spawn}
[...]

Execution of ./configure
$ ./configure
[...]
checking for spawn.h... yes
Header spawn.h was found
yes
[...]

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 57/99
 Checking for libraries

AC_SEARCH_LIBS (function, search-libs,

[action-if-found], [action-if-not-found],
[other-libraries])

I Search for a library defining function, by linking a simple program calling

function
I Tries first with no library, and then with the different libraries in search-libs,
one after the other.
I If a library is found, -llibrary is prepended to the LIBS variable, so programs
will be linked against it. action-if-found is executed.
I If not, action-if-not-found is executed
I other-libraries allows to pass additional -l<foo> arguments that may be
needed for the link test to succeed.
I Result in ac_cv_search_<function>
Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 58/99
 AC SEARCH LIBS example

Demo 10

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 59/99
 Other checks

I Programs with AC_CHECK_PROGS

I AC_CHECK_PROGS(PERL, [perl5 perl])
I Declarations with AC_CHECK_DECLS
I Structure members with AC_CHECK_MEMBERS
I Types with AC_CHECK_TYPES
I AC_CHECK_TYPES(int8_t)
I See the autoconf manual for details

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 60/99
 Writing new tests

I You can create your own tests by pre-processing, compiling or linking small test
programs:
I Pre-processing test
AC_PREPROC_IFELSE (input, [action-if-true], [action-if-false])
I Compiling test
AC_COMPILE_IFELSE (input, [action-if-true], [action-if-false])
I Link test
AC_LINK_IFELSE (input, [action-if-true], [action-if-false])
I Input should be formatted with AC_LANG_SOURCE or AC_LANG_PROGRAM
I Runtime tests can also be created
I Beware, by nature, they cannot work for cross-compilation!
I AC_RUN_IFELSE

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 61/99
 Writing new tests: AC LINK IFELSE

Demo 11

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 62/99
 Printing messages

I When creating new tests, you may want to show messages, warnings, errors, etc.
I AC_MSG_CHECKING (feature-description)
I Notify the user that configure is checking for a particular feature.
I AC_MSG_RESULT (result-description)
I Notify the user of the results of a check
I AC_MSG_NOTICE (message)
I Deliver the message to the user.
I AC_MSG_ERROR (error-description, [exit-status = $?/1])
I Notify the user of an error that prevents configure from completing.
I AC_MSG_WARN (problem-description)
I Notify the configure user of a possible problem.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 63/99
 Printing messages: example

Demo 11 continued

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 64/99
 Cache variables

I Each test done by autoconf is normally associated to a cache variable.

I Allows to speed-up the configure step by passing a cache file with pre-defined values.
I Allows to override the results of tests if they are not correct for some reason
I AC_CACHE_VAL(cache-id, commands-to-set-it), runs commands if cache-id
is not already set. commands must set the cache-id variable and have no
side-effect.
I AC_CACHE_CHECK(message, cache-id, commands), wrapper around
AC_CACHE_VAL to print the message.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 65/99
 Cache variables demo

Demo 11 further continued

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 66/99
 Using external software

I When a package uses external software, --with-<package>=<arg> and

--without-<package> options are generally offered to control usage of the
external software.
I Implemented using the AC_ARG_WITH macro.

AC_ARG_WITH (package, help-string,

[action-if-given], [action-if-not-given])

I package gives the name of the option

I help-string is the help text, visible in ./configure --help
I action-if-given is executed when the option is used, either positively (--with)
or negatively (--without)
I action-if-not-given is executed when the option is not used
I <arg> available as $withval inside action-if-given, $with_<package> outside.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 67/99
 Package options

I When a package offers optional features, --enable-<feature> and

--disable-<feature> options are generally offered to control the optional
feature.
I Implemented using the AC_ARG_ENABLE macro.

AC_ARG_ENABLE (feature, help-string,

[action-if-given], [action-if-not-given])

I Usage very similar to the one of AC_ARG_WITH

I Value available as $enableval inside action-if-given, $enable_<feature>
outside.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 68/99
 Formatting the help string

I To help formatting the help string, autoconf provides the AS_HELP_STRING macro
I Allows to properly align the different options in the ./configure --help output

AS_HELP_STRING (left-hand-side, right-hand-side,

[indent-column = '26'], [wrap-column = '79'])

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 69/99
 AC ARG ENABLE example

Demo 12

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 70/99
 Using pkg-config with autoconf

I To find libraries, a much better solution than AC_SEARCH_LIBS is to use

pkg-config
I pkg-config is a database of small text files, using the .pc extension, describing
how to use a given library
I installed in usr/lib/pkgconfig on most systems
I installed by most modern libraries
I The pkg-config command line tool allows to query this database for the
compiler and linker flags needed to use a given library.
I The PKG_CHECK_MODULES autoconf macro allows to query the pkg-config
database.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 71/99
 The PKG CHECK MODULES macro

I Syntax:

PKG_CHECK_MODULES(prefix, list-of-modules,
action-if-found, action-if-not-found)
I prefix will be used to create the <prefix>_CFLAGS and <prefix>_LIBS
variables
I Contain the pre-processor and linker flags to use the libraries listed in
list-of-modules
I Are already AC_SUBSTed, so can be used directly in [Link]
I list-of-modules is one or several pkg-config libraries
I Can contain version specifiers, such as foo >= 3 bar baz <= 4
I Will exit with a failure if one of the dependencies is missing.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 72/99
 PKG CHECK MODULES example

Demo 13

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 73/99
 autoscan

I autoscan is a program provided together with autoconf

I Scans the source tree in the current directory (or the one passed as argument)
I From that, autoscan:
I Searches the source files for common portability problems
I Checks for incompleteness of the [Link] file, if any
I Generates [Link], which can be used as a preliminary [Link]

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 74/99
 Additional m4 macros

I The core autoconf macros are installed in /usr/share/autoconf/autoconf/

I Additional macros can be installed by other packages in /usr/share/aclocal
I Examples: pkg.m4 (for pkg-config), gpg-error.m4, iconv.m4, etc.
I The GNU Autoconf Archive is a collection of more than 500 macros for
autoconf
I [Link]
I Example: AX_C_LONG_LONG, Provides a test for the existence of the long long int
type and defines HAVE LONG LONG if it is found.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 75/99
 autoconf-archive example

Demo 14

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 76/99
 automake advanced

Free Electrons

automake advanced Embedded Linux

Developers

Thomas Petazzoni

© Copyright 2004-2016, Free Electrons.

Creative Commons BY-SA 3.0 license.
Corrections, suggestions, contributions and translations are welcome!

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 77/99
 Subdirectories

I A project is often organized with multiple directories

I automake offers two options to support this:
I recursive make, where a sub-call to make is made for sub-directories, and each
directory has its own [Link]
I non-recursive make, where there is a single [Link], building everything
I recursive make used to be the norm, but has significant drawbacks
I Performance for parallel building
I Recursive make considered harmful,
[Link]
I non-recursive make is more and more commonly used in modern projects
I If the [Link] grows too large, one can use include to split it.

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 78/99
 Recursive make

I The SUBDIRS variable in a [Link] indicates the sub-directories that contain

other [Link]

[Link]
AC_CONFIG_FILES([Makefile src/Makefile])

[Link]
SUBDIRS = src

src/[Link]
bin_PROGRAMS = hello
hello_SOURCES = main.c

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 79/99
 Non-recursive make

I The AM_INIT_AUTOMAKE macro accepts a subdir-objects argument

I If specified, allows a [Link] to reference code in another directory

[Link]
AM_INIT_AUTOMAKE([subdir-objects])
AC_CONFIG_FILES([Makefile])

[Link]
bin_PROGRAMS = hello
hello_SOURCES = src/main.c

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 80/99
 automake subdirectories: demo

Demo 15 and 16

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 81/99
 automake conditionals

I In order to use a conditional in a [Link], it must be defined in the

[Link] script.
I Done using the AM_CONDITIONAL(conditional, condition) macro

[Link]
AM_CONDITIONAL([DEBUG], [test "${debug}" = "true"])

[Link]
if DEBUG
...
else
...
endif

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 82/99
 Usage of automake conditionals

You cannot use You should instead use an

conditionals inside a intermediate variable Or the += assigment sign
variable definition Working example Working example
bin_PROGRAMS = \
Non-working example if DEBUG
bar \
DEBUG_PROGS = baz
bin_PROGRAMS = \ endif foobar
bar \
if DEBUG bin_PROGRAMS = \ if DEBUG
baz \ bar \ bin_PROGRAMS += baz
endif $(DEBUG_PROGS) \ endif
foobar foobar

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 83/99
 Conditional example

Demo 17

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 84/99
 Building shared libraries

I Building shared libraries is very different between Unix variants

I A specific tool, called libtool, was created to abstract away the differences
between platforms.
I Concept called libtool libraries, using the .la suffix
I A libtool library can designate a static library, a shared library, or both.
I --{enable,disable}-{static,shared} to select
I Libtool libraries declared using the LTLIBRARIES primary in a [Link]
I Typically used in conjunction with the HEADERS primary to install public headers.
I [Link] must call the LT_PREREQ and LT_INIT macros

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 85/99
 Libtool library example

[Link]
[...]
LT_PREREQ([2.4])
LT_INIT
[...]

[Link]
bin_PROGRAMS = hello
hello_SOURCES = src/main.c

lib_LTLIBRARIES = [Link]
libmyhello_la_SOURCES = lib/core.c
include_HEADERS = lib/myhello.h

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 86/99
 Libtool versioning

I Needed to support changes in the library interface

I Each system handles library versioning differently
I libtool does not use the traditional <major>.<minor>.<revision>
I It uses a more abstract representation, converted differently depending on the
system on which you’re building.
I libtool representation is <current>:<revision>:<age>
I current is the interface number, incremented whenever the public interface changes
I revision is incremented whenever the library source code is changed
I age is incremented when new functions are added, reset to 0 when functions are
removed
I Defined using -version-info <current>:<revision>:<age> in
<product>_LDFLAGS

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 87/99
 Libtool: demo

Demo 18

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 88/99
 Global automake variables

I Variables that you can define in [Link]

I Apply to the current [Link]
I Affect all products described in the current [Link]
I AM_CPPFLAGS, default pre-processor flags
I AM_CFLAGS, default compiler flags
I AM_LDFLAGS, default linker flags
I LDADD, libraries not detected by configure that we should link with
I Do not set CPPFLAGS, CFLAGS and LDFLAGS, so that they can be passed in the
environment by users

Example
LDADD = $(top_builddir)/glib/[Link]
AM_CPPFLAGS = $(gmodule_INCLUDES) $(GLIB_DEBUG_FLAGS)
AM_CFLAGS = -g

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 89/99
 Per product variables

I <product>_SOURCES, list of source files

I <product>_LDADD, libraries to link with
I <product>_CPPFLAGS, pre-processor flags, overrides AM_CPPFLAGS
I <product>_CFLAGS, compiler flags, overrides AM_CFLAGS
I <product>_LDFLAGS, linker flags, overrides AM_LDFLAGS

Example
LDADD = $(top_builddir)/glib/[Link]

module_test_LDADD = $(top_builddir)/gmodule/[Link] $(LDADD)

module_test_LDFLAGS = $(G_MODULE_LDFLAGS)
slice_threadinit_LDADD = $(top_builddir)/gthread/[Link] $(LDADD)

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 90/99
 Useful variables

I Autoconf provides several variables that can be useful in your [Link]:

I top_srcdir, the relative path to the top of the source tree
I srcdir, the relative path to the directory that contains the current Makefile
I top_builddir, the relative path to the top of the build tree
I builddir, the current directory
I abs_top_srcdir, abs_srcdir, abs_top_builddir, abs_builddir, absolute
variants of the previous variables
I Example usage: library code in lib/, header files in include/:
lib/[Link]
lib_LTLIBRARIES = [Link]
libhello_la_SOURCES = ...
libhello_la_CPPFLAGS = -I$(top_srcdir)/include

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 91/99
 Demo 19

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 92/99
 Silent rules

I By default, automake generate Makefiles that displays the full compilation

commands
I Using the AM_SILENT_RULES, you can get a slimmer build output
I By default, the output remains verbose, but can be silenced by passing the V=0
variable.
I If AM_SILENT_RULES([yes]) is used, the output is quiet by default, and verbose
if V=1 is passed.

$ make
CC lib/[Link]
CCLD [Link]
CC src/main.o
CCLD hello
$ make V=1
[...]
libtool: link: (cd ".libs" && rm -f "[Link].0" && ln -s "[Link].0.0.0" ...
libtool: link: (cd ".libs" && rm -f "[Link]" && ln -s "[Link].0.0.0" ...
libtool: link: ar cru .libs/libmyhello.a lib/core.o
libtool: link: ranlib .libs/libmyhello.a
[...]

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 93/99
 Demo 20

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 94/99
 make dist

I make dist generates a tarball to release the software

I All files listed in _SOURCES variables are automatically included, as well as the
necessary autotools files
I Additional files can be added to the distribution using the EXTRA_DIST variable in
[Link]:
[Link]
# These files are used in the preparation of a release
EXTRA_DIST += \
PrepareRelease \
CheckMan \
CleanTxt \
[...]

I Distribution can also be controlled using the dist and nodist automake product
modifiers:
[Link]
nodist_include_HEADERS += pcrecpparg.h
dist_doc_DATA = doc/[Link]

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 95/99
 Macro directory

I By default, all the third-party autoconf macros get copied into the (very large)
aclocal.m4 file.
I It is possible to get some of the third-party macros copied to individiual files in a
separate directory, which is nicer.
I Directory declared using AC_CONFIG_MACRO_DIR, generally named m4 by
convention:
[Link]
AC_CONFIG_MACRO_DIR([m4])
I The ACLOCAL_AMFLAGS in [Link] should also be adjusted:
[Link]
ACLOCAL_AMFLAGS = -I m4
I For now, mainly used by libtool for its own m4 macros.
Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 96/99
 Auxiliary directory

I The auxiliary files generated by autotools such as compile, [Link],

[Link], depcomp, etc. are by default in the main directory of the source
tree.
I This clutters the main directory with lots of files, which may not be very pleasant.
I AC_CONFIG_AUX_DIR allows to customize where these files are generated:
[Link]
AC_CONFIG_AUX_DIR([build-aux])
I One condition: it must be placed before the calls to AM_INIT_AUTOMAKE and
LT_INIT

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 97/99
 Macro/auxiliary directory: demo

Demo 21

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 98/99
 Questions?

Thomas Petazzoni
[Link]@[Link]

Slides under CC-BY-SA 3.0

[Link]
Demos: [Link]

Free Electrons - Embedded Linux, kernel, drivers and Android - Development, consulting, training and support. [Link] 99/99