Context Navigation

make.html

Last change on this file was 5129, checked in by abarral, 5 months ago
Re-add removed by mistake fcm
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 > 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>
54	fcm 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 > 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>
89	steps = extract build # 1
90
91	extract.ns = egg ham bacon # 2
92	# ... more extract configuration
93
94	build.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>
112	step.class[build-this build-that] = build # 1
113	steps = extract build-this build-that # 2
114
115	extract.ns = egg ham bacon # 3
116	# ... more extract configuration
117
118	build-this.prop{fc.defs} = DEFS TO BUILD THIS # 4
119	build-this.target = this.exe
120	# ... more build configuration for "build-this"
121
122	build-that.prop{fc.defs} = DEFS TO BUILD THAT # 5
123	build-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>
143	use = /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/...
161	extract/...
162	build/...
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 ->
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 ->
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 -> .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>
250	steps = extract # line 1
251	extract.ns = ops var um # line 2
252	extract.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>
286	extract/ops/...
287	extract/um/...
288	extract/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 > 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>
374	doc/...
375	src/bar/...
376	src/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>
384	steps = extract # line 1
385	extract.ns = foo # line 2
386	extract.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>
392	extract/foo/bar/...
393	extract/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>
402	src/bar/wine/red.c
403	src/bar/wine/rose.c
404	src/bar/wine/white.c
405	src/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>
413	steps = extract # line 1
414	extract.ns = foo
415	extract.path-root[foo] = src # line 3
416	extract.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>
427	extract/foo/bar/wine/red.c
428	extract/foo/bar/wine/white.c
429	extract/foo/bar/...
430	extract/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>
440	steps = extract # line 1
441	extract.ns = foo # line 2
442	extract.path-root[foo] = src # line 3
443	extract.path-excl[foo] = bar/wine # line 4
444	extract.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>
450	extract/foo/bar/wine/rose.c
451	extract/foo/bar/...
452	extract/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>
465	doc/...
466	src/egg/boiled.y
467	src/egg/microwave.x
468	src/egg/omelette.c
469	src/egg/poached.f90
470	src/...
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>
480	D src/egg/boiled.y
481	A src/egg/fried.pl
482	M 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>
488	M src/egg/omelette.c
489	M 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>
495	M src/egg/boiled.y
496	A 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">
502	steps = extract
503	extract.ns = food
504	extract.location[food] = trunk@3739
505	extract.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>
522	extract/doc/...
523	extract/src/egg/fried.pl
524	extract/src/egg/microwave.x
525	extract/src/egg/omelette.c
526	extract/src/egg/poached.f90
527	extract/src/egg/scrambled.bash
528	extract/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>
589	use = /home/food/latest
590	extract.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>
599	extract/src/egg/fried.pl
600	extract/src/egg/omelette.c
601	extract/src/egg/poached.f90
602	extract/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>
805	steps = extract mirror # 1
806	# ... some extract declarations
807	mirror.target = user@somewhere:/path/in/somewhere # 2
808	mirror.prop{config-file.name} = -at-somewhere # 3
809	mirror.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>
898	steps = build
899	build.target{task} = link
900	build.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>
919	build/bin/...
920	build/include/...
921	build/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>
966	steps = build
967	build.target{task} = link
968	build.source = $HOME/my-source-tree
969
970	# Set Fortran compiler/linker
971	build.prop{fc} = ifort
972	# Set Fortran compiler options
973	build.prop{fc.flags} = -i8 -r8 -O3
974	# Add include paths to Fortran compiler
975	build.prop{fc.include-paths} = /a/path/to/include /more/path/to/include
976	# Set link libraries for Fortran executables
977	build.prop{fc.lib-paths} = /path/to/my-lib
978	build.prop{fc.libs} = mine
979	# Set C compiler/linker
980	build.prop{cc} = icc
981	# Set C compiler options
982	build.prop{cc.flags} = -O3
983	# Set C++ compiler options
984	build.prop{cxx.flags} = -O2
985	# Set link libraries for C executables
986	build.prop{cc.lib-paths} = /path/to/my-lib /path/to/your-lib
987	build.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
1024	build.ns-excl = / # exclude everything ...
1025	build.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
1068	build.prop{fc.flags} = -O3
1069
1070	# The Fortran compiler flags for the "food" name-space
1071	build.prop{fc.flags}[food] = -O2 -i8 -r8
1072
1073	# The Fortran compiler flags for a source file
1074	build.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>
1119	build.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>
1131	build.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
1250	build.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
1254	build.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
1313	build.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	-> 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 -> 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 -> 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) -> 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 -> 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) -> 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) -> 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) -> 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) -> 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 -> 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 -> 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 -> 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>
1677	build.prop{fc.flags}[sausage.o] = -O4
1678	# would be the same as:
1679	build.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>
1686	build.prop{no-dep.include}[sausage.o] = enum.f90
1687	build.prop{include-paths}[sausage.o] = /path/to/additives
1688	</pre>
1689
1690	<p>However, the following will not work:</p>
1691
1692	<pre>
1693	build.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>
1700	build.prop{no-dep.include}[sausage.o] = pork.mod
1701	build.prop{no-dep.o}[sausage.mod] = pork.o
1702	# would be the same as:
1703	build.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	<module></code> statement. We recommend adding the <code>ONLY</code>
1722	clause in a <code>USE <module></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	<module></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
1779	build.target = egg.bin ham.o bacon.sh
1780
1781	# Select all targets doing tasks "install" or "link"
1782	build.target{task} = install link
1783
1784	# Select targets in name-space "foo" or "bar" doing tasks "link"
1785	build.target{task}[foo bar] = link
1786
1787	# Select all targets in the "bin" category
1788	build.target{category} = bin
1789
1790	# Select targets in name-space "foo" in the "etc" category
1791	build.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>
1800	build.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.
1816	build.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>
1827	build.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 > 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 > 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:
1978	build.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>
1985	use = /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>
1991	use /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:
2041	egg/hen.c
2042	egg/fried.h
2043
2044	# Sources in current build:
2045	egg/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 <- lib/function/hello_func.f90
2132	[info] ext-iface 0.0 M hello_func.interface <- lib/function/hello_func.f90
2133	[info] install 0.0 M hello_inc.f90 <- include/hello_inc.f90
2134	[info] compile 0.0 M hello_1.o <- bin/hello_1.f90
2135	[info] link 0.1 M hello_1.exe <- 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] -> ( include) hello_inc.f90
2152	[info] -> ( o) hello_void.o
2153	[info] -> ( 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->target / -> (archive) lib/ libo.a
2162	[info] source->target hello.f90 -> (link) bin/ hello.exe
2163	[info] source->target hello.f90 -> (install) include/ hello.f90
2164	[info] source->target hello.f90 -> (compile) o/ hello.o
2165	[info] source->target world.f90 -> (install) include/ world.f90
2166	[info] source->target world.f90 -> (compile+) include/ world.mod
2167	[info] source->target world.f90 -> (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>
2242	steps = extract preprocess build
2243
2244	# ... some extract configuration
2245
2246	# Switch off preprocessing for all
2247	preprocess.target{task} =
2248	# Only preprocess source files in these name-spaces
2249	preprocess.target{task}[foo/bar egg/fried.F90] = process
2250	# Specifies the macro definitions for the Fortran preprocessor
2251	preprocess.prop{fpp.defs} = THING=stuff HIGH=tall
2252	# Specifies the macro definitions for the C preprocessor
2253	preprocess.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 <name.h></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>
2320	preprocess.target =
2321	preprocess.target{task} = process
2322	preprocess.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 -> 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 -> 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 -> 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	Copyright © 2006-2021 British Crown (Met Office) & Contributors.
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.

Context Navigation

source: LMDZ6/branches/Amaury_dev/tools/fcm/doc/user_guide/make.html

Download in other formats: