Linux Tools Project/Autotools/User Guide

{{#eclipseproject:tools.linuxtools}}

• User Guides
• Contributor Guides
• Learning

Notice

As of the Linux Tools 1.0 release (June 27/2012), Autotools no longer resides in the Linux Tools project and has officially been moved to the CDT project. The following documentation applies to the Autotools plug-ins that appeared in pre-1.0 Linux Tools releases. This would apply to the Indigo and Helios releases of Eclipse which contain pre-1.0 Linux Tools but not to the Juno release of Eclipse which is the first to contain Linux Tools 1.0. For details on the new CDT Autotools, see the CDT/Autotools/User_Guide

Introduction

The Autotools plug-in for Eclipse extends the CDT (C/C++ Development Tools) to add support for maintaining and building C/C++ projects that use GNU Autotools.

The GNU Autotools are a set of tools used to make a project portable to multiple systems or build environments. The tools aid the developer to create a configure script which is meant to be invoked prior to performing the build. The configure script may perform tests such as testing the current platform, the OS, what is locally installed, or any number of things. Parameters can be passed as well to provide information that is not calculable (e.g. what will be the target platform the project will be run on). Results of tests and parameters are used to create the Makefiles for the build or in some cases, additional files such as header files or code sequences.

What gets tested is fully controllable by the developer by way of special input files which are fed to the Autotools. Typically, the most commonly used Autotools are 'autoconf', 'automake', and 'aclocal'. The 'autoconf' tool takes a 'configure.in' or 'configure.ac' input file and creates the 'configure' script previously discussed. It is possible to have multiple configure scripts in various subdirectories, but a project should be designed so there is one top-level configure script that calls any lower-level ones automatically.

The 'automake' tool takes a 'Makefile.am' input file and creates a 'Makefile.in' file which is used at configuration time by the configure script as a template for creating a Makefile. Each Makefile will have its own corresponding Makefile.in file. There may be if/else logic used to determine what ends up in the Makefile or there may be requests to directly substitute variables calculated in the configure step.

The 'aclocal' tool creates a repository of macros that are specified directly or indirectly in the 'autoconf' input files. Such macros are provided to perform commonly used tests or actions (e.g. test that a certain header file exists or find the C compiler). The macros are written in a language called m4 and the developer is free to create their own macros to add to the repository.

The Autotools plug-in adds support for running the configure script prior to the build. As well, support is added for invoking the Autotools themselves as well as maintaining the files they use. An Autotools project extends a CDT Makefile project. Therefore, functionality in the CDT for supporting such a project applies to an Autotools project as well (e.g. C/C++ Property pages).

For more details on the GNU Autotools, see http://www.gnu.org/software/autoconf/ and http://www.gnu.org/software/automake/

Supported Environments

While the Autotools should work on any Unix-based system, it has only been tested on Linux (note that it is part of the Linux Tools project). OS-specific bugs or problems that are not reproducible on Linux may require a user work-around. For example, users of Cygwin or MinGW may require setting modifications to get the plug-in working for their project. The Autotools plug-in is not supported under a regular Windows environment (i.e. without Cygwin or MinGW).

To use the Autotools plug-in, it is required that you have the CDT (C/C++ Development Tools) already installed in Eclipse, the GNU Autotools installed on your system, and the "sh" (shell) command must be available. The "sh" command is required to invoke the configure script.

Creating an Autotools Project

There a number of ways to create an Autotools project. The first method is through the CDT C and C++ Project wizards which can be activated from the File -> New -> C Project and File -> New -> C++ Project menu items, respectively, which are available while in the C/C++ Perspective. These two wizards can also be located by clicking on the File -> New -> Project... menu item and then opening the C/C++ folder found there.

Looking at the C Wizard, we see that there is a GNU Autotools category.

Opening the category, there are two choices: Empty Project or Hello World Ansi C Autotools Project. The Empty Project template means that no files will be supplied to the new project while the Hello World project will supply a sample hello world program that uses Autotools for configuring the build. The C++ Project Wizard also has the same GNU Autotools category and two project templates: an Empty Project and a Hello World C++ Autotools sample program. If you are creating a project from scratch, it is recommended that you use the Hello World sample project and make modifications. Otherwise, you will need to create a configure script for the Autotools plug-in to invoke at build time or provide a Makefile so the configuration step does not fail.

The C and C++ Wizards can also be used when importing an existing Autotools project. For example, when importing a project from CVS using File -> Import... -> CVS -> you are given the choice to "Check out as a project configured by the new project wizard".

From the New Project menu, open the C/C++ category and choose either a C Project or C++ Project, depending on the type of project being imported. If the code is both C and C++, choose C++ Project.

Let's say you have a C application using Autotools and select C Project. This will bring up the C Project Wizard as displayed earlier. In this case, choose the Empty Project from the GNU Autotools category as you already have all the configuration files in place.

Another method to create an Autotools project is to convert an existing project. For example, if we import a project from SVN or CVS and do not configure using the new project wizard, the project will simply be downloaded into the workspace. At this point, it cannot be built or access various tools from the CDT.

To convert it, select the project in the Project Explorer and open the File -> New -> Convert to C/C++ Project menu item as found in the C/C++ Perspective. If in another perspective, this same wizard can be found by selecting File -> New -> Other... -> C/C++ -> Convert to a C/C++ Project. This brings up the C/C++ Conversion wizard.

Note how there is a set of projects that are candidates for conversion. This list contains any projects that are not already C or C++ projects. A C or C++ project includes regular CDT Managed Make and Makefile projects. Also note that the project you selected is automatically selected when the wizard opens.

There is a choice of C or C++ project and a set of project types to choose from. For Autotools, select the GNU Autotools category and this will convert to an Autotools project. Once converted, this project will not show up as a candidate project in the conversion wizard.

The final way to create an Autotools project is to use the Autotools Conversion wizard. This wizard allows one to convert from any form of project to an Autotools project. Obviously, converting a project that isn't actually C or C++ and using Autotools will result in undefined behaviour. You need to first select the project you wish to convert. After selecting, go to File -> New -> Other... -> C/C++, open the category, select "Convert to a C/C++ Autotools Project" and hit the Next button.

This brings up the following dialog:

Again, there are candidates for conversion. This list contains all projects that are not currently C or C++ Autotool projects. You are given the choice of C or C++ as with the standard C/C++ conversion wizard. Hitting the Finish button is all that is needed, but if you hit the Next button and continue on you can select referenced projects, if desired.

Once converted to an Autotools project, there is no UI method to convert back to a regular C/C++ project. If this is desired, you need to manually remove the .project, .cproject, and .autotools files from the project directory. This will effectively remove the natures and CDT settings for the project, allowing you to convert it again however you want.

Configuration

Prior to running a build, the Autotools plug-in runs the configure script. Parameters to be passed to configure may be entered via the Project -> Properties -> Autotools -> Configure Settings UI shown below:

You will notice how the actual configure script name is editable. It is not recommended you change the name of the configure script as this is standard for Autotool projects. However, one use of this text input is to add environment variables to set prior to invoking the configure script. For example, you might want to set the command to: CFLAGS="-g -debug" configure to have the CFLAGS environment variable overridden while configuring. The same applies to the autogen.sh script settings.

For configure, there are a number of standard parameters that apply to generated configure scripts. Each parameter has its command line name presented so you can look it up in Autotools documentation. In addition, tool-tip hover help is provided.

Under the Advanced category, there is a free-form line called "Additional command-line options" where you may enter any options in their command-line format. This is useful for entering custom options that your configure script supports (e.g. --enable-feature-x or --with-lib-y). It can also be used for any of the standard parameters as well if that is more familiar tor you. Parameters in this list are appended to the end of parameters derived from the standard option entries (i.e. you could get two specifications of a parameter). In the case of multiple specification, behaviour is the same as it is on the command line. You can optionally check off the "Display help contents (--help)" option under the General category to see all the standard and custom options the configure script accepts. As the configure script help is a product of how it is written, it is sometimes possible that the help is out of date with regards to added features.

In some cases, a project may choose not to invoke the Autotools ahead of time and instead require this be done prior to configuration. The input files that are fed to the Autotools are provided, but the output of the Autotools are not. This may be done to lower the download size and additionally to avoid having to constantly regenerate the output files as the Autotools are updated. In such cases, an autogen.sh script may be provided which is simply a script that runs the various Autotools required. This script may or may not run the configure script at the end. Alternatively, there is also the autoreconf tool which can be invoked to recursively run through the source tree and run all Autotools where the input files are newer than the output files (this includes the case where no output file is present). Any options required when invoking the Autotools can be encoded within the input files themselves.

The following defines a priority list of scenarios that the Autotools plug-in checks for when performing the configure step and how each one is handled.

1. A config.status file exists and configure script options have not changed since the last configuration
   • The config.status file is created as part of running a generated configure script. It itself is a script file and indicates a configuration has already been performed. If the configure options have not changed since that configuration, there is no need to do a full reconfigure. A simple check is performed by calling the config.status script with the --recheck option. This will verify that the generated Makefile exists and is up to date.
2. A configure script exists
   • In this case, the configure script is run with any configuration options specified in the project properties.
3. An autogen script exists
   • In this case, the autogen.sh script is run and following that, a check is made to see if config.status has been created, indicating that the configure script was run. If has not configured, the configure script is run automatically if it was successfully created.
4. A Makefile.cvs file exists
   • A Makefile.cvs is an alternate form of autogen.sh/configure script. In this case, the file is fed to the make command. If a configure script is created and not run as part of this process, it is run automatically.
5. default case
   • At this point, there is no configure script or autogen.sh script and configure has not been run previously. A last resort is to run the autoreconf command with -i to recursively search the source tree and invoke Autotools for any input file that is older than its output target (or if the target is missing). If this generates a configure script, it is run automatically.

If after all of this, the top-level Makefile is not created, an error is generated and building stops.

The configure process can be manually forced for a project via the Project -> Reconfigure Project menu item. A reconfigure runs the configure script even if a config.status file is found indicating a prior configuration was successful.

The entire configuration step is performed by a special builder that is added when an Autotools project is created or converted from another project. The special builder runs the configure step and is positioned to run prior to the Makefile builder.

From the Project -> Properties -> Builders tab for a project you will see:

Do not un-check the Autotools Makefile builder nor change the order of the builders. Modifying this will result in undefined behaviour.

The configure step is run in a special Configuration console added by the Autotools plug-in. This console is separate from the C-Build console which is used to display the results of the make command invocation.

To see the Configure console, click on the console selector button (icon looks like a T.V.) found in the Console View as follows:

Note that the configure console output is per project and shows configuration output for the last build of the project. It is not saved between Eclipse sessions.

The Autotools console is an instance of a CDT Build console so the console preferences set in Window -> Preferences -> C/C++ -> Build Console apply as well.

Invoking Autotools

To invoke the Autotools, a special menu item has been added to the Project menu. Under Project -> Invoke Autotools there are a set of menu items to invoke the various Autotools for your project. The output of the tool invocation is presented in a special Autotools Console. Like the Configure and C-Build Consoles, the Autotools console is per-project and is not saved across Eclipse sessions. The console, if present, can be accessed via the "Display Selected Console" button in the Console View.

The tools provided are:

1. Invoke Autoconf
   • The autoconf tool is run in the current directory for the current file or folder selected for the project. There are no parameters. Autoconf can also be run by right-clicking a configure.in or configure.ac file and selected Invoke Autoconf.
     
2. Invoke Automake
   • The automake tool is run from the current directory for the file or folder selected in the project. A dialog is presented to allow specification of options.
     The first text entry is for options while the 2nd text window is for Makefiles targets to generate. The automake tool should be invoked where the configure script is found that will generate the Makefile(s). There may be multiple Makefiles to generate in the current directory or lower. Each target location should be a Makefile and should have a corresponding Makefile.am file at the relative location specified. For example, automake x/Makefile y/Makefile Makefile specifies three targets. It is expected that there is an x/Makefile.am, y/Makefile.am, and a Makefile.am relative to the current directory. For details on automake, enter --help as an option.
     
3. Invoke Aclocal
   • The aclocal tool is run from the current directory for the file or folder selected in the project. A dialog is presented to allow specification of options.
     The first text entry is for options while the 2nd text window is for directories to search for m4 macros. The directories can also be specified directly in the options parameters using the -I option. For details, enter --help as an option.
     
4. Invoke Autoheader
   • The autoheader tool is run from the current directory for the file or folder selected in the project. A dialog is presented to allow specification of options.
     The tool is used to create a template for generated header files. It should be run in a directory containing a configure script as it gets its information from there. For details, enter --help as an option.
     
5. Invoke Autoreconf
   • The autoreconf tool is run from the current directory for the file or folder selected in the project. A dialog is presented to allow specification of options.
     The most useful option is the -i option to recursively call Autotools for all input files out of date with respect to their outputs. For details, enter --help as an option.
     
6. Invoke Libtoolize
   • The libtoolize tool is run from the current directory for the file or folder selected in the project. A dialog is presented to allow specification of options. .
     The tool is used to add libtool support to a package. Libtool provides macros to allow a package to create a shared library without having to know all the details required for the current platform. This might include special compiler flags or linker options or special tools. For details on libtoolize, enter --help as an option.
     

By default, the autotools are invoked simply by their names; expecting that the path has been set up appropriately. In some instances, you might want to specify a specific location for the autotools. For example, your project may require old versions of the tools which you have installed locally, but do not wish to be on your path. To set these for your project, select your project or a file/folder within it and go to Project -> Properties -> Autotools -> General and select the Tool Settings tab.

Special Editors

The Autotools plug-in provides two special editors for editing Autotool input files. The first is the Autoconf Editor. This editor is invoked when opening configure.in, configure.ac files as well as the resultant configure scripts that autoconf creates. Support includes full colourization, outline view, rudimentary error parsing, and hover help/completion.

The outline view shows macro references and program control statements such as if, else, for, etc... Hover help with text completion is provided for the various AC-prefixed and AM-prefixed macros that are provided as standard. As the macros vary from release to release of autoconf and automake, the editor uses an autoconf and automake version property to determine which set of macros it should adhere to. The versions selected affect the parsing which will issue warnings for macros that do not have enough parameters or too many parameters. To set the autoconf and automake versions for the Autoconf Editor, go to the Project -> Properties -> Autotools -> General page and select the Editors tab.

There you will find a pull-down of the various versions supported. Future releases may add new versions.

The default autoconf and automake versions to use for editing can be set as a preference. Go to Window -> Preferences -> C/C++ -> Autotools -> Autoconf Editor and click on the Versions tab.

Under the Syntax tab of the same preference page, you can change the colours used for the various elements shown in the editor.

A second editor, the Automake Editor is also provided by the Autotools plug-in. This editor is invoked when opening a Makefile.am or Makefile.in file. Support includes full colourization, outline view, rudimentary error parsing, and hover help.

In the example shown, one can see the $ variable references are displayed when hovered over. This is particularly useful for $< and $@ in make targets to understand what is being referenced. In some instances, you will see reference to variables surrounded by the @ symbol (e.g. @srcdir@). This represents a variable that is to be substituted by the configure script.

Rudimentary error parsing looks for syntax errors. As with the Autoconf editor, colourization can be controlled by preferences. Go to Window -> Preferences -> C/C++ -> Autotools -> Automake Editor and click on the Syntax tab.

Building

As mentioned, an Autotools project is an extended CDT Makefile project. Building the project is done the same as for any Makefile project. You can kick off a build manually by clicking on the Project -> Build Project menu item or if you choose, you can set up builds to occur automatically when resources are changed by checking off the Project -> Build Automatically menu item. The former build option is disabled when automatic builds are selected. By default, a make all is performed following the Autotools configure step.

The build is performed on the active build configuration. A build configuration is a CDT construct which is a group of settings for a particular build. This is not to be confused with an Autotools configuration which is just the settings passed to the configure script. The CDT build configuration is saved across Eclipse sessions and includes environment variable settings, build macros, build location, tool settings, etc... used to perform a build. A project may have multiple build configurations. For example, a build with debugging info and a regular optimized build. As such, one configuration is designated the active configuration and as previously stated, is the one used for the build.

The Autotools configure script parameters and the autogen.sh script parameters are treated as part of the CDT build configuration. While CDT settings are stored in the .cproject file within the project, the Autotools parameters are stored in a special file: .autotools. There is a one-to-one mapping of Autotools configuration parameters to a build configuration. By default, each Autotools project starts with a base build configuration named Build (GNU) which configures and builds in the top-level project directory. This is common for Autotools projects to have the user configure and build directly in the top-level source directory. The location of the build can be changed in the C/C++ Build properties:

Notice how the default is ${workspace_loc:/xxxx} where xxxx is the project name. This represents the project's location which may or may not be physically under the workspace root directory. To change the build location, it is recommended that you add a directory following the project location: e.g. ${workspace_loc:/xxxx}/yyyy.

It should be noted that the configure script automatically checks to see if a configuration has been performed in the source directory. It does so by looking for the config.status file existing in the same directory as the configure script. If configuring in a different directory and the configure script finds config.status in the source directories, it will stop and report a failure. Such is the case if you originally configure and build the default configuration and either change the build location or add a new configuration later and try to build it. The second configuration fails and recommends running make distclean first. A make distclean performs a clean and in addition removes configuration files such as config.status. The Autotools plug-in recognizes when this situation is about to occur during the configure step and will automatically issue a make distclean on your behalf to avoid the failure. The cleaning operation is recorded in the Configure console. Since it also removes build artefacts for the default configuration, these may have to be regenerated by a future configure/build with the default configuration marked active. If you know you will be creating multiple configurations for the project, you can either specify the default build location to something other than the top-level project directory or else you can avoid using the default configuration and only build configurations you have added yourself.

CDT build configurations are managed via the Managed Configurations dialog. The dialog is accessed via a button that can be found on any property page that alters data that is part of the build configuration. This includes the Project -> Properties -> Autotools -> Configure Settings page. Pressing the button results in the Manage Configurations dialog:

From the dialog, it is possible to create a new configuration, rename a configuration, delete a configuration, or set a particular configuration as being the active one. Deletion is disabled when there is only one configuration. Likewise, if there is only one configuration, it is active by default. When you choose to create a new configuration (hit the New... button), you are given a number of choices. You can:

1. create a new one based on the default configuration
   • In the case of Autotools this is the default Build (GNU) configuration before any modifications were made.
2. copy from an existing configuration
   • This copies all settings made.
3. import from an existing project
   • This is unsupported if the project is not also an Autotools project in which case undefined behavior occurs.
4. import a predefined configuration
   • This is not supported as it offers non-Autotools configurations. Undefined behavior will result if one of these are chosen.

Copying a configuration copies all of its settings, including the Autotools configuration parameters. Copying all settings would normally include the build location (the directory where the build will be performed), but the Autotools plug-in, by default, intercedes and for every new configuration subsequent to the initial one, it sets the build location to build-xxxx where xxxx is the unique configuration name. The Autotools plug-in replaces any white-space in the configuration name with underscores so it is possible if you have named two configurations similarly with different white-space characters or one with underscores that you might result in a build location collision. The replacement of white-space is done because the build directory will get placed in the generated Makefile where white-space is used as delimiters and undefined behaviour would therefore occur. The automatic build directory naming behaviour can be turned off from the Project -> Properties -> Autotools page, but it is discouraged since switching between different configurations and building in the same directory can cause undefined behaviour.

Note: changes to configurations are not performed unless the Ok or Apply buttons are pressed from a Property page with the Manage Configurations button on it. That is, pressing Ok from the Manage Configurations dialog does not make the changes permanent. You could add new configurations, delete others, and then hit the Cancel button from the corresponding property page and the changes would be reverted.

Make Targets

A Makefile has a set of targets that can be built. Typically, every Makefile has an all target which builds all targets, but there may be optional targets as well. A CDT Makefile project enables one to invoke the various make targets via the Make Targets dialog. Since an Autotools project is a form of Makefile project, it too supports the Make Targets dialog. Make Targets are important for an Autotool project because there are a large number of make targets added to the Makefile automatically by configuration. Typically, a project is built by running make all, but it is installed by invoking make install. The install target places files in standard locations; usually system directories on a Linux system. For example, header files would be installed in /usr/include and made available to all users of the system. The install prefix (/usr) can be overridden using the configure --prefix parameter or else by specifying prefix=xxxx on the call to make (e.g. make install prefix=/my/local/directory) so that testing can be performed without modifying the whole system.

A regular CDT Makefile project requires users to add their own Make Targets, however, the Autotools plug-in analyzes the top-level Makefile for you and creates top-level Make Targets for the project. As mentioned, these automatically added targets can be numerous. If you wish to create targets to run in sub-directories of the main build directory, you must add these manually. For example, you might wish to build docs in a lower-level sub-directory, but not for the entire project.

The Make Targets dialog can be displayed in two ways:

1. Selecting a file or folder in a project and clicking on the Project -> Make Target menu item
2. Right clicking on a file or folder in a project and selecting Make Target

This brings up a sub-menu containing Create... and Build.... to either create a new Make Target or build an existing Make Target, respectively.

Creating a Make Target is relatively straight-forward:

There is nothing different in the Make Target dialog for Autotools, however, a few concepts need to be clarified.

For Make Targets added as part of the Project -> Make Target menu item, the target is for the top-level Makefile for the current build. This means that if you add a Make Target this way, it will persist across configurations and will try and run the make command in the top-level build location specified for the active configuration.

Make Targets added by using the right-click Make Target menu are location sensitive. This means that the make command will attempt to run in that directory where the right-click was performed, regardless of whether there is a Makefile present there. Let's say you want to add your own Make Target that performed a make all install (i.e. you want to group multiple targets together into one). If you are in configuration X with build directory build-X, you want to right-click in a directory that is build-X or a sub-directory of build-X. This target will issue a make all install in that particular directory. If you wanted the same target for another configuration, you would have to right-click in its build directory or lower and add another Make Target. Obviously, for top-level Make Targets, using the Project -> Make Target menu item makes the most sense since it applies to all configurations. If you add a Make Target to a source directory, it will likely fail when run because it will try and run make in that directory which will probably only contain a Makefile.in or Makefile.am file and not a Makefile which is only generated at configure time.

The Make Target dialog can be used to override various flags within the Makefile. For example, to perform a make install and reset the prefix to /my/local/directory, you would first select the install target from the Build... dialog.

Then, you would click the Edit button to edit the Make Target. You can then override the prefix by specifying its value after the make command. You edit the build command by first un-checking "Use Builder Settings" which enables text entry.

The check-box that says "Run all project builders" should be left un-checked. By default, we only want the CDT Makefile builder to run and not the Autotools configure builder or any other builder.