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

Difference between revisions of "Linux Tools Project/Autotools/User Guide"

(Overview)
(Overview)
Line 4: Line 4:
 
building C/C++ projects that use GNU Autotools.
 
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.  The tools aid the developer to create
+
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
one or more configuration scripts which are meant to be invoked prior to performing the build.  A configuration script may test
+
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.  
the platform, the OS, what is locally installed, or any number of things.  Results of the tests are used to create the Makefiles or they may be used to create additional files such as header files or even code.
+
  
 
What gets tested is fully controllable by the developer by way of special input files which
 
What gets tested is fully controllable by the developer by way of special input files which
are fed to the Autotools.  In some cases, a project may choose not to invoke the Autotools ahead of time and
+
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 discussedIt 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.
require this be done prior to the build.  The input files that are fed to the Autotools are provided.  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 endAlternatively, 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.
+
  
Typically, the most commonly used Autotools are 'autoconf', 'automake', 'aclocal', and 'autoreconf'.  The 'autoconf' tool takes
+
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.
a 'configure.in' or 'configure.ac' input file and creates the 'configure' script.  As mentioned, the configure script
+
is what is invoked prior to the build.  There may be multiple configuration scripts in various subdirectories but the top-level
+
configuration script should run these automatically.
+
  
The 'automake' tools takes a 'Makefile.am' input file and creates a 'Makefile.in'
+
The 'aclocal' tool creates a repository of macros that are specified directly or indirectly in the 'autoconf' input filesSuch macros are provided to perform commonly used tests or actions (e.g. test that a certain header file
output fileThe 'Makefile.in' file is input to the 'configure' script and is a template for the resulting 'Makefile'It may contain alternate paths based on tests performed in the configuration script and also might contain values that will be directly substituted from the configuration step.generated (sort of template).   
+
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 'aclocal' tool creates a repository of macros that are specified directly or indirectly in the 'autoconf' input files.  Such macros make it easy to perform common tests or actions (e.g. test that a certain header file
+
For more details on the GNU Autotools, see http://www.gnu.org/software/autoconf/ and
exists or find the C compiler).  For more details on the GNU Autotools, see http://www.gnu.org/software/autoconf/ and
+
 
http://www.gnu.org/software/automake/
 
http://www.gnu.org/software/automake/
  

Revision as of 16:28, 10 November 2009

Overview

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/

Configuration

As mentioned, a project using Autotools requires a step prior to building known as configuration. There are multiple alternatives as to what files exist in the project before-hand and how Autotools will perform the configuration. The following documents various set-ups and what Autotools does.

  1. A config.status file exists
    • This file indicates a configuration has already been performed. If the file already exists in the build directory, it is simply run with a --recheck option
  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 it has run configure. If not, configure is run automatically.
  4. A Makefile.cvs file exists
    • In this case, make is performed for this file. If a configure script is created and not run by invoking make, it is run automatically.
  5. autoreconf -i is performed
    • The autoreconf -i will invoke autotools for all input files that are older than their output targets or if their output targets do not exist. If the configure script is generated, it is run automatically

If after all of this, the top-level Makefile is not created, an error is generated and building stops. The entire configuration step is performed by a special builder that is added by the Autotools plug-in. A separate console is used for the output of all tools runs by this builder. To access this special console, click the little t.v. icons in the Console tab 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.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.