Autotools. A Practitioner’s Guide to GNU Autoconf, Automake and Libtool

352 Pages·2010·7.025 MB·english

by  John Calcote

Autotools_02.book Page iii Tuesday, June 15, 2010 2:38 PM
AUTOTOOLS
A Practitioner’s Guide to
GNU Autoconf, Automake,
and Libtool
by John Calcote
San Francisco
Autotools_02.book Page iv Tuesday, June 15, 2010 2:38 PM
AUTOTOOLS. Copyright © 2010 by John Calcote.
14 13 12 11 10 1 2 3 4 5 6 7 8 9
ISBN-10: 1-59327-206-5
ISBN-13: 978-1-59327-206-7
Library of Congress Cataloging-in-Publication Data
Calcote, John, 1964-
Autotools : a practitioner's guide to GNU Autoconf, Automake, and Libtool / by John Calcote.
p. cm.
ISBN-13: 978-1-59327-206-7 (pbk.)
ISBN-10: 1-59327-206-5 (pbk.)
1. Autotools (Electronic resource) 2. Cross-platform software development. 3. Open source software.
4. UNIX (Computer file) I. Title.
QA76.76.D47C335 2010
005.3--dc22
2009040784
Autotools_02.book Page vii Tuesday, June 15, 2010 2:38 PM
B R I E F C O N T E N T S
Foreword by Ralf Wildenhues..........................................................................................xv
Preface.......................................................................................................................xvii
Introduction..................................................................................................................xxi
Chapter 1: A Brief Introduction to the GNU Autotools..........................................................1
Chapter 2: Understanding the GNU CodingStandards.....................................................19
Chapter 3: Configuring Your Project with Autoconf...........................................................57
Chapter 4: More Fun with Autoconf: Configuring User Options..........................................89
Chapter 5: Automatic Makefiles with Automake..............................................................119
Chapter 6: Building Libraries with Libtool.......................................................................145
Chapter 7: Library Interface Versioning and Runtime Dynamic Linking...............................171
Chapter 8: FLAIM: An Autotools Example.......................................................................195
Chapter 9: FLAIM Part II: Pushing the Envelope...............................................................229
Chapter 10: Using the M4 Macro Processor with Autoconf..............................................251
Chapter 11: A Catalog of Tips and Reusable Solutions for Creating Great Projects.............271
Index.........................................................................................................................313
Autotools_02.book Page ix Tuesday, June 15, 2010 2:38 PM
C O N T E N T S I N D E T A I L
FOREWORD by Ralf Wildenhues xv
PREFACE xvii
Why Use the Autotools? .........................................................................................xviii
Acknowledgments ...................................................................................................xx
I Wish You the Very Best ..........................................................................................xx
INTRODUCTION xxi
Who Should Read This Book ..................................................................................xxii
How This Book Is Organized ..................................................................................xxii
Conventions Used in This Book ...............................................................................xxiii
Autotools Versions Used in This Book .......................................................................xxiii
1
A BRIEF INTRODUCTION TO THE GNU AUTOTOOLS 1
Who Should Use the Autotools? .................................................................................2
When Should You Not Use the Autotools? ...................................................................2
Apple Platforms and Mac OS X .................................................................................3
The Choice of Language ...........................................................................................4
Generating Your Package Build System.......................................................................5
Autoconf .................................................................................................................6
autoconf ...........................................................................................................7
autoreconf ........................................................................................................7
autoheader .......................................................................................................7
autoscan...........................................................................................................7
autoupdate .......................................................................................................7
ifnames ............................................................................................................8
autom4te ..........................................................................................................8
Working Together..............................................................................................8
Automake................................................................................................................9
automake .......................................................................................................10
aclocal ...........................................................................................................10
Libtool...................................................................................................................11
libtool.............................................................................................................12
libtoolize ........................................................................................................12
ltdl, the Libtool C API ........................................................................................12
Building Your Package ............................................................................................13
Running configure ............................................................................................13
Running make .................................................................................................15
Installing the Most Up-to-Date Autotools .....................................................................16
Summary ...............................................................................................................18
Autotools_02.book Page x Tuesday, June 15, 2010 2:38 PM
2
UNDERSTANDING THE GNU CODING STANDARDS 19
Creating a New Project Directory Structure................................................................20
Project Structure .....................................................................................................21
Makefile Basics ......................................................................................................22
Commands and Rules .......................................................................................23
Variables ........................................................................................................24
A Separate Shell for Each Command .................................................................25
Variable Binding .............................................................................................26
Rules in Detail .................................................................................................27
Resources for Makefile Authors ..........................................................................32
Creating a Source Distribution Archive......................................................................32
Forcing a Rule to Run .......................................................................................34
Leading Control Characters ..............................................................................35
Automatically Testing a Distribution ..........................................................................36
Unit Testing, Anyone? .............................................................................................37
Installing Products...................................................................................................38
Installation Choices ..........................................................................................40
Uninstalling a Package .....................................................................................41
Testing Install and Uninstall ...............................................................................42
The Filesystem Hierarchy Standard ...........................................................................44
Supporting Standard Targets and Variables ..............................................................45
Standard Targets .............................................................................................46
Standard Variables ..........................................................................................46
Adding Location Variables to Jupiter ..................................................................47
Getting Your Project into a Linux Distro .....................................................................48
Build vs. Installation Prefix Overrides ........................................................................50
User Variables .......................................................................................................52
Configuring Your Package ......................................................................................54
Summary ...............................................................................................................55
3
CONFIGURING YOUR PROJECT WITH AUTOCONF 57
Autoconf Configuration Scripts .................................................................................58
The Shortest configure.ac File ..................................................................................59
Comparing M4 to the C Preprocessor .......................................................................60
The Nature of M4 Macros .......................................................................................60
Executing autoconf .................................................................................................61
Executing configure ................................................................................................62
Executing config.status ............................................................................................63
Adding Some Real Functionality ...............................................................................64
Generating Files from Templates ..............................................................................67
Adding VPATH Build Functionality ............................................................................68
Let’s Take a Breather ..............................................................................................70
An Even Quicker Start with autoscan ........................................................................71
The Proverbial autogen.sh Script ........................................................................73
Updating Makefile.in .......................................................................................75
Initialization and Package Information ......................................................................76
AC_PREREQ ...................................................................................................76
AC_INIT .........................................................................................................76
AC_CONFIG_SRCDIR ......................................................................................77
x Contents in Detail
Autotools_02.book Page xi Tuesday, June 15, 2010 2:38 PM
The Instantiating Macros .........................................................................................78
AC_CONFIG_HEADERS ...................................................................................83
Using autoheader to Generate an Include File Template .......................................84
Back to Remote Builds for a Moment .........................................................................87
Summary ...............................................................................................................88
4
MORE FUN WITH AUTOCONF:
CONFIGURING USER OPTIONS 89
Substitutions and Definitions ....................................................................................90
AC_SUBST ......................................................................................................90
AC_DEFINE ....................................................................................................91
Checking for Compilers ..........................................................................................91
Checking for Other Programs ..................................................................................93
A Common Problem with Autoconf ...........................................................................95
Checks for Libraries and Header Files .......................................................................98
Is It Right or Just Good Enough?.......................................................................101
Printing Messages ..........................................................................................106
Supporting Optional Features and Packages ...........................................................107
Coding Up the Feature Option ........................................................................109
Formatting Help Strings ..................................................................................112
Checks for Type and Structure Definitions ................................................................112
The AC_OUTPUT Macro .......................................................................................116
Summary .............................................................................................................117
5
AUTOMATIC MAKEFILES
WITH AUTOMAKE 119
Getting Down to Business ......................................................................................120
Enabling Automake in configure.ac..................................................................121
A Hidden Benefit: Automatic Dependency Tracking ...........................................124
What’s in a Makefile.am File? ...............................................................................125
Analyzing Our New Build System ..........................................................................126
Product List Variables .....................................................................................127
Product Source Variables ................................................................................132
PLV and PSV Modifiers ...................................................................................132
Unit Tests: Supporting make check..........................................................................133
Reducing Complexity with Convenience Libraries .....................................................134
Product Option Variables................................................................................136
Per-Makefile Option Variables .........................................................................138
Building the New Library.......................................................................................138
What Goes into a Distribution? ..............................................................................140
Maintainer Mode .................................................................................................141
Cutting Through the Noise .....................................................................................142
Summary .............................................................................................................144
Autotools_02.book Page xii Tuesday, June 15, 2010 2:38 PM
6
BUILDING LIBRARIES WITH LIBTOOL 145
The Benefits of Shared Libraries .............................................................................146
How Shared Libraries Work ..................................................................................146
Dynamic Linking at Load Time .........................................................................147
Automatic Dynamic Linking at Runtime .............................................................148
Manual Dynamic Linking at Runtime .................................................................149
Using Libtool........................................................................................................150
Abstracting the Build Process ...........................................................................150
Abstraction at Runtime ....................................................................................151
Installing Libtool ...................................................................................................152
Adding Shared Libraries to Jupiter ..........................................................................152
Using the LTLIBRARIES Primary .........................................................................153
Public Include Directories ................................................................................153
Customizing Libtool with LT_INIT Options..........................................................157
Reconfigure and Build ....................................................................................161
So What Is PIC, Anyway? ...............................................................................164
Fixing the Jupiter PIC Problem .........................................................................167
Summary .............................................................................................................170
7
LIBRARY INTERFACE VERSIONING AND
RUNTIME DYNAMIC LINKING 171
System-Specific Versioning ....................................................................................172
Linux and Solaris Library Versioning .................................................................172
IBM AIX Library Versioning .............................................................................173
HP-UX/AT&T SVR4 Library Versioning ..............................................................176
The Libtool Library Versioning Scheme ....................................................................176
Library Versioning Is Interface Versioning..........................................................177
When Library Versioning Just Isn’t Enough ........................................................180
Using libltdl .........................................................................................................181
Necessary Infrastructure .................................................................................181
Adding a Plug-In Interface ...............................................................................183
Doing It the Old-Fashioned Way .....................................................................184
Converting to Libtool’s ltdl Library ....................................................................188
Preloading Multiple Modules ...........................................................................192
Checking It All Out ........................................................................................193
Summary .............................................................................................................194
8
FLAIM: AN AUTOTOOLS EXAMPLE 195
What Is FLAIM? ...................................................................................................196
Why FLAIM? .......................................................................................................196
An Initial Look ......................................................................................................197
Getting Started ....................................................................................................199
Adding the configure.ac Files ..........................................................................199
The Top-Level Makefile.am File ........................................................................202
The FLAIM Subprojects ..........................................................................................204
The FLAIM Toolkit configure.ac File ..................................................................205
The FLAIM Toolkit Makefile.am File ..................................................................212
xii Contents in Detail
Autotools_02.book Page xiii Tuesday, June 15, 2010 2:38 PM
Designing the ftk/src/Makefile.am File .............................................................215
Moving On to the ftk/util Directory ..................................................................217
Designing the XFLAIM Build System ........................................................................218
The XFLAIM configure.ac File ..........................................................................219
Creating the xflaim/src/Makefile.am File .........................................................222
Turning to the xflaim/util Directory ...................................................................223
Summary .............................................................................................................227
9
FLAIM PART II: PUSHING THE ENVELOPE 229
Building Java Sources Using the Autotools ...............................................................230
Autotools Java Support ...................................................................................230
Using ac-archive Macros ................................................................................233
Canonical System Information .........................................................................234
The xflaim/java Directory Structure ..................................................................234
The xflaim/src/Makefile.am File ......................................................................235
Building the JNI C++ Sources ..........................................................................236
The Java Wrapper Classes and JNI Headers .....................................................237
A Caveat About Using the JAVA Primary ..........................................................239
Building the C# Sources ........................................................................................239
Manual Installation ........................................................................................242
Cleaning Up Again ........................................................................................243
Configuring Compiler Options ...............................................................................243
Hooking Doxygen into the Build Process .................................................................245
Adding Nonstandard Targets ................................................................................247
Summary .............................................................................................................250
10
USING THE M4 MACRO PROCESSOR WITH AUTOCONF 251
M4 Text Processing ..............................................................................................252
Defining Macros ............................................................................................253
Macros with Arguments ..................................................................................255
The Recursive Nature of M4 ..................................................................................256
Quoting Rules ...............................................................................................258
Autoconf and M4 .................................................................................................259
The Autoconf M4 Environment .........................................................................260
Writing Autoconf Macros ......................................................................................260
Simple Text Replacement ................................................................................260
Documenting Your Macros ..............................................................................263
M4 Conditionals............................................................................................264
Diagnosing Problems ............................................................................................268
Summary .............................................................................................................269
11
A CATALOG OF TIPS AND REUSABLE SOLUTIONS
FOR CREATING GREAT PROJECTS 271
Item 1: Keeping Private Details out of Public Interfaces ..............................................272
Solutions in C ................................................................................................273
Solutions in C++ ............................................................................................273
Contents in Detail xiii
Autotools_02.book Page xiv Tuesday, June 15, 2010 2:38 PM
Item 2: Implementing Recursive Extension Targets .....................................................276
Item 3: Using a Repository Revision Number in a PackageVersion.............................279
Item 4: Ensuring Your Distribution Packages Are Clean .............................................281
Item 5: Hacking Autoconf Macros ..........................................................................282
Providing Library-Specific Autoconf Macros.......................................................287
Item 6: Cross-Compiling ........................................................................................287
Item 7: Emulating Autoconf Text Replacement Techniques ..........................................293
Item 8: Using the ac-archive Project ........................................................................298
Item 9: Using pkg-config with Autotools ..................................................................299
Providing pkg-config Files for Your Library Projects.............................................300
Using pkg-config Files in configure.ac ..............................................................301
Item 10: Using Incremental Installation Techniques ...................................................302
Item 11: Using Generated Source Code..................................................................302
Using the BUILT_SOURCES Variable ................................................................302
Dependency Management ..............................................................................303
Built Sources Done Right .................................................................................306
Item 12: Disabling Undesirable Targets ...................................................................309
Item 13: Watch Those Tab Characters! ...................................................................310
Item 14: Packaging Choices ..................................................................................311
Wrapping Up ......................................................................................................312
INDEX 313
Autotools_02.book Page xv Tuesday, June 15, 2010 2:38 PM
F O R E W O R D
When I was asked to do a technical review on a book
about the Autotools, I was rather skeptical. Several
online tutorials and a few books already introduce
readers to the use of GNU Autoconf, Automake, and
Libtool. However, many of these texts are less than ideal in at least some
ways: They were either written several years ago and are starting to show their
age, contain at least some inaccuracies, or tend to be incomplete for typical
beginner’s tasks. On the other hand, the GNU manuals for these programs
are fairly large and rather technical, and as such, they may present a signifi-
cant entry barrier to learning your ways around the Autotools.
John Calcote began this book with an online tutorial that shared at least
some of the problems facing other tutorials. Around that time, he became a
regular contributor to discussions on the Autotools mailing lists, too. John
kept asking more and more questions, and discussions with him uncovered
some bugs in the Autotools sources and documentation, as well as some
issues in his tutorial.