Makefiles, autotools & CMake

Sylvain Fargier (CERN)

03/02/2022
1
Introduction

2
Introduction

This document is only a brief introduction to give a

gloal/overall understanding
 
It is not a complete neither an exhaustive
documentation
Please refer to "References" sections for additional
documentation

3
Introduction
Make:
Created in 1976, Still widely used

Three major flavors : BSD Make, GNU Make and Microsoft Nmake

Specified in POSIX standardization

Autotools :
Autoconf 1992, Automake 1994, Libtool 1996

Also known as « GNU build system », Tightly related to GCC collection

CMake :
First release in 2004, Cpack 2012

Meant to be cross-platform

4
Makefiles

5
Makefiles : basics & examples
Simple Makefile example (POSIX compliant):

6
Makefiles : basics & examples
More complete example:

7
Makefiles: macros

8
Makefiles : macros
Macros basics :
Evaluated when used
Can be overridden when invoking make:

Can be expanded and allows substitution:

9
Makefiles : macros
GNU extensions:

10
Makefiles : macros
Predefined macros:
MACRO DEFINITION MACRO (GNU) DEFINITION
AR Archiver name CXX C++ compiler
ARFLAGS Archiver flags CXXFLAGS C++ flags
YACC Parser name CPP Preprocessor
YFLAGS Parser flags CPPFLAGS Preprocessor
flags
LEX Lexer name
LINT Lint program
LFLAGS Lexer flags
MAKEINFO Texinfo converter
LDFLAGS Linker flags
RM Command to
CC Compiler
remove a file
CFLAGS Compiler flags
...
FC Fortran compiler
FFLAGS Fortran flags

11
Makefiles : rules

12
Makefiles : rules
Rules syntax:
Targets:
Most of the time targets are files to generate
It can still be just a name and will be callable from the command-line (ex: clean)

Prerequisites
The target's dependencies
Expanded when the target is evaluated
Can be file names (this file's mod time will be automatically compared with the
target)

Commands
Prefixed with a <tab>
Used to generate the target(s)

13
Makefiles : rules
Commands
Prefixed with a <tab>
Used to generate the target(s)
Some prefixes are available:

PREFIX DESCRIPTION
- Ignore errors
@ Do not display command
+ Execute the command not regarding make
execution mode (see -n, -q, -t arguments)

14
Makefiles : rules
Inference rules
Inference rules are rules that contains a '.'

Also called conversion rules

Used to convert files from one format to another using "suffixes" :

New suffixes can be declared using the .SUFFIXES

special rule :

15
Makefiles : rules
Internal macros
Generated by the tool

Can be used in rules

MACRO DEFINITION
$@ Target name
$* Target name without suffix
$< First prerequisite
$? All prerequisites newer than target
$+ All prerequisites (GNU)
$^ All prerequisites, duplicates removed (GNU)
...

17
Makefiles : exercise

18
Makefiles : exercise
Exercise (15min) 10pts :
Write the world's famous helloworld.c source file
Write its associated Makefile to generate helloworld executable
Do not rely on predefined inference rules
Use an intermediate object file (.o)

 
Bonus
Write the "clean" rule (1pt)
Use a "template" makefile defining everything in macros (2pt)
Write your own inference rule (2pt)
Display how many times your project has been built (5pt)

19
Autotools

20
Autotools : basics & examples
Purpose :
Check dependencies
Manage options/conditionals
Compile on any unix-like platform
Standardize makefile rules, options definitions …
Manage out of source builds

A set of GNU utility programs :

AutoConf : generates configure executable
AutoMake : creates intermediate Makefiles
Libtool : manages libraries

Supports other tools :

Pkg-config : handle package level dependencies
Gettext : traduction files management
...

21
Autotools : basics & examples
Global overview :

22
Autotools : configure.ac

23
Autotools : configure.ac
Example "configure.ac" :
The project description file

24
Autotools : configure.ac
Variables, defines and options :

25
Autotools : configure.ac
Tests and checks (1/2) :

26
Autotools : configure.ac
Tests and checks (2/2) :

27
Autotools : Makefile.am

28
Autotools : Makefile.am
Example "Makefile.am" :
The simplified Makefile

Most of the work is done through variables

Makefile rules can be added in those files (should not
be necessary)

29
Autotools : Makefile.am
Variables :
One "primary" that will be recognized by the tool

One or several prefixed that add some extra information

Primaries :
Most used primaries are PROGRAMS, LIBRARIES, LTLIBRARIES, DATA,
HEADERS, SCRIPTS, MANS ...

Other exists (PYTHON, lIST, JAVA ...)

At least one destination prefix is required (bin, lib, pkgdata ...)

30
Autotools : Makefile.am
Building a program :
Primary : PROGRAMS

Destinations : bin, sbin, libexec, pkglibexec

31
Autotools : Makefile.am
Building a static library :
Primary : LIBRARIES

Destinations : noinst, lib, pkglib

32
Autotools : Makefile.am
Building a libtool library :
Will be either static or dynamic depending on destination and platform

Primary : LTLIBRARIES

Destinations : noinst, lib, pkglib, libexec

33
Autotools : Makefile.am
Installing headers :
Primary : HEADERS

Destinations : include, pkginclude

Other suffixes : nobase (keep subdir prefix)

Installing scripts :
Scripts are executables that doesn't need to be compiled

Primary : SCRIPTS

Destinations : bin, sbin, libexec, pkglibexec, pkgdata

34
Autotools : Makefile.am
Installing data :
Primary : DATA

Destinations : data, pkgdata, sysconf, sharedstate, localstate

Other suffixes : dist, nobase

Custom destination :
Custom destinations prefixes can be created by filling-in variables

35
Autotools : Makefile.am
Subdirectories :
Subdirectories are recursed in depth-first mode (entered before current
directory is parsed)

'.' can be used to change the order

Conditionals :
Conditionals are declared in configure.ac using AM_CONDITIONAL

36
Autotools : pkg-config

37
Autotools : pkg-config
Purpose :
Standardized module description

Installed in “/usr/lib/pkgconfig” on any unix-like platform

Contents
Name, description

Version information

cflags, ldflags, static/shared library information

extraneous information (data path, ...)

38
Autotools : usage

39
Autotools : usage

Generating "configure" and "Makefile.in" files :

Generating "Makefile" files :

40
Autotools : usage

Enabling/disabling options :

Compiling :

41
CMake

42
CMake : basics & examples

Foreword : this is a training !

There are hands-on exercises at the end of each section

Requirements :
A working CMake (>= 3.17) and compiler installation

Preferably a Unix like system (Mac, Unix, Linux)

43
CMake : basics & examples

Recommendations :
No internet connection is required, referring to online documentation
(or stackoverflow ...) is strongly discouraged

The only source of information should be (as advised in every exercise) :

cmake --help-command (--help-command-list)

cmake --help-variable (--help-variable-list)

cmake --help-module (--help-module-list)

This is not a trap nor a competition

44
CMake : basics & examples
CMake is a Makefile generator that supports:
UNIX, Borland, MSYS, MinGW, NMake, Ninja, Watcom Makefiles

But it also supports your preferred IDEs:

Visual Studio 6,7…12, Xcode, CodeBlocks, Eclipse CDT4, Kdevelop3, Kate,
Sublime Text 2 …

And more:
Package bundling, installers, unit-tests …

45
CMake : basics & examples

Simple CMakeLists.txt example :

46
CMake : basics & examples
Generating Makefiles :

Compiling :

☟ 48
CMake : basics & examples

☞ hands-on !
49
CMake : usage ☞ hands-on !
Create your first CMake project
write an helloworld.c (1pt)

write your main CMakeLists.txt generating an executable (2pt)

compile in a build directory (2pt)

Hints :
commands: cmake_minimum_required, project, add_executable (use
cmake --help-command <cmd>)

Note: This step is a base for all incoming hands-on exercise (mandatory !)

50
CMake : usage ☞ hands-on !
(Possible) Solution

Shell commands
helloworld.c

CMakelists.txt

51
CMake : syntax

52
CMake : syntax & purpose

CMake is a Makefile generator (keep this in mind) !

Commands written in CMakeLists.txt are executed when invoking CMake
(generation-time).
It can also be used at build-time, being re-invoked by Make, but this is
advanced usage (that we'll cover)

53
CMake : syntax & purpose

There are only 2 syntactic elements in CMake files :

variables
commands (functions or macros)

Functions can be regrouped in modules

With this 3 concepts we've covered complete CMake
syntax
No worries it'll be explained in details

54
CMake : variables & cache

55
CMake : variables & cache

Variables are the basic unit of storage in CMake

To set/unset a variable :

To use a variable :

56
CMake : variables & cache
Variables are directory scoped by default
Modules inclusion (“include” function) doesn’t create a new scope

add_subdirectory function does create a new scope

Scope can be extended using “PARENT_SCOPE” option

Variables are also scoped by functions

Not by macros

57
CMake : variables & cache
A global cache can also be used
Makes variables persistent and global

Used by “options” and most dependencies functions

Located in ${CMAKE_BINARY_DIR}/CMakeCache.txt

Can be edited using “ccmake” or “make edit_cache”

To set a variable in cache :

58
CMake : variables & cache
Default built-in variables :
Complete list in man (7) cmake-variables

See also : cmake --help-variable CMAKE_SOURCE_DIR

CMAKE_BINARY_DIR The path to the top level of the build tree
CMAKE_SOURCE_DIR The path to the top level of the source tree
CMAKE_CURRENT_SOURCE_DIR The path to the source directory currently being
processed
CMAKE_CURRENT_BINARY_DIR The path to the binary directory currently being
processed
...

59
CMake : variables & cache

Variables can also be treated as lists

CMake will manage lists using a ‘;’ separator in a regular string

Built-in functions are available to manipulate lists (list, foreach …)

60
CMake : variables & cache

One can also access environment variables :

Variables expansion is recursive :

Advice :
do always quote a string when expanding a variable

☟ 62
CMake : variables & cache

☞ hands-on !
63
CMake : variables & cache ☞ hands-on !
Be organized ! (1pt)
Set your sources list in a variable and use it

Be nice ! (2pt)
Display "Building <project_name>" on CMake invocation

Be pedantic ! (5pt)
Add "-pedantic" to your C_FLAGS (mind the _)

It mustn't override CFLAGS from environment that CMake also uses !

Hints :
variables: CMAKE_PROJECT_NAME, CMAKE_<LANG>_FLAGS (use cmake --
help-variable "<var>")
CMake lists uses ";" as a separator, gcc may not like it

64
CMake : usage ☞ hands-on !
(Possible) Solution

CMakelists.txt

Shell commands

65
CMake : conditionals & loops

66
CMake : conditionals & loops
CMake has some constants evaluation rules:
False : 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, empty string, anything
that ends with –NOTFOUND.

True : 1, ON, YES, TRUE, Y, or a non-zero number

Anything else will be tested as a variable name

Variables are automatically expanded and tested

The test will evaluate as true if the variable is defined and doesn’t
contain one of the False values

No worries, there’ll be examples !

67
CMake : conditionals & loops
Built-in conditional keywords:
Usual keywords are available: NOT, AND, OR

String comparison using STREQUAL, STRGREATER …

Numbers comparison using EQUAL, GREATER …

Versions comparison using VERSION_EQUAL …

Extra keywords for specific use-cases:

COMMAND <name> : true if name is a command, function or macro
POLICY <name> : true if the given policy exist
TARGET <name> : true if the given target exist
DEFINED <name> : true if given variable is defiend (not evaluating its value)
EXISTS, IS_DIRECTORY, IS_SYMLINK, IS_ABSOLUTE : don’t really have to explain

68
CMake : conditionals & loops

An example is worth a thousand words :

69
CMake : conditionals & loops

Two examples is even better :

70
CMake : conditionals & loops

One can loop on lists we saw before, or on items :

☟ 72
CMake : conditionals & loops
☞ hands-on !
73
CMake : ☞ hands-on !
If there's a ".git" directory in your source dir (2pt)
display a message

If there's a TEST variable in your env (1pt)

display a message

Say something if you're on an UNIX system (1pt)

 
Hints :
command: if (use cmake --help-command <cmd>)
variables: UNIX (use cmake --help-variable <variable>)

74
CMake : usage ☞ hands-on !
(Possible) Solution

CMakelists.txt

75
CMake : functions & macros

76
CMake : functions & macros
Functions creates a new scope, macros don't !

Both can use named or positional arguments :

Some special variables are available to access arguments (ARGC,
ARGV{0, 1 …}, ARGN)

Note: macro arguments are not real variables (specific rules apply)

77
CMake : functions & macros
A CMake built-in function exists to parse arguments
Getopt like

Used to be an external module on CMake <= 3.4

78
CMake : functions & macros

Common usage :
optional arguments uses keywords <args...> syntax

79
CMake : functions & macros
Builtin commands (functions or macros) :
Complete list in man (7) cmake-commands

See also : cmake --help-command execute_process

Name Description
project declare your project
set, unset, list manipulate variables
if, endif, foreach ... control macros
add_library, add_executable create a library or executable target
include_directories, link_libraries use dependencies
install install rule for files, targets, directories ...
execute_process run an external command
...

☟ 81
CMake : functions & macros

☞ hands-on !
82
CMake : ☞ hands-on !
Write a function that executes "date" command (3pt)
It must store its result in a variable (1pt)
Variable name is an argument (2pt)
Do it again with a macro !
Hints:
cmake --help-command function

cmake --help-command macro

cmake --help-command execute_process

83
CMake : ☞ hands-on !
(Possible) Solution
Note: command is ran at
CMake execution time, not
when calling make

CMakelists.txt

84
CMake : targets

85
CMake : targets
Targets are used to declare build-time actions
Similar to Makefile rules : executed when calling make

Note: Everything else is done when calling CMake (generation-time)

CMake can compile executables :

Or libraries :

86
CMake : targets

There are several built-in functions to manage targets :

87
CMake : targets

The same functions also exist at directory level :

But their use should be deprecated

88
CMake : targets

Custom targets can also be created :

89
CMake : targets

Installing generated files :

☟ 91
CMake : targets ☞ hands-on !
92
CMake : targets ☞ hands-on !
Install your helloworld binary (2pt)
Use an intermediate static library (2pt)
Split your program in 3 files (helloworld.c/.h main.c)

Generate a .stamp file with current date (3pt)

must be callable with : make stamp

Hints :
commands: install, add_library, target_link_libraries, add_custom_target
(use cmake --help-command <cmd>)

to test your install: make install DESTDIR=$(pwd)/instroot

93
CMake : usage ☞ hands-on !
(Possible) Solution

main.c Shell commands

helloworld.h
CMakelists.txt
helloworld.c

94
CMake : properties

95
CMake : properties
Properties are "variables" (kind of)
bound to a target, file or directory (or global)
can be accessed with set_property/get_property
or dedicated versions set_target_properties/get_target_property ...
Most built-in commands manipulate properties (link_libraries,
include_directories ...)

☟ 97
CMake : properties

☞ hands-on !
98
CMake : properties ☞ hands-on !
Set your executable sources using properties (3pt)

Hints :
properties : SOURCES (use cmake --help-property <prop>)

commands : set_target_properties (use cmake --help-command <cmd>)

lists are ";" separated strings in CMake (if you have more than a file)

99
CMake : usage ☞ hands-on !
(Possible) Solution

CMakelists.txt

No worries, properties are really advanced topic, one can use CMake without
being a property expert !

100
CMake : modules

101
CMake : modules
Modules are libraries of functions

Modules can be used using "include" function :

Loaded from directories listed in CMAKE_MODULE_PATH

See man (7) cmake-modules for standard modules documentation

102
CMake : modules

Find* modules are available for major frameworks

and libraries :
Those modules are used by find_package function

103
CMake : modules

Adding custom modules

CMakeLists.txt project file

104
 CMake : modules
CMake script mode (-P)
Using CMake as a build tool can be really convenient

A common pattern to run commands at compile-time

CMakeLists.txt project file (from previous slide)

cmake/MkName.cmake (self-calling script)

105
CMake : modules
More elaborate example :
Generating a git badge (with external dependency on shields.io)

☟
107
CMake : modules ☞ hands-on !
Check for "-march=native" compiler flag support (1pt)
and add it to your CFLAGS

Generate a header at build time (5pt)

Containing a define with date-stamp

Using a custom CMake module

Hints :
module: CheckCCompilerFlag (use cmake --help-module <module>)

commands: file, execute_process, add_custom_target,

add_dependencies (use cmake --help-command <cmd>)

Note: CMake -D options must come before -P on the command line

108
CMake : modules ☞ hands-on !
(Possible) Solution

cmake/GenHeader.cmake

helloworld.c

CMakelists.txt 109
CMake : dependencies

110
CMake : dependencies
Finding libraries and headers :

Using it :

111
CMake : dependencies
Dependencies for CMake heroes !
CMake >= 3 recommended way

Using it :

112
CMake : dependencies

Using pkg-config to find packages :

113
CMake : dependencies
Finding CMake pre-bundled dependencies
Uses Find* modules

Custom Find* modules can be implemented

Automatically found by find_package when in CMAKE_MODULES_PATH

A FindPackageHandleStandardArgs module helper is available

☟ 115
CMake : dependencies ☞ hands-on !
Write your very own FindPWET module
must find curl.h header

must link to libcurl.so library

for CMake-heroes : must declare an imported target

Hints :
module: FindPackageHandleStandardArgs (use cmake --help-module
<module>)
commands: find_path, find_library, include (use cmake --help-command
<cmd>)

116
CMake : dependencies ☞ hands-on !
(Possible) Solution

CMakelists.txt
cmake/FindPWET.cmake

117
CMake : CTest & CPack

118
CMake : CTest & CPack

Two major modules comes along with CMake :

CTest : to declare unit-tests and implement “make test”
CPack : to bundle app/lib in rpm, installer …

This training is big enough without those parts, read

the docs if you’re interested !

119
References

120
References

Makefile references :

Name Link
POSIX spec http://pubs.opengroup.org/onlinepubs/009695399/utiliti
es/make.html
GNU Make http://www.gnu.org/software/make/manual/make.html
BSD Make http://www.khmere.com/freebsd_book/html/ch01.html
Microsoft NMake http://msdn.microsoft.com/en-us/library/dd9y37ha.aspx

121
References

Autotools references :

Name Link
Automake doc https://www.gnu.org/software/automake/manual/automake.html
Autoconf doc http://www.gnu.org/software/autoconf/manual/autoconf.html
General overview http://devmanual.gentoo.org/general-concepts/autotools/

122
References

CMake references :

Name Link
Man pagews cmake (1), cmake-commands (7), cmake-modules (7) ...
CMake doc https://cmake.org/documentation/

123