Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Linux Tools Project/Autotools/User Guide

< Linux Tools Project
Revision as of 19:25, 11 November 2009 by Jjohnstn.redhat.com (Talk | contribs) (Invoking Autotools)

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.

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

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.

Linuxtools-AutotoolsCProjectWizard.png

Opening the category, there are two choices: Empty Project or Hello World Ansi C Project. The Empty Project 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++ sample program. If you are creating the 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".

Linuxtools-AutotoolsCheckout.png

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.

This will bring up the C Project Wizard as displayed earlier. In this case, choose the Empty Project from the GNU Autotools category.

Another method to create an Autotools project is to convert an existing project to an Autotools 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 Explorere then 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 -> Project... -> C/C++ -> Convert to a C/C++ Project. This brings up the C/C++ Conversion wizard.

Linuxtools-AutotoolsConvertWizard.png

Note how there is a set of projects that are candidates for conversion. These are 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 already checked off when the wizard opens.

There is a choice of C or C++ project and a set of project types to choose from. Select the GNU Autotools category and this will convert the project 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 another form of C/C++ project to an Autotools project. Again, 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.

Linuxtools-AutotoolsNewOther.png

This brings up the following dialog:

Linuxtools-AutotoolsConvAutotoolsWizard.png

Again there are candidates for conversion. This list contains all projects that are not currently C or C++ Autotools projects. You are given the choice of C or C++ as with the other 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.

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:

Linuxtools-AutotoolsConfsettings.png

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 flags 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. You may set flags in a similar manner.

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, behavior is the same as it is on the command line.

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:

Linuxtools-AutotoolsBuilders.png

Do not uncheck the Autotools Makefile builder nor change the order of the builders. Modifying this will result in undefined behavior.

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:

Linuxtools-AutotoolsConsoleSelect.png

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.

Linuxtools-AutotoolsConsolePrefs.png

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.

Linuxtools-AutotoolsAutotoolsConsole.png

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. Linuxtools-AutotoolsAutomake.png
      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. Linuxtools-AutotoolsAclocal.png
      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. Linuxtools-AutotoolsAutoheader.png
      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. Linuxtools-AutotoolsAutoreconf.png
      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. 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. A dialog is presented to allow specification of options. Linuxtools-AutotoolsLibtoolize.png
      For details on libtoolize, enter --help as an option.

Back to the top