247 lines
10 KiB
XML
247 lines
10 KiB
XML
<?xml version="1.0" encoding="iso-8859-15"?>
|
|
<!-- $Id$ -->
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
<!ENTITY firstname "Pierre">
|
|
<!ENTITY surname "Pronchery">
|
|
<!ENTITY email "khorben@defora.org">
|
|
<!ENTITY title "configure documentation">
|
|
]>
|
|
<article>
|
|
<info>
|
|
<title>&title;</title>
|
|
<author>
|
|
<firstname>&firstname;</firstname>
|
|
<surname>&surname;</surname>
|
|
<contrib>Code and documentation.</contrib>
|
|
<address>
|
|
<email>&email;</email>
|
|
</address>
|
|
</author>
|
|
</info>
|
|
<para>
|
|
These are the documentation notes for configure. The configure project
|
|
generates and maintain software build systems, suitable for use with the most
|
|
common implementations of the make command. It uses project description files
|
|
to provide simple Makefiles. It is intended to keep the code generated as
|
|
simple and portable as possible.
|
|
</para>
|
|
<section>
|
|
<title>Overview</title>
|
|
<section>
|
|
<title>What is configure</title>
|
|
<para>
|
|
configure generates Makefiles needed in an entire project. Instead
|
|
of trying every little trick to let it work in a number of
|
|
potential uses, it sticks to the simplest possible code
|
|
generation.
|
|
</para>
|
|
<para>
|
|
Although primarily dedicated to the generation of build systems through
|
|
Makefiles, primarily to compile source code in the C/C++ and assembly
|
|
languages, configure can be extended for integration with external software
|
|
and processes such as translations, documentation generation, dynamic
|
|
bindings...
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Who should use configure</title>
|
|
<para>
|
|
Some software developers could gain using configure. However, due to its
|
|
intentional simplicity, it may also be limiting in some cases; this can
|
|
be expected when building large projects in particular.
|
|
</para>
|
|
<para>
|
|
Advanced users willing to modify the build process of projects using
|
|
configure may have to learn about configure as well.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Who should not use configure</title>
|
|
<para>
|
|
configure was primarily designed for projects using the C or C++
|
|
languages. Although possibly extended through the help of shell scripts,
|
|
configure may not be appropriate for other languages or complex build
|
|
processes.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Why use configure</title>
|
|
<para>
|
|
configure was created to be efficient at writing simple and compliant
|
|
Makefiles for software development projects of all sizes. It should be
|
|
useful:
|
|
<itemizedlist>
|
|
<listitem><para>for people learning software development using
|
|
Makefiles;</para></listitem>
|
|
<listitem><para>for developers of C/C++ software
|
|
projects;</para></listitem>
|
|
<listitem><para>for developers concerned by the readability, efficiency,
|
|
portability or maintenance of their Makefiles.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Using configure</title>
|
|
<section>
|
|
<title>configure usage</title>
|
|
<para>
|
|
The configure utility may be invoked from the command line this way:
|
|
<cmdsynopsis>
|
|
<command>configure</command>
|
|
<arg>-n</arg>
|
|
<arg>-v</arg>
|
|
<arg>-S</arg>
|
|
<arg rep="repeat">options</arg>
|
|
<arg rep="repeat">directory</arg>
|
|
</cmdsynopsis>
|
|
</para>
|
|
<para>
|
|
The "-n" option just parses the project definition files, without actually
|
|
re-generating the Makefiles.
|
|
</para>
|
|
<para>
|
|
The "-v" option gives information about the progress of the operation.
|
|
</para>
|
|
<para>
|
|
The "-S" option warns about potential security risks.
|
|
</para>
|
|
<para>
|
|
It then processes the current directory, or the ones given at the
|
|
command line, according to the project configuration files encountered.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Project configuration</title>
|
|
<para>
|
|
This file should be found in every project directory. It must be named
|
|
"project.conf". It is organized in sections, and string variables. Section names
|
|
are written on their own line, between brackets (eg "[section]"). Variables are
|
|
given on their own line too, like this:
|
|
<computeroutput>
|
|
variable=value
|
|
</computeroutput>
|
|
Configuration files may be commented, comment lines being prepended with a
|
|
hash sign "#".
|
|
</para>
|
|
<para>
|
|
The most significant variables are the following:
|
|
<itemizedlist>
|
|
<listitem><para>in the default section (has an empty name, eg "[]" in the file)
|
|
<itemizedlist>
|
|
<listitem><para>subdirs: subdirectories to look for
|
|
too</para></listitem>
|
|
<listitem><para>cppflags_force: CPPFLAGS to force globally</para></listitem>
|
|
<listitem><para>cppflags: optional global CPPFLAGS</para></listitem>
|
|
<listitem><para>cflags_force: CFLAGS to force globally</para></listitem>
|
|
<listitem><para>cflags: optional global CFLAGS</para></listitem>
|
|
<listitem><para>ldflags_force: LDFLAGS to force globally</para></listitem>
|
|
<listitem><para>ldflags: optional global LDFLAGS</para></listitem>
|
|
<listitem><para>targets: targets to handle in the Makefile</para></listitem>
|
|
<listitem><para>dist: additional files to include in a source archive</para></listitem>
|
|
</itemizedlist></para></listitem>
|
|
<listitem><para>in sections named like the target they define:
|
|
<itemizedlist>
|
|
<listitem><para>type (mandatory): type of the target (eg "binary", "library", "object", ...)</para></listitem>
|
|
<listitem><para>cppflags: additional CPPFLAGS for this target</para></listitem>
|
|
<listitem><para>cflags: additional CFLAGS for this target</para></listitem>
|
|
<listitem><para>ldflags: additional LDFLAGS for this target</para></listitem>
|
|
<listitem><para>sources: source files to compile</para></listitem>
|
|
<listitem><para>depends: a list of files (or other targets) that
|
|
this target depends on</para></listitem>
|
|
<listitem><para>install: the destination path for installation</para></listitem>
|
|
</itemizedlist>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Target definitions</title>
|
|
<section>
|
|
<title>Target types</title>
|
|
<para>
|
|
The following target types are currently supported:
|
|
<itemizedlist>
|
|
<listitem><para>"binary": produces binary files, linked from every object file produced with their source files.</para></listitem>
|
|
<listitem><para>"library": produces a static and a shared version of
|
|
the target, linked from every object file produced
|
|
with their source files, and respectively appending
|
|
".a" and ".so" extensions to the target name; the
|
|
shared object are also assigned a version number.</para></listitem>
|
|
<listitem><para>"object": produces a binary object file from the given source.</para></listitem>
|
|
<listitem><para>"plugin": produces a shared version of the target,
|
|
linked from every object file produced with their
|
|
source files, and appending the ".so" extension to the target name.</para></listitem>
|
|
<listitem><para>"script": runs the given script, expecting the target
|
|
file to be generated from the sources defined.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section>
|
|
<title>Script targets</title>
|
|
<para>
|
|
Scripts have to be provided by the software project itself, as
|
|
configure does not provide any pre-installed set of standard
|
|
scripts. A few sample scripts are, however, distributed along with
|
|
the source code of the configure project, and introduced here.
|
|
</para>
|
|
<para>
|
|
These scripts are primarily meant to allow further integration of
|
|
the build process, as defined by the Makefiles generated, with the
|
|
requirements of a software project beyond that of compiling code.
|
|
configure is already known to have been successfully integrated this
|
|
way with:
|
|
<itemizedlist>
|
|
<listitem><para>AppBroker: integration with the DeforaOS distributed
|
|
computing framework (see appbroker.sh)</para></listitem>
|
|
<listitem><para>DocBook: markup language for technical documentation,
|
|
based on either SGML or XML (see docbook.sh)</para></listitem>
|
|
<listitem><para>Gettext: internationalization (i18n) and localization
|
|
(l10n) framework, notably allowing software to be easily translated to
|
|
other languages (see gettext.sh)</para></listitem>
|
|
<listitem><para>Gtk-doc: generates API documentation from comments within
|
|
software projects, in the format expected by the <ulink
|
|
url="http://live.gnome.org/devhelp">DevHelp API browser</ulink> (see
|
|
gtkdoc.sh)</para></listitem>
|
|
<listitem><para>pkg-config: unified interface to define compilation and
|
|
linking rules to installed software (see pkgconfig.sh)</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Writing scripts</title>
|
|
<para>
|
|
It is naturally possible to write scripts for integration with configure.
|
|
<!-- FIXME complete this section -->
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Migrating to configure</title>
|
|
<para>
|
|
You may first create all necessary "project.conf" files with the
|
|
subdirectories definitions. Then for every binary or library built, specify
|
|
the adequate target along with its section.
|
|
</para>
|
|
<para>
|
|
When migrating from automake/autoconf, the existing subdirectories are
|
|
defined in the "Makefile.am" files, in the "SUBDIRS" variable. The binary
|
|
targets are defined in the same file, as the "bin_PROGRAMS" variable, each
|
|
declined to "program_SOURCES" for their respective source files.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Getting further</title>
|
|
<section>
|
|
<title>Additional resources</title>
|
|
<para>
|
|
More information can be found on the project page at <ulink
|
|
url="http://www.defora.org/os/project/16/configure"/>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</article>
|
|
<!-- vim: set noet ts=1 sw=1 sts=1: -->
|