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

Last change on this file was 5129, checked in by abarral, 5 months ago

Re-add removed by mistake fcm
File size: 52.3 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4  <title>FCM: User Guide: Annex: FCM Configuration File</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: Annex: FCM Configuration File</h1>
31  </div>
32
33  <div class="container">
34  <div class="row">
35  <div class="col-md-12">
36
37  <h2 id="syntax">Syntax</h2>
38
39  <h3 id="syntax.comment">Syntax: comment</h3>
40
41  <p>An empty line, a line with only space characters and a line beginning with
42  a <kbd>#</kbd> character is a comment line. For example:</p>
43  <pre>
44# This is a comment.
45    # This is also a comment.
46</pre>
47
48  <p>Also, if a line contains a space character followed by a <kbd>#</kbd>
49  character then this, and any following characters, are treated as an end of
50  line comment and are ignored.</p>
51
52  <h3 id="syntax.declaration">Syntax: declaration</h3>
53
54  <p>The general syntax of a declaration consists of a label, a set of
55  modifiers, a list of name-spaces, and a value:</p>
56  <pre>
57label{mod:mod-value}[ns] = value
58label{mod:mod-value} = value
59label[ns] = value
60label = value
61label = value\
62    value # "value    value"
63label = value\
64    \value # "valuevalue"
65</pre>
66
67  <p>The label is compulsory. It defines the declaration, and may have one or
68  more characters in the alpha-numeric, the underscore, the minus sign and the
69  full stop. The label cannot be substituted with a variable.</p>
70
71  <p>The modifier is an optional part of the syntax, but may be a compulsory
72  part of some declarations. The modifiers are embedded between a pair of curly
73  braces and must come after the label, but before the name-spaces and the
74  equal sign. It should be a comma-separated list of colon-separated key-value
75  pairs, (i.e. <kbd>{key1: value1, key2: value2, ...}</kbd>). The value in each
76  modifier is optional - if a key is set without a value, its value is assumed
77  to be 1. The contents of the modifiers can be substituted using a
78  variable.</p>
79
80  <p>The name-space is an optional part of the syntax, but may be a compulsory
81  part of some declarations. The name-spaces are embedded between a pair of
82  square braces and must come after the label and/or modifiers but before the
83  equal sign. It should be a space-separated list of names. If a name contains
84  space, the space character can be escaped using a backslash character or the
85  name can be quoted. The contents of the name-spaces can be substituted using
86  a variable.</p>
87
88  <p>The first non-space character after the equal sign begins the value of the
89  declaration. If there is nothing after the equal sign, the value is an empty
90  string. The contents of the value can be substituted using a variable.
91  Trailing space characters are ignored. The end of line can be escaped using a
92  backslash, and the value of the declaration will continue from the next
93  non-comment line. If the first non-space character on that line is a
94  backslash then the line contents up to and including that backslash are
95  ignored.</p>
96
97  <h3 id="syntax.variable">Syntax: variable</h3>
98
99  <p>A variable is used to substitute commonly used values in a declaration. It
100  can refer to an environment variable or can be defined locally using the
101  syntax:</p>
102  <pre>
103$var = value    # Sets "var" variable to "value"
104$var{?} = value # Sets "var" variable to "value" only if "var" is not defined
105# E.g.:
106$projects = foo bar baz
107$long_path = src/path/is/very/very/very/long
108$UMDIR{?} = /projects/um1
109# time passes...
110extract.ns = $projects
111extract.path-excl[$projects egg ham] = doc man ${long_path}_longer
112build.prop{cc.defs} = foo=\$foo # escape substitution
113</pre>
114
115  <p>The name of a variable must begin with an alphabet or an underscore and
116  followed by 0 or more alpha-numeric or underscore characters, (i.e. it must
117  match this regular expression: <var>^[A-Za-z_][A-Za-z0-9_]*$</var>).</p>
118
119  <p>Locally defined variables only apply in the context of the configuration
120  file and are not passed down, for instance, to the compiler. If there is an
121  environment variable with the same identifier, its value is normally
122  overridden (within the context of the configuration file) by any local
123  setting. However, if a <kbd>?</kbd> modifier is given, it assigns the value
124  to the variable only if the variable is not already defined (either as an
125  environment variable or locally). Substitution can be escaped using a
126  backslash character in front of the dollar sign. Any attempt to reference an
127  undefined variable will trigger an exception.</p>
128
129  <p>Note: <var>$HERE</var> is a reserved variable to indicate the parent
130  directory of the current configuration file. (The system ignores the $HERE
131  environment variable, if there is one.) Any attempt to assign a value to
132  <var>$HERE</var> will trigger an exception.</p>
133
134  <h3 id="syntax.include">Syntax: include</h3>
135
136  <p>An <code>include</code> declaration specifies the logical locations of a
137  list of configuration files, where contents are to be included inline:</p>
138  <pre>
139include{type:type} = location ...
140# E.g.:
141include = fcm:foo/path/to/config/file
142include = svn://server/path/to/config/file@1234
143include{type:svn} = http://server/path/to/config/file
144include = /path/to/config/file $HERE/another-config-file
145include = $HERE/another-config-file
146include = ~/path/to/config/file ~fred/path/to/config/file
147</pre>
148
149  <p>If the value of an <code>include</code> declaration is a relative path,
150  the system will search the directory containing the current configuration
151  file for the include file. More include search paths can be specified using
152  the <code>include-path</code> declaration. E.g.:</p>
153
154  <pre>
155# Define or replace include search paths
156include-path=/path/to/some/cfg /path/to/more/cfg
157# Append to include search paths
158include-path{+}=host2:/path/to/cfg
159include-path{type:svn,+}=https://host1/path/to/cfg
160# ... Include files can now be relative paths
161include=foo.cfg bar.cfg
162</pre>
163
164  <p>Some commands, e.g. <code>fcm make</code>, accept one or more
165  <code>--config-file-path=PATH</code> command line option, which can be used
166  to pre-define the include search paths when they read their configuration
167  files.</p>
168
169  <p>Currently, the location can be a path in the file system, a Subversion URL,
170  a FCM keyword pointing to a Subversion URL, or a location in the file system
171  of a remote host accessible via passphrase-less SSH. The system will attempt
172  to make an intelligent guess of the location type. To allow for future
173  expansion, both the <code>include</code> and the <code>include-path</code>
174  declarations accept a <var>type:TYPE</var> modifier (where TYPE can currently
175  be <samp>fs</samp> for a file system path or <samp>svn</samp> for a Subversion
176  location) to allow the location type to be defined where it is ambiguous.</p>
177
178  <h2 id="keyword">FCM Keyword Configuration</h2>
179
180  <p>The keyword configuration files are mainly used to define FCM location
181  keywords and related settings. The <code>fcm</code> command searches for
182  keyword configuration files from the following locations:</p>
183
184  <ol>
185    <li><dfn>(Deprecated)</dfn> <samp>$HOME/.fcm</samp> - expects FCM 1
186    configuration file format. See <a href="annex_fcm_cfg.html">Annex:
187    Declarations in FCM 1 central/user configuration file</a> for detail.</li>
188
189    <li><samp>$FCM/etc/fcm/keyword.cfg</samp> where <var>$FCM/bin/</var> is the
190    path at which <code>fcm</code> is installed.</li>
191
192    <li><samp>$HOME/.metomi/fcm/keyword.cfg</samp>.</li>
193  </ol>
194
195  <p>The following are declarations recognised by the keyword configuration
196  files:</p>
197
198  <dl>
199    <dt id="keyword.location">location</dt>
200
201    <dd>
202      <p><dfn>description</dfn>: Associates a namespace with a location, and
203      allows the use of <samp>fcm:namespace</samp> as a substitute of the
204      location.</p>
205
206      <p><dfn>modifier</dfn>: <var>primary</var>: Optional. If specified, the
207      location is a primary location, i.e. the system will create the
208      <samp>_tr</samp>, <samp>_br</samp>, <samp>_tg</samp>, <samp>-tr</samp>,
209      <samp>-br</samp> and <samp>-tg</samp> keywords for this location.</p>
210
211      <p><dfn>modifier</dfn>: <var>type</var>: Optional. Specifies the type of
212      the location. The system currently supports <samp>svn</samp> for a
213      Subversion location and <samp>fs</samp> for a file system location. If
214      not specified, the system will make an intelligent guess based on the
215      given value.</p>
216
217      <p><dfn>namespace</dfn>: The namespace to be associated with the
218      location.</p>
219
220      <p><dfn>value</dfn>: A valid location of a type supported by the
221      system.</p>
222
223      <p><dfn>example</dfn>:</p>
224      <pre>
225location{primary}[var] = svn://fcm5/VAR_svn/VAR
226location{primary, type:svn}[egg] = http://chicken/egg
227</pre>
228    </dd>
229
230    <dt id="keyword.revision">revision</dt>
231
232    <dd>
233      <p><dfn>description</dfn>: Associates a keyword with a revision of a
234      location in a version control system.</p>
235
236      <p><dfn>namespace</dfn>: The namespace of a location (already defined
237      using the <code>location</code> declaration), followed by a colon and the
238      namespace of the revision.</p>
239
240      <p><dfn>value</dfn>: A valid revision of the location.</p>
241
242      <p><dfn>example</dfn>:</p>
243      <pre>
244revision[um:vn7.5] = 18479
245revision[egg:free-range] = 1
246</pre>
247    </dd>
248
249    <dt id="keyword.browser.comp-pat">browser.comp-pat</dt>
250
251    <dd>
252      <p><dfn>description</dfn>: Specifies a regular expression to capture
253      components in the scheme-specific part of a version control system
254      location (already defined using the <code>location{primary}</code>
255      declaration). These components can then be used in the
256      <code>browser.loc-tmpl</code> template string.</p>
257
258      <p><dfn>namespace</dfn>: Optional. The namespace of a location. If not
259      specified, the declaration applies globally.</p>
260
261      <p><dfn>value</dfn>: A valid regular expression.</p>
262
263      <p><dfn>example</dfn>:</p>
264      <pre>
265browser.comp-pat = (?msx-i:\A // ([^/]+) /+ ([^/]+)_svn /*(.*) \z) # default
266browser.comp-pat[egg] = (?msx-i:\A//([^/]+)/(.*)\z)
267</pre>
268    </dd>
269
270    <dt id="keyword.browser.loc-tmpl">browser.loc-tmpl</dt>
271
272    <dd>
273      <p><dfn>description</dfn>: Specifies a template string, in which the
274      components captured by the <code>browser.comp.pat</code> regular
275      expression are used to fill in the numbered fields. The template should
276      have one more field than the number of components captured by
277      <code>browser.comp-pat</code>. The final field is used to place the
278      revision, which is generated via the <code>browser.rev-tmpl</code>.</p>
279
280      <p><dfn>namespace</dfn>: Optional. The namespace of a location. If not
281      specified, the declaration applies globally.</p>
282
283      <p><dfn>value</dfn>: A valid template.</p>
284
285      <p><dfn>example</dfn>:</p>
286      <pre>
287browser.loc-tmpl = http://{1}/projects/{2}/intertrac/source:/{3}{4} # default
288browser.loc-tmpl[egg] = http://{1}/intertrac/source:/{3}{4}
289</pre>
290    </dd>
291
292    <dt id="keyword.browser.rev-tmpl">browser.rev-tmpl</dt>
293
294    <dd>
295      <p><dfn>description</dfn>: Specifies a template string, which should have
296      a single numbered field for filling in the revision number.</p>
297
298      <p><dfn>namespace</dfn>: Optional. The namespace of a location. If not
299      specified, the declaration applies globally.</p>
300
301      <p><dfn>value</dfn>: A valid template.</p>
302
303      <p><dfn>example</dfn>:</p>
304      <pre>
305browser.rev-tmpl = @{1} # default
306</pre>
307    </dd>
308  </dl>
309
310  <h2 id="external">FCM External Configuration</h2>
311
312  <p>The external configuration files are used to define the name of external
313  commands used by the FCM system. The <code>fcm</code> command searches for
314  external configuration files from the following locations:</p>
315
316  <ol>
317    <li><samp>$FCM/etc/fcm/external.cfg</samp> where <var>$FCM/bin/</var> is
318    the path at which <code>fcm</code> is installed.</li>
319
320    <li><samp>$HOME/.metomi/fcm/external.cfg</samp>.</li>
321  </ol>
322
323  <p>The following are declarations recognised by the external configuration
324  files:</p>
325
326  <dl>
327    <dt id="external.browser">browser</dt>
328
329    <dd>
330      <p><dfn>description</dfn>: Specifies the command to invoke the web
331      browser. (default=<samp>firefox</samp>)</p>
332
333      <p><dfn>example</dfn>:</p>
334      <pre>
335browser = konqueror
336</pre>
337    </dd>
338
339    <dt id="external.diff3">diff3</dt>
340
341    <dd>
342      <p><dfn>description</dfn>: The shell command used by the extract system of
343      FCM Make to perform a 3-way merge. (default=<samp>diff3</samp>)</p>
344
345      <p><dfn>example</dfn>:</p>
346      <pre>
347diff3 = diff3
348</pre>
349    </dd>
350
351    <dt id="external.diff3.flags">diff3.flags</dt>
352
353    <dd>
354      <p><dfn>description</dfn>: The options used by the 3-way merge shell
355      command. (default=<samp>-E -m</samp>)</p>
356
357      <p><dfn>example</dfn>:</p>
358      <pre>
359diff3.flags = -E -m
360</pre>
361    </dd>
362
363    <dt id="external.graphic-diff">graphic-diff</dt>
364
365    <dd>
366      <p><dfn>description</dfn>: Specifies the command to invoke the graphic
367      diff tool. (default=<samp>xxdiff</samp>)</p>
368
369      <p><dfn>example</dfn>:</p>
370      <pre>
371graphic-diff = tkdiff
372</pre>
373    </dd>
374
375    <dt id="external.graphic-merge">graphic-merge</dt>
376
377    <dd>
378      <p><dfn>description</dfn>: Specifies the command to invoke the graphic
379      merge tool. (default=<samp>xxdiff</samp>)</p>
380
381      <p><dfn>example</dfn>:</p>
382      <pre>
383graphic-merge = xxdiff
384</pre>
385    </dd>
386
387    <dt id="external.ssh">ssh</dt>
388
389    <dd>
390      <p><dfn>description</dfn>: The secure remote shell command to execute
391      commands on a remote host.  (default=<samp>ssh</samp>)</p>
392
393      <p><dfn>example</dfn>:</p>
394      <pre>
395ssh = ssh
396</pre>
397    </dd>
398
399    <dt id="external.ssh.flags">ssh.flags</dt>
400
401    <dd>
402      <p><dfn>description</dfn>: The options used by the secure shell command to
403      execute commands on a remote host. (default=<samp>-n
404      -oBatchMode=yes</samp>)</p>
405
406      <p><dfn>example</dfn>:</p>
407      <pre>
408ssh.flags = -n -oBatchMode=yes
409</pre>
410    </dd>
411
412    <dt id="external.rsync">rsync</dt>
413
414    <dd>
415      <p><dfn>description</dfn>: The <code>rsync</code> command.
416      (default=<samp>rsync</samp>)</p>
417
418      <p><dfn>example</dfn>:</p>
419      <pre>
420rsync = rsync
421</pre>
422    </dd>
423
424    <dt id="external.rsync.flags">rsync.flags</dt>
425
426    <dd>
427      <p><dfn>description</dfn>: The options used by the <code>rsync</code>
428      command. (default=<samp>-a --exclude=.* --delete-excluded --timeout=900
429      --rsh=ssh\ -oBatchMode=yes</samp>)</p>
430
431      <p><dfn>example</dfn>:</p>
432      <pre>
433rsync.flags = -a --exclude=.* --delete-excluded --timeout=900 --rsh=ssh\ -oBatchMode=yes
434</pre>
435    </dd>
436  </dl>
437
438  <h2 id="make">FCM Make Configuration</h2>
439
440  <p>A typical FCM make configuration consists of some top level declarations
441  to define the make, and specific declarations for each step. The top level
442  declarations are described below, and the specific declarations for each type
443  of step will be described in the sub-sections to follow.</p>
444
445  <p>Note:</p>
446
447  <ul>
448    <li>Unless stated otherwise, FCM make configuration declarations are
449    non-cumulative, i.e. if more than one declarations apply to the
450    <dfn>same</dfn> configuration, the value of the last declaration overrides
451    those of the earlier ones. E.g.:
452      <pre>
453# Sets the Fortran compiler flags for the root name-space
454build.prop{fc.flags} = -O3
455# build.prop{fc.flags}[/] = -O3
456
457# Sets the C/Fortran compiler flags for the "foo/bar" name-space
458build.prop{cc.flags, fc.flags}[foo/bar] = -g -C
459# build.prop{cc.flags}[foo/bar] = -g -C
460# build.prop{fc.flags}[/] = -O3
461# build.prop{fc.flags}[foo/bar] = -g -C
462
463# Sets the Fortran compiler flags for the root and "foo/bar" name-spaces
464build.prop{fc.flags}[/ foo/bar] = -O2
465# build.prop{cc.flags}[foo/bar] = -g -C
466# build.prop{fc.flags}[/] = -O2
467# build.prop{fc.flags}[foo/bar] = -O2
468
469# Sets the Fortran compiler flags for the "foo/bar" name-spaces
470build.prop{fc.flags}[foo/bar] = -O1
471# build.prop{cc.flags}[foo/bar] = -g -C
472# build.prop{fc.flags}[/] = -O2
473# build.prop{fc.flags}[foo/bar] = -O1
474</pre>
475    </li>
476
477    <li>Unless stated otherwise, declarations are inherited.</li>
478
479    <li>The default values of the property settings of each step class (e.g.
480    <code>build.prop{fc}</code>) can be modified in:
481
482      <ol>
483        <li>The site configuration file <samp>$FCM/etc/fcm/make.cfg</samp>
484        where <var>$FCM/bin/</var> is the path at which <code>fcm</code> is
485        installed.</li>
486
487        <li>The user configuration file
488        <samp>$HOME/.metomi/fcm/make.cfg</samp>.</li>
489
490        <li><samp>*.prop{class,*}</samp> declarations in the FCM make
491        configuration file of the current session.</li>
492      </ol>
493
494      <p>The syntax is identical to a normal FCM make configuration file
495      declaration except that:</p>
496
497      <ul>
498        <li>Only <samp>*.prop{*}</samp> declarations are accepted.</li>
499
500        <li>The settings apply to a step class, not an individual step.</li>
501
502        <li>Name-space is not allowed.</li>
503      </ul>
504    </li>
505  </ul>
506
507  <p>For further details, please refer to the chapter on <a href=
508  "make.html">FCM Make</a>.</p>
509
510  <dl>
511    <dt id="make.description">description</dt>
512
513    <dd>
514      <p><dfn>description</dfn>: Specifies a description string for the current
515      make.</p>
516
517      <p><dfn>value</dfn>: A string.</p>
518
519      <p><dfn>example</dfn>:</p>
520      <pre>
521description = Release 2.71.82
522</pre>
523    </dd>
524
525    <dt id="make.dest">dest</dt>
526
527    <dd>
528      <p><dfn>description</dfn>: Specifies the output destination of the make
529      system. If not specified, the system assumes the output destination to be
530      the current working directory. This setting is not inherited.</p>
531
532      <p><dfn>value</dfn>: A writable directory path.</p>
533
534      <p><dfn>example</dfn>:</p>
535      <pre>
536dest = path
537# E.g.:
538dest = $HERE
539</pre>
540    </dd>
541
542    <dt id="make.name">name</dt>
543
544    <dd>
545      <p><dfn>description</dfn>: Specifies the NAME of the make, so that the
546      command will search for <q>fcm-make<var>NAME</var>.cfg</q> instead of
547      <q>fcm-make.cfg</q>, and will write context files in
548      <q>.fcm-make<var>NAME</var>/</q> and log files as
549      <q>fcm-make<var>NAME</var>.log</q>, etc.</p>
550
551      <p><dfn>value</dfn>: A file name friendly string.</p>
552
553      <p><dfn>example</dfn>:</p>
554      <pre>
555name = -friend
556</pre>
557    </dd>
558
559    <dt id="make.require-version">require-version</dt>
560
561    <dd>
562      <p><dfn>description</dfn>: Specifies the minimum FCM version and
563      optionally the maximum FCM version that can be used on the current
564      configuration. If specified, FCM make fails immediately if its version
565      does not meet the criteria.</p>
566
567      <p><dfn>value</dfn>: The minimum version required, and optionally the
568      maximum version required.</p>
569
570      <p><dfn>example</dfn>:</p>
571      <pre>
572# Requires minimum FCM release at 2016.02.0
573require-version = 2016.02.0
574# Requires minimum FCM release at 2016.02.0, and maximum at 2038.01.0
575require-version = 2016.02.0 2038.01.0
576</pre>
577    </dd>
578
579    <dt id="make.steps">steps</dt>
580
581    <dd>
582      <p><dfn>description</dfn>: Specifies a list of steps for the make system
583      to invoke. Each specified step can either be the ID of a known
584      sub-system, i.e. <samp>extract</samp>, <samp>mirror</samp>,
585      <samp>preprocess</samp> and <samp>build</samp>, or an ID defined using
586      the <code>step.class</code> declaration. (See below.)</p>
587
588      <p><dfn>value</dfn>: A list of steps for the make system to invoke.</p>
589
590      <p><dfn>example</dfn>:</p>
591      <pre>
592steps = id-1 id-2 ...
593# E.g.:
594steps = extract mirror
595</pre>
596    </dd>
597
598    <dt id="make.step.class">step.class</dt>
599
600    <dd>
601      <p><dfn>description</dfn>: Defines custom step IDs. This allows built-in
602      steps to be renamed, or re-used in multiple steps.</p>
603
604      <p><dfn>namespace</dfn>: Specifies the step IDs.</p>
605
606      <p><dfn>value</dfn>: An ID of a known sub-system, i.e.
607      <samp>extract</samp>, <samp>mirror</samp>, <samp>preprocess</samp> and
608      <samp>build</samp>.</p>
609
610      <p><dfn>example</dfn>:</p>
611      <pre>
612step.class[id ...] = id-of-class
613# E.g.:
614step.class[build-qxrecon build-ieee] = build
615</pre>
616    </dd>
617
618    <dt id="make.use">use</dt>
619
620    <dd>
621      <p><dfn>description</dfn>: Specifies inheritance locations. It is worth
622      noting that this declaration is cumulative, i.e. a <code>use</code>
623      declaration adds more inheritance locations rather than overrides the
624      inheritance locations of any previous <code>use</code> declarations.</p>
625
626      <p><dfn>value</dfn>: A list of paths where this make can inherit items
627      and properties from.</p>
628
629      <p><dfn>example</dfn>:</p>
630      <pre>
631use = path1 path2 ...
632E.g.:
633use = /path/to/inherit
634</pre>
635    </dd>
636  </dl>
637
638  <h3 id="make.extract">FCM Make Configuration: Extract</h3>
639
640  <p>All declarations are prefixed with <samp>extract.*</samp>. Where
641  appropriate, replace the leading <samp>extract</samp> with the appropriate
642  step ID. With the exception of the <code>extract.location{diff}</code>
643  declaration, any attempt to specify any extract declarations in an inherited
644  extract will result in an exception.</p>
645
646  <dl>
647    <dt id="make.extract.ns">extract.ns</dt>
648
649    <dd>
650      <p><dfn>description</dfn>: Specifies a list of names of the projects to
651      extract.</p>
652
653      <p><dfn>value</dfn>: A space-delimited list of names of the projects to
654      extract.</p>
655
656      <p><dfn>example</dfn>:</p>
657      <pre>
658extract.ns = gen ops um var ver
659</pre>
660    </dd>
661
662    <dt id="make.extract.location">extract.location</dt>
663
664    <dd>
665      <p><dfn>description</dfn>: Specifies the location of the base source tree
666      a project. If the base source tree is not specified for a Subversion
667      project, the system will try to use <samp>trunk@HEAD</samp>.</p>
668
669      <p><dfn>modifier</dfn>: <var>type</var>: Specifies the type of the
670      locations. The system currently supports <samp>svn</samp> for a Subversion
671      location, <samp>ssh</samp> for a file system on a remote host accessible
672      via SSH and RSYNC, and <samp>fs</samp> for a file system location.
673      (default=<samp>svn</samp> if the location is recognised as a Subversion
674      URL, <samp>ssh</samp> if the location has the form
675      <var>[USER@]HOST:PATH</var> and <var>HOST</var> is a valid remote host,
676      <samp>fs</samp> otherwise)</p>
677
678      <p><dfn>namespace</dfn>: A space-delimited list of project IDs.</p>
679
680      <p><dfn>value</dfn>: A location, which can be a full path in the file
681      system, or a relative location of the project root.</p>
682
683      <p><dfn>example</dfn>:</p>
684      <pre>
685extract.location[um] = trunk@vn7.5
686extract.location[gen ops var] = trunk@HEAD
687</pre>
688    </dd>
689
690    <dt id="make.extract.location.diff">extract.location{diff}</dt>
691
692    <dd>
693      <p><dfn>description</dfn>: Specifies the location(s) of one or more diff
694      source trees of a project. It is OK to add more diff source trees in an
695      inheriting extract.</p>
696
697      <p><dfn>modifier</dfn>: <var>type</var>: -as above-</p>
698
699      <p><dfn>namespace</dfn>: A project ID.</p>
700
701      <p><dfn>value</dfn>: A space-delimited list of locations. A location can
702      be a full path in the file system, or a relative location of the project
703      root.</p>
704
705      <p><dfn>example</dfn>:</p>
706      <pre>
707extract.location{diff}[gen] = \
708    branches/dev/fred/r12345_678 \
709    branches/dev/free/r12345_678@123
710</pre>
711    </dd>
712
713    <dt id="make.extract.location.primary">extract.location{primary}</dt>
714
715    <dd>
716      <p><dfn>description</dfn>: Specifies the project locations for an
717      extract, if they are not already defined in the keyword
718      configuration.</p>
719
720      <p><dfn>modifier</dfn>: <var>type</var>: -as above-</p>
721
722      <p><dfn>namespace</dfn>: A project ID.</p>
723
724      <p><dfn>value</dfn>: A project location. The location can be a path in
725      the file system, a Subversion URL or a FCM keyword pointing to a
726      Subversion URL.</p>
727
728      <p><dfn>example</dfn>:</p>
729      <pre>
730extract.location{primary}[egg] = svn://server2/egg
731extract.location{primary,type:svn}[foo] = http://server1/foo
732</pre>
733    </dd>
734
735    <dt id="make.extract.path-excl">extract.path-excl / <span id=
736    "make.extract.path-incl">extract.path-incl</span></dt>
737
738    <dd>
739      <p><dfn>description</dfn>: Specifies the paths in a project tree to
740      exclude/include. (A path-incl takes precedence over a path-excl
741      declaration.)</p>
742
743      <p><dfn>namespace</dfn>: A space-delimited list of project IDs.</p>
744
745      <p><dfn>value</dfn>: A space-delimited list of paths in a project
746      tree.</p>
747
748      <p><dfn>example</dfn>:</p>
749      <pre>
750extract.path-excl[foo] = / # everything
751extract.path-incl[foo] = bin lib src/code
752</pre>
753    </dd>
754
755    <dt id="make.extract.path-root">extract.path-root</dt>
756
757    <dd>
758      <p><dfn>description</dfn>: Specifies the root paths in the source trees
759      of the projects to be extracted. By default, the root path is the
760      root of a source tree. If this setting is specified, the system will only
761      extract source files under the specified root path. The system will also
762      adjust the name-space of each source file to be relative to the specified
763      root path. The <code>extract.path-excl</code> and
764      <code>extract.path-incl</code> declarations will apply from the level of
765      the specified root path.</p>
766
767      <p><dfn>namespace</dfn>: A space-delimited list of project IDs.</p>
768
769      <p><dfn>value</dfn>: A relative path in the project source trees.</p>
770
771      <p><dfn>example</dfn>:</p>
772      <pre>
773extract.path-root[gen] = src/code
774</pre>
775    </dd>
776
777    <dt id="make.extract.prop">extract.prop</dt>
778
779    <dd>
780      <p><dfn>description</dfn>: Sets or modifies a property.</p>
781
782      <p><dfn>modifier</dfn>: <var>diff3</var>: The shell command to perform a
783      3-way merge. If not specified, use the <a href="#external.diff3">diff3</a>
784      setting of the FCM external configuration.</p>
785
786      <p><dfn>modifier</dfn>: <var>diff3.flags</var>: The options used by the
787      3-way merge shell command. If not specified, use the <a href=
788      "#external.diff3.flags">diff3.flags</a> setting of the FCM external
789      configuration.</p>
790
791      <p><dfn>value</dfn>: The value of the property.</p>
792
793      <p><dfn>example</dfn>:</p>
794      <pre>
795extract.prop{diff3} = diff3
796extract.prop{diff3.flags} = -E -m
797</pre>
798    </dd>
799  </dl>
800
801  <h3 id="make.mirror">FCM Make Configuration: Mirror</h3>
802
803  <p>All declarations are prefixed with <samp>mirror.*</samp>. Where
804  appropriate, replace the leading <samp>mirror</samp> with the appropriate
805  ID.</p>
806
807  <dl>
808    <dt id="make.mirror.target">mirror.target</dt>
809
810    <dd>
811      <p><dfn>description</dfn>: Specifies the mirror target. This setting is
812      not inherited.</p>
813
814      <p><dfn>value</dfn>: The mirror target.</p>
815
816      <p><dfn>example</dfn>:</p>
817      <pre>
818mirror.target = fred@server:/path/of/dest
819
820# Or if the current user ID is "fred"
821# Or if the user ID for "server" is configured under "~/.ssh/config"
822mirror.target = server:/path/of/dest
823
824# Or if mirroring to a path accessible only by user ID "bob"
825mirror.target = bob@localhost:/path/of/dest
826
827# Or if the current user ID is "fred" and local host is "server"
828mirror.target = /path/of/dest
829</pre>
830    </dd>
831
832    <dt id="make.mirror.prop">mirror.prop</dt>
833
834    <dd>
835      <p><dfn>description</dfn>: Sets or modifies a property.</p>
836
837      <p><dfn>modifier</dfn>: See below.</p>
838
839      <p><dfn>value</dfn>: The value of the property.</p>
840
841      <p><dfn>example</dfn>:</p>
842      <pre>
843mirror.prop{rsync} = cnysr
844</pre>
845    </dd>
846  </dl>
847
848  <p>The following is a list of properties accepted by the
849  <code>mirror.prop</code> declaration:</p>
850
851  <dl>
852    <dt id="make.mirror.prop.config-file.name">config-file.name</dt>
853
854    <dd>The context name to be included in the generated configuration file in
855    the mirror destination.</dd>
856
857    <dt id="make.mirror.prop.config-file.steps">config-file.steps</dt>
858
859    <dd>The steps to be included in the generated configuration file in the
860    mirror destination.</dd>
861
862    <dt id="make.mirror.prop.no-config-file">no-config-file</dt>
863
864    <dd>If specified, do not generate a <samp>fcm-make.cfg</samp> in the mirror
865    target.</dd>
866
867    <dt id="make.mirror.prop.ssh">ssh</dt>
868
869    <dd>The secure remote shell command to execute commands on a remote machine.
870    If not specified, use the <a href= "#external.ssh">ssh</a> setting of the
871    FCM external configuration.</dd>
872
873    <dt id="make.mirror.prop.ssh.flags">ssh.flags</dt>
874
875    <dd>The flags used by the remote shell command to execute commands on a
876    remote machine. If not specified, use the <a href=
877    "#external.ssh.flags">ssh.flags</a> setting of the FCM external
878    configuration.</dd>
879
880    <dt id="make.mirror.prop.rsync">rsync</dt>
881
882    <dd>The <code>rsync</code> command. If not specified, use the <a href=
883    "#external.rsync">rsync</a> setting of the FCM external configuration.</dd>
884
885    <dt id="make.mirror.prop.rsync.flags">rsync.flags</dt>
886
887    <dd>The options used by the <code>rsync</code> command. If not specified,
888    use the <a href= "#external.rsync.flags">rsync.flags</a> setting of the FCM
889    external configuration.</dd>
890  </dl>
891
892  <h3 id="make.build">FCM Make Configuration: Build</h3>
893
894  <p>All declarations are prefixed with <samp>build.*</samp>. Where
895  appropriate, replace the leading <samp>build</samp> with the appropriate
896  ID.</p>
897
898  <dl>
899    <dt id="make.build.source">build.source</dt>
900
901    <dd>
902      <p><dfn>description</dfn>: Specifies one or more source files and/or
903      directories.</p>
904
905      <p><dfn>namespace</dfn>: Optional. Specifies the namespace of the
906      specified paths.</p>
907
908      <p><dfn>value</dfn>: A list of space-delimited file system paths.</p>
909
910      <p><dfn>example</dfn>:</p>
911      <pre>
912build.source[foo] = $HOME/foo $DATADIR/foo
913</pre>
914    </dd>
915
916    <dt id="make.build.ns-excl">build.ns-excl / <span id=
917    "make.build.ns-incl">build.ns-incl</span></dt>
918
919    <dd>
920      <p><dfn>description</dfn>: Specifies the name-spaces in the source tree
921      to exclude/include. (A <code>build.ns-incl</code> takes precedence over a
922      <code>build.ns-excl</code> declaration.)</p>
923
924      <p><dfn>value</dfn>: A list of space-delimited items. Each item is a
925      name-space to exclude/include.</p>
926
927      <p><dfn>example</dfn>:</p>
928      <pre>
929build.ns-excl = / # exclude everything
930build.ns-incl = foo bar/baz # include items in these name-spaces
931</pre>
932    </dd>
933
934    <dt id="make.build.target">build.target</dt>
935
936    <dd>
937      <p><dfn>description</dfn>: Selects targets to build according to their
938      keys, categories and tasks.</p>
939
940      <p><dfn>modifier</dfn>: <samp>key</samp> (default if no modifier
941      specified), <samp>category</samp> or <samp>task</samp></p>
942
943      <p><dfn>namespace</dfn>: Not allowed if modifier is <samp>key</samp>.
944      Optional if modifier is <samp>category</samp> or <samp>task</samp>. If
945      specified, setting only applies to given name-spaces. Otherwise, setting
946      applies to all name-spaces.</p>
947
948      <p><dfn>value</dfn>: A list of space-delimited items (according to the
949      modifier).</p>
950
951      <p><dfn>example</dfn>:</p>
952      <pre>
953build.target{category}[etc/namelists etc/configs] = etc
954build.target{category}[src/hello src/greet src/world] = bin lib
955build.target{task}[src/public] = archive install
956build.target = egg.sh mince.py
957</pre>
958    </dd>
959
960    <dt id="make.build.target-rename">build.target-rename</dt>
961
962    <dd>
963      <p><dfn>description</dfn>: Rename targets.</p>
964
965      <p><dfn>value</dfn>: A list of space-delimited items. Each item should be
966      the (automatic) key of a target, followed by a colon and its preferred
967      key.</p>
968
969      <p><dfn>example</dfn>:</p>
970      <pre>
971build.target-rename = hello.exe:hello
972</pre>
973    </dd>
974
975    <dt id="make.build.prop">build.prop</dt>
976
977    <dd>
978      <p><dfn>description</dfn>: Sets or modifies a property.</p>
979
980      <p><dfn>modifier</dfn>: The name of one (or more) property. See
981      below.</p>
982
983      <p><dfn>namespace</dfn>: Optional. A list of space-delimited namespaces to
984      which this setting applies. The namespaces can be target names, when used
985      with target properties (dependency properties are regarded as source
986      properties), or the hierarchical namespaces of source files. If not
987      specified, the setting applies to the global/root namespace. N.B. Not all
988      build properties accept a namespace. See below for detail.</p>
989
990      <p><dfn>value</dfn>: The value of the property.</p>
991
992      <p><dfn>example</dfn>:</p>
993      <pre>
994build.prop{fc} = gfortran
995build.prop{cc.flags,fc.flags} = -C -g
996build.prop{fc.flags}[foo/bar] = -C -g -W
997build.prop{fc.flags}[egg ham bacon] = -C -W
998build.prop{fc.flag-define} = -D%s
999build.prop{cc.defs,fc.defs}[gen] = LOWERCASE UNDERSCORE
1000build.prop{fc.libs}[myprog.exe] = netcdf grib
1001</pre>
1002    </dd>
1003  </dl>
1004
1005  <p>The following is a list of properties accepted by the
1006  <code>build.prop</code> declaration. The default value is an empty string
1007  unless given otherwise. Properties that do not accept a namespace are marked
1008  with an asterisk (*).</p>
1009
1010  <dl>
1011    <dt id="make.build.prop.ar">ar</dt>
1012
1013    <dd>The archive command. (default=<samp>ar</samp>)</dd>
1014
1015    <dt id="make.build.prop.ar.flags">ar.flags</dt>
1016
1017    <dd>If a list of values is specified, the system will not inherit sources
1018    with the name-spaces matching the specified values. If the value is a
1019    <samp>*</samp>, the system will not inherit any sources.</dd>
1020    <dd>The options used by the archive command. (default=<samp>rs</samp>)</dd>
1021
1022    <dt id=
1023    "make.build.prop.archive-ok-target-category">archive-ok-target-category
1024    *</dt>
1025
1026    <dd>If <code>fcm make</code> is invoked with the <code>--archive</code>
1027    option, sub-directories in categories containing intermediate build files
1028    will be put into TAR-GZIP files. E.g. with the default setting,
1029    <samp>include/</samp> and <samp>o/</samp> will become
1030    <samp>include.tar.gz</samp> and <samp>o.tar.gz</samp> respectively.
1031    (default=<samp>include o</samp>)</dd>
1032
1033    <dt id="make.build.prop.cc">cc</dt>
1034
1035    <dd>The C compiler and linker. (default=<samp>gcc</samp>)</dd>
1036
1037    <dt id="make.build.prop.cc.defs">cc.defs</dt>
1038
1039    <dd>The C compiler will pre-define each word in this setting as a
1040    macro.</dd>
1041
1042    <dt id="make.build.prop.cc.flags">cc.flags</dt>
1043
1044    <dd>The options used by the C compiler at compile time.</dd>
1045
1046    <dt id="make.build.prop.cc.flags-ld">cc.flags-ld</dt>
1047
1048    <dd>The options used by the C compiler at link time.</dd>
1049
1050    <dt id="make.build.prop.cc.flag-compile">cc.flag-compile</dt>
1051
1052    <dd>The option used by the C compiler to suppress the linking stage.
1053    (default=<samp>-c</samp>)</dd>
1054
1055    <dt id="make.build.prop.cc.flag-define">cc.flag-define</dt>
1056
1057    <dd>The option used by the C compiler to define a macro.
1058    (default=<samp>-D%s</samp>)</dd>
1059
1060    <dt id="make.build.prop.cc.flag-include">cc.flag-include</dt>
1061
1062    <dd>The option used by the C compiler to specify an include search
1063    path. (default=<samp>-I%s</samp>)</dd>
1064
1065    <dt id="make.build.prop.cc.flag-lib">cc.flag-lib</dt>
1066
1067    <dd>The option used by the C compiler at link time to specify a
1068    library. (default=<samp>-l%s</samp>)</dd>
1069
1070    <dt id="make.build.prop.cc.flag-lib-path">cc.flag-lib-path</dt>
1071
1072    <dd>The option used by the C compiler at link time to specify a library
1073    search path. (default=<samp>-L%s</samp>)</dd>
1074
1075    <dt id="make.build.prop.cc.flag-omp">cc.flag-omp</dt>
1076
1077    <dd>The option used by the C compiler to switch on OpenMP.</dd>
1078
1079    <dt id="make.build.prop.cc.flag-output">cc.flag-output</dt>
1080
1081    <dd>The option used by the C compiler to specify the output file name.
1082    (default=<samp>-o%s</samp>)</dd>
1083
1084    <dt id="make.build.prop.cc.include-paths">cc.include-paths</dt>
1085
1086    <dd>The C compiler will add each directory in this setting as an include
1087    search path.</dd>
1088
1089    <dt id="make.build.prop.cc.libs">cc.libs</dt>
1090
1091    <dd>The C linker will add each item in this setting as a link
1092    library.</dd>
1093
1094    <dt id="make.build.prop.cc.lib-paths">cc.lib-paths</dt>
1095
1096    <dd>The C linker will add each directory in this setting as a library
1097    search path.</dd>
1098
1099    <dt id="make.build.prop.checksum-method">checksum-method</dt>
1100
1101    <dd>The checksum method to use to determine if the content of a file is
1102    changed or not. Either MD5 or one of the SHA algorithms supported by the
1103    Perl module <a href="http://perldoc.perl.org/Digest/SHA.html">Digest::SHA</a>
1104    can be used. (default=<samp>md5</samp>)</dd>
1105
1106    <dt id="make.build.prop.cxx">cxx</dt>
1107
1108    <dd>The C++ compiler and linker. (default=<samp>g++</samp>)</dd>
1109
1110    <dt id="make.build.prop.cxx.defs">cxx.defs</dt>
1111
1112    <dd>The C++ compiler will pre-define each word in this setting as a
1113    macro.</dd>
1114
1115    <dt id="make.build.prop.cxx.flags">cxx.flags</dt>
1116
1117    <dd>The options used by the C++ compiler at compile time.</dd>
1118
1119    <dt id="make.build.prop.cxx.flags-ld">cxx.flags-ld</dt>
1120
1121    <dd>The options used by the C++ compiler at link time.</dd>
1122
1123    <dt id="make.build.prop.cxx.flag-compile">cxx.flag-compile</dt>
1124
1125    <dd>The option used by the C++ compiler to suppress the linking stage.
1126    (default=<samp>-c</samp>)</dd>
1127
1128    <dt id="make.build.prop.cxx.flag-define">cxx.flag-define</dt>
1129
1130    <dd>The option used by the C++ compiler to define a macro.
1131    (default=<samp>-D%s</samp>)</dd>
1132
1133    <dt id="make.build.prop.cxx.flag-include">cxx.flag-include</dt>
1134
1135    <dd>The option used by the C++ compiler to specify an include search
1136    path. (default=<samp>-I%s</samp>)</dd>
1137
1138    <dt id="make.build.prop.cxx.flag-lib">cxx.flag-lib</dt>
1139
1140    <dd>The option used by the C++ compiler at link time to specify a
1141    library. (default=<samp>-l%s</samp>)</dd>
1142
1143    <dt id="make.build.prop.cxx.flag-lib-path">cxx.flag-lib-path</dt>
1144
1145    <dd>The option used by the C++ compiler at link time to specify a library
1146    search path. (default=<samp>-L%s</samp>)</dd>
1147
1148    <dt id="make.build.prop.cxx.flag-omp">cxx.flag-omp</dt>
1149
1150    <dd>The option used by the C++ compiler to switch on OpenMP.</dd>
1151
1152    <dt id="make.build.prop.cxx.flag-output">cxx.flag-output</dt>
1153
1154    <dd>The option used by the C++ compiler to specify the output file name.
1155    (default=<samp>-o%s</samp>)</dd>
1156
1157    <dt id="make.build.prop.cxx.include-paths">cxx.include-paths</dt>
1158
1159    <dd>The C++ compiler will add each directory in this setting as an include
1160    search path.</dd>
1161
1162    <dt id="make.build.prop.cxx.libs">cxx.libs</dt>
1163
1164    <dd>The C++ linker will add each item in this setting as a link
1165    library.</dd>
1166
1167    <dt id="make.build.prop.cxx.lib-paths">cxx.lib-paths</dt>
1168
1169    <dd>The C++ linker will add each directory in this setting as a library
1170    search path.</dd>
1171
1172    <dt id="make.build.prop.dep.bin">dep.bin</dt>
1173
1174    <dd>Specifies a list of manual dependencies on external executable
1175    commands.</dd>
1176
1177    <dt id="make.build.prop.dep.f.module">dep.f.module</dt>
1178
1179    <dd>Specifies a list of manual Fortran module dependencies. Note: This
1180    modifier does not work if the name-space is specified using a target
1181    name.</dd>
1182
1183    <dt id="make.build.prop.dep.include">dep.include</dt>
1184
1185    <dd>Specifies a list of manual include dependencies.</dd>
1186
1187    <dt id="make.build.prop.dep.o">dep.o</dt>
1188
1189    <dd>Specifies a list of manual object dependencies.</dd>
1190
1191    <dt id="make.build.prop.dep.o.special">dep.o.special</dt>
1192
1193    <dd>Specifies a list of manual object dependencies, which must appear on
1194    the command line of the linker, (e.g. an object containing a Fortran
1195    blockdata program unit).</dd>
1196
1197    <dt id="make.build.prop.fc">fc</dt>
1198
1199    <dd>The Fortran compiler and linker. (default=<samp>gfortran</samp>)</dd>
1200
1201    <dt id="make.build.prop.fc.defs">fc.defs</dt>
1202
1203    <dd>The Fortran compiler will pre-define each word in this setting as a
1204    macro.</dd>
1205
1206    <dt id="make.build.prop.fc.flags">fc.flags</dt>
1207
1208    <dd>The options used by the Fortran compiler at compile time.</dd>
1209
1210    <dt id="make.build.prop.fc.flags-ld">fc.flags-ld</dt>
1211
1212    <dd>The options used by the Fortran compiler at link time.</dd>
1213
1214    <dt id="make.build.prop.fc.flag-compile">fc.flag-compile</dt>
1215
1216    <dd>The option used by the Fortran compiler to suppress the linking stage.
1217    (default=<samp>-c</samp>)</dd>
1218
1219    <dt id="make.build.prop.fc.flag-define">fc.flag-define</dt>
1220
1221    <dd>The option used by the Fortran compiler to define a macro.
1222    (default=<samp>-D%s</samp>)</dd>
1223
1224    <dt id="make.build.prop.fc.flag-include">fc.flag-include</dt>
1225
1226    <dd>The option used by the Fortran compiler to specify an include search
1227    path. (default=<samp>-I%s</samp>)</dd>
1228
1229    <dt id="make.build.prop.fc.flag-lib">fc.flag-lib</dt>
1230
1231    <dd>The option used by the Fortran compiler at link time to specify a
1232    library. (default=<samp>-l%s</samp>)</dd>
1233
1234    <dt id="make.build.prop.fc.flag-lib-path">fc.flag-lib-path</dt>
1235
1236    <dd>The option used by the Fortran compiler at link time to specify a
1237    library search path. (default=<samp>-L%s</samp>)</dd>
1238
1239    <dt id="make.build.prop.fc.flag-module">fc.flag-module</dt>
1240
1241    <dd>The option used by the Fortran compiler to specify a module search
1242    path.</dd>
1243
1244    <dt id="make.build.prop.fc.flag-omp">fc.flag-omp</dt>
1245
1246    <dd>The option used by the Fortran compiler to switch on OpenMP. If
1247    specified, the build system will treat <code>USE</code> and
1248    <code>INCLUDE</code> statements that are protected by <code>!$ </code>
1249    sentinels as normal dependency statements.</dd>
1250
1251    <dt id="make.build.prop.fc.flag-output">fc.flag-output</dt>
1252
1253    <dd>The option used by the Fortran compiler to specify the output file
1254    name. (default=<samp>-o%s</samp>)</dd>
1255
1256    <dt id="make.build.prop.fc.include-paths">fc.include-paths</dt>
1257
1258    <dd>The Fortran compiler will add each directory in this setting as an
1259    include search path.</dd>
1260
1261    <dt id="make.build.prop.fc.libs">fc.libs</dt>
1262
1263    <dd>The Fortran linker will add each item in this setting as a link
1264    library.</dd>
1265
1266    <dt id="make.build.prop.fc.lib-paths">fc.lib-paths</dt>
1267
1268    <dd>The Fortran linker will add each directory in this setting as a library
1269    search path.</dd>
1270
1271    <dt id="make.build.prop.file-ext.a">file-ext.a *</dt>
1272
1273    <dd>Specifies the extension of an object archive file.
1274    (default=<samp>.a</samp>)</dd>
1275
1276    <dt id="make.build.prop.file-ext.bin">file-ext.bin *</dt>
1277
1278    <dd>Specifies the extension of a binary executable file.
1279    (default=<samp>.exe</samp>)</dd>
1280
1281    <dt id="make.build.prop.file-ext.c">file-ext.c *</dt>
1282
1283    <dd>Specifies the extensions of a C source file.
1284    (default=<samp>.c .i .m .mi</samp>)</dd>
1285
1286    <dt id="make.build.prop.file-ext.cxx">file-ext.cxx *</dt>
1287
1288    <dd>Specifies the extensions of a C++ source file.
1289    (default=<samp>.cc .cp .cxx .cpp .CPP .c++ .C .mm .M .mii</samp>)</dd>
1290
1291    <dt id="make.build.prop.file-ext.fortran">file-ext.fortran *</dt>
1292
1293    <dd>Specifies the extensions of a Fortran source file. (default=<samp>.F
1294    .FOR .FTN .F90 .F95 .f .for .ftn .f90 .f95 .inc</samp>)</dd>
1295
1296    <dt id="make.build.prop.file-ext.f90-interface">file-ext.f90-interface
1297    *</dt>
1298
1299    <dd>Specifies the extension of a Fortran interface file.
1300    (default=<samp>.interface</samp>)</dd>
1301
1302    <dt id="make.build.prop.file-ext.f90-mod">file-ext.f90-mod *</dt>
1303
1304    <dd>Specifies the extension of a compiled Fortran module file.
1305    (default=<samp>.mod</samp>)</dd>
1306
1307    <dt id="make.build.prop.file-ext.h">file-ext.h *</dt>
1308
1309    <dd>Specifies the extensions of a C/C++ header file.
1310    (default=<samp>.h</samp>)</dd>
1311
1312    <dt id="make.build.prop.file-ext.o">file-ext.o *</dt>
1313
1314    <dd>Specifies the extension of a compiled object file.
1315    (default=<samp>.o</samp>)</dd>
1316
1317    <dt id="make.build.prop.file-ext.script">file-ext.script *</dt>
1318
1319    <dd>Specifies the extensions of script files.</dd>
1320
1321    <dt id="make.build.prop.file-name-option.f90-mod">file-name-option.f90-mod
1322    *</dt>
1323
1324    <dd>Specifies other options for naming a compiled Fortran module file.
1325    Accepts <samp>case=upper</samp> or <samp>case=lower</samp> (default).</dd>
1326
1327    <dt id="make.build.prop.file-pat.script">file-pat.script *</dt>
1328
1329    <dd>Specifies a regular expression for matching the name of script
1330    files.</dd>
1331
1332    <dt id="make.build.prop.ignore-missing-dep-ns">ignore-missing-dep-ns *</dt>
1333
1334    <dd>Specifies a list of source name-spaces, in which targets can ignore
1335    missing dependencies.</dd>
1336
1337    <dt id="make.build.prop.keep-lib-o">keep-lib-o</dt>
1338
1339    <dd>Relevant when linking a binary executable and <a href=
1340    "#make.build.prop.link-without-ar">link-without-ar</a> is not set to
1341    <kbd>true</kbd>. If <kbd>true</kbd>, create and keep the dependent object
1342    library as <samp>lib/libNAME.a</samp>, where <var>NAME</var> is the root
1343    name of the executable. In the absence of this setting, the behaviour is to
1344    create the dependent object library in a temporary directory, which is
1345    removed after the linker command is completed.</dd>
1346
1347    <dt id="make.build.prop.ld">ld</dt>
1348
1349    <dd>The linker command. If not specified, use the compiler of the source
1350    file.</dd>
1351
1352    <dt id="make.build.prop.link-without-ar">link-without-ar</dt>
1353
1354    <dd>Relevant when linking a binary executable. If <kbd>true</kbd>, do not
1355    create the dependent object library when linking. Instead, locations of the
1356    dependent objects will be specified on the command line of the linker. In
1357    the absence of this setting, the behaviour is to create the dependent object
1358    library in a temporary directory, with the location of the object library
1359    specified using the relevant options of the linker.</dd>
1360
1361    <dt id="make.build.prop.no-dep.bin">no-dep.bin</dt>
1362
1363    <dd>Switches off a list of automatic dependencies on external executable.
1364    If the value is a <samp>*</samp>, switches off all automatic external
1365    executable dependencies.</dd>
1366
1367    <dt id="make.build.prop.no-dep.f.module">no-dep.f.module</dt>
1368
1369    <dd>Switches off a list of automatic Fortran module dependencies. If the
1370    value is a <samp>*</samp>, switches off all automatic Fortran module
1371    dependencies. Note: This modifier does not work if the name-space is
1372    specified using a target name.</dd>
1373
1374    <dt id="make.build.prop.no-dep.include">no-dep.include</dt>
1375
1376    <dd>Switches off a list of automatic include dependencies. If the value is
1377    a <samp>*</samp>, switches off all automatic include dependencies.</dd>
1378
1379    <dt id="make.build.prop.no-dep.o">no-dep.o</dt>
1380
1381    <dd>Switches off a list of automatic object dependencies. If the value is a
1382    <samp>*</samp>, switches off all automatic object dependencies.</dd>
1383
1384    <dt id="make.build.prop.no-inherit-source">no-inherit-source *</dt>
1385
1386    <dd>If a list of values is specified, the system will not inherit sources
1387    with the name-spaces matching the specified values. If the value is a
1388    <samp>*</samp>, the system will not inherit any sources.</dd>
1389
1390    <dt id="make.build.prop.no-inherit-target-category">
1391    no-inherit-target-category *</dt>
1392
1393    <dd>If a list of values is specified, the system will not inherit a target
1394    in a category matching a specified value. (default=<samp>bin etc
1395    lib</samp>)</dd>
1396
1397    <dt id="make.build.prop.no-step-source">no-step-source *</dt>
1398
1399    <dd>If a list of make steps is specified, the system will not search for
1400    source files from the specified make steps.</dd>
1401
1402    <dt id="make.build.prop.ns-dep.o">ns-dep.o</dt>
1403
1404    <dd>Specifies a list of link-time object dependencies on all objects in the
1405    list of name-spaces in the value.</dd>
1406  </dl>
1407
1408  <h3 id="make.preprocess">FCM Make Configuration: Preprocess</h3>
1409
1410  <p>The preprocess system uses the same declarations as the build system (see
1411  <a href="#make.build">FCM Make Configuration: Build</a>), although their
1412  prefixes should be replaced with <samp>preprocess.*</samp> or the appropriate
1413  step ID. The following is a list of modifiers accepted by the
1414  <code>preprocess.prop</code> declaration. The default value of a property is
1415  an empty string unless given otherwise. Properties that do not accept a
1416  namespace are marked with an asterisk (*).</p>
1417
1418  <dl>
1419    <dt id="make.preprocess.prop.cpp">cpp</dt>
1420
1421    <dd>The command of the C/C++ pre-processor. (default=<samp>cpp</samp>)</dd>
1422
1423    <dt id="make.preprocess.prop.cpp.defs">cpp.defs</dt>
1424
1425    <dd>The C/C++ pre-processor will pre-define each word in this setting as a
1426    macro.</dd>
1427
1428    <dt id="make.preprocess.prop.cpp.flags">cpp.flags</dt>
1429
1430    <dd>The options used by the C/C++ pre-processor.</dd>
1431
1432    <dt id="make.preprocess.prop.cpp.flag-define">cpp.flag-define</dt>
1433
1434    <dd>The option used by the C/C++ pre-processor to define a macro.
1435    (default=<samp>-D%s</samp>)</dd>
1436
1437    <dt id="make.preprocess.prop.cpp.flag-include">cpp.flag-include</dt>
1438
1439    <dd>The option used by the C/C++ pre-processor to specify the include
1440    search path. (default=<samp>-I%s</samp>)</dd>
1441
1442    <dt id="make.preprocess.prop.cpp.include-paths">cpp.include-paths</dt>
1443
1444    <dd>The C/C++ preprocessor will add each directory in this setting as an
1445    include search path.</dd>
1446
1447    <dt id="make.preprocess.prop.dep.include">dep.include</dt>
1448
1449    <dd>Specifies a list of manual include dependencies.</dd>
1450
1451    <dt id="make.preprocess.prop.file-ext.cpp">file-ext.cpp *</dt>
1452
1453    <dd>Specifies the extensions of C/C++ source file.
1454    (default=<samp>.c .m .cc .cp .cxx .cpp .CPP .c++ .C .mm .M</samp>)</dd>
1455
1456    <dt id="make.preprocess.prop.file-ext.fpp">file-ext.fpp *</dt>
1457
1458    <dd>Specifies the extensions of Fortran source file requiring
1459    preprocessing. (default=<samp>.F .FOR .FTN .F90 .F95</samp>)</dd>
1460
1461    <dt id="make.preprocess.prop.file-ext.h">file-ext.h *</dt>
1462
1463    <dd>Specifies the extensions of a C/C++ header file.
1464    (default=<samp>.h</samp>)</dd>
1465
1466    <dt id="make.preprocess.prop.fpp">fpp</dt>
1467
1468    <dd>The command of the Fortran pre-processor.
1469    (default=<samp>cpp</samp>)</dd>
1470
1471    <dt id="make.preprocess.prop.fpp.defs">fpp.defs</dt>
1472
1473    <dd>The Fortran pre-processor will pre-define each word in this setting as
1474    a macro.</dd>
1475
1476    <dt id="make.preprocess.prop.fpp.flags">fpp.flags</dt>
1477
1478    <dd>The options used by the Fortran pre-processor. (default=<samp>-P
1479    -traditional</samp>)</dd>
1480
1481    <dt id="make.preprocess.prop.fpp.flag-define">fpp.flag-define</dt>
1482
1483    <dd>The option used by the Fortran pre-processor to define a macro.
1484    (default=<samp>-D%s</samp>)</dd>
1485
1486    <dt id="make.preprocess.prop.fpp.flag-include">fpp.flag-include</dt>
1487
1488    <dd>The option used by the Fortran pre-processor to specify the include
1489    search path. (default=<samp>-I%s</samp>)</dd>
1490
1491    <dt id="make.preprocess.prop.fpp.include-paths">fpp.include-paths</dt>
1492
1493    <dd>The Fortran preprocessor will add each directory in this setting as an
1494    include search path.</dd>
1495
1496    <dt id="make.preprocess.prop.no-dep.include">no-dep.include</dt>
1497
1498    <dd>Switches off a list of automatic include dependencies. If the value is
1499    a <samp>*</samp>, it switches off all automatic include dependencies.</dd>
1500
1501    <dt id="make.preprocess.prop.no-inherit-source">no-inherit-source *</dt>
1502
1503    <dd>Same as the build property of the same name.</dd>
1504
1505    <dt id="make.preprocess.prop.no-inherit-target-category">
1506    no-inherit-target-category *</dt>
1507
1508    <dd>Same as the build property of the same name.</dd>
1509
1510    <dt id="make.preprocess.prop.no-step-source">no-step-source *</dt>
1511
1512    <dd>Same as the build property of the same name.</dd>
1513  </dl>
1514
1515  </div>
1516  </div>
1517  </div>
1518
1519  <hr/>
1520  <div class="container-fluid text-center">
1521    <div class="row"><div class="col-md-12">
1522    <address><small>
1523      Copyright &copy; 2006-2021 British Crown (Met Office) &amp; Contributors.
1524      <a href="http://www.metoffice.gov.uk">Met Office</a>.
1525      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
1526      This document is released under the British <a href=
1527      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
1528      "license">Open Government Licence</a>.<br />
1529    </small></address>
1530    </div></div>
1531  </div>
1532
1533  <script type="text/javascript" src="../etc/jquery.min.js"></script>
1534  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
1535  <script type="text/javascript" src="../etc/fcm.js"></script>
1536  <script type="text/javascript" src="../etc/fcm-version.js"></script>
1537</body>
1538</html>
Note: See TracBrowser for help on using the repository browser.