<?xml version="1.0" encoding="iso-8859-15"?>
<!-- $Id$ -->
<!DOCTYPE refentry 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 section   "1">
	<!ENTITY package   "DeforaOS configure">
	<!ENTITY name      "configure">
	<!ENTITY title     "configure documentation">
	<!ENTITY purpose   "Generates and maintain software build systems">
]>
<refentry>
	<refentryinfo>
		<title>&title;</title>
		<productname>&package;</productname>
		<authorgroup>
			<author>
				<firstname>&firstname;</firstname>
				<surname>&surname;</surname>
				<contrib>Code and documentation.</contrib>
				<address>
					<email>&email;</email>
				</address>
			</author>
		</authorgroup>
		<copyright>
			<year>2012</year>
			<year>2013</year>
			<year>2014</year>
			<year>2015</year>
			<year>2016</year>
			<year>2017</year>
			<year>2018</year>
			<holder>&firstname; &surname; &lt;&email;&gt;</holder>
		</copyright>
		<legalnotice>
			<para>This manual page was written for the DeforaOS project (and may be
				used by others).</para>
			<para>Permission is granted to copy, distribute and/or modify this
				document under the terms of the GNU General Public License,
				Version 3 as published by the Free Software Foundation.</para>
		</legalnotice>
	</refentryinfo>
	<refmeta>
		<refentrytitle>&name;</refentrytitle>
		<manvolnum>&section;</manvolnum>
	</refmeta>
	<refnamediv>
		<refname>&name;</refname>
		<refpurpose>&purpose;</refpurpose>
	</refnamediv>
	<refsynopsisdiv>
		<cmdsynopsis>
			<command>&name;</command>
			<arg choice="opt"><option>-n</option></arg>
			<arg choice="opt"><option>-q</option></arg>
			<arg choice="opt"><option>-S</option></arg>
			<arg choice="opt"><option>-v</option></arg>
			<arg choice="opt"><option>-b</option> <replaceable>bindir</replaceable></arg>
			<arg choice="opt"><option>-d</option> <replaceable>destdir</replaceable></arg>
			<arg choice="opt"><option>-i</option> <replaceable>includedir</replaceable></arg>
			<arg choice="opt"><option>-l</option> <replaceable>libdir</replaceable></arg>
			<arg choice="opt"><option>-O</option> <replaceable>system</replaceable></arg>
			<arg choice="opt"><option>-p</option> <replaceable>prefix</replaceable></arg>
			<arg choice="opt"><option>-s</option> <replaceable>sbindir</replaceable></arg>
			<arg rep="repeat"><replaceable>directory</replaceable></arg>
		</cmdsynopsis>
	</refsynopsisdiv>
	<refsect1 id="description">
		<title>Description</title>
		<para>
			&name; 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>
		<para>
			It processes the current directory, or the ones given at the command line,
			according to the project configuration files encountered.
		</para>
	</refsect1>
	<refsect1 id="options">
		<title>Options</title>
		<para>The following options are available:</para>
		<variablelist>
			<varlistentry>
				<term><option>-b</option></term>
				<listitem>
					<para>Where to install regular executables (BINDIR)</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-d</option></term>
				<listitem>
					<para>Where to stage the installation (DESTDIR)</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-i</option></term>
				<listitem>
					<para>Where to install header files (INCLUDEDIR)</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-l</option></term>
				<listitem>
					<para>Where to install libraries (LIBDIR)</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-n</option></term>
				<listitem>
					<para>This option just parses the project definition files, without
						actually re-generating the Makefiles.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-O</option></term>
				<listitem>
					<para>Force a specific platform, bypassing auto-detection.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-p</option></term>
				<listitem>
					<para>Where to base the package installation (PREFIX)</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-q</option></term>
				<listitem>
					<para>This option runs &name; in quiet mode.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-S</option></term>
				<listitem>
					<para>This option warns about potential security risks.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-v</option></term>
				<listitem>
					<para>This option gives information about the progress of the
						operation.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>
	<refsect1>
		<title>Overview</title>
		<refsect2>
			<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, or dynamic
				bindings for instance.</para>
			<para>
				Basic support for Java and Verilog is also available.
			</para>
		</refsect2>
		<refsect2>
			<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>
		</refsect2>
		<refsect2>
			<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>
		</refsect2>
		<refsect2>
			<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>
		</refsect2>
		<refsect2>
			<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>
		</refsect2>
	</refsect1>
	<refsect1 id="files">
		<title>Files</title>
		<para>
			<variablelist>
				<varlistentry>
					<term><filename>project.conf</filename></term>
					<listitem><para>Project definition files.</para></listitem>
				</varlistentry>
			</variablelist>
		</para>
	</refsect1>
	<refsect1 id="bugs">
		<title>Bugs</title>
		<para>Issues can be listed and reported at <ulink
				url="https://www.defora.org/os/project/bug_list/16/configure"/>.</para>
	</refsect1>
	<refsect1 id="see_also">
		<title>See also</title>
		<para>
			<citerefentry>
				<refentrytitle>make</refentrytitle>
				<manvolnum>1</manvolnum>
			</citerefentry>,
			<citerefentry>
				<refentrytitle>project.conf</refentrytitle>
				<manvolnum>5</manvolnum>
			</citerefentry>
		</para>
		<refsect2>
			<title>Additional resources</title>
			<para>More information can be found on the project page at <ulink
					url="https://www.defora.org/os/project/16/configure"/>.</para>
		</refsect2>
	</refsect1>
</refentry>
<!-- vim: set noet ts=1 sw=1 sts=1 tw=80: -->
