|Developing software with GNU
An introduction to the GNU development tools
This is edition 0.1.5
Last updated, 26 March 1999
Department of Applied Mathematics
University of Washington
@dircategory Development * toolsmanual: (toolsmanual). Developing software with GNU
@shorttitlepage Developing software with GNU
This edition of the manual is consistent with:
Autoconf 2.13, Automake 1.4, Libtool 1.3,
Autotools 0.11, Texinfo 3.12b, Emacs 20.3.
Published on the Internet
Copyright (C) 1998, 1999 Eleftherios Gkioulekas. All rights reserved.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that they are marked clearly as modified versions, that the authors' names and title are unchanged (though subtitles and additional authors' names may be added), and that other clearly marked sections held under separate copyright are reproduced under the conditions given withinthem, and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
The GNU project was founded in 1984 by Richard Stallman in response to the increasing obstacles to cooperation imposed on the computing community by the owners of proprietary software. The goal of the GNU project is to remove these obstacles by developing a complete software system, named GNU (1) and distributing it as free software. GNU is not about software that costs $0. It is about software that gives to all its users the freedom to use, modify and redistribute it. These freedoms are essential to building a community based on cooperation and the open sharing of ideas.
Today, millions of people use GNU/Linux, a combination of the GNU system and the popular Linux kernel that was developed since 1991 by Linus Torvalds and a group of volunteers. The GNU project's kernel, the Hurd, is also in service but it is not yet sufficiently developed for widespread use. Technically, Unix and GNU have many similarities, and it is very easy to port software from Unix to GNU or use GNU software on Unix systems.
Because GNU is a community effort, it provides very powerful development tools that enable every user to contribute to the community by writing free software. The GNU development tools include the GNU compilers, the GNU build system and Emacs. Proprietary systems often do not bundle such tools with their distributions because their developers regard the users as a market that buys software licenses and treats the computer as an appliance. (2)
This manual will introduce you to the development tools that are used in the GNU system. These tools can also be used to develop software with GNU/Linux and Unix. This manual will not teach you how to use C, or any other programming language. It is assumed that you are already familiar with C. This manual will also not cover every detail about the tools that we discuss. Each tool has its own reference manual, and you should also read these manuals, sooner or later, if you want to learn more. This manual aims to be a practical introduction to the GNU development tools that will show you how to use them together to accomplish specific common tasks. The intended audience is a programmer that has learned programming in C, and would now like to learn everything else that person needs to know to develop software that conforms to the GNU coding standards. So, we will tell you what to need to know, and then you can read the specific reference manuals to learn everything that you can possibly learn.
Note on terminology
There is a growing concern among womyn that there are important gender issues with the English language. As a result, it became common to use terms such as "chairperson" instead of "chairman". In this manual we will use the words person, per, pers and perself. These words are used just like the words she, her, hers, herself. For example, we will say: "person wrote a manual to feel good about perself, and to encourage per potential significant other's heart to become pers". These terms were introduced, and perhaps invented, by Marge Piercy, and have been first used in software documentation and email correspondance by Richard Stallman. By using these terms, we hope to make this manual less threatening to womyn and to encourage our womyn readers to join the free software community.
Roadmap to manual
This manual was written as a tutorial and not a reference manual, so in general, it works to read the chapters in the order in which they are presented. If you came fresh from your CS courses with a good knowledge of C, but have learned nothing about the GNU development tools, reading all the chapters in order is probably what you should do. However, if you are already familiar with some of the topics that we discuss, you might want to skip a few chapters to get to the material that is new to you.
For example, many readers are already familiar with Emacs and Makefiles, and they just want to get started with learning about Autoconf and Automake. In that case, you can skip to section The GNU build system, and start reading from there. If you are a vi user and are not interested in learning Emacs, please reconsider (see section Using vi emulation). You will find some of the other development tools, especially the Texinfo documentation system, much easier to use with Emacs than without it.
Here's a brief outline of the chapters in this manual, and what is covered by each chapter.
section Installing GNU software, explains how to install free software that is distributed in autoconfiguring source distributions. The rest of the manual will tell you what you need to know to make your software autoconfiguring as well.
section Using GNU Emacs, shows you how to install and configure Emacs, and how to use it to develop and maintain your software.
section Compiling with Makefiles, introduces the compiler and the `make' utility and explains how to write Makefiles.
section The GNU build system, explains how to develop simple programs with Automake and Autoconf.
section Using Automake, explains in a lot more detail how to write sophisticated `Makefile.am' files.
section Using Libtool, explains how to use Libtool to write portable source distributions that compile shared libraries both on GNU and Unix.
section Using C effectively, explains how to make the best use of the GNU build system to develop C programs.
section Using Fortran effectively, explains how to write programs that use both Fortran and C.
section Internationalization, explains how to write programs whose user interface can be translated to foreign languages.
section Maintaining Documentation, explains how to document your software using Texinfo, LaTeX and man pages.
section Portable shell programming, explains how to write portable shell scripts. This is essential to writing your own Autoconf macros.
section Writing Autoconf macros, explains how to write your own Autoconf macros.
section Legal issues with Free Software, discusses legal issues such as software copyrights, patents and governmental stupidity. Understanding these issues is essential in keeping your free software free and protecting it from hoarders. If you are publishing free software to our community it is very important to understand the law, even if in your country copyrights and patents are not strictly enforced.
section Philosophical issues, is a collection of articles by Richard Stallman that discuss the free software philosophy. Our philosophy is very important, because it is what will motivate us to keep free software free, and defend our freedom now that the free software movement has been noticed by the mainstream media.
section Licensing Free Software, is another collection of articles that contain advice about licensing free software. Most of these articles, except for one, have also been written by Richard Stallman.
This book that you are now reading is actually free. The information in it is freely available to anyone. The machine readable source code for the book is freely distributed on the internet and anyone may take this book and make as many copies as they like. (take a moment to check the copying permissions on the Copyright page). If you paid money for this book, what you actually paid for was the book's nice printing and binding, and the publisher's associated costs to produce it.
The GNU development tools include Automake, Autoconf, Libtool, Make, Emacs, Texinfo and the GNU C and C++ compilers. These programs are "free"; this means that everyone is free to use them and free to redistribute them on a free basis. These programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.
Specifically, we want to make sure that you have the right to give away copies of the programs and documents that relate to them, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things.
To make sure that everyone has such rights, we don't allow you to deprive anyone else of these rights. For example, if you distribute copies of the code related to the GNU development tools, you must give the recipients all the rights that you have. You must make sure that they, too, can get the source code. And you must tell them their rights.
Also for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to the GNU development tools. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.
The precise conditions of the licenses for the GNU development tools are found in the General Public Licenses that accompany them.
This manual was written and is being maintained by Eleftherios Gkioulekas. Many people have contributed to this effort in various ways. Here is a list of these contributions. Please help me keep it complete and exempt of errors.
section Philosophical issues, and section Licensing Free Software, were written by Richard Stallman. Richard has also contributed many useful review comments and helped me with the legal paperwork.
section Installation standard directories, was adapted from The GNU coding standards.
section Maintaining the documentation files, was adapted from an unfinished draft of The GNITS coding standards, which was developed by the members of the GNITS-pickers gang: Francois Pinard, Tom Tromey, Jim Meyering, Aharon Robbins, Ulrich Drepper, Karl Berry, Greg McGary.
Most of the material in section Using Fortran effectively, is based on my studying of GNU Octave's source code, written by John Eaton. John is the first free software developer, to the best of my knowledge, that has written an extensive project that combines Fortran, C and C++ so effectively.
Installing GNU software
Free software is distributed in source code distributions. Many of these programs are difficult to install because they use system dependent features, and they require the user to edit makefiles and configuration headers. By contrast, the software distributed by the GNU project is autoconfiguring; it is possible to compile it from source code and install it automatically, without any tedious user intervention.
In this chapter we discuss how to compile and install autoconfiguring software written by others. In the subsequent chapters we discuss how to use the development tools that allow you to make your software autoconfiguring as well.
Installing a GNU package
Autoconfiguring software is distributed with packaged source code distributions. These are big files with filenames of the form:
For example, the file `autoconf-2.13.tar.gz' contains version 2.13 of GNU Autoconf. We often call these files source distributions; sometimes we simply call them packages.
The steps for installing an autoconfiguring source code distribution are simple, and if the distribution is not buggy, can be carried out without substantial user intervention.
First, you have to unpack the package to a directory:
% gunzip foo-1.0.tar.gz
% tar xf foo-1.0.tar
This will create the directory `foo-1.0' which contains the package's source code and documentation. Look for the files `README' to see if there's anything that you should do next. The `README' file might suggest that you need to install other packages before installing this one, or it might suggest that you have to do unusual things to install this package. If the source distribution conforms to the GNU coding standards, you will find many other documentation files like `README'. See section Maintaining the documentation files, for an explanation of what these files mean.
Configure the source code. Once upon a time that used to mean that you have to edit makefiles and header files. In the wonderful world of Autoconf, source distributions provide a `configure' script that will do that for you automatically. To run the script type:
Now you can compile the source code. Type:
% cd foo-1.0
and if the program is big, you can make some coffee. After the program compiles, you can run its regression test-suite, if it has one, by typing
% make check
If everything is okey, you can install the compiled distribution with:
# make install
The `make' program launches the shell commands necessary for compiling, testing and installing the package from source code. However, `make' has no knowledge of what it is really doing. It takes its orders from makefiles, files called `Makefile' that have to be present in every subdirectory of your source code directory tree. From the installer perspective, the makefiles define a set of targets that correspond to things that the installer wants to do. The default target is always compiling the source code, which is what gets invoked when you simply run make. Other targets, such as `install', `check' need to be mentioned explicitly. Because `make' takes its orders from the makefile in the current directory, it is important to run it from the correct directory. See section Compiling with Makefiles, for the full story behind `make'.
The `configure' program is a shell script that probes your system through a set of tests to determine things that it needs to know, and then uses the results to generate `Makefile' files from templates stored in files called `Makefile.in'. In the early days of the GNU project, developers used to write `configure' scripts by hand. Now, no-one ever does that any more. Now, `configure' scripts are automatically generated by GNU Autoconf from an input file `configure.in'. GNU Autoconf is part of the GNU build system and we first introduce in in section The GNU build system.
As it turns out, you don't have to write the `Makefile.in' templates by hand either. Instead you can use another program, GNU Automake, to generate `Makefile.in' templates from higher-level descriptions stored in files called `Makefile.am'. In these files you describe what is being created by your source code, and Automake computes the makefile targets for compiling, installing and uninstalling it. Automake also computes targets for compiling and running test suites, and targets for recursively calling make in subdirectories. The details about Automake are first introduced in section Using Automake.
The Makefile standards
The GNU coding standards are a document that describes the requirements that must be satisfied by all GNU programs. These requirements are driven mainly by technical ocnsiderations, and they are excellent advice for writing good software. The makefile standards, a part of the GNU coding standards, require that your makefiles do a lot more than simply compile and install the software.
One requirement is cleaning targets; these targets remove the files that were generated while installing the package and restore the source distribution to a previous state. There are three cleaning targets that corresponds to three levels of cleaning: clean, distclean, maintainer-clean.
Cleans up all the files that were generated by make and make check, but not the files that were generated by running configure. This targets cleans the build, but does not undo the source configuration by the configure script.
Cleans up all the files generated by make and make check, but also cleans the files that were generated by running configure. As a result, you can not invoke any other make targets until you run the configure script again. This target reverts your source directory tree back to the state in which it was when you first unpacked it.
Cleans up all the files that distclean cleans. However it also removes files that the developers have automatically generated with the GNU build system. Because users shouldn't need the entire GNU build system to install a package, these files should not be removed in the final source distribution. However, it is occasionally useful for the maintainer to remove and regenerate these files.
Another type of cleaning that is required is erasing the package itself from the installation directory; uninstalling the package. To uninstall the package, you must call
% make uninstall
from the toplevel directory of the source distribution. This will work only if the source distribution is configured first. It will work best only if you do it from the same source distribution, with the same configuration, that you've used to install the package in the first place.
When you install GNU software, archive the source code to all the packages that you install in a directory like `/usr/src' or `/usr/local/src'. To do that, first run make clean on the source distribution, and then use a recursive copy to copy it to `/usr/src'. The presense of a source distribution in one of these directories should be a signal to you that the corresponding package is currently installed.
Francois Pinard came up with a cute rule for remembering what the cleaning targets do:
If configure or make did it, make distclean undoes it.
If make did it, make clean undoes it.
If make install did it, make uninstall undoes it.
If you did it, make maintainer-clean undoes it.
GNU standard compliant makefiles also have a target for generating tags. Tags are files, called `TAGS', that are used by GNU Emacs to allow you to navigate your source distribution more efficiently. More specifically, Emacs uses tags to take you from a place where a C function is being used in a file, to the file and line number where the function is defined. To generate the tags call:
% make tags
Tags are particularly useful when you are not the original author of the code you are working on, and you haven't yet memorized where everything is. See section Navigating source code, for all the details about navigating large source code trees with Emacs.
Finally, in the spirit of free redistributable code, there must be targets for cutting a source code distribution. If you type
% make dist
it will rebuild the `foo-1.0.tar.gz' file that you started with. If you modified the source, the modifications will be included in the distribution (and you should probably change the version number). Before putting a distribution up on FTP, you can test its integrity with:
% make distcheck
This makes the distribution, then unpacks it in a temporary subdirectory and tries to configure it, build it, run the test-suite, and check if the installation script works. If everything is okey then you're told that your distribution is ready.
Writing reliable makefiles that support all of these targets is a very difficult undertaking. This is why we prefer to generate our makefiles instead with GNU Automake.
The `configure' script accepts many command-line flags that modify its behaviour and the configuration of your source distribution. To obtain a list of all the options that are available type
% ./configure --help
on the shell prompt.
The most useful parameter that the installer controls during configuration is the directory where they want the package to be installed. During installation, the following files go to the following directories:
Executables ==> /usr/local/bin
Libraries ==> /usr/local/lib
Header files ==> /usr/local/include
Man pages ==> /usr/local/man/man?
Info files ==> /usr/local/info
The `/usr/local' directory is called the prefix. The default prefix is always `/usr/local' but you can set it to anything you like when you call `configure' by adding a `--prefix' option. For example, suppose that you are not a privilidged user, so you can not install anything in `/usr/local', but you would still like to install the package for your own use. Then you can tell the `configure' script to install the package in your home directory `/home/username':
% ./configure --prefix=/home/username
% make check
% make install
The `--prefix' argument tells `configure' where you want to install your package, and `configure' will take that into account and build the proper makefile automatically.
If you are installing the package on a filesystem that is shared by computers that run variations of GNU or Unix, you need to install the files that are independent of the operating system in a shared directory, but separate the files that are dependent on the operating systems in different directories. Header files and documentation can be shared. However, libraries and executables must be installed separately. Usually the scheme used to handle such situations is:
Executables ==> /usr/local/system/bin
Libraries ==> /usr/local/system/lib
Header files ==> /usr/local/include
Man pages ==> /usr/local/man/mann
Info files ==> /usr/local/info
The directory `/var/local/system' is called the executable prefix, and it is usually a subdirectory of the prefix. In general, it can be any directory. If you don't specify the executable prefix, it defaults to being equal to the prefix. To change that, use the `--exec-prefix' flag. For example, to configure for a GNU/Linux system, you would run:
% configure --exec-prefix=/usr/local/linux
To configure for GNU/Hurd, you would run:
% configure --exec-prefix=/usr/local/hurd
In general, there are many directories where a package may want to install files. Some of these directories are controlled by the prefix, where others are controlled by the executable prefix. See section Installation standard directories, for a complete discussion of what these directories are, and what they are for.
Some packages allow you to enable or disable certain features while you configure the source code. They do that with flags of the form:
The --enable flags usually control whether to enable certain optional features of the package. Support for international languages, debugging features, and shared libraries are features that are usually controlled by these options. The --with flags instead control whether to compile and install certain optional components of the package. The specific flags that are available for a particular source distribution should be documented in the `README' file.
Finally, configure scripts can be passed parameters via environment variables. One of the things that configure does is decide what compiler to use and what flags to pass to that compiler. You can overrule the decisions that configure makes by setting the flags CC and CFLAGS. For example, to specify that you want the package to compile with full optimization and without any debugging symbols (which is a bad idea, yet people want to do it):
% export CFLAGS="-O3"
To tell configure to use the system's native compiler instead of gcc, and compile without optimization and with debugging symbols:
% export CC="cc"
% export CFLAGS="-g"
This assumes that you are using the bash shell as your default shell. If you use the csh or tcsh shellls, you need to assign environment variables with the setenv command instead. For example:
% setenv CFLAGS "-O3"
Similarly, the flags CXX, CXXFLAGS control the C++ compiler.