configure

Browse Download file Permalink

<?xml version="1.0" encoding="iso-8859-15"?>

<!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">

<title>&title;</title>

<productname>&package;</productname>

<firstname>&firstname;</firstname>

<surname>&surname;</surname>

<contrib>Code and documentation.</contrib>

<email>&email;</email>

</address>

</author>

</authorgroup>

<holder>&firstname; &surname; <&email;></holder>

</copyright>

<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>

<manvolnum>&section;</manvolnum>

</refmeta>

<refpurpose>&purpose;</refpurpose>

</refnamediv>

<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>

<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 square

brackets (e.g. "[section]"). Variables are given on their own line too, like

this:

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>

<title>Important variables</title>

<para>

The most significant variables recognized are mentioned below.

</para>

<para>

In the default section:

<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:

<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>

<listitem><para><varname>enabled</varname>: set to 0 to not build this

target by default</para></listitem>

</itemizedlist>

</para>

</refsect2>

</refsect1>

<title>Target definitions</title>

<title>Target types</title>

<para>

The following target types are currently supported:

<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>

<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; provides

support through these scripts for:<itemizedlist>

<listitem><para>AppBroker: integration with the DeforaOS distributed

computing framework (see

<filename>appbroker.sh</filename>)</para></listitem>

<listitem><para><ulink url="http://www.docbook.org/">DocBook</ulink>:

markup language for technical documentation, based on either SGML or XML

(see <filename>docbook.sh</filename>)</para></listitem>

<listitem><para><ulink

url="https://gcc.gnu.org/onlinedocs/gcc/Gcov.html">GCOV</ulink>: code

coverage analysis and profiling tool, part of the GNU Compiler Collection

suite (see <filename>coverage.sh</filename>)</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

<filename>gettext.sh</filename>)</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

<filename>gtkdoc.sh</filename>)</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 <filename>pkgconfig.sh</filename>)</para></listitem>

<listitem><para>syntax checkers: convenience scripts for a number of

programming languages and markup formats are provided, such as C (see

<filename>clint.sh</filename>), HTML (see

<filename>htmllint.sh</filename>), <ulink

url="https://www.php.net/">PHP</ulink> (see

<filename>phplint.sh</filename>), Python PEP-8 (see

<filename>pylint.sh</filename>), POSIX shell scripts (see

<filename>shlint.sh</filename>), or XML (see

<filename>xmllint.sh</filename>)</para></listitem>

</itemizedlist>

</para>

<title>Writing scripts</title>

<para>

It is naturally possible to write scripts for integration with &package;.

</para>

</refsect3>

</refsect2>

</refsect1>

<para>

<refentrytitle>configure</refentrytitle>

</citerefentry>,

</citerefentry>

</para>

</refsect1>

</refentry>