134 lines
5.0 KiB
Plaintext
134 lines
5.0 KiB
Plaintext
configure documentation
|
|
-----------------------
|
|
|
|
|
|
These are the documentation notes for configure. The configure project is a
|
|
Makefiles generator. It uses project description files to propose simple
|
|
Makefiles. It is intended to keep generated code as simple as possible.
|
|
|
|
----------------------------------------
|
|
|
|
|
|
Table of contents
|
|
-----------------
|
|
|
|
I. Overview of configure
|
|
1.1 What is configure
|
|
1.2 Who should use configure
|
|
1.3 Who should not use configure
|
|
1.4 Why use configure
|
|
|
|
II. Using configure
|
|
2.1 configure usage
|
|
2.2 Project configuration
|
|
2.3 Targets definition
|
|
2.4 Migrating to configure
|
|
|
|
III. Getting further
|
|
3.1 Current caveats
|
|
3.2 Planned improvements
|
|
|
|
----------------------------------------
|
|
|
|
|
|
I. Overview of configure
|
|
|
|
1.1 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.
|
|
|
|
1.2 Who should use configure
|
|
Every software developer 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.
|
|
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.
|
|
|
|
1.3 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.
|
|
|
|
1.4 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:
|
|
- 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.
|
|
|
|
----------------------------------------
|
|
|
|
|
|
II. Using configure
|
|
|
|
2.1 configure usage
|
|
The configure utility may be invoked from the command line this way:
|
|
$ configure [-nv][directory]
|
|
|
|
The "-n" option just parses the project definition files, without actually
|
|
re-generating the Makefiles.
|
|
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.
|
|
|
|
2.2 Project configuration
|
|
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:
|
|
variable=value
|
|
Configuration files may be commented, comment lines being prepended with a
|
|
hash sign "#".
|
|
The 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
|
|
|
|
2.3 Targets 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.
|
|
- "object": produces a binary object file from the given source.
|
|
|
|
2.4 Migrating to configure
|
|
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.
|
|
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.
|
|
|
|
----------------------------------------
|
|
|
|
|
|
III. Getting further
|
|
|
|
3.1 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")
|
|
|
|
3.2 Planned improvements
|
|
- run-time system detection or selection;
|
|
- generation of the Makefiles altered acordingly;
|
|
- tweakable installation path.
|