DeforaOS/configure
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Completing the documentation

Browse Source
This commit is contained in:
Pierre Pronchery 2012-05-05 00:52:34 +00:00
parent 4c67383e9d
commit 9a93bcc313
1 changed files with 85 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
doc/configure.xml
View File

@ -1,58 +1,74 @@
<?xml version="1.0" encoding="iso-8859-15"?> <?xml version="1.0" encoding="iso-8859-15"?>
<!-- $Id$ --> <!-- $Id$ -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN" <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "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> <article>
<artheader> <info>
<title>configure documentation</title> <title>&title;</title>
<author><firstname>Pierre</firstname><surname>Pronchery</surname></author> <author>
</artheader> <firstname>&firstname;</firstname>
<surname>&surname;</surname>
<contrib>Code and documentation.</contrib>
<address>
<email>&email;</email>
</address>
</author>
</info>
<para> <para>
These are the documentation notes for configure. The configure project is a These are the documentation notes for configure. The configure project is a
Makefiles generator. It uses project description files to provide simple Makefiles generator. It uses project description files to provide simple
Makefiles. It is intended to keep generated code as simple as possible. Makefiles. It is intended to keep generated code as simple and portable as
possible.
</para> </para>
<section> <section>
<title>Overview</title> <title>Overview</title>
<section> <section>
<title>What is configure</title> <title>What is configure</title>
<para> <para>
configure generates Makefiles needed in an entire project. Instead of trying configure generates Makefiles needed in an entire project. Instead
every little trick to let it work in a number of potential uses, it sticks to of trying every little trick to let it work in a number of
the simplest possible code generation. Consequently, it will mostly be useful potential uses, it sticks to the simplest possible code
for projects running on UNIX platforms first. generation.
</para> </para>
</section> </section>
<section> <section>
<title>Who should use configure</title> <title>Who should use configure</title>
<para> <para>
Some software developers could gain using configure. However, due to its Some software developers could gain using configure. However, due to its
intentional simplicity, it may not be appropriate to use along with code intentional simplicity, it may also be limiting in some cases; this can
compilation on some non-portable platforms. be expected when building large projects in particular.
</para> </para>
<para> <para>
Of course an advanced user, trying to modify a given project Makefile on his Advanced users willing to modify the build process of projects using
platform, inside a project using configure may have to use configure too. configure may have to learn about configure as well.
</para> </para>
</section> </section>
<section> <section>
<title>Who should not use configure</title> <title>Who should not use configure</title>
<para> <para>
configure will certainly not be appropriate alone for cross-plaform projects, configure was primarily designed for projects using the C or C++
and maybe not for big projects. However one should be able to keep its languages. Although possibly extended through the help of shell scripts,
configuration files inside a project without creating any trouble for potential configure may not be appropriate for other languages or complex build
other Makefile files generators. processes.
</para> </para>
</section> </section>
<section> <section>
<title>Why use configure</title> <title>Why use configure</title>
<para> <para>
configure has been created to be efficient at writing simple and compliant configure was created to be efficient at writing simple and compliant
Makefiles for small to big software development projects. It should be useful: Makefiles for software development projects of all sizes. It should be
useful:
<itemizedlist> <itemizedlist>
<listitem><para>for people learning software development using Makefiles;</para></listitem> <listitem><para>for people learning software development using Makefiles;</para></listitem>
<listitem><para>for developers of some small to big projects;</para></listitem> <listitem><para>for developers of C/C++ software projects;</para></listitem>
<listitem><para>for developers concerned by the readability and efficiency of their Makefiles.</para></listitem> <listitem><para>for developers concerned by the readability,
efficiency, portability or maintenance of their
Makefiles.</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
@ -64,7 +80,7 @@
<para> <para>
The configure utility may be invoked from the command line this way: The configure utility may be invoked from the command line this way:
<computeroutput> <computeroutput>
$ configure [-nv][directory] $ configure [-nvS][options...][directory...]
</computeroutput> </computeroutput>
</para> </para>
<para> <para>
@ -75,8 +91,11 @@
The "-v" option gives information about the progress of the operation. The "-v" option gives information about the progress of the operation.
</para> </para>
<para> <para>
It then processes the current directory, or one given at the command line, The "-S" option warns about potential security risks.
according to the project configuration files. </para>
<para>
It then processes the current directory, or the ones given at the
command line, according to the project configuration files encountered.
</para> </para>
</section> </section>
<section> <section>
@ -93,32 +112,53 @@
hash sign "#". hash sign "#".
</para> </para>
<para> <para>
The significant variables are the following: The most significant variables are the following:
<itemizedlist> <itemizedlist>
<listitem><para>in the default section (has an empty name, eg "[]" in the file) <listitem><para>in the default section (has an empty name, eg "[]" in the file)
* subdirs: subdirectories to look for too <itemizedlist>
* cflags_force: CFLAGS to force globally <listitem><para>subdirs: subdirectories to look for
* cflags: optional global CFLAGS too</para></listitem>
* ldflags_force: LDFLAGS to force globally <listitem><para>cppflags_force: CPPFLAGS to force globally</para></listitem>
* ldflags: optional global LDFLAGS <listitem><para>cppflags: optional global CPPFLAGS</para></listitem>
* targets: targets to handle in the Makefile <listitem><para>cflags_force: CFLAGS to force globally</para></listitem>
* dist: additional files to include in a source archive <listitem><para>cflags: optional global CFLAGS</para></listitem>
- in sections named like the target they define: <listitem><para>ldflags_force: LDFLAGS to force globally</para></listitem>
* type (mandatory): type of the target (eg "binary", "library", "object", ...) <listitem><para>ldflags: optional global LDFLAGS</para></listitem>
* cflags: additional CFLAGS for this target <listitem><para>targets: targets to handle in the Makefile</para></listitem>
* ldflags: additional LDFLAGS for this target <listitem><para>dist: additional files to include in a source archive</para></listitem>
* sources: source files to compile</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> </itemizedlist>
</para> </para>
</section> </section>
<section> <section>
<title>Targets definitions</title> <title>Target definitions</title>
<para> <para>
The following target types are currently supported: The following target types are currently supported:
<itemizedlist> <itemizedlist>
<listitem><para>"binary": produces binary files, linked from every object file produced with their source files.</para></listitem> <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.</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>"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> </itemizedlist>
</para> </para>
</section> </section>
@ -140,18 +180,11 @@
<section> <section>
<title>Getting further</title> <title>Getting further</title>
<section> <section>
<title>Current caveats</title> <title>Additional resources</title>
<itemizedlist> <para>
<listitem><para>configure is not user-proof when necessary development files are not available (relies on appropriate third-party programs error messages, eg "project-config" or "pkgconfig")</para></listitem> More information can be found on the project page at <ulink
</itemizedlist> url="http://www.defora.org/os/project/16/configure"/>.
</section> </para>
<section>
<title>Planned improvements</title>
<itemizedlist>
<listitem><para>run-time system detection or selection;</para></listitem>
<listitem><para>generation of the Makefiles altered acordingly;</para></listitem>
<listitem><para>tweakable installation path.</para></listitem>
</itemizedlist>
</section> </section>
</section> </section>
</article> </article>