diff --git a/doc/configure.xml b/doc/configure.xml index b3f9c6d..4d8e7eb 100644 --- a/doc/configure.xml +++ b/doc/configure.xml @@ -1,58 +1,74 @@ +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + + + + +]>
- - configure documentation - PierrePronchery - + + &title; + + &firstname; + &surname; + Code and documentation. +
+ &email; +
+ + 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 as possible. + Makefiles. It is intended to keep generated code as simple and portable as + possible.
Overview
What is configure - 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. Consequently, it will mostly be useful - for projects running on UNIX platforms first. + 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.
Who should use configure Some software developers could gain using configure. However, due to its - intentional simplicity, it may not be appropriate to use along with code - compilation on some non-portable platforms. + intentional simplicity, it may also be limiting in some cases; this can + be expected when building large projects in particular. - Of course an advanced user, trying to modify a given project Makefile on his - platform, inside a project using configure may have to use configure too. + Advanced users willing to modify the build process of projects using + configure may have to learn about configure as well.
Who should not use configure - configure will certainly not be appropriate alone for cross-plaform projects, - and maybe not for big projects. However one should be able to keep its - configuration files inside a project without creating any trouble for potential - other Makefile files generators. + 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.
Why use configure - configure has been created to be efficient at writing simple and compliant - Makefiles for small to big software development projects. It should be useful: + configure was created to be efficient at writing simple and compliant + Makefiles for software development projects of all sizes. It should be + useful: for people learning software development using Makefiles; - for developers of some small to big projects; - for developers concerned by the readability and efficiency of their Makefiles. + for developers of C/C++ software projects; + for developers concerned by the readability, + efficiency, portability or maintenance of their + Makefiles.
@@ -64,7 +80,7 @@ The configure utility may be invoked from the command line this way: - $ configure [-nv][directory] + $ configure [-nvS][options...][directory...] @@ -75,8 +91,11 @@ The "-v" option gives information about the progress of the operation. - It then processes the current directory, or one given at the command line, - according to the project configuration files. + The "-S" option warns about potential security risks. + + + It then processes the current directory, or the ones given at the + command line, according to the project configuration files encountered.
@@ -93,32 +112,53 @@ hash sign "#". - The significant variables are the following: + The most significant variables are the following: in the default section (has an empty name, eg "[]" in the file) - * subdirs: subdirectories to look for too - * cflags_force: CFLAGS to force globally - * cflags: optional global CFLAGS - * ldflags_force: LDFLAGS to force globally - * ldflags: optional global LDFLAGS - * targets: targets to handle in the Makefile - * dist: additional files to include in a source archive - - in sections named like the target they define: - * type (mandatory): type of the target (eg "binary", "library", "object", ...) - * cflags: additional CFLAGS for this target - * ldflags: additional LDFLAGS for this target - * sources: source files to compile + + subdirs: subdirectories to look for + too + cppflags_force: CPPFLAGS to force globally + cppflags: optional global CPPFLAGS + cflags_force: CFLAGS to force globally + cflags: optional global CFLAGS + ldflags_force: LDFLAGS to force globally + ldflags: optional global LDFLAGS + targets: targets to handle in the Makefile + dist: additional files to include in a source archive + + in sections named like the target they define: + + type (mandatory): type of the target (eg "binary", "library", "object", ...) + cppflags: additional CPPFLAGS for this target + cflags: additional CFLAGS for this target + ldflags: additional LDFLAGS for this target + sources: source files to compile + depends: a list of files (or other targets) that + this target depends on + install: the destination path for installation + +
- Targets definitions + Target definitions The following target types are currently supported: "binary": produces binary files, linked from every object file produced with their source files. - "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. + "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. "object": produces a binary object file from the given source. + "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. + "script": runs the given script, expecting the target + file to be generated from the sources defined.
@@ -140,18 +180,11 @@
Getting further
- Current caveats - - 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") - -
-
- Planned improvements - - run-time system detection or selection; - generation of the Makefiles altered acordingly; - tweakable installation path. - + Additional resources + + More information can be found on the project page at . +