New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
make.html in vendors/doc/user_guide – NEMO

source: vendors/doc/user_guide/make.html @ 10669

Last change on this file since 10669 was 10669, checked in by nicolasmartin, 5 years ago

Import latest FCM release from Github into the repository for testing

File size: 91.7 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4  <title>FCM: User Guide: FCM Make</title>
5  <meta name="author" content="FCM team" />
6  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7  <link rel="icon" href="../etc/fcm-icon.png" type="image/png" />
8  <link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" />
9  <link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" />
10  <link href="../etc/fcm.css" rel="stylesheet" media="screen" />
11</head>
12<body>
13  <div class="navbar navbar-inverse">
14    <div class="container-fluid">
15      <div class="navbar-header">
16        <a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a>
17      </div>
18      <div class="collapse navbar-collapse">
19        <ul class="nav navbar-nav">
20          <li><a href="../installation/">Installation</a></li>
21
22          <li><a class="active" href="#">User Guide</a></li>
23        </ul>
24      </div>
25    </div>
26  </div>
27
28  <div class="page-header">
29    <div class="fcm-page-content pull-right well well-sm"></div>
30    <h1>FCM: User Guide: FCM Make</h1>
31  </div>
32
33  <div class="container">
34  <div class="row">
35  <div class="col-md-12">
36
37  <h2 id="introduction">Introduction</h2>
38
39  <p>The FCM make system provides a common environment for running the extract
40  system, build system, and other utilities. Simply put, it controls a chain of
41  steps. It is NOT to be confused with the standard Unix utility
42  <code>make</code>.</p>
43
44  <p>See <a href="annex_cfg.html#make">Annex: FCM Configuration File &gt; FCM
45  Make Configuration</a> for a full list of declarations in an FCM Make
46  configuration file.</p>
47
48  <h2 id="concept">FCM Make Concept</h2>
49
50  <h3 id="concept.cli">FCM Make Concept: Command Line Interface</h3>
51
52  <p>The FCM make system can be invoked using the command line interface:</p>
53  <pre>
54fcm make [OPTIONS] [DECLARAION ...]
55</pre>
56
57  <p>The FCM make system relies on a configuration file to tell it what to do.
58  It looks for configurations with the following logic:</p>
59
60  <ol>
61    <li>It reads each configuration file specified using the
62    <code>--config-file=PATH</code> option in the order they are
63    specified.</li>
64   
65    <li>If the <code>--config-file=PATH</code> option is not specified, it will
66    attempt to read <code>fcm-make.cfg</code> if it exists.</li>
67
68    <li>It looks at the current working directory, or the directory specified
69    in the <code>--directory=PATH</code> option for configuration files
70    specified as relative paths.</li>
71
72    <li>If one or more <code>--config-file-path=PATH</code> option is
73    specified, it also searches for configuration files under the specified
74    values, in the order the options are specified.</li>
75
76    <li>Finally, each <var>KEY=VALUE</var> command line argument is considered
77    a configuration declaration line.</li>
78  </ol>
79
80  <p>For details of the other command line options please see <a href=
81  "command_ref.html#fcm-make">FCM Command Reference &gt; fcm make</a>.</p>
82
83  <h3 id="concept.cfg">FCM Make Concept: Configuration File</h3>
84
85  <p>The FCM make configuration file is expected to be an FCM configuration
86  file. (See <a href="annex_cfg.html">Annex: FCM Configuration File</a>.) A
87  typical FCM make configuration file may look like:</p>
88  <pre>
89steps = extract build                           # 1
90
91extract.ns = egg ham bacon                      # 2
92# ... more extract configuration
93
94build.target = egg.exe ham.exe bacon            # 3
95# ... more build configuration
96</pre>
97
98  <p>At point 1, the <code><a href="annex_cfg.html#make.steps">steps</a></code>
99  declaration tells the system to invoke two steps. Their IDs are
100  <samp>extract</samp> and <samp>build</samp>, both are IDs for built-in
101  systems. (The other 2 being <samp>mirror</samp> and <samp>preprocess</samp>.)
102  Each step has its own declarations, which are prefixed with the step ID and a
103  full stop. The declarations at point 2 are used by the logic for running the
104  <samp>extract</samp> step and the declarations at point 3 are used by the
105  logic for running the <samp>build</samp> step.</p>
106
107  <p>There are times when you may need to invoke the same system (e.g. the
108  build system) in slightly different configurations. To do this you need to
109  use the <code><a href="annex_cfg.html#make.step.class">step.class</a></code>
110  declaration to define custom step IDs for each build. E.g.:</p>
111  <pre>
112step.class[build-this build-that] = build       # 1
113steps = extract build-this build-that           # 2
114
115extract.ns = egg ham bacon                      # 3
116# ... more extract configuration
117
118build-this.prop{fc.defs} = DEFS TO BUILD THIS   # 4
119build-this.target = this.exe
120# ... more build configuration for "build-this"
121
122build-that.prop{fc.defs} = DEFS TO BUILD THAT   # 5
123build-that.target = that.exe
124# ... more build configuration for "build-that"
125</pre>
126
127  <p>At point 1, we define the IDs <samp>build-this</samp> and
128  <samp>build-that</samp> to be an instance of the <samp>build</samp> class. At
129  point 2, we tell the system to run <samp>extract</samp>, then
130  <samp>build-this</samp>, then <samp>build-that</samp>. At point 4 and 5, we
131  define the configurations for <samp>build-this</samp> and
132  <samp>build-that</samp> respectively.</p>
133
134  <h3 id="concept.use">FCM Make Concept: Inheritance</h3>
135
136  <p>The FCM Make system allows inheritance of configuration and files from
137  succeeded makes, so the current make does not have to re-do everything that
138  may already be available else where. To do this, specify the inheritance with
139  a <code><a href= "annex_cfg.html#make.use">use</a> declaration</code>,
140  e.g.:</p>
141
142  <pre>
143use = /path/to/succeeded/make/
144</pre>
145
146  <p>For more information on how an inheritance behaves, see:</p>
147
148  <ul>
149    <li><a href="#extract.inherit">Extract Inheritance</a></li>
150
151    <li><a href="#build.inherit">Build Inheritance</a></li>
152  </ul>
153
154  <h3 id="concept.dest">FCM Make Concept: Directory Structure</h3>
155
156  <p>When you run <code>fcm make</code>, it will create a directory
157  structure that may look like:</p>
158
159  <pre>
160.fcm-make/...
161extract/...
162build/...
163...
164</pre>
165
166  <p>Each normal sub-directory, such as <samp>extract/</samp> and
167  <samp>build/</samp>, contains the result of each step. The hidden
168  sub-directory <samp>.fcm-make/</samp> is used by <code>fcm make</code> as a
169  working area. It may contain the following items:</p>
170
171  <dl>
172    <dt><samp>.fcm-make/cache/</samp></dt>
173
174    <dd>An area for caching non-local items. E.g. the extract system exports
175    source trees from the version control system into this cache. If <code>fcm
176    make</code> is invoked with the <code>--archive</code> option, contents in
177    this directory will be compressed into TAR-GZIP files, e.g.
178    <samp>.fcm-make/cache/extract/</samp> will become
179    <samp>.fcm-make/cache/extract.tar.gz</samp>.</dd>
180
181    <dt><samp>fcm-make-as-parsed.cfg -&gt;
182    .fcm-make/config-as-parsed.cfg</samp></dt>
183
184    <dd>The configuration file as parsed by the latest <code>fcm make</code>
185    command at this destination.</dd>
186
187    <dt><samp>fcm-make-on-success.cfg -&gt;
188    .fcm-make/config-on-success.cfg</samp></dt>
189
190    <dd>The configuration file that can be used to repeat the latest successful
191    <code>fcm make</code> command at this destination.</dd>
192
193    <dt><samp>.fcm-make/ctx.gz</samp></dt>
194   
195    <dd>A serialised data structure that represents the context of the latest
196    <code>fcm make</code> command at this destination.  It is a
197    <code>gzip</code> file containing data in the <a
198    href="http://perldoc.perl.org/Storable.html">Perl Storable</a> format.</dd>
199
200    <dt><samp>fcm-make.log -&gt; .fcm-make/log</samp></dt>
201   
202    <dd>A diagnostic log generated by the latest <code>fcm make</code> command
203    at this destination. The content should be equivalent to the diagnostic
204    output in STDOUT and STDERR at <code>-vv</code> verbosity.</dd>
205  </dl>
206
207  <h3 id="concept.name">FCM Make Concept: Context Name</h3>
208
209  <p>You may sometimes need to run <code>fcm make</code> in the same location of
210  the file system. Perhaps you are on a network with a shared file system, but
211  only certain tools are available on different hosts, e.g. you can only extract
212  on one host and build on a different host, you should name the makes so that
213  they don't end up overwriting each other's context, logs and other
214  outputs. To do so, you can use the <code>--name=NAME</code> option on the
215  command line, and/or the <a href="annex_cfg.html#make.name">name</a>
216  declaration in the configuration file. Using <code>--name=2</code> as an
217  example, you will get the following:</p>
218
219  <ul>
220    <li>The command will search for <code>fcm-make2.cfg</code> instead of
221    <code>fcm-make.cfg</code>.</li>
222
223    <li>The command will dump context, logs, etc with file names such as
224    <samp>.fcm-make2/*</samp>, <samp>fcm-make2-as-parsed.cfg</samp>,
225    <samp>fcm-make2.log</samp>, etc.</li>
226
227    <li>The command will only allow inheritance from a location where a
228    successful make with the same name exists.</li>
229  </ul>
230
231  <h2 id="extract">Extract</h2>
232
233  <p>The extract system provides an interface between the version control
234  system (currently Subversion) and the build system. Where appropriate, it
235  extracts code and combines changes from the repositories and other
236  user-defined locations to a directory tree suitable for feeding into the build
237  system.</p>
238
239  <p>The extract system supports the <code>--jobs=N</code> option of the
240  <code>fcm make</code> command. It uses <var>N</var> child processes to get
241  source trees information and to export source trees from their repositories in
242  parallel.</p>
243
244  <h3 id="extract.basic">Extract: Basic</h3>
245
246  <p>The following is an example of how to extract the source trees from a file
247  system path and the trunks of 2 known projects (version controlled in
248  Subversion repositories with a standard FCM layout):</p>
249  <pre>
250steps = extract                    # line 1
251extract.ns = ops var um            # line 2
252extract.location[ops] = $HOME/ops  # line 3
253</pre>
254
255  <p>Here is an explanation of what each line does:</p>
256
257  <ul>
258    <li><dfn>line 1</dfn>: the <code><a href=
259    "annex_cfg.html#make.steps">steps</a></code> declaration tells the make
260    system to invoke the extract system.</li>
261
262    <li><dfn>line 2</dfn>: the <code><a href=
263    "annex_cfg.html#make.extract.ns">extract.ns</a></code> declaration is used
264    to specify a space delimited list of names of the projects to extract.</li>
265
266    <li><dfn>line 3</dfn>: the <code><a href=
267    "annex_cfg.html#make.extract.location">extract.location</a></code>
268    declaration is used to specify the base source tree of a project
269    (<samp>ops</samp> in this case) to extract. The value of the declaration
270    can be a path in the file system or a location in a version control system.
271    In this case, the declaration specifies the base source tree of the
272    <samp>ops</samp> project to be a path in the file system at
273    <samp>$HOME/ops</samp>. If the base source tree of a specified project
274    name-space is not declared, the system will make an assumption. For a
275    project hosted in a Subversion repository, the system will assume
276    <samp>trunk@HEAD</samp> if the project URL is registered in the keyword
277    configuration file or with the <code><a href=
278    "annex_cfg.html#make.extract.location.primary">extract.location{primary}</a></code>
279    declaration (see below).</li>
280  </ul>
281
282  <p>If you save this file as <samp>fcm-make.cfg</samp> and invoke the
283  <code>fcm make</code> command you should end up with a source tree in the
284  current working directory that looks like (hidden path not shown):</p>
285  <pre>
286extract/ops/...
287extract/um/...
288extract/var/...
289</pre>
290
291  <p>The result of the extract can be found in the <samp>extract/</samp>
292  sub-directory. Note: The generated source tree will not contain any symbolic
293  links or hidden files (e.g. file names beginning with a <samp>.</samp>),
294  because the extract system ignores them.</p>
295
296  <div class="well">
297    <p><strong><span class="glyphicon glyphicon-pencil"
298    aria-hidden="true"></span> Note - project name-space and
299    location</strong></p>
300
301    <p>Whoever installed FCM at your site would have defined the name-spaces
302    and the locations of the common projects at your site using the keyword
303    configuration file at <samp>$FCM/etc/fcm-keyword.cfg</samp> (where
304    <samp>$FCM/bin</samp> is the path at which FCM is installed).
305    Alternatively, users can define their own set of project name-spaces and
306    their locations using <samp>$HOME/.metomi/fcm/keyword.cfg</samp>. For
307    information on keyword configuration files, please refer to <a href=
308    "system_admin.html#fcm-keywords">System Administration &gt; FCM
309    keywords</a>. If a project name-space is not defined in a keyword
310    configuration, it can be defined in the FCM make configuration using the
311    <code><a href=
312    "annex_cfg.html#make.extract.location.primary">extract.location{primary}</a></code>
313    declaration. E.g. to define the location of the <samp>foo</samp> project,
314    you can do: <samp>extract.location{primary}[foo] =
315    svn://server/repos/foo</samp>.</p>
316  </div>
317
318  <div class="well">
319    <p><strong><span class="glyphicon glyphicon-pencil"
320    aria-hidden="true"></span> Note - incremental mode</strong></p>
321
322    <p>Suppose you have already invoked <code>fcm make</code> using the above
323    configuration file. At a later time, you have made some changes to some of
324    the files in the source trees. Re-running <code>fcm make</code> on the same
325    configuration will trigger the incremental mode. In the incremental mode,
326    the extract system will update only those files that are modified. If the
327    last modified time (or last commit revision) of a source file in the
328    current extract differs from that in the previous extract, the system will
329    attempt a content comparison. The system updates the destination only if
330    the content and/or file access permission of the source differs from that
331    of the destination. To avoid the incremental mode and start afresh, invoke
332    <code>fcm make</code> with the <code>--new</code> option.</p>
333  </div>
334
335  <h3 id="extract.location-types">Extract: Location Types</h3>
336
337  <p>The extract system currently supports the following location types:</p>
338
339  <dl class="dl-horizontal">
340    <dt>fs</dt>
341
342    <dd>A readable location in the local file system. E.g.
343    <code>~/my-project</code>, <code>/home/lily/my-project</code>, etc.</dd>
344
345    <dt>ssh</dt>
346
347    <dd>A readable location in the file system of a remote host accessible via
348    <code>ssh</code> and <code>rsync</code>, specified in the form
349    <var>[USER@]HOST:PATH</var>. The <code>ssh</code> access must be
350    without a password, and you must be able to run the <a href=
351    "http://www.gnu.org/software/coreutils/">GNU coreutils</a> version of the
352    <code>find</code> and <code>stat</code> on the remote host. E.g.
353    <code>mylinuxbox:my-project</code>,
354    <code>holly@hpc:/data/holly/my-project</code>.</dd>
355
356    <dt>svn</dt>
357
358    <dd>A Subversion location, which may be a working copy or a valid Subversion
359    URL. Supported URL schemes are: <code>file</code>, <code>http</code>,
360    <code>https</code>, <code>svn</code> and <code>svn+ssh</code>. E.g.
361    <code>svn://mysvnhost/my-project/trunk@40778</code>,
362    <code>~/my-project@32734</code>.</dd>
363  </dl>
364
365  <p>See also <a href=
366  "annex_cfg.html#make.extract.location">extract.location</a>.</p>
367
368  <h3 id="extract.path-root">Extract: Redefine the Root of the Source Tree of a
369  Project</h3>
370
371  <p>Consider a project called <samp>foo</samp> with a source tree that looks
372  like:</p>
373  <pre>
374doc/...
375src/bar/...
376src/baz/...
377</pre>
378
379  <p>Suppose you are only interested in the contents of the <samp>src/</samp>
380  sub-tree. You can specify the root of the extract using the <code><a href=
381  "annex_cfg.html#make.extract.path-root">extract.path-root</a></code>
382  declaration. E.g.:</p>
383  <pre>
384steps = extract              # line 1
385extract.ns = foo             # line 2
386extract.path-root[foo] = src # line 3
387</pre>
388
389  <p>Running <code>fcm make</code> with this configuration should give a source
390  tree that looks like (hidden path not shown):</p>
391  <pre>
392extract/foo/bar/...
393extract/foo/baz/...
394</pre>
395
396  <h3 id="extract.path-filter">Extract: Filter the Paths in the Source Tree of
397  a Project</h3>
398
399  <p>Going back to the above source tree in the <samp>foo</samp> project,
400  imagine the <samp>src/bar/</samp> sub-directory contains:</p>
401  <pre>
402src/bar/wine/red.c
403src/bar/wine/rose.c
404src/bar/wine/white.c
405src/bar/...
406</pre>
407
408  <p>If you do not want <samp>src/bar/wine/rose.c</samp> in the extract, you
409  can ask for it to be excluded using the <code><a href=
410  "annex_cfg.html#make.extract.path-excl">extract.path-excl</a></code>
411  declaration. E.g.:</p>
412  <pre>
413steps = extract                          # line 1
414extract.ns = foo
415extract.path-root[foo] = src             # line 3
416extract.path-excl[foo] = bar/wine/rose.c # line 4
417</pre>
418
419  <p>Note: Because the root is redefined in line 3, the path in the
420  <code><a href=
421  "annex_cfg.html#make.extract.path-excl">extract.path-excl</a></code>
422  declaration in line 4 is declared from the new root level.</p>
423
424  <p>Running <code>fcm make</code> with this configuration should give a source
425  tree that looks like (hidden path not shown):</p>
426  <pre>
427extract/foo/bar/wine/red.c
428extract/foo/bar/wine/white.c
429extract/foo/bar/...
430extract/foo/baz/...
431</pre>
432
433  <p>On the other hand, if you only want <samp>src/bar/wine/rose.c</samp> in
434  the extract, you can ask the system to exclude everything in
435  <samp>src/bar/wine/</samp> but include <samp>src/bar/wine/rose.c</samp> using
436  the <code><a href=
437  "annex_cfg.html#make.extract.path-incl">extract.path-incl</a></code>
438  declaration. E.g.:</p>
439  <pre>
440steps = extract                          # line 1
441extract.ns = foo                         # line 2
442extract.path-root[foo] = src             # line 3
443extract.path-excl[foo] = bar/wine        # line 4
444extract.path-incl[foo] = bar/wine/rose.c # line 5
445</pre>
446
447  <p>Running <code>fcm make</code> with this configuration should give a source
448  tree that looks like (hidden path not shown):</p>
449  <pre>
450extract/foo/bar/wine/rose.c
451extract/foo/bar/...
452extract/foo/baz/...
453</pre>
454
455  <h3 id="extract.location-diff">Extract: Combining Changes from Multiple
456  Branches of a Project</h3>
457
458  <p>We have so far only dealt with extracts from a single base source tree in
459  each project. The extract system can also be used to <em>combine</em> changes
460  from different source trees (against a base source tree) of a project.</p>
461
462  <p>E.g. consider a project called <samp>food</samp>. In the latest release
463  (<samp>trunk@3739</samp>), the source tree looks like this:</p>
464  <pre>
465doc/...
466src/egg/boiled.y
467src/egg/microwave.x
468src/egg/omelette.c
469src/egg/poached.f90
470src/...
471</pre>
472
473  <p>Jamie, Gordon and Rick are all developing changes against the latest
474  release of the project.</p>
475
476  <p>Jamie has made the following changes (displayed using the notation of
477  <code>svn status</code>) in his branch at
478  <samp>branches/dev/jamie/r3739_t381@3984</samp>:</p>
479  <pre>
480D      src/egg/boiled.y
481A      src/egg/fried.pl
482M      src/egg/omelette.c
483</pre>
484
485  <p>Gordon has made the following changes in his branch at
486  <samp>branches/dev/gordon/r3739_t376@3993</samp>:</p>
487  <pre>
488M      src/egg/omelette.c
489M      src/egg/poached.f90
490</pre>
491
492  <p>Rick has made the following changes in his working copy at
493  <samp>~rick/food</samp>, but has yet to commit his changes back:</p>
494  <pre>
495M      src/egg/boiled.y
496A      src/egg/scrambled.bash
497</pre>
498
499  <p>To combine their changes in an extract, the FCM make configuration file
500  should look like:</p>
501  <pre id="example.extract">
502steps = extract
503extract.ns = food
504extract.location[food] = trunk@3739
505extract.location{diff}[food] = \
506    branches/dev/jamie/r3739_t381@3984 \
507    branches/dev/gordon/r3739_t376@3993 \
508    ~rick/food
509</pre>
510
511  <p>Here we have an <code><a href=
512  "annex_cfg.html#make.extract.location">extract.location</a></code>
513  declaration like before. This time it is pointing to the latest release of
514  the <samp>food</samp> project. The changes against the base source tree are
515  declared using the <code><a href=
516  "annex_cfg.html#make.extract.location.diff">extract.location{diff}</a></code>
517  declaration.</p>
518
519  <p>Invoking <code>fcm make</code> with this configuration file will result in
520  a source tree that looks like (hidden file not shown):</p>
521  <pre>
522extract/doc/...
523extract/src/egg/fried.pl
524extract/src/egg/microwave.x
525extract/src/egg/omelette.c
526extract/src/egg/poached.f90
527extract/src/egg/scrambled.bash
528extract/src/...
529</pre>
530
531  <p>Note:</p>
532
533  <ul>
534    <li>There is no <samp>extract/src/egg/boiled.y</samp> file in the extract
535    tree because it is deleted by Jamie's branch. Even though this file is
536    modified in Rick's working copy, the extract will ignore this and assume
537    that the deletion takes precedence.</li>
538
539    <li>The <samp>extract/src/egg/fried.pl</samp> file comes from Jamie's
540    branch.</li>
541
542    <li>The <samp>extract/src/egg/microwave.x</samp> file comes from the latest
543    release (base).</li>
544
545    <li>The <samp>extract/src/egg/omelette.c</samp> file is the result of a
546    merge of the changes in Jamie's and Gordon's branches. This example assumes
547    that there is no conflict in the merge. If the merge results in a conflict,
548    the extract will fail.</li>
549
550    <li>The <samp>extract/src/egg/poached.f90</samp> file comes from Gordon's
551    branch.</li>
552
553    <li>The <samp>extract/src/egg/scrambled.bash</samp> file comes from Rick's
554    working copy.</li>
555  </ul>
556
557  <h3 id="extract.inherit">Extract Inheritance</h3>
558
559  <p>If a previous extract with a similar configuration exists in another
560  location, it can be more efficient to inherit from this previous extract in
561  your current extract. This works like a normal incremental extract, except
562  that your extract will only contain the changes you have specified (compared
563  with the inherited extract) instead of the full directory tree in the
564  destination. This type of incremental extract is useful in several ways. For
565  instance:</p>
566
567  <ul>
568    <li>It is fast, because you only have to extract files that you have
569    changed.</li>
570
571    <li>The subsequent build will also be fast, since it will act like an
572    incremental build.</li>
573
574    <li>You do not need write access to the original extract. A system
575    administrator can set up a stable version in a central account, which
576    developers can then inherit from.</li>
577
578    <li>You want an incremental extract, but you need to leave the original
579    extract unmodified.</li>
580  </ul>
581
582  <p>Consider the <a href="#example.extract">previous example</a>. Imagine an
583  extract already exists for the latest release for the <samp>food</samp>
584  project at <samp>/home/food/latest/</samp>, and now you want to test the
585  changes introduced by Jamie, Gordon and Rick. You can <code><a href=
586  "annex_cfg.html#make.use">use</a></code> the original extract with the
587  changes:</p>
588  <pre>
589use = /home/food/latest
590extract.location{diff}[food] = \
591    branches/dev/jamie/r3739_t381@3984 \
592    branches/dev/gordon/r3739_t376@3993 \
593    ~rick/food
594</pre>
595
596  <p>Invoking <code>fcm make</code> with this configuration file will result in
597  a source tree that looks like (hidden file not shown):</p>
598  <pre>
599extract/src/egg/fried.pl
600extract/src/egg/omelette.c
601extract/src/egg/poached.f90
602extract/src/egg/scrambled.bash
603</pre>
604
605  <p>The extract will work in an incremental-like mode. The only difference is
606  that the original extract at <samp>/home/food/latest/</samp> will be left
607  untouched, and the new extract will contain only the changes introduced by
608  the diff locations. Note that, although
609  <samp>extract/src/egg/boiled.y</samp> remains in the original extract, it
610  will not be used in any subsequent build step.</p>
611
612  <dl>
613    <dt>Extract inheritance limitation</dt>
614
615    <dd>
616      <p>Extract inheritance allows you to add more diff locations to a project,
617      but you should not include any other declarations relating to the extract.
618      Doing so is not safe and should trigger an exception.</p>
619
620      <p>In some situations this implies that it will not be possible to use
621      inherited extracts. You should use a new extract if, for instance, a new
622      diff location contains a change which requires the use of source files in
623      a previously excluded name-space.</p>
624    </dd>
625  </dl>
626
627  <h3 id="extract.diagnostic">Extract Diagnostic</h3>
628
629  <p>The amount of diagnostic messages generated by the extract system is
630  dependent on the diagnostic verbosity level that can be modified by the
631  <code>-v</code> and <code>-q</code> options to the <code>fcm make</code>
632  command.</p>
633
634  <p>The following is a list of diagnostic output at each verbosity level:</p>
635
636  <dl>
637    <dt>-q</dt>
638
639    <dd>
640      <ul>
641        <li>Exceptions.</li>
642      </ul>
643    </dd>
644
645    <dt>default</dt>
646
647    <dd>
648      <ul>
649        <li>Everything at the -q level.</li>
650
651        <li>Start time of the extract.</li>
652
653        <li>The number and location of each source tree in each project. The
654        base source tree is number 0. E.g.:
655          <pre>
656[info] location um: 0: svn://fcm2/UM_svn/UM/trunk@11732
657[info] location um: 1: svn://fcm2/UM_svn/UM/branches/dev/Share/VN7.3_hg3_dust_443@11858
658[info] location um: 2: svn://fcm2/UM_svn/UM/branches/dev/Share/VN7.3_hg3_ccw_precip@11857
659[info] location um: 3: svn://fcm2/UM_svn/UM/branches/dev/hadco/VN7.3_HG3_porting_lsp_fixes@12029
660...
661</pre>
662        </li>
663
664        <li>The number of targets by their destination status and their source
665        status. E.g.:
666          <pre>
667[info]   dest:    3 [A added]
668[info]   dest:  134 [a added, overriding inherited]
669[info]   dest:    6 [d deleted, overriding inherited]
670[info]   dest: 2818 [U unchanged]
671[info] source:    3 [A added by a diff source tree]
672[info] source:    6 [D deleted by a diff source tree]
673[info] source:   16 [G merged from 2+ diff source trees]
674[info] source:  118 [M modified by a diff source tree]
675[info] source: 2818 [U from base]
676</pre>
677        </li>
678
679        <li>Total time.</li>
680      </ul>
681    </dd>
682
683    <dt>-v</dt>
684
685    <dd>
686      <ul>
687        <li>Everything at the default level.</li>
688
689        <li>The destination and source status for each modified target. E.g.:
690          <pre>
691...
692[info] aM um:0,13    atmosphere/short_wave_radiation/r2_lwrad3c.F90
693[info] aG um:0,6,13  control/top_level/scm_main.F90
694[info] AA um:-,8     include/constant/cnv_parc_lim.h
695...
696</pre>
697
698          <p>The 2 letters following <samp>[info]</samp> is the destination
699          status and the source status of the target. This is followed by the
700          name-space of the project, a colon and the source tree number(s)
701          providing the source for the target (in a comma separated list). This
702          is then followed by the name-space of the target path. The source
703          tree number <samp>0</samp> denotes the base source tree, a dash
704          <samp>-</samp> in place of a <samp>0</samp> means that the source
705          only exists in a diff source tree.</p>
706        </li>
707      </ul>
708    </dd>
709
710    <dt>-vv</dt>
711
712    <dd>
713      <ul>
714        <li>Everything at the -v level.</li>
715
716        <li>Each shell command invoked with elapsed time and return code.</li>
717      </ul>
718    </dd>
719  </dl>
720
721  <p>Here is an explanation of each target destination status:</p>
722
723  <dl>
724    <dt><samp>[A added]</samp></dt>
725
726    <dd>Target newly added to the destination.</dd>
727
728    <dt><samp>[a added, overriding inherited]</samp></dt>
729
730    <dd>Target added to the current extract destination, i.e. modified compared
731    with the target with the same name-space in an inherited extract
732    destination.</dd>
733
734    <dt><samp>[D deleted]</samp></dt>
735
736    <dd>Target deleted from the extract destination during an incremental
737    extract.</dd>
738
739    <dt><samp>[d deleted, overriding inherited]</samp></dt>
740
741    <dd>Target deleted from the current extract destination, i.e. a target with
742    the same name-space exists in an inherited extract destination.</dd>
743
744    <dt><samp>[M modified]</samp></dt>
745
746    <dd>Target modified in the extract destination during an incremental
747    extract.</dd>
748
749    <dt><samp>[U unchanged]</samp></dt>
750
751    <dd>Target unchanged compared with the previous (or any inherited)
752    extract.</dd>
753
754    <dt><samp>[? unknown]</samp></dt>
755
756    <dd>Target does not have a destination. This destination status is normally
757    associated with the <samp>[D deleted]</samp> source status.</dd>
758  </dl>
759
760  <p>Here is an explanation of each target source status:</p>
761
762  <dl>
763    <dt><samp>[A added by a diff source tree]</samp></dt>
764
765    <dd>The source of the target comes from a diff source tree, and the base
766    source tree does not have a source in the same name-space.</dd>
767
768    <dt><samp>[D deleted by a diff source tree]</samp></dt>
769
770    <dd>Target is deleted by a diff source tree, (i.e. exists in base source
771    tree, but missing from a diff source tree).</dd>
772
773    <dt><samp>[G merged from 2+ diff source trees]</samp></dt>
774
775    <dd>The source of the target comes from 2 or more diff source trees, (i.e.
776    the actual source is the result of a merge between all the changes).</dd>
777
778    <dt><samp>[M modified by a diff source tree]</samp></dt>
779
780    <dd>The source of the target comes from a diff source tree.</dd>
781
782    <dt><samp>[U from base]</samp></dt>
783
784    <dd>The source of the target comes from the base source tree, (i.e. the
785    source is unchanged by any diff source tree).</dd>
786
787    <dt><samp>[? unknown]</samp></dt>
788
789    <dd>The target has no source. This source status is normally displayed in an
790    incremental extract, where a target in a previous extract is not a target in
791    the current extract, and is normally associated with the <samp>[D
792    deleted]</samp> destination status.</dd>
793  </dl>
794
795  <h2 id="mirror">Mirror</h2>
796
797  <p>The mirror system provides a way to mirror the results of the make steps
798  to another location, where the FCM make may need to continue. It is typically
799  used after an extract to set up the build on an alternate platform.</p>
800
801  <h3 id="mirror.basic">Mirror: Basic</h3>
802
803  <p>Consider the following example:</p>
804  <pre>
805steps = extract mirror                            # 1
806# ... some extract declarations
807mirror.target = user@somewhere:/path/in/somewhere # 2
808mirror.prop{config-file.name} = -at-somewhere     # 3
809mirror.prop{config-file.steps} = preprocess build # 4
810# ... some preprocess declarations
811# ... some build declarations
812</pre>
813
814  <p>When the system runs with this configuration, the system will mirror the
815  result of the extract to the <a href=
816  "annex_cfg.html#make.mirror.target">mirror.target</a>, i.e.
817  <samp>somewhere:/path/in/somewhere</samp> using <code>ssh</code> and
818  <code>rsync</code>.</p>
819 
820  <p>With the <a href=
821  "annex_cfg.html#make.mirror.prop.config-file.name">config-file.name</a>
822  property set at point 3 and the <a href=
823  "annex_cfg.html#make.mirror.prop.config-file.steps">config-file.steps</a>
824  property set at point 4, it will write a configuration file called
825  <samp>fcm-make-at-somewhere.cfg</samp> with the make name set as
826  <samp>-at-somewhere</samp> in the mirror target so that the
827  <samp>preprocess</samp> and <samp>build</samp> steps can continue there.</p>
828
829  <h3 id="mirror.diagnostic">Mirror Diagnostic</h3>
830
831  <p>The amount of diagnostic messages generated by the mirror system is
832  dependent on the diagnostic verbosity level that can be modified by the
833  <code>-v</code> and <code>-q</code> options to the <code>fcm make</code>
834  command.</p>
835
836  <p>The following is a list of diagnostic output at each verbosity level:</p>
837
838  <dl>
839    <dt>-q</dt>
840
841    <dd>
842      <ul>
843        <li>Exceptions.</li>
844      </ul>
845    </dd>
846
847    <dt>default</dt>
848
849    <dd>
850      <ul>
851        <li>Everything at the -q level.</li>
852
853        <li>Start time of the mirror.</li>
854
855        <li>The updated destination and its source.</li>
856
857        <li>Total time.</li>
858      </ul>
859    </dd>
860
861    <dt>-v</dt>
862
863    <dd>
864      <ul>
865        <li>Everything at the default level.</li>
866      </ul>
867    </dd>
868
869    <dt>-vv</dt>
870
871    <dd>
872      <ul>
873        <li>Everything at the -v level.</li>
874
875        <li>Each shell command invoked with elapsed time and return code.</li>
876      </ul>
877    </dd>
878  </dl>
879
880  <h2 id="build">Build</h2>
881
882  <p>The build system performs actions on a set of source files using its
883  predefined logic and the properties specified in the configuration. For
884  example, it will attempt to create a binary executable for a source file
885  containing a Fortran program.</p>
886
887  <p>The build system supports the <code>--jobs=N</code> option of the <code>fcm
888  make</code> command. It uses <var>N</var> child processes to analyse the
889  source files and to update the targets in parallel.</p>
890
891  <h3 id="build.basic">Build: Basic</h3>
892
893  <p>Consider a source tree at <samp>$HOME/my-source-tree/</samp> containing
894  some Fortran source files including at least one with a main program (and
895  maybe other supported types of source files), you can set up an FCM make
896  configuration file to build an executable. E.g.:</p>
897  <pre>
898steps = build
899build.target{task} = link
900build.source = $HOME/my-source-tree
901</pre>
902
903  <p>In this simple 3 line configuration, the <code><a href=
904  "annex_cfg.html#make.steps">steps</a></code> declaration tells the make
905  system to invoke the build system, the <code><a href=
906  "annex_cfg.html#make.build.target">build.target</a></code> declaration tells
907  the system to build any targets which require linking (i.e. any main
908  programs), and the <code><a href=
909  "annex_cfg.html#make.build.source">build.source</a></code> declaration
910  specifies the location of the source tree.</p>
911
912  <p>If you save this file as <samp>fcm-make.cfg</samp> and invoke the
913  <code>fcm make</code> command it should attempt to build the source tree in
914  the current working directory, using the default properties. If the default
915  Fortran compiler <samp>gfortran</samp> is installed, and nothing goes wrong,
916  you will end up with a directory tree that looks like (hidden path not
917  shown):</p>
918  <pre>
919build/bin/...
920build/include/...
921build/o/...
922</pre>
923
924  <p>The result of the build can be found in the sub-directories of the
925  <samp>build/</samp> sub-directory. Each <samp>build/*/</samp> sub-directory
926  contains a category of targets:</p>
927
928  <dl>
929    <dt id="build.category.bin"><samp>bin</samp></dt>
930
931    <dd>e.g. executable binary and script.</dd>
932
933    <dt id="build.category.etc"><samp>etc</samp></dt>
934
935    <dd>e.g. data files.</dd>
936
937    <dt id="build.category.include"><samp>include</samp></dt>
938
939    <dd>e.g. include files and Fortran module definition files.</dd>
940
941    <dt id="build.category.lib"><samp>lib</samp></dt>
942
943    <dd>e.g. object archives.</dd>
944
945    <dt id="build.category.o"><samp>o</samp></dt>
946
947    <dd>e.g. object files</dd>
948  </dl>
949
950  <p>Sub-directories are only created as necessary, so you may not find all of
951  the above in your destination tree.</p>
952
953  <p>If <code>fcm make</code> is invoked with the <code>--archive</code> option,
954  sub-directories in categories containing intermediate build files (or any
955  category specified in the
956  <a href="annex_cfg.html#make.build.prop.archive-ok-target-category">
957  archive-ok-target-category</a>
958  property) will be put into TAR-GZIP files. E.g. with the default setting,
959  <samp>include/</samp> and <samp>o/</samp> will become
960  <samp>include.tar.gz</samp> and <samp>o.tar.gz</samp> respectively.</p>
961
962  <p>To use a different compiler and/or compiler options for Fortran/C/C++, you
963  use the <a href="annex_cfg.html#make.build.prop">build.prop</a> declaration to
964  redefine the build properties. E.g.:</p>
965  <pre>
966steps = build
967build.target{task} = link
968build.source = $HOME/my-source-tree
969
970# Set Fortran compiler/linker
971build.prop{fc} = ifort
972# Set Fortran compiler options
973build.prop{fc.flags} = -i8 -r8 -O3
974# Add include paths to Fortran compiler
975build.prop{fc.include-paths} = /a/path/to/include /more/path/to/include
976# Set link libraries for Fortran executables
977build.prop{fc.lib-paths} = /path/to/my-lib
978build.prop{fc.libs} = mine
979# Set C compiler/linker
980build.prop{cc} = icc
981# Set C compiler options
982build.prop{cc.flags} = -O3
983# Set C++ compiler options
984build.prop{cxx.flags} = -O2
985# Set link libraries for C executables
986build.prop{cc.lib-paths} = /path/to/my-lib /path/to/your-lib
987build.prop{cc.libs} = mine yours
988# Set linker, if compiler cannot be used as linker
989#build.prop{ld} = ld
990</pre>
991
992  <h3 id="build.source-locations">Build Source Locations</h3>
993
994  <p>The build system locates its source files from various places,
995  including:</p>
996
997  <ul>
998    <li>Inherited locations. (See <a href="#build.inherit">Build
999    Inheritance</a>.)</li>
1000
1001    <li>Usable target locations of previous steps in the make. E.g. targets of
1002    an extract step, and <samp><a href=
1003    "#preprocess.category.src">src</a></samp> category targets of a preprocess
1004    step can both be source files of the build system. The <code><a href=
1005    "annex_cfg.html#make.build.prop.no-step-source">build.prop{no-step-source}</a></code>
1006    declaration can be used to switch off this behaviour.</li>
1007
1008    <li>Locations specified by the <code><a href=
1009    "annex_cfg.html#make.build.source">build.source</a></code> declaration.
1010    Note: If you assign a relative path to the <code><a href=
1011    "annex_cfg.html#make.build.source">build.source</a></code> declaration, the
1012    system will assume the path to be relative to the make destination (not the
1013    current working directory, unless they happen to be the same).</li>
1014  </ul>
1015
1016  <p>There are situations when it may not be desirable to consider every source
1017  file in a build. You can apply filters by source file name-spaces using the
1018  <code><a href="annex_cfg.html#make.build.ns-excl">build.ns-excl</a></code>
1019  and <code><a href=
1020  "annex_cfg.html#make.build.ns-incl">build.ns-incl</a></code> declarations.
1021  E.g.:</p>
1022  <pre>
1023# To include items in "foo" and "bar/baz" only
1024build.ns-excl = /              # exclude everything ...
1025build.ns-incl = foo bar/baz    # but include items from these name-spaces
1026</pre>
1027
1028  <h3 id="build.source-ns">Build Source Name-spaces and Properties</h3>
1029
1030  <p>Each source file is assigned a name-space (which is used to fine tune the
1031  build properties, such as the compiler flags). If the source file is a target
1032  of an extract, the name-space will be the same as the extract target (the
1033  relative path of the <samp>extract/</samp> sub-directory in the make
1034  destination). If the source file is a file in a source tree specified by
1035  <code><a href="annex_cfg.html#make.build.source">build.source</a></code>, the
1036  name-space is the relative path to the specified value. The <code><a href=
1037  "annex_cfg.html#make.build.source">build.source</a></code> declaration also
1038  accepts an optional name-space, in which case the name-space of each source
1039  file in the tree will be prefixed with the specified name-space. Suppose you
1040  have a source tree in <samp>$HOME/food</samp>:</p>
1041  <pre>
1042$HOME/food/egg.c
1043$HOME/food/ham.f90
1044</pre>
1045
1046  <p>If you specify the source tree with <samp>build.source =
1047  $HOME/food</samp>, then <samp>$HOME/food/egg.c</samp> will be given the
1048  name-space <samp>egg.c</samp> and <samp>$HOME/food/ham.f90</samp> will be
1049  given the name-space <samp>ham.f90</samp>.</p>
1050
1051  <p>On the other hand, if you specify the source tree with
1052  <samp>build.source[food] = $HOME</samp>, then
1053  <samp>$HOME/food/egg.c</samp> will be given the name-space
1054  <samp>food/egg.c</samp> and <samp>$HOME/food/ham.f90</samp> will be given the
1055  name-space <samp>food/ham.f90</samp>.</p>
1056
1057  <p>The name-space is organised in a simple hierarchy. For instance, the
1058  <samp>foo/bar/egg</samp> name-space belongs to <samp>foo/bar</samp>, which
1059  belongs to <samp>foo</samp>, which belongs to the root name-space. (The root
1060  name-space is either an empty string or a <samp>/</samp>.)</p>
1061
1062  <p>For instance, you can set the flags of the Fortran compiler using the
1063  <code><a href=
1064  "annex_cfg.html#make.build.prop.fc.flags">build.prop{fc.flags}</a></code>
1065  declaration at different name-space levels:</p>
1066  <pre>
1067# The global Fortran compiler flags
1068build.prop{fc.flags} = -O3
1069
1070# The Fortran compiler flags for the "food" name-space
1071build.prop{fc.flags}[food] = -O2 -i8 -r8
1072
1073# The Fortran compiler flags for a source file
1074build.prop{fc.flags}[food/bacon.f90] = -O0 -g -C
1075</pre>
1076
1077  <h3 id="build.source-types">Build Source Types</h3>
1078
1079  <p>Before the build system can do anything with its source files, it needs to
1080  know what they are. It determines the type of each source file by looking at
1081  its file name extension, then the file name itself, and then the
1082  <code>#!</code> line for a text file. Source files without a type are treated
1083  as data files.</p>
1084
1085  <p>The following types are associated with file extensions:</p>
1086
1087  <dl>
1088    <dt><a href="annex_cfg.html#make.build.prop.file-ext.c">c</a> (C source
1089    file)</dt>
1090
1091    <dd>.c .i .m .mi</dd>
1092
1093    <dt><a href="annex_cfg.html#make.build.prop.file-ext.cxx">cxx</a> (C++
1094    source file)</dt>
1095
1096    <dd>.cc .cp .cxx .cpp .CPP .c++ .C .mm .M .mii</dd>
1097
1098    <dt><a href="annex_cfg.html#make.build.prop.file-ext.fortran">fortran</a>
1099    (Fortran source file)</dt>
1100
1101    <dd>.F .FOR .FTN .F90 .F95 .f .for .ftn .f90 .f95 .inc</dd>
1102
1103    <dt><a href="annex_cfg.html#make.build.prop.file-ext.h">h</a> (Preprocessor
1104    header file)</dt>
1105
1106    <dd>.h</dd>
1107
1108    <dt><a href="annex_cfg.html#make.build.prop.file-ext.script">script</a>
1109    (script in various languages)</dt>
1110
1111    <dd>(empty)</dd>
1112  </dl>
1113
1114  <p>The <code>prop{file-ext.type} = extensions</code> declaration can be used
1115  to modify the extensions associated with a type. E.g. if you need to add
1116  <samp>.fort</samp> as a file extension for a Fortran source file, you can
1117  do:</p>
1118  <pre>
1119build.prop{file-ext.fortran} = .F .FOR .FORT .FTN .F90 .F95 \
1120                               .f .for .fort .ftn .f90 .f95 .inc
1121</pre>
1122
1123  <p>You can associate file names to some file types using a
1124  <code>prop{file-pat.type} = regular-expression</code> declaration. E.g. if
1125  you have executable scripts in the source tree with no <code>#!</code> lines
1126  but are recognised by a <samp>*Scr_*</samp> pattern of their file names, you
1127  can specify a regular expression to match their file names using the <a href=
1128  "annex_cfg.html#make.build.prop.file-pat.script">file-pat.script</a>
1129  property:</p>
1130  <pre>
1131build.prop{file-pat.script} = (?msx-i:\w+Scr_\w+)
1132</pre>
1133
1134  <p>All other text files with a <code>#!</code> line are recognised as scripts
1135  by the build system.</p>
1136
1137  <h3 id="build.source-analysis">Build Source Analysis</h3>
1138
1139  <p>Each source file with a known type (that is not ignored) is analysed by
1140  the build system for dependencies and other information. Here is a list of
1141  what the system looks for in each type of file:</p>
1142
1143  <dl>
1144    <dt>c and cxx</dt>
1145
1146    <dd>
1147      <p><dfn>main program</dfn>: e.g. <samp>int main()</samp>.</p>
1148
1149      <p><dfn>dependency on include</dfn>: e.g. <samp>#include
1150      "name.h"</samp>.</p>
1151
1152      <p><dfn>dependency on object</dfn>: e.g. <samp>/* depends on: name.o
1153      */</samp> (for <a href="#build.source-analysis.legacy">legacy
1154      support</a>).</p>
1155    </dd>
1156
1157    <dt>fortran</dt>
1158
1159    <dd>
1160      <p><dfn>main program</dfn>: e.g. <samp>program name</samp>.</p>
1161
1162      <p><dfn>list of symbols</dfn>: i.e. names of top level program units
1163      including blockdata, function, module, program and subroutine.</p>
1164
1165      <p><dfn>dependency on include</dfn>: e.g. <samp>#include "name.h"</samp>
1166      and <samp>include 'name.f90'</samp>.</p>
1167
1168      <p><dfn>dependency on module</dfn>: e.g. <samp>use name</samp>.</p>
1169
1170      <p><dfn>dependency on object</dfn>: e.g. <samp>! depends on:
1171      name.o</samp> (for <a href="#build.source-analysis.legacy">legacy
1172      support</a>).</p>
1173    </dd>
1174
1175    <dt>h</dt>
1176
1177    <dd>
1178      <p><dfn>dependency on include</dfn>: e.g. <samp>#include
1179      "file-name"</samp> (and <samp>include 'file-name'</samp> for <a href=
1180      "#build.source-analysis.legacy">legacy support</a>).</p>
1181    </dd>
1182
1183    <dt>script</dt>
1184
1185    <dd>
1186      <p><dfn>dependency on executable</dfn>: e.g. <samp># calls: name</samp>
1187      (for <a href="#build.source-analysis.legacy">legacy support</a>).</p>
1188    </dd>
1189  </dl>
1190
1191  <div class="well">
1192    <p><strong><span class="glyphicon glyphicon-pencil"
1193    aria-hidden="true"></span> Note: The following features are for
1194    legacy support.</strong></p>
1195
1196    <dl id="build.source-analysis.legacy">
1197      <dt><code>DEPENDS ON: x</code> directives in C/Fortran source files</dt>
1198
1199      <dd>The <code>DEPENDS ON: x</code> directive can be used to identify
1200      dependencies on other compiled objects. However, it is much better to
1201      specify this kind of dependency information in the configuration for the
1202      build where necessary. In any case, in modern Fortran code almost all
1203      dependencies should be identified automatically via the use of modules
1204      and/or interface files.</dd>
1205
1206      <dt><code>calls: x</code> directives in scripts</dt>
1207
1208      <dd>The <code>calls: x</code> directive can be used to identify a
1209      dependency on another executable. However, it is much better to specify
1210      this kind of dependency information in the configuration for the build, and
1211      leave the source code to concentrate on the run time logic.</dd>
1212
1213      <dt><samp>*.h</samp> files as Fortran include files</dt>
1214
1215      <dd><samp>*.h</samp> files are normally identified as C header files.
1216      However, they are also being used by some old Fortran programs as include
1217      files. Therefore, when the system analyses a <samp>*.h</samp> file, it has
1218      to detect the Fortran include syntax, i.e. <samp>include 'file-name'</samp>
1219      as well as the regular C preprocessor include syntax.</dd>
1220    </dl>
1221  </div>
1222
1223  <div class="well">
1224    <p><strong><span class="glyphicon glyphicon-pencil"
1225    aria-hidden="true"></span> Note: Dependency Analysis and Fortran
1226    OpenMP Sentinels.</strong></p>
1227
1228    <p>The build system recognises statements with Fortran OpenMP sentinels that
1229    affect build dependencies. E.g.:</p>
1230
1231    <pre>
1232!$ USE my_omp_mod, ONLY: my_omp_sub
1233! ...
1234!$ INCLUDE 'my_omp_logic'
1235</pre>
1236
1237    <p>These dependencies are normally ignored. However, if a relevant
1238    <code>build.prop{fc.flag-omp}</code> property is specified, the build system
1239    will treat these statements as normal dependency statements.</p>
1240  </div>
1241
1242  <p>There are some situations when it is not possible for the system to
1243  identify a dependency. E.g. a Fortran source file may depend on external
1244  objects that are not detected by the automatic analysis. Therefore, the
1245  system allows you to specify manual dependencies in the configuration file
1246  using the <code>build.prop{dep.type}</code> and
1247  <code>build.prop{ns-dep.type}</code> declarations. E.g.:</p>
1248  <pre>
1249# Tell the system that (the object of) food/egg.c depends on chicken.o
1250build.prop{dep.o}[food/egg.c] = chicken.o
1251
1252# Tell the system that (the object of) meal/big.c depends on all objects in the
1253# "food" and "drink" name-spaces
1254build.prop{ns-dep.o}[meal/big.c] = food drink
1255</pre>
1256
1257  <p>Like all declarations that accept name-spaces, if you specify a name-space
1258  in this declaration, the property will apply to all source files in the
1259  name-space. If you do not specify a name-space, it applies to the root
1260  name-space (i.e. globally to all relevant source files).</p>
1261
1262  <p>The following manual dependency declarations are recognised:</p>
1263
1264  <dl>
1265    <dt><a href=
1266    "annex_cfg.html#make.build.prop.dep.bin">build.prop{dep.bin}</a></dt>
1267
1268    <dd>Specifies a list of dependencies on a script or a binary
1269    executable.</dd>
1270
1271    <dt><a href=
1272    "annex_cfg.html#make.build.prop.dep.f.module">build.prop{dep.f.module}</a></dt>
1273
1274    <dd>Specifies a list of Fortran module import dependencies. Note: a
1275    dependency on a Fortran module called <samp>module_1</samp> becomes an
1276    <dfn>include</dfn> dependency on <samp>module_1.mod</samp> when the system
1277    turns the source file into its targets.</dd>
1278
1279    <dt><a href=
1280    "annex_cfg.html#make.build.prop.dep.include">build.prop{dep.include}</a></dt>
1281
1282    <dd>Specifies a list of include file dependencies.</dd>
1283
1284    <dt><a href=
1285    "annex_cfg.html#make.build.prop.dep.o">build.prop{dep.o}</a></dt>
1286
1287    <dd>Specifies a list of link-time object dependencies.</dd>
1288
1289    <dt><a href=
1290    "annex_cfg.html#make.build.prop.dep.o.special">build.prop{dep.o.special}</a></dt>
1291
1292    <dd>Specifies a list of special type of link-time object dependencies.
1293    Normally, an object file can be put in an object archive before being
1294    linked with the main object. There are special cases when an object file
1295    must be specified on the command line of the linker. (E.g. an object file
1296    containing a Fortran blockdata program unit.) This special behaviour must
1297    be declared using this declaration.</dd>
1298
1299    <dt><a href=
1300    "annex_cfg.html#make.build.prop.ns-dep.o">build.prop{ns-dep.o}</a></dt>
1301
1302    <dd>Specifies a list of link-time object dependencies on all objects in the
1303    specified name-space.</dd>
1304  </dl>
1305
1306  <p>There are times when you know that your source tree does not contain a
1307  particular type of dependency, in which case you can switch off the automatic
1308  analysis by using the <code>build.prop{no-dep.type}</code> declaration. E.g.
1309  if you know that all include files in the <samp>food</samp> name-space are
1310  provided outside of the source tree, you can do:</p>
1311  <pre>
1312# Do not check for "include" dependencies
1313build.prop{no-dep.include}[food] = *
1314</pre>
1315
1316  <p>All the types supported by the <code>build.prop{dep.type}</code>
1317  declarations are supported by the <code>build.prop{no-dep.type}</code>,
1318  except that there is no <code>build.prop{no-dep.o.special}</code>
1319  (because this type of dependency is never automatic).</p>
1320
1321  <h3 id="build.target-source">Build Targets from Source Files</h3>
1322
1323  <p>The system derives the build targets from the source files. E.g. a C
1324  source file <samp>egg.c</samp> is turned into a compile target to generate
1325  <samp>egg.o</samp>.</p>
1326
1327  <p>The following is a list of what targets are available for each type of
1328  file. The title of each item in the list is in the format <dfn>source type
1329  -&gt; target key</dfn>. The <dfn>description</dfn> of each target describes
1330  what the target is, and where appropriate, explains how the target keys are
1331  named. The <dfn>task</dfn> is the action the target needs to perform to get
1332  up to date. The <dfn>category and destination</dfn> is the sub-directory and
1333  destination of the target. The <dfn>properties</dfn> are the list of
1334  properties that may be used by the <dfn>task</dfn> to update the target. The
1335  <dfn>dependencies</dfn> list the types of dependencies the target may have.
1336  The <dfn>update if</dfn> is the condition when the target is considered out
1337  of date. The <dfn>pass on</dfn> information is a list of dependeny types
1338  which a target can pass on the status, (see <a href=
1339  "#build.target-update">Build Targets Update in Incremental Mode</a> for an
1340  explanation of what this means.)</p>
1341
1342  <dl>
1343    <dt>c/cxx -&gt; name</dt>
1344
1345    <dd>
1346      <p><dfn>description</dfn>: source file as an include file.</p>
1347
1348      <p><dfn>task</dfn>: <a href="#build.task.install">install</a>.</p>
1349
1350      <p><dfn>category and destination</dfn>: <a href=
1351      "#build.category.include">include</a> and include/name</p>
1352
1353      <p><dfn>dependencies</dfn>: include and o (object).</p>
1354
1355      <p><dfn>update if</dfn>: source file is modified.</p>
1356
1357      <p><dfn>pass on</dfn>: include, o and o.special.</p>
1358    </dd>
1359
1360    <dt>c/cxx -&gt; name.o</dt>
1361
1362    <dd>
1363      <p><dfn>description</dfn>: object file. The file is named by mapping the
1364      base name of the original source file in lower case characters, with the
1365      file extension replaced by the first value of the <code><a href=
1366      "annex_cfg.html#make.build.prop.file-ext.o">file-ext.o</a></code>
1367      property.</p>
1368
1369      <p><dfn>task</dfn>: <a href="#build.task.compile">compile</a> (cc).</p>
1370
1371      <p><dfn>category and destination</dfn>: <a href="#build.category.o">o</a>
1372      and o/name.o</p>
1373
1374      <p><dfn>properties</dfn>: <a href=
1375      "annex_cfg.html#make.build.prop.cc">cc</a>, <a href=
1376      "annex_cfg.html#make.build.prop.cc.flags">cc.flags</a>, <a href=
1377      "annex_cfg.html#make.build.prop.cc.defs">cc.defs</a>, <a href=
1378      "annex_cfg.html#make.build.prop.cc.flag-compile">cc.flag-compile</a>,
1379      <a href=
1380      "annex_cfg.html#make.build.prop.cc.flag-define">cc.flag-define</a>,
1381      <a href=
1382      "annex_cfg.html#make.build.prop.cc.flag-include">cc.flag-include</a>,
1383      <a href=
1384      "annex_cfg.html#make.build.prop.cc.include-paths">cc.include-paths</a>,
1385      <a href=
1386      "annex_cfg.html#make.build.prop.cc.flag-omp">cc.flag-omp</a>,
1387      <a href=
1388      "annex_cfg.html#make.build.prop.cc.flag-output">cc.flag-output</a></p>
1389
1390      <p><dfn>dependencies</dfn>: include and o (object).</p>
1391
1392      <p><dfn>update if</dfn>: source file or any of the required properties
1393      are modified, or if any include dependencies are updated.</p>
1394
1395      <p><dfn>pass on</dfn>: o and o.special.</p>
1396    </dd>
1397
1398    <dt>c/cxx (with main function) -&gt; name.exe</dt>
1399
1400    <dd>
1401      <p><dfn>description</dfn>: binary executable. The file is named after the
1402      base name of the original source file, with the file extension replaced by
1403      the first value of the <code><a href=
1404      "annex_cfg.html#make.build.prop.file-ext.bin">file-ext.bin</a></code>
1405      property.</p>
1406
1407      <p><dfn>task</dfn>: <a href="#build.task.link">link</a> (cc).</p>
1408
1409      <p><dfn>category and destination</dfn>: <a href=
1410      "#build.category.bin">bin</a> and bin/name.exe</p>
1411
1412      <p><dfn>properties</dfn>:
1413      <a href="annex_cfg.html#make.build.prop.ar">ar</a>,
1414      <a href="annex_cfg.html#make.build.prop.ar.flags">ar.flags</a>,
1415      <a href="annex_cfg.html#make.build.prop.file-ext.a">file-ext.a</a>,
1416      <a href="annex_cfg.html#make.build.prop.cc">cc</a>,
1417      <a href="annex_cfg.html#make.build.prop.cc.flags-ld">cc.flags-ld</a>,
1418      <a href="annex_cfg.html#make.build.prop.cc.flag-lib">cc.flag-lib</a>,
1419      <a href=
1420      "annex_cfg.html#make.build.prop.cc.flag-lib-path">cc.flag-lib-path</a>,
1421      <a href="annex_cfg.html#make.build.prop.cc.libs">cc.libs</a>,
1422      <a href="annex_cfg.html#make.build.prop.cc.lib-paths">cc.lib-paths</a>,
1423      <a href=
1424      "annex_cfg.html#make.build.prop.cc.flag-omp">cc.flag-omp</a>,
1425      <a href=
1426      "annex_cfg.html#make.build.prop.cc.flag-output">cc.flag-output</a></p>
1427
1428      <p><dfn>dependencies</dfn>: name.o and other objects (o and
1429      o.special).</p>
1430
1431      <p><dfn>update if</dfn>: source file or any of the required properties
1432      are modified, or if any dependencies are updated.</p>
1433    </dd>
1434
1435    <dt>fortran -&gt; name</dt>
1436
1437    <dd>
1438      <p><dfn>description</dfn>: source file as an include file.</p>
1439
1440      <p><dfn>task</dfn>: <a href="#build.task.install">install</a>.</p>
1441
1442      <p><dfn>category and destination</dfn>: <a href=
1443      "#build.category.include">include</a> and include/name</p>
1444
1445      <p><dfn>dependencies</dfn>: include and o (object). A source's f.module
1446      dependency on a module called <samp>xyz</samp> is turned into an include
1447      dependency on the <samp>xyz.mod</samp>.</p>
1448
1449      <p><dfn>update if</dfn>: source file is modified.</p>
1450
1451      <p><dfn>pass on</dfn>: include, o and o.special.</p>
1452    </dd>
1453
1454    <dt>fortran (with a valid Fortran program unit) -&gt; unit.o</dt>
1455
1456    <dd>
1457      <p><dfn>description</dfn>: object file. The file is named by concatenating
1458      the lower case characters of the name of the first program unit in the
1459      source file and the first value of the <code><a href=
1460      "annex_cfg.html#make.build.prop.file-ext.o">file-ext.o</a></code>
1461      property.</p>
1462
1463      <p><dfn>task</dfn>: <a href="#build.task.compile">compile</a> (fc).</p>
1464
1465      <p><dfn>category and destination</dfn>: <a href="#build.category.o">o</a>
1466      and o/unit.o</p>
1467
1468      <p><dfn>properties</dfn>: <a href=
1469      "annex_cfg.html#make.build.prop.fc">fc</a>, <a href=
1470      "annex_cfg.html#make.build.prop.fc.flags">fc.flags</a>, <a href=
1471      "annex_cfg.html#make.build.prop.fc.defs">fc.defs</a>, <a href=
1472      "annex_cfg.html#make.build.prop.fc.flag-compile">fc.flag-compile</a>,
1473      <a href=
1474      "annex_cfg.html#make.build.prop.fc.flag-define">fc.flag-define</a>,
1475      <a href=
1476      "annex_cfg.html#make.build.prop.fc.flag-include">fc.flag-include</a>,
1477      <a href=
1478      "annex_cfg.html#make.build.prop.fc.include-paths">fc.include-paths</a>,
1479      <a href=
1480      "annex_cfg.html#make.build.prop.fc.flag-module">fc.flag-module</a>,
1481      <a href=
1482      "annex_cfg.html#make.build.prop.fc.flag-omp">fc.flag-omp</a>,
1483      <a href=
1484      "annex_cfg.html#make.build.prop.fc.flag-output">fc.flag-output</a></p>
1485
1486      <p><dfn>dependencies</dfn>: include and o (object). A source's f.module
1487      dependency on a module called <samp>xyz</samp> is turned into an include
1488      dependency on the <samp>xyz.mod</samp>.</p>
1489
1490      <p><dfn>update if</dfn>: source file or any of the required properties
1491      are modified, or if any include dependencies are updated.</p>
1492
1493      <p><dfn>pass on</dfn>: o and o.special.</p>
1494
1495      <p><dfn>remark</dfn>: trigger <samp>unit.mod</samp> targets if source
1496      file contains a Fortran module.</p>
1497    </dd>
1498
1499    <dt>fortran (with function or subroutine) -&gt; name.interface</dt>
1500
1501    <dd>
1502      <p><dfn>description</dfn>: Fortran interface file. The file is named by
1503      concatenating the base name of the source file with the file extension
1504      replaced by the <code><a href=
1505      "annex_cfg.html#make.build.prop.file-ext.f90-interface">file-ext.f90-interface</a></code>
1506      property.</p>
1507
1508      <p><dfn>task</dfn>: <a href="#build.task.ext-iface">ext-iface</a></p>
1509
1510      <p><dfn>category and destination</dfn>: <a href=
1511      "#build.category.include">include</a> and include/name.interface</p>
1512
1513      <p><dfn>dependencies</dfn>: unit.o</p>
1514
1515      <p><dfn>update if</dfn>: source file or unit.o is modified.</p>
1516
1517      <p><dfn>pass on</dfn>: include, o and o.special.</p>
1518    </dd>
1519
1520    <dt>fortran (each module in source) -&gt; unit.mod</dt>
1521
1522    <dd>
1523      <p><dfn>description</dfn>: Fortran module definition file. The file is
1524      named by concatenating the lower case characters of the name of the
1525      module and the first value of the <code><a href=
1526      "annex_cfg.html#make.build.prop.file-ext.f90-mod">file-ext.f90-mod</a></code>
1527      property.</p>
1528
1529      <p><dfn>task</dfn>: <a href="#build.task.compile-plus">compile+</a>.</p>
1530
1531      <p><dfn>category and destination</dfn>: <a href=
1532      "#build.category.include">include</a> and include/unit.mod</p>
1533
1534      <p><dfn>dependencies</dfn>: unit.o</p>
1535
1536      <p><dfn>update if</dfn>: source file or unit.o is modified.</p>
1537
1538      <p><dfn>pass on</dfn>: o.</p>
1539    </dd>
1540
1541    <dt>fortran (with program) -&gt; name.exe</dt>
1542
1543    <dd>
1544      <p><dfn>description</dfn>: binary executable. The object file is named
1545      after the base name of the original source file, with the file extension
1546      replaced by the first value of the <code><a href=
1547      "annex_cfg.html#make.build.prop.file-ext.bin">file-ext.bin</a></code>
1548      property.</p>
1549
1550      <p><dfn>task</dfn>: <a href="#build.task.link">link</a> (fc).</p>
1551
1552      <p><dfn>category and destination</dfn>: <a href=
1553      "#build.category.bin">bin</a> and bin/name.exe</p>
1554
1555      <p><dfn>properties</dfn>:
1556      <a href="annex_cfg.html#make.build.prop.ar">ar</a>,
1557      <a href="annex_cfg.html#make.build.prop.ar.flags">ar.flags</a>,
1558      <a href="annex_cfg.html#make.build.prop.fc">fc</a>,
1559      <a href="annex_cfg.html#make.build.prop.fc.flags-ld">fc.flags-ld</a>,
1560      <a href="annex_cfg.html#make.build.prop.fc.flag-lib">fc.flag-lib</a>,
1561      <a href=
1562      "annex_cfg.html#make.build.prop.fc.flag-lib-path">fc.flag-lib-path</a>,
1563      <a href="annex_cfg.html#make.build.prop.fc.libs">fc.libs</a>,
1564      <a href="annex_cfg.html#make.build.prop.fc.lib-paths">fc.lib-paths</a>,
1565      <a href=
1566      "annex_cfg.html#make.build.prop.fc.flag-omp">fc.flag-omp</a>,
1567      <a href=
1568      "annex_cfg.html#make.build.prop.fc.flag-output">fc.flag-output</a></p>
1569
1570      <p><dfn>dependencies</dfn>: unit.o and other objects (o and
1571      o.special).</p>
1572
1573      <p><dfn>update if</dfn>: source file or any of the required properties
1574      are modified, or if any dependencies are updated.</p>
1575    </dd>
1576
1577    <dt>h -&gt; name</dt>
1578
1579    <dd>
1580      <p><dfn>description</dfn>: a header (include) file.</p>
1581
1582      <p><dfn>task</dfn>: <a href="#build.task.install">install</a>.</p>
1583
1584      <p><dfn>category and destination</dfn>: <a href=
1585      "#build.category.include">include</a> and include/name</p>
1586
1587      <p><dfn>dependencies</dfn>: include and o (object).</p>
1588
1589      <p><dfn>update if</dfn>: source file is modified.</p>
1590
1591      <p><dfn>pass on</dfn>: include, o and o.special.</p>
1592    </dd>
1593
1594    <dt>script -&gt; name</dt>
1595
1596    <dd>
1597      <p><dfn>description</dfn>: an executable script.</p>
1598
1599      <p><dfn>task</dfn>: <a href="#build.task.install">install</a>.</p>
1600
1601      <p><dfn>category and destination</dfn>: <a href=
1602      "#build.category.bin">bin</a> and bin/name</p>
1603
1604      <p><dfn>dependencies</dfn>: bin (executable).</p>
1605
1606      <p><dfn>update if</dfn>: source file is modified.</p>
1607
1608      <p><dfn>pass on</dfn>: bin.</p>
1609    </dd>
1610
1611    <dt>data -&gt; name-space</dt>
1612
1613    <dd>
1614      <p><dfn>description</dfn>: a data file.</p>
1615
1616      <p><dfn>task</dfn>: <a href="#build.task.install">install</a>.</p>
1617
1618      <p><dfn>category and destination</dfn>: <a href=
1619      "#build.category.etc">etc</a> and etc/name-space</p>
1620
1621      <p><dfn>update if</dfn>: source file is modified.</p>
1622    </dd>
1623  </dl>
1624
1625  <p>Here is an explanation of what each build system <dfn>task</dfn> does:</p>
1626
1627  <dl>
1628    <dt id="build.task.archive">archive</dt>
1629
1630    <dd>Creates an object archive by invoking an archiver command. (See
1631    <a href="#build.target-ns">Build Targets from Name-space</a>.)</dd>
1632
1633    <dt id="build.task.compile">compile</dt>
1634
1635    <dd>Creates an object file by invoking the C/C++/Fortran compiler on the
1636    source file.</dd>
1637
1638    <dt id="build.task.compile-plus">compile+</dt>
1639
1640    <dd>Copies the Fortran module definition file created by a compile task to
1641    the include sub-directory.</dd>
1642
1643    <dt id="build.task.ext-iface">ext-iface</dt>
1644
1645    <dd>Extracts the calling interfaces of all functions and subroutines in a
1646    Fortran source file (free format only) and writes the results in an
1647    interface block that can be included by other Fortran source files with an
1648    <samp>INCLUDE 'name.interface'</samp> statement. In an incremental build,
1649    if you have modified a Fortran source file, its interface file will only be
1650    re-generated if the content of the interface has changed. This can make
1651    incremental build very efficient, as non-interface changes in a function or
1652    subroutine will only trigger a re-link of the executable.</dd>
1653
1654    <dt id="build.task.install">install</dt>
1655
1656    <dd>Copies the source file to the destination.</dd>
1657
1658    <dt id="build.task.link">link</dt>
1659
1660    <dd>Creates an executable by invoking the archiver to load all required
1661    objects into an archive, and then the C/C++/Fortran compiler on the object
1662    file previously compiled using a source file containing a main program, with
1663    the temporary archive.</dd>
1664  </dl>
1665
1666  <h3 id="build.target-prop">Build Targets and Properties</h3>
1667
1668  <p>If you need to specify a property for a specific target, you can either use
1669  their source file namespace or the target key. E.g. If the
1670  <samp>sausage.o</samp> target is generated from the source file in the
1671  <samp>src/food/sausage.f90</samp> namespace, you can specify its Fortran
1672  compiler flags <code><a href=
1673  "annex_cfg.html#make.build.prop.fc.flags">build.prop{fc.flags}</a></code> by
1674  doing either:</p>
1675
1676  <pre>
1677build.prop{fc.flags}[sausage.o] = -O4
1678# would be the same as:
1679build.prop{fc.flags}[src/food/sausage.f90] = -O4
1680</pre>
1681
1682  <p>This works with most property modifiers, even for dependency related
1683  modifiers such as <code>no-dep.o</code>. E.g.:</p>
1684
1685  <pre>
1686build.prop{no-dep.include}[sausage.o] = enum.f90
1687build.prop{include-paths}[sausage.o] = /path/to/additives
1688</pre>
1689 
1690  <p>However, the following will not work:</p>
1691
1692  <pre>
1693build.prop{no-dep.f.module}[sausage.o] = pork
1694</pre>
1695
1696  <p>This is because an object file target is never dependent on a Fortran
1697  module by its name. The following will work, however:</p>
1698
1699  <pre>
1700build.prop{no-dep.include}[sausage.o] = pork.mod
1701build.prop{no-dep.o}[sausage.mod] = pork.o
1702# would be the same as:
1703build.prop{no-dep.f.module}[src/food/sausage.f90] = pork
1704</pre>
1705
1706  <h3 id="build.target-source-fortran">Build Targets from Source Files: Fortran
1707  Specifics</h3>
1708
1709  <p>To ensure that a Fortran application is built automatically, its source
1710  code should be designed with the following considerations:</p>
1711
1712  <p><dfn>The name of each compilable program unit should be unique</dfn> in
1713  the source tree, bearing in mind that Fortran is NOT case sensitive.</p>
1714
1715  <p><dfn>Always supply an interface for functions and subroutines</dfn>,
1716  i.e.:</p>
1717
1718  <ul>
1719    <li>Place functions and subroutines in a module, and give them the
1720    <code>PUBLIC</code> attribute. Import them with the <code>USE
1721    &lt;module&gt;</code> statement. We recommend adding the <code>ONLY</code>
1722    clause in a <code>USE &lt;module&gt;</code> when importing symbols from a
1723    module. This makes it easier to locate the source of each symbol, and avoids
1724    unintentional access to other <code>PUBLIC</code> symbols within the
1725    <code>MODULE</code>. If you are importing from an intrinsic module, you
1726    should add the <code>INTRINSIC</code> clause to the <code>USE
1727    &lt;module&gt;</code> statement to tell the build system not to look for the
1728    module from your source tree.</li>
1729
1730    <li>Place functions and subroutines in the <code>CONTAINS</code> section of
1731    a standalone program unit. There are two advantages for this approach.
1732    Firstly, the sub-programs will get an automatic interface when the container
1733    program unit is compiled. Secondly, it should be easier for the compiler to
1734    provide optimisation when the sub-programs are internal to the caller. The
1735    disadvantage of this approach is that the sub-programs are local to the
1736    caller, and so they cannot be called by other program units. Therefore, this
1737    approach is only suitable for small sub-programs local to a particular
1738    program unit.</li>
1739
1740    <li>Use the build system's automatic interface file feature. See below.</li>
1741  </ul>
1742
1743  <p>For each free format Fortran source file, e.g. <samp>name.f90</samp>, with
1744  1 or more top level function and/or subroutine, the system creates a target
1745  with the <a href="#build.task.ext-iface">ext-iface</a> task in the
1746  <a href="#build.category.include">include</a> category, e.g.
1747  <samp>name.interface</samp>, to extract the calling interfaces of all
1748  functions and subroutines into an interface block. Another Fortran source
1749  file, e.g. <samp>caller.f90</samp> that relies on the functions and/or
1750  subroutines in <samp>name.f90</samp> can have an <samp>INCLUDE
1751  'name.interface'</samp> statement in its specification section, which serves
1752  2 purposes:</p>
1753
1754  <ul>
1755    <li>It allows <samp>caller.f90</samp> to call the functions and/or
1756    subroutines in <samp>name.f90</samp> with explicit interfaces.</li>
1757
1758    <li>It introduces an <a href=
1759    "annex_cfg.html#make.build.prop.dep.include">include</a> dependency for
1760    <samp>caller.o</samp> on <samp>name.interface</samp>.</li>
1761  </ul>
1762
1763  <p>In an incremental build, if you modify <samp>name.f90</samp>, the system
1764  will only regenerate <samp>name.interface</samp> if only the calling
1765  interfaces of the functions and/or subroutines in <samp>name.f90</samp> have
1766  changed. Consequently, non-interface changes in <samp>name.f90</samp> will
1767  not trigger the re-compile of <samp>caller.o</samp>, but will only trigger a
1768  re-link of the executable.</p>
1769
1770  <h3 id="build.target-selection">Build Targets Selection and Rename</h3>
1771
1772  <p>You need to tell the build system what targets to build or it will do
1773  nothing. The <code><a href=
1774  "annex_cfg.html#make.build.target">build.target</a></code> declaration allows
1775  you to select targets according to their categories, source name-spaces,
1776  tasks and keys. The logic is demonstrated by the following example:</p>
1777  <pre>
1778# Select targets matching these keys
1779build.target = egg.bin ham.o bacon.sh
1780
1781# Select all targets doing tasks "install" or "link"
1782build.target{task} = install link
1783
1784# Select targets in name-space "foo" or "bar" doing tasks "link"
1785build.target{task}[foo bar] = link
1786
1787# Select all targets in the "bin" category
1788build.target{category} = bin
1789
1790# Select targets in name-space "foo" in the "etc" category
1791build.target{category}[foo] = etc
1792</pre>
1793
1794  <p>There are times when an automatic target name is not what you want. In
1795  which case, you can rename a target using the <code><a href=
1796  "annex_cfg.html#make.build.target-rename">build.target-rename</a></code>
1797  declaration to specify an alternate name. E.g. if the target
1798  <samp>bacon.sh</samp> should be called <samp>streaky</samp>, you can do:</p>
1799  <pre>
1800build.target-rename = bacon.sh:streaky
1801</pre>
1802
1803  <p>In order for a target to build, all its dependencies must be satisfied. If
1804  a target has a dependency that is not available in the list of targets, the
1805  build will fail. Normally, you can avoid this by using one of the
1806  <code>build.prop{no-dep.*}</code> declarations to switch off a non-existent
1807  dependency, as described in the <a href="#build.source-analysis">Build Source
1808  Analysis</a> section. However, there may be times when this is inefficient or
1809  insufficient, in which case you can use the property <code><a href=
1810  "annex_cfg.html#make.build.prop.ignore-missing-dep-ns">ignore-missing-dep-ns</a></code>
1811  to specify a list of source name-spaces, in which targets can ignore missing
1812  dependencies. E.g.:</p>
1813  <pre>
1814# Allows targets in the "foo" and "bar/baz"
1815# name-spaces to ignore missing dependencies.
1816build.prop{ignore-missing-dep-ns} = foo bar/baz
1817</pre>
1818
1819  <h3 id="build.target-file-ext">Build Targets File Extensions</h3>
1820
1821  <p>You can rename the file name extension of the targets using
1822  <code>build.prop{file-ext.type}</code> declaration (provided that the file
1823  name extension is supported by your compiler, etc). E.g. if you want your
1824  binary executables to have <samp>.bin</samp> extension rather than the
1825  default <samp>.exe</samp>, you can do:</p>
1826  <pre>
1827build.prop{file-ext.bin} = .bin
1828</pre>
1829
1830  <p>The following file extensions are currently used by the system:</p>
1831
1832  <dl>
1833    <dt><a href="annex_cfg.html#make.build.prop.file-ext.a">a</a> (object
1834    archive)</dt>
1835
1836    <dd>.a</dd>
1837
1838    <dt><a href="annex_cfg.html#make.build.prop.file-ext.bin">bin</a> (binary
1839    executable)</dt>
1840
1841    <dd>.exe</dd>
1842
1843    <dt><a href=
1844    "annex_cfg.html#make.build.prop.file-ext.f90-interface">f90-interface</a>
1845    (Fortran free format interface file)</dt>
1846
1847    <dd>.interface</dd>
1848
1849    <dt><a href="annex_cfg.html#make.build.prop.file-ext.f90-mod">f90-mod</a>
1850    (Fortran compiler module definition file)</dt>
1851
1852    <dd>.mod</dd>
1853
1854    <dt><a href="annex_cfg.html#make.build.prop.file-ext.o">o</a> (object
1855    file)</dt>
1856
1857    <dd>.o</dd>
1858  </dl>
1859
1860  <h3 id="build.target-ns">Build Targets from Name-space</h3>
1861
1862  <p>Apart from source file targets, the build system also generates targets
1863  for each (directory-level) name-space. One target is for creating an object
1864  archive to contain all object files in the name-space. The other target is a
1865  convenient shorthand to allow all data files in the name-space to be
1866  installed. The following is the full description:</p>
1867
1868  <dl>
1869    <dt>name-space &gt; name-space/libo.a</dt>
1870
1871    <dd>
1872      <p><dfn>description</dfn>: object archive.</p>
1873
1874      <p><dfn>task</dfn>: <a href="#build.task.archive">archive</a>.</p>
1875
1876      <p><dfn>category and destination</dfn>: <a href=
1877      "#build.category.lib">lib</a> and lib/name-space/libo.a</p>
1878
1879      <p><dfn>dependencies</dfn>: all o (object) targets in the name-space.</p>
1880
1881      <p><dfn>properties</dfn>: <a href=
1882      "annex_cfg.html#make.build.prop.ar">ar</a>, <a href=
1883      "annex_cfg.html#make.build.prop.ar.flags">ar.flags</a></p>
1884
1885      <p><dfn>update if</dfn>: any dependencies or properties are modified.</p>
1886    </dd>
1887
1888    <dt>name-space &gt; name-space/.etc</dt>
1889
1890    <dd>
1891      <p><dfn>description</dfn>: dummy file.</p>
1892
1893      <p><dfn>task</dfn>: <a href="#build.task.install">install</a>.</p>
1894
1895      <p><dfn>category and destination</dfn>: <a href=
1896      "#build.category.etc">etc</a> and etc/name-space/.etc</p>
1897
1898      <p><dfn>dependencies</dfn>: all data files in the name-space.</p>
1899
1900      <p><dfn>update if</dfn>: any dependencies are modified.</p>
1901    </dd>
1902  </dl>
1903
1904  <h3 id="build.target-update">Build Targets Update in Incremental Mode</h3>
1905
1906  <p>In incremental mode, a target is only updated if it is marked out of date.
1907  A target is considered out of date if:</p>
1908
1909  <ul>
1910    <li>the source file's checksum is changed.</li>
1911
1912    <li>a required property is modified.</li>
1913
1914    <li>a dependency is marked as modified, and the dependency is a type that
1915    the target cannot pass on. E.g. If <samp>object_1.o</samp> depends on
1916    <samp>object_2.o</samp>, and <samp>object_2.o</samp> is marked as modified,
1917    the system does not need to re-compile <samp>object_1.o</samp> (as long as
1918    its source file and properties remain unchanged). However,
1919    <samp>object_1.o</samp> will have to pass the information up the dependency
1920    tree, so that a target with a <samp><a href=
1921    "#build.task.link">link</a></samp> task to build an executable (or an
1922    <samp><a href="#build.task.archive">archive</a></samp> task to build a
1923    library) will know that it needs to be updated.</li>
1924
1925    <li>a dependency is passing on a <q>modified</q> status for a dependency
1926    type, which cannot be passed on by the target.</li>
1927
1928    <li>the target does not exist or its checksum is changed.</li>
1929  </ul>
1930
1931  <p>If, after an update, the target's checksum is the same as before, the
1932  target will be considered unchanged and up to date. In an incremental build,
1933  the use of checksum ensures that any targets manually modified by the user
1934  after the previous build is rebuilt accordingly. It also prevents unnecessary
1935  updates of targets in incremental and inherited builds.</p>
1936
1937  <p>E.g. Consider an incremental build where the only change is the content of
1938  a Fortran module <samp>my_mod.f90</samp>. The content change should trigger
1939  an update of the <samp>my_mod.o</samp> and <samp>my_mod.mod</samp> targets,
1940  and everything depending on them. However, if the source content is modified
1941  in such a way that it does not affect the module's public interface, most
1942  compilers will generate an identical <samp>my_mod.mod</samp>. The system can
1943  detect this by comparing the checksums. If <samp>my_mod.mod</samp> is
1944  unchanged, the build system will not need to trigger the re-compile of all
1945  targets depending on <samp>my_mod.mod</samp>, and it will only need to
1946  re-link the executable. This allows incremental builds to be more
1947  efficient.</p>
1948
1949  <div class="well">
1950    <p><strong><span class="glyphicon glyphicon-pencil"
1951    aria-hidden="true"></span> Note - checksum algorithm</strong></p>
1952
1953    <p>By default, the MD5 algorithm is used to calculate the checksum. This is
1954    normally good enough to detect whether a file is modified or not. If this is
1955    insufficient for whatever reasons, you can tell the build system to use one
1956    of the SHA algorithms supported by the Perl module <a href=
1957    "http://perldoc.perl.org/Digest/SHA.html">Digest::SHA</a>, by setting the
1958    value of <a href=
1959    "annex_cfg.html#make.build.prop.checksum-method">build.prop{checksum-method}</a>.</p>
1960  </div>
1961
1962  <h3 id="build.inherit">Build Inheritance</h3>
1963
1964  <p>If a previous build with a similar configuration exists in another
1965  location, it can be more efficient to inherit from this previous build in
1966  your current build. This works like a normal incremental build, except that
1967  your build will only contain the changes you have specified (compared with
1968  the inherited build) instead of the full set of targets.</p>
1969
1970  <p>The current build inherits all properties and target settings, as well as
1971  sources and targets from the inherited build. While properties and target
1972  settings can be overridden with a corresponding declaration, source
1973  inheritance can only be prevented by using a <code><a href=
1974  "annex_cfg.html#make.build.prop.no-inherit-source">build.prop{no-inherit-source}</a></code>
1975  declaration. E.g.:</p>
1976  <pre>
1977# Prevents inheritance from some name-spaces:
1978build.prop{no-inherit-source} = food/mint drink/soft/cola.c
1979</pre>
1980
1981  <p>For multiple inheritance, the last one takes precedence, and any search
1982  for source files or targets are recursive and depth first. For instance, if
1983  we have the following declarations in the current FCM make configuration:</p>
1984  <pre>
1985use = /path/to/a /path/to/b /path/to/c
1986</pre>
1987
1988  <p>and the following in the FCM make configuration of
1989  <samp>/path/to/b</samp>:</p>
1990  <pre>
1991use /path/to/d
1992</pre>
1993
1994  <p>The relationship looks like:</p>
1995  <pre>
1996/path/to/current
1997    /path/to/c
1998    /path/to/b
1999        /path/to/d
2000    /path/to/a
2001</pre>
2002
2003  <p>Therefore, we would expect the search path to follow the order:</p>
2004  <pre>
2005/path/to/current
2006/path/to/c
2007/path/to/b
2008/path/to/d
2009/path/to/a
2010</pre>
2011
2012  <p>In its normal setting, the system does not inherit targets in the
2013  <samp>bin</samp>, <samp>etc</samp> and <samp>lib</samp> categories. A target
2014  in one of these categories is rebuilt in the current destination, whether the
2015  inherited target is up to date or not. This allows someone to use the
2016  executables of the build by setting the <var>PATH</var> environment variable
2017  to point only to <samp>$DEST/build/bin/</samp> (where <var>$DEST</var> is the
2018  destination of the current make). If this behaviour is undesirable for
2019  whatever reason, it can be altered using the <code><a href=
2020  "annex_cfg.html#make.build.prop.no-inherit-target-category">build.prop{no-inherit-target-category}</a></code>
2021  declaration.</p>
2022
2023  <dl>
2024    <dt>Build inheritance limitation: handling of include files</dt>
2025
2026    <dd>
2027      <p>The build system uses the compiler's <code>-I</code> option to specify
2028      the search path for include files. E.g. it uses this option to specify
2029      the <samp>inc/</samp> sub-directories of the current build and its
2030      inherited build.</p>
2031
2032      <p>However, some compilers (e.g. <code>cpp</code>) search for include
2033      files from the container directory of the source file before searching
2034      for the paths specified by the <code>-I</code> options. This behaviour
2035      may cause the build to behave incorrectly.</p>
2036
2037      <p>Consider a source file <samp>egg/hen.c</samp> that includes
2038      <samp>fried.h</samp>. If the directory structure looks like:</p>
2039      <pre>
2040# Sources in inherited build:
2041egg/hen.c
2042egg/fried.h
2043
2044# Sources in current build:
2045egg/fried.h
2046</pre>
2047
2048      <p>The system will correctly identify that <samp>fried.h</samp> is out of
2049      date, and trigger a re-compilation of <samp>egg/hen.c</samp>. However, if
2050      the compiler searches for the include files from the container directory
2051      of the source file first, it will wrongly use the include file in the
2052      inherited build instead of the current one.</p>
2053
2054      <p>If your directory structure does not have any include files in the same
2055      directory as the source files that include them then you do not need to
2056      worry. If it does then you need to check whether you are affected by this
2057      problem before using an inherited build. The situation will vary
2058      according to whether the affected code uses Fortran or preprocessor
2059      include statements and also whether you are using the
2060      <a href="#preprocess">preprocess system</a>. Some compilers (e.g.
2061      <code>gfortran</code>) work fine for Fortran includes but not preprocessor
2062      includes. Others (e.g. <code>ifort</code>) have options which can be used
2063      (e.g. <code>-assume nosource_include</code>) to get the desired behaviour.
2064      The FCM distribution includes some simple test code to help you test how
2065      your chosen compilers behave. If you cannot ensure the correct behaviour
2066      then it is safer not to use inherited builds.</p>
2067    </dd>
2068  </dl>
2069
2070  <h3 id="build.diagnostic">Build Diagnostic</h3>
2071
2072  <p>The amount of diagnostic messages generated by the build system is
2073  dependent on the diagnostic verbosity level that can be modified by the
2074  <code>-v</code> and <code>-q</code> options to the <code>fcm make</code>
2075  command.</p>
2076
2077  <p>The following is a list of diagnostic output at each verbosity level:</p>
2078
2079  <dl>
2080    <dt>-q</dt>
2081
2082    <dd>
2083      <ul>
2084        <li>Exceptions.</li>
2085      </ul>
2086    </dd>
2087
2088    <dt>default</dt>
2089
2090    <dd>
2091      <ul>
2092        <li>Everything at the -q level.</li>
2093
2094        <li>Start time of the build.</li>
2095
2096        <li>The summary of source analysis.</li>
2097
2098        <li>The summary of targets. Each row except the last reports the number
2099        of modified and unchanged targets with a given type of task, and the
2100        total time spent to perform the tasks. The last row reports the total
2101        number of modified and unchanged targets, and the actual elapsed time.
2102        It is worth noting that the elapsed time in a multi-process build
2103        should be significant shorter than the sum of the total time for each
2104        type of task. E.g.:
2105          <pre>
2106[info] compile   targets: modified=5, unchanged=0, total-time=0.5s
2107[info] compile+  targets: modified=1, unchanged=0, total-time=0.0s
2108[info] ext-iface targets: modified=2, unchanged=0, total-time=0.0s
2109[info] install   targets: modified=1, unchanged=0, total-time=0.0s
2110[info] link      targets: modified=1, unchanged=0, total-time=0.1s
2111[info] TOTAL     targets: modified=10, unchanged=0, elapsed-time=0.7s
2112</pre>
2113        </li>
2114
2115        <li>Total time.</li>
2116      </ul>
2117    </dd>
2118
2119    <dt>-v</dt>
2120
2121    <dd>
2122      <ul>
2123        <li>Everything at the default level.</li>
2124
2125        <li>Elapsed time and name-space for each analysed source.</li>
2126
2127        <li>Task name, elapsed time, target status (<samp>M</samp> for modified
2128        or <samp>U</samp> for unchanged), target key, and source name-space for
2129        each modified target. E.g.:
2130          <pre>
2131[info] compile    0.0 M hello_func.o         &lt;- lib/function/hello_func.f90
2132[info] ext-iface  0.0 M hello_func.interface &lt;- lib/function/hello_func.f90
2133[info] install    0.0 M hello_inc.f90        &lt;- include/hello_inc.f90
2134[info] compile    0.0 M hello_1.o            &lt;- bin/hello_1.f90
2135[info] link       0.1 M hello_1.exe          &lt;- bin/hello_1.f90
2136</pre>
2137        </li>
2138      </ul>
2139    </dd>
2140
2141    <dt>-vv</dt>
2142
2143    <dd>
2144      <ul>
2145        <li>Everything at the -v level.</li>
2146
2147        <li>A list of dependencies (type and name) of each analysed source.
2148        E.g.
2149          <pre>
2150[info] analyse  0.0 bin/hello_1.f90
2151[info]              -&gt; (  include) hello_inc.f90
2152[info]              -&gt; (        o) hello_void.o
2153[info]              -&gt; ( f.module) hello_mod
2154</pre>
2155        </li>
2156
2157        <li>A list of the available targets from the sources. Each row contains
2158        the source namespace, the target task, the target category and the key
2159        of the target. E.g.:
2160          <pre>
2161[info] source-&gt;target / -&gt; (archive) lib/ libo.a
2162[info] source-&gt;target hello.f90 -&gt; (link) bin/ hello.exe
2163[info] source-&gt;target hello.f90 -&gt; (install) include/ hello.f90
2164[info] source-&gt;target hello.f90 -&gt; (compile) o/ hello.o
2165[info] source-&gt;target world.f90 -&gt; (install) include/ world.f90
2166[info] source-&gt;target world.f90 -&gt; (compile+) include/ world.mod
2167[info] source-&gt;target world.f90 -&gt; (compile) o/ world.o
2168</pre>
2169        </li>
2170
2171        <li>A list of the required targets for this build. Each row contains
2172        the task, the category and the key of the target. E.g.:
2173          <pre>
2174[info] required-target: link      bin     hello_1.exe
2175</pre>
2176        </li>
2177
2178        <li>The dependency tree of all the required targets. (N.B. A
2179        <samp>(n-deps=N)</samp> at the end of a line means that the target has
2180        already appeared earlier and that it has <samp>N</samp> direct
2181        dependencies, which will not be reported again.) E.g.:
2182          <pre>
2183[info] target hello_1.exe
2184[info] target  - hello_void.o
2185[info] target  - hello_1.o
2186[info] target  -  - hello_mod.mod
2187[info] target  -  -  - hello_mod.o
2188[info] target  -  - hello_void.o
2189[info] target  -  - hello_inc.f90
2190[info] target  -  -  - hello_sub.interface
2191[info] target  -  -  -  - hello_sub.o
2192[info] target  -  -  -  -  - hello_func.interface
2193[info] target  -  -  -  -  -  - hello_func.o
2194[info] target  - hello_2.o
2195[info] target  -  - hello_mod.mod (n-deps=1)
2196</pre>
2197        </li>
2198
2199        <li>Each shell command invoked with elapsed time and return code.</li>
2200
2201        <li>STDOUT and STDERR from shell commands invoked by the build
2202        tasks, e.g. diagnostic output from compilers and linkers.</li>
2203      </ul>
2204    </dd>
2205  </dl>
2206
2207  <h2 id="preprocess">Preprocess</h2>
2208
2209  <p>As most modern compilers can handle preprocessing, you should normally
2210  leave preprocessing to the compiler. However, it is recognised that some code
2211  is written with preprocessor directives that can alter the calling interface
2212  of the procedure and/or their dependencies. If a source file requires
2213  preprocessing in such a way, we have to preprocess it before feeding it to
2214  the build system. The preprocess system can be used to do this. It is
2215  typically run as a step before build.</p>
2216
2217  <p>However, using a separate preprocess step is not the best way of working,
2218  as it adds an overhead to the build process. If your code requires
2219  preprocessing, you should try to design it to avoid changes in the above.</p>
2220
2221  <p>In practice, the only reasonable use of a preprocessor with Fortran is for
2222  code selection. For example, preprocessing is useful for isolating machine
2223  specific libraries or instructions, where it may be appropriate to use inline
2224  alternatives for small sections of code. Another example is when multiple
2225  versions of the same procedure exist in the source tree and you need to use
2226  the preprocessor to select the correct version for your build.</p>
2227
2228  <p>Avoid using the a preprocessor for code inclusion, as you should be able
2229  to do the same via the Fortran <code>INCLUDE</code> statement. You should
2230  also avoid embedding preprocessor macros within the continuations of a
2231  Fortran statement, as it can make your code very confusing.</p>
2232
2233  <p>The preprocess system works using the same logic as the build system, but
2234  is configured primarily to preprocess C/C++ and Fortran source files. We
2235  shall document only the main differences to the build system in the remainder
2236  of this section.</p>
2237
2238  <h3 id="preprocess.basic">Preprocess: Basic</h3>
2239
2240  <p>A typical usage of the preprocess system may look like:</p>
2241  <pre>
2242steps = extract preprocess build
2243
2244# ... some extract configuration
2245
2246# Switch off preprocessing for all
2247preprocess.target{task} =
2248# Only preprocess source files in these name-spaces
2249preprocess.target{task}[foo/bar egg/fried.F90] = process
2250# Specifies the macro definitions for the Fortran preprocessor
2251preprocess.prop{fpp.defs} = THING=stuff HIGH=tall
2252# Specifies the macro definitions for the C preprocessor
2253preprocess.prop{cpp.defs} = LOWER=lower UNDER LINUX
2254
2255# ... some build configuration
2256</pre>
2257
2258  <p>The result of the preprocess can be found in the sub-directories of the
2259  <samp>preprocess/</samp> sub-directory. There are only 2 target
2260  categories:</p>
2261
2262  <dl>
2263    <dt id="preprocess.category.include"><samp>include</samp></dt>
2264
2265    <dd>e.g. include files.</dd>
2266
2267    <dt id="preprocess.category.src"><samp>src</samp></dt>
2268
2269    <dd>e.g. preprocessed source files</dd>
2270  </dl>
2271
2272  <h3 id="preprocess.source-type">Preprocess Source Types</h3>
2273
2274  <p>Only files in the following types (with the given file extensions) are
2275  recognised by the preprocess system:</p>
2276
2277  <dl>
2278    <dt><a href="annex_cfg.html#make.preprocess.prop.file-ext.cpp">cpp</a>
2279    (C/C++ source file)</dt>
2280
2281    <dd>.c .m .cc .cp .cxx .cpp .CPP .c++ .C .mm .M</dd>
2282
2283    <dt><a href="annex_cfg.html#make.preprocess.prop.file-ext.fpp">fpp</a>
2284    (Fortran source file requiring preprocessing)</dt>
2285
2286    <dd>.F .FOR .FTN .F90 .F95</dd>
2287
2288    <dt><a href="annex_cfg.html#make.preprocess.prop.file-ext.h">h</a>
2289    (Preprocessor header file)</dt>
2290
2291    <dd>.h</dd>
2292  </dl>
2293
2294  <h3 id="preprocess.source-analysis">Preprocess Source Analysis</h3>
2295
2296  <p>The preprocess system only looks for include dependencies using the
2297  pattern <samp>#include "name.h"</samp>. Macros using the angle brackets
2298  syntax (e.g. <samp>#include &lt;name.h&gt;</samp>) are ignored.</p>
2299
2300  <h3 id="preprocess.target-source">Preprocess Targets from Source Files</h3>
2301
2302  <p>The preprocess system only generates targets from source files, (i.e.
2303  targets are not generated by name-spaces). Targets of the preprocess system
2304  perform one of the following <dfn>tasks</dfn>:</p>
2305
2306  <dl>
2307    <dt id="preprocess.task.install">install</dt>
2308
2309    <dd>Copies the source file to the destination.</dd>
2310
2311    <dt id="preprocess.task.process">process</dt>
2312
2313    <dd>Creates a new source file by invoking the C/Fortran preprocessor on the
2314    original source file.</dd>
2315  </dl>
2316
2317  <p>By default, it attempts to build all targets with a <samp><a href=
2318  "#preprocess.task.process">process</a></samp> task, i.e.:</p>
2319  <pre>
2320preprocess.target =
2321preprocess.target{task} = process
2322preprocess.target{category} =
2323</pre>
2324
2325  <p>Here is a list of what targets are available for each type of file:</p>
2326
2327  <dl>
2328    <dt>cpp -&gt; name-space</dt>
2329
2330    <dd>
2331      <p><dfn>description</dfn>: the preprocessed version of the original
2332      file.</p>
2333
2334      <p><dfn>task</dfn>: <a href="#preprocess.task.process">process</a>
2335      (cpp).</p>
2336
2337      <p><dfn>category and destination</dfn>: <a href=
2338      "#preprocess.category.src">src</a> and src/name-space</p>
2339
2340      <p><dfn>properties</dfn>: <a href=
2341      "annex_cfg.html#make.preprocess.prop.cpp">cpp</a>, <a href=
2342      "annex_cfg.html#make.preprocess.prop.cpp.flags">cpp.flags</a>, <a href=
2343      "annex_cfg.html#make.preprocess.prop.cpp.defs">cpp.defs</a>, <a href=
2344      "annex_cfg.html#make.preprocess.prop.cpp.flag-define">cpp.flag-define</a>,
2345      <a href=
2346      "annex_cfg.html#make.preprocess.prop.cpp.flag-include">cpp.flag-include</a>,
2347      <a href=
2348      "annex_cfg.html#make.preprocess.prop.cpp.include-paths">cpp.include-paths</a></p>
2349      <p><dfn>dependencies</dfn>: include.</p>
2350
2351      <p><dfn>update if</dfn>: source file or any of the required properties
2352      are modified, or if any include dependencies are updated.</p>
2353    </dd>
2354
2355    <dt>fpp -&gt; name-space</dt>
2356
2357    <dd>
2358      <p><dfn>description</dfn>: the preprocessed version of the original
2359      file.</p>
2360
2361      <p><dfn>task</dfn>: <a href="#preprocess.task.process">process</a>
2362      (fpp).</p>
2363
2364      <p><dfn>category and destination</dfn>: <a href=
2365      "#preprocess.category.src">src</a> and src/name-space</p>
2366
2367      <p><dfn>properties</dfn>: <a href=
2368      "annex_cfg.html#make.preprocess.prop.fpp">fpp</a>, <a href=
2369      "annex_cfg.html#make.preprocess.prop.fpp.flags">fpp.flags</a>, <a href=
2370      "annex_cfg.html#make.preprocess.prop.fpp.defs">fpp.defs</a>, <a href=
2371      "annex_cfg.html#make.preprocess.prop.fpp.flag-define">fpp.flag-define</a>,
2372      <a href=
2373      "annex_cfg.html#make.preprocess.prop.fpp.flag-include">fpp.flag-include</a>,
2374      <a href=
2375      "annex_cfg.html#make.preprocess.prop.fpp.include-paths">fpp.include-paths</a></p>
2376
2377      <p><dfn>dependencies</dfn>: include.</p>
2378
2379      <p><dfn>update if</dfn>: source file or any of the required properties
2380      are modified, or if any include dependencies are updated.</p>
2381    </dd>
2382
2383    <dt>h -&gt; name</dt>
2384
2385    <dd>
2386      <p><dfn>description</dfn>: a header (include) file.</p>
2387
2388      <p><dfn>task</dfn>: <a href="#preprocess.task.install">install</a>.</p>
2389
2390      <p><dfn>category and destination</dfn>: <a href=
2391      "#preprocess.category.include">include</a> and include/name</p>
2392
2393      <p><dfn>dependencies</dfn>: include.</p>
2394
2395      <p><dfn>update if</dfn>: source file is modified.</p>
2396    </dd>
2397  </dl>
2398
2399  </div>
2400  </div>
2401  </div>
2402
2403  <hr/>
2404  <div class="container-fluid text-center">
2405    <div class="row"><div class="col-md-12">
2406    <address><small>
2407      &copy; British Crown Copyright 2006-16
2408      <a href="http://www.metoffice.gov.uk">Met Office</a>.
2409      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
2410      This document is released under the British <a href=
2411      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
2412      "license">Open Government Licence</a>.<br />
2413    </small></address>
2414    </div></div>
2415  </div>
2416
2417  <script type="text/javascript" src="../etc/jquery.min.js"></script>
2418  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
2419  <script type="text/javascript" src="../etc/fcm.js"></script>
2420  <script type="text/javascript" src="../etc/fcm-version.js"></script>
2421</body>
2422</html>
Note: See TracBrowser for help on using the repository browser.