From fb5c492242f8d3cb67473a5217718e86ee41f439 Mon Sep 17 00:00:00 2001
From: Björn Persson <bjorn@rombobjörn.se>
Date: Thu, 17 Oct 2013 15:50:23 +0200
Subject: Documented targets.

---
 manual.css     |  8 ++++++
 manual.en.html | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/manual.css b/manual.css
index 570c4ef..904cbe2 100644
--- a/manual.css
+++ b/manual.css
@@ -9,6 +9,14 @@ p, ul, ol, dl, .example {
    margin-bottom : 0.5em;
 }
 
+dt {
+   margin-bottom : 0;
+}
+
+dd, dd > *:first-child {
+   margin-top : 0;
+}
+
 pre, code {
    font-family : monospace;
 }
diff --git a/manual.en.html b/manual.en.html
index 730d6de..fbeb65c 100755
--- a/manual.en.html
+++ b/manual.en.html
@@ -520,6 +520,84 @@ root of the source tree. Here's an example:</p>
 
 <pre class="example gpr">for Source_Dirs use ($Srcdir &amp; "/tools");</pre>
 
+<h3 id="targets">Make Targets</h3>
+
+<p>These phony targets are defined in <var>comfignat.mk</var>:</p>
+
+<dl>
+<dt><var>build</var></dt>
+<dd><p>This is what a plain “<samp>make</samp>” will do (unless your makefile
+defines some other target before it includes <var>comfignat.mk</var>). By
+default it builds and stages the build projects that are listed in
+<var>build_GPRs</var>, and preprocesses and stages any usage project files that
+are listed in <var>usage_GPRs</var>. You may add additional prerequisites if
+there are other things that should be built and installed by default, for
+example documentation:</p>
+
+<pre class="example make">build: man html pdf</pre></dd>
+
+<dt><var>install</var></dt>
+<dd><p>If a user unpacks a source package and immediately runs
+“<samp>make install</samp>”, then the <var>build</var> target is built and then
+installed. If some files have already been staged in the staging directory,
+then “<samp>make install</samp>” doesn't rebuild anything but just copies the
+staged directory structure to the directory specified in <var>DESTDIR</var>, or
+to the root directory if <var>DESTDIR</var> is empty.</p></dd>
+
+<dt><var>all</var></dt>
+<dd><p>By default <var>all</var> is the same as <var>build</var>, but you may
+add additional prerequisites to it if you have optional components that
+shouldn't be built by default. Such targets will be built by
+“<samp>make all</samp>” but not by a plain “<samp>make</samp>”:</p>
+
+<pre class="example make">all: demo_programs auxiliary_tools</pre></dd>
+
+<dt><var>base</var></dt>
+<dd><p>This builds and stages the build projects that are listed in
+<var>build_GPRs</var>, but does not do everything that <var>build</var> does.
+It can be used to bypass targets that you don't want to rebuild all the time
+when you're programming. Any targets that you do want to rebuild every time may
+be added as prerequisites.</p></dd>
+
+<dt><var>preprocess</var></dt>
+<dd><p>This preprocesses files that need to be preprocessed before projects are
+built.</p></dd>
+
+<dt><var>configure</var></dt>
+<dd><p>“<samp>make configure</samp>” is used to set values in the
+<a href="#configuration">persistent configuration</a> and to set up a
+<a href="#build_directories">separate build directory</a>. This is a
+double-colon rule so you can add your own <var>configure</var> recipe in case
+you need to configure things that can't easily be expressed as Make
+variables.</p></dd>
+
+<dt><var>show_configuration</var></dt>
+<dd><p>“<samp>make show_configuration</samp>” outputs the configured variables
+in the <a href="#configuration">persistent configuration</a>. This is a
+double-colon rule so you can add your own <var>show_configuration</var> recipe
+to accompany your own <var>configure</var> recipe.</p></dd>
+
+<dt><var>unconfigure</var></dt>
+<dd><p>This deletes the configuration file that “<samp>make configure</samp>”
+writes. This is a double-colon rule. If you add your own <var>configure</var>
+recipe that writes additional configuration files, then you should also add an
+<var>unconfigure</var> recipe to delete those files.</p></dd>
+
+<dt><var>clean</var></dt>
+<dd><p>This deletes all files that are normally created by building the
+software, but preserves the configuration. It's a double-colon rule so you can
+add your own <var>clean</var> recipe to delete files that your recipes
+generate.</p></dd>
+
+<dt><var>distclean</var></dt>
+<dd><p>This deletes all files that are normally created by configuring or
+building the software. In an unpacked source tree where builds have been done
+but no other files have been created, “<samp>make distclean</samp>” leaves only
+the files that were in the source package. In a
+<a href="#build_directories">separate build directory</a> it leaves only the
+delegating makefile.</p></dd>
+</dl>
+
 <h3 id="installation_instructions">Adjusting the Installation Instructions</h3>
 
 <p>After writing your makefile and project files, you should adapt the
@@ -549,7 +627,8 @@ working in subdirectories use the right build and staging directories.</p></li>
 <li><p>The ability to save environment variables in the persistent
 configuration was added.</p></li>
 
-<li><p>The Make target <var>show_configuration</var> was added.</p></li>
+<li><p>The Make targets <var>all</var>, <var>base</var> and
+<var>show_configuration</var> were added.</p></li>
 </ul>
 
 <!--#include virtual="/SSIfragment/giltig.shtml" -->
-- 
cgit v1.2.3