191 lines
7.5 KiB
XML
191 lines
7.5 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 is a
|
|
Makefiles generator. It uses project description files to provide simple
|
|
Makefiles. It is intended to keep generated code 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>
|
|
</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:
|
|
<computeroutput>
|
|
$ configure [-nvS][options...][directory...]
|
|
</computeroutput>
|
|
</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>
|
|
<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>
|
|
<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>
|