diff --git a/Makefile b/Makefile index 4a870e3..556fcf5 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,7 @@ dist: $(PACKAGE)-$(VERSION)/doc/Makefile \ $(PACKAGE)-$(VERSION)/doc/docbook.sh \ $(PACKAGE)-$(VERSION)/doc/configure.xml \ + $(PACKAGE)-$(VERSION)/doc/project.conf.xml \ $(PACKAGE)-$(VERSION)/doc/project.conf \ $(PACKAGE)-$(VERSION)/doc/scripts/Makefile \ $(PACKAGE)-$(VERSION)/doc/scripts/appbroker.sh \ diff --git a/doc/project.conf b/doc/project.conf index ac41d92..6c765c4 100644 --- a/doc/project.conf +++ b/doc/project.conf @@ -1,9 +1,15 @@ subdirs=scripts -targets=configure.html -dist=Makefile,docbook.sh,configure.xml +targets=configure.html,project.conf.5 +dist=Makefile,docbook.sh,configure.xml,project.conf.xml [configure.html] type=script script=./docbook.sh install= depends=configure.xml + +[project.conf.5] +type=script +script=./docbook.sh +install= +depends=project.conf.xml diff --git a/doc/project.conf.xml b/doc/project.conf.xml new file mode 100644 index 0000000..9939c25 --- /dev/null +++ b/doc/project.conf.xml @@ -0,0 +1,185 @@ + + + + + + + + + + + +]> + + + &title; + &package; + + + &firstname; + &surname; + Code and documentation. +
+ &email; +
+
+
+ + 2012 + &firstname; &surname; <&email;> + + + This manual page was written for the DeforaOS project (and may be + used by others). + 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. + +
+ + &name; + §ion; + + + &name; + &purpose; + + + Project configuration + + A project definition file should be found in every project directory managed + by &package;. These files must be named &name;. + + + File format + + 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: +
+ + variable=value + +
+ Configuration files may be commented, comment lines being prepended with a + hash sign "#". +
+ + Variable 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. + +
+ + Important variables + + The most significant variables recognized are mentioned below. + + + In the default section: + + subdirs: subdirectories to look for too + cppflags_force: CPPFLAGS to force + globally + cppflags: optional global CPPFLAGS + 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 subsequent sections, respectively named after the target + they define: + + type (mandatory): type of the target (eg "binary", + "library", "object", ...) + cppflags: additional CPPFLAGS for this + target + cflags: additional CFLAGS for this + target + ldflags: additional LDFLAGS for this + target + sources: source files to compile + depends: a list of files (or other targets) that this + target depends on + install: the destination path for + installation + + + +
+ + Target definitions + + Target types + + 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; the + shared object are also assigned a version number. + "object": produces a binary object file from the given source. + "plugin": 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. + "script": runs the given script, expecting the target + file to be generated from the sources defined. + + + + + Script targets + + Scripts have to be provided by the software project itself, as + configure does not provide any pre-installed set of standard + scripts. A few sample scripts are, however, distributed along with + the source code of the configure project, and introduced here. + + + 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. + configure is already known to have been successfully integrated this + way with: + + AppBroker: integration with the DeforaOS distributed + computing framework (see appbroker.sh) + DocBook: + markup language for technical documentation, based on either SGML or XML + (see docbook.sh) + Gettext: + internationalization (i18n) and localization (l10n) framework, notably + allowing software to be easily translated to other languages (see + gettext.sh) + Gtk-doc: + generates API documentation from comments within software projects, in + the format expected by the DevHelp API browser (see + gtkdoc.sh) + pkg-config: unified + interface to define compilation and linking rules to installed software + (see pkgconfig.sh) + + + + Writing scripts + + It is naturally possible to write scripts for integration with configure. + + + + + +
+