configure/doc/configure.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 package   "configure">
	<!ENTITY name      "configure">
	<!ENTITY title     "configure documentation">
	<!ENTITY purpose   "Generates and maintain software build systems">
]>
<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 &package;. The &package; 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 &package;</title>
			<para>
				&package; 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, &package; can be extended for integration with external software
				and processes such as translations, documentation generation, dynamic
				bindings...
			</para>
		</section>
		<section>
			<title>Who should use &package;</title>
			<para>
				Some software developers could gain using &package;. 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
				&package; may have to learn about &package; as well.
			</para>
		</section>
		<section>
			<title>Who should not use &package;</title>
			<para>
				&package; was primarily designed for projects using the C or C++
				languages. Although possibly extended through the help of shell scripts,
				&package; may not be appropriate for other languages or complex build
				processes.
			</para>
		</section>
		<section>
			<title>Why use &package;</title>
			<para>
				&package; 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 &package;</title>
		<section>
			<title>&name; usage</title>
			<para>
				The &name; utility may be invoked from the command line this way:
				<cmdsynopsis>
					<command>&name;</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>Migrating to &package;</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 tw=80: -->