214 lines
8.7 KiB
XML
214 lines
8.7 KiB
XML
<?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 username "khorben">
|
|
<!ENTITY email "khorben@defora.org">
|
|
<!ENTITY section "5">
|
|
<!ENTITY title "configure Developer Manual">
|
|
<!ENTITY package "configure">
|
|
<!ENTITY name "project.conf">
|
|
<!ENTITY purpose "Project definition files for configure">
|
|
]>
|
|
<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>
|
|
<holder>&firstname; &surname; <&email;></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>§ion;</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>&name;</refname>
|
|
<refpurpose>&purpose;</refpurpose>
|
|
</refnamediv>
|
|
<refsect1 id="description">
|
|
<title>Project configuration</title>
|
|
<para>
|
|
A project definition file should be found in every project directory managed
|
|
by &package;. These files must be named <filename>&name;</filename>.
|
|
</para>
|
|
<refsect2>
|
|
<title>File format</title>
|
|
<para>
|
|
A definition file is organized in sections, each containing a number of
|
|
variables. Section names are written on their own line, between brackets (eg
|
|
"[section]"). Variables are given on their own line too, like this:
|
|
<blockquote>
|
|
<computeroutput>
|
|
variable=value
|
|
</computeroutput>
|
|
</blockquote>
|
|
Configuration files may be commented, comment lines being prepended with a
|
|
hash sign "#".
|
|
</para>
|
|
<para>
|
|
Variables can be defined directly without specifying a particular section
|
|
first; they belong then to the default section, which is simply considered
|
|
to have an empty name.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>Important variables</title>
|
|
<para>
|
|
The most significant variables recognized are mentioned below.
|
|
</para>
|
|
<para>
|
|
In the default section:
|
|
<itemizedlist>
|
|
<listitem><para><varname>subdirs</varname>: subdirectories to look for
|
|
too</para></listitem>
|
|
<listitem><para><varname>cppflags_force</varname>: CPPFLAGS to force
|
|
globally</para></listitem>
|
|
<listitem><para><varname>cppflags</varname>: optional global
|
|
CPPFLAGS</para></listitem>
|
|
<listitem><para><varname>cflags_force</varname>: CFLAGS to force
|
|
globally</para></listitem>
|
|
<listitem><para><varname>cflags</varname>: optional global
|
|
CFLAGS</para></listitem>
|
|
<listitem><para><varname>ldflags_force</varname>: LDFLAGS to force
|
|
globally</para></listitem>
|
|
<listitem><para><varname>ldflags</varname>: optional global
|
|
LDFLAGS</para></listitem>
|
|
<listitem><para><varname>targets</varname>: targets to handle in the
|
|
Makefile</para></listitem>
|
|
<listitem><para><varname>dist</varname>: additional files to include in a
|
|
source archive</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>In subsequent sections, respectively named after the target
|
|
they define:
|
|
<itemizedlist>
|
|
<listitem><para><varname>type</varname> (mandatory): type of the target (eg
|
|
<emphasis>binary</emphasis>, <emphasis>library</emphasis>,
|
|
<emphasis>object</emphasis>, ...)</para></listitem>
|
|
<listitem><para><varname>cppflags</varname>: additional CPPFLAGS for this
|
|
target</para></listitem>
|
|
<listitem><para><varname>cflags</varname>: additional CFLAGS for this
|
|
target</para></listitem>
|
|
<listitem><para><varname>ldflags</varname>: additional LDFLAGS for this
|
|
target</para></listitem>
|
|
<listitem><para><varname>sources</varname>: source files to
|
|
compile</para></listitem>
|
|
<listitem><para><varname>depends</varname>: a list of files (or other
|
|
targets) that this target depends on</para></listitem>
|
|
<listitem><para><varname>install</varname>: the destination path for
|
|
installation</para></listitem>
|
|
<listitem><para><varname>phony</varname>: determines if the target defined
|
|
should always be built, regardless of the presence of a file of a same
|
|
name (possible values: 0, 1)</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
<refsect1 id="targets">
|
|
<title>Target definitions</title>
|
|
<refsect2>
|
|
<title>Target types</title>
|
|
<para>
|
|
The following target types are currently supported:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>binary</emphasis>: produces binary files, linked
|
|
from every object file produced with their source
|
|
files.</para></listitem>
|
|
<listitem><para><emphasis>library</emphasis>: 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><emphasis>libtool</emphasis>: uses the <ulink url="http://www.gnu.org/software/libtool/">libtool</ulink> project to generate libraries, as supported by the project on the underlying platform.</para></listitem>
|
|
<listitem><para><emphasis>object</emphasis>: produces a binary object file
|
|
from the given source.</para></listitem>
|
|
<listitem><para><emphasis>plugin</emphasis>: 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><emphasis>script</emphasis>: runs the given script,
|
|
expecting the target file to be generated from the sources
|
|
defined.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 id="targets_scripts">
|
|
<title>Script targets</title>
|
|
<para>Scripts should be provided by the software project itself, as &package;
|
|
does not provide a convenient set of pre-installed standard scripts. A few
|
|
sample scripts are, however, distributed along with the source code of the
|
|
&package; project, and introduced here.</para>
|
|
<para>These scripts are primarily meant to allow further integration of the
|
|
build process, as defined by the Makefiles generated, with the requirements
|
|
of a software project beyond that of compiling code. &package; is already
|
|
known to have been successfully integrated this way with:<itemizedlist>
|
|
<listitem><para>AppBroker: integration with the DeforaOS distributed
|
|
computing framework (see appbroker.sh)</para></listitem>
|
|
<listitem><para><ulink url="http://www.docbook.org/">DocBook</ulink>:
|
|
markup language for technical documentation, based on either SGML or XML
|
|
(see docbook.sh)</para></listitem>
|
|
<listitem><para><ulink
|
|
url="http://www.gnu.org/software/gettext/">Gettext</ulink>:
|
|
internationalization (i18n) and localization (l10n) framework, notably
|
|
allowing software to be easily translated to other languages (see
|
|
gettext.sh)</para></listitem>
|
|
<listitem><para><ulink url="http://www.gtk.org/gtk-doc/">Gtk-doc</ulink>:
|
|
generates API documentation from comments within software projects, in
|
|
the format expected by the <ulink
|
|
url="http://live.gnome.org/devhelp">DevHelp API browser</ulink> (see
|
|
gtkdoc.sh)</para></listitem>
|
|
<listitem><para><ulink
|
|
url="http://pkgconfig.freedesktop.org/">pkg-config</ulink>: unified
|
|
interface to define compilation and linking rules to installed software
|
|
(see pkgconfig.sh)</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<refsect3>
|
|
<title>Writing scripts</title>
|
|
<para>
|
|
It is naturally possible to write scripts for integration with &package;.
|
|
<!-- FIXME complete this section -->
|
|
</para>
|
|
</refsect3>
|
|
</refsect2>
|
|
</refsect1>
|
|
<refsect1 id="see_also">
|
|
<title>See also</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>configure</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>make</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
<!-- vim: set noet ts=1 sw=1 sts=1 tw=80: -->
|