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

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.

build.html in vendors/doc/user_guide – NEMO

Context Navigation

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

Last change on this file since 10669 was 10669, checked in by nicolasmartin, 5 years ago
Import latest FCM release from Github into the repository for testing
File size: 72.8 KB

Line
1	<!DOCTYPE html>
2	<html>
3	<head>
4	<title>FCM: User Guide: Annex: The FCM 1 Build System</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: The FCM 1 Build System</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><em>The FCM 1 build system is deprecated. The documentation for the current
40	build system can be found at <a href="make.html">FCM Make</a>.</em></p>
41
42	<p>The build system analyses the directory tree containing a set of source
43	code, processes the configuration, and invokes <code>make</code> to
44	compile/build the source code into the project executables. In this chapter,
45	we shall use many examples to explain how to use the build system. At the end
46	of this chapter, you should be able to use the build system, either by
47	defining the build configuration file directly or by using the extract system
48	to generate a suitable build configuration file.</p>
49
50	<h2 id="command">The Build Command</h2>
51
52	<p>To invoke the build system, simply issue the command:</p>
53	<pre>
54	fcm build
55	</pre>
56
57	<p>By default, the build system searches for a build configuration file
58	<samp>bld.cfg</samp> in <samp>$PWD</samp> and then <samp>$PWD/cfg</samp>. If
59	a build configuration file is not found in these directories, the command
60	fails with an error. If a build configuration file is found, the system will
61	use the configuration specified in the file to perform the build. If you use
62	the extract system to extract your source tree, a build configuration should
63	be written for you automatically at the <samp>cfg/</samp> sub-directory of
64	the destination root directory.</p>
65
66	<p>If the root directory of the build does not exist, the system performs a
67	new full build at this directory. If a previous build already exists at this
68	directory, the system performs an incremental build. If a full (fresh) build
69	is required for whatever reason, you can invoke the build system using the
70	<code>-f</code> option, (i.e. the command becomes <code>fcm build -f</code>).
71	If you simply want to remove all the items generated by a previous build in
72	the destination, you can invoke the build system using the
73	<code>--clean</code> option.</p>
74
75	<p>The build system uses GNU <code>make</code> to perform the majority of the
76	build. GNU <code>make</code> has a <code>-j jobs</code> option to specify the
77	number of <var>jobs</var> to run simultaneously. Invoking the build system
78	with the same option triggers this option when the build system invokes the
79	<code>make</code> command. The argument to the option <var>jobs</var> must be
80	an integer. The default is <samp>1</samp>. For example, the command <code>fcm
81	build -j 4</code> will allow <code>make</code> to perform 4 jobs
82	simultaneously.</p>
83
84	<p>For further information on the build command, please see <a href=
85	"command_ref.html#fcm-build">FCM Command Reference > fcm build</a>.</p>
86
87	<h2 id="basic">Basic Features</h2>
88
89	<p>The build configuration file is the user interface of the build system. It
90	is a line based text file. You can create your own build configuration file
91	or you can use the extract system to create one for you. For a complete set
92	of build configuration file declarations, please refer to the <a href=
93	"annex_bld_cfg.html">Annex: Declarations in FCM build configuration
94	file</a>.</p>
95
96	<h3 id="basic_build">Basic build configuration</h3>
97
98	<p>Suppose we have a directory at <samp>$HOME/example</samp>. Its
99	sub-directory at <samp>$HOME/example/src</samp> contains a source tree to be
100	built. You may want to have a build configuration file
101	<samp>$HOME/example/cfg/bld.cfg</samp>, which may contain:</p>
102	<pre id="example_1">
103	# Example 1
104	# ----------------------------------------------------------------------
105	cfg::type bld # line 1
106	cfg::version 1.0 # line 2
107
108	dest $HOME/example # line 4
109
110	target foo.exe bar.exe # line 6
111
112	tool::fc ifort # line 8
113	tool::fflags -O3 # line 9
114	tool::cc gcc # line 10
115	tool::cflags -O3 # line 11
116
117	tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
118	</pre>
119
120	<p>Here is an explanation of what each line does:</p>
121
122	<ul>
123	<li><dfn>line 1</dfn>: the label <code>CFG::TYPE</code> declares the type
124	of the configuration file. The value <samp>bld</samp> tells the system that
125	it is a build configuration file.</li>
126
127	<li><dfn>line 2</dfn>: the label <code>CFG::VERSION</code> declares the
128	version of the build configuration file. The current default is
129	<samp>1.0</samp>. Although it is not currently used, if we have to change
130	the format of the configuration file at a later stage, we shall be able to
131	use this number to determine whether we are reading a file with an older
132	format or one with a newer format.</li>
133
134	<li><dfn>line 4</dfn>: the label <code>DEST</code> declares the root
135	directory of the current build.</li>
136
137	<li><dfn>line 6</dfn>: the label <code>TARGET</code> declares a list of
138	<em>default</em> targets. The default targets of the current build will be
139	<samp>foo.exe</samp> and <samp>bar.exe</samp>.</li>
140
141	<li><dfn>line 8</dfn>: the label <code>TOOL::FC</code> declares the Fortran
142	compiler command.</li>
143
144	<li><dfn>line 9</dfn>: the label <code>TOOL::FFLAGS</code> declares the
145	options to be used when invoking the Fortran compiler command.</li>
146
147	<li><dfn>line 10</dfn>: the label <code>TOOL::CC</code> declares the C
148	compiler command.</li>
149
150	<li><dfn>line 11</dfn>: the label <code>TOOL::CFLAGS</code> declares the
151	options to be used when invoking the C compiler command.</li>
152
153	<li><dfn>line 13</dfn>: the label <code>TOOL::LDFLAGS</code> declares the
154	options to be used when invoking the linker command.</li>
155	</ul>
156
157	<p>When we invoke the build system, it reads the above configuration file. It
158	will go through various internal processes, such as dependency generations,
159	to obtain the required information to prepare the <samp>Makefile</samp> of
160	the build. (All of which will be described in later sections.) The
161	<samp>Makefile</samp> of the build will be placed at
162	<samp>$HOME/example/bld</samp>. The system will then invoke <code>make</code>
163	to build the targets specified in line 6, i.e. <samp>foo.exe</samp> and
164	<samp>bar.exe</samp> using the build tools specified between line 8 to line
165	13. On a successful build, the target executables will be sent to
166	<samp>$HOME/example/bin/</samp>. The build system also creates a shell script
167	called <samp>fcm_env.sh</samp> in <samp>$HOME/example/</samp>. If you source
168	the shell script, it will export your <var>PATH</var> environment variable to
169	search the <samp>$HOME/example/bin/</samp> directory for executables.</p>
170
171	<p>N.B. You may have noticed that the <code>-c</code> (compile to object file
172	only) option is missing from the compiler flags declarations. This is because
173	the option is inserted automatically by the build system, unless it is
174	already declared.</p>
175
176	<p>N.B. You can declare the linker using <code>TOOL::LD</code>. If it is not
177	specified, the default is to use the compiler command for the source file
178	containing the main program.</p>
179
180	<dl>
181	<dt>Note - declaration of source files for build</dt>
182
183	<dd>
184	<p>Source files do not have to reside in the <samp>src/</samp>
185	sub-directory of the build root directory. They can be anywhere, but you
186	will have to declare them using the label <code>SRC::<pcks></code>,
187	where <code><pcks></code> is the sub-package name in which the
188	source belongs. If a directory is specified then the build system
189	automatically searches for all source files in this directory. E.g.</p>
190	<pre>
191	# Declare a source in the sub-package "foo/bar"
192	src::foo/bar $HOME/foo/bar
193	</pre>
194
195	<p>By default, the build system searches the <samp>src/</samp>
196	sub-directory of the build root directory for source files. If all source
197	files are already declared explicitly, you can switch off the automatic
198	directory search by setting the <code>SEARCH_SRC</code> flag to false.
199	E.g.</p>
200	<pre>
201	search_src false
202	</pre>
203
204	<p>As mentioned in the previous chapter, the name of a sub-package
205	<pcks> provides a unique namespace for a file. The name of a
206	sub-package is a list of words delimited by a slash <code>/</code>. (The
207	system uses the double colons <code>::</code> and the double underscores
208	<code>__</code> internally. Please avoid using <code>::</code> and
209	<code>__</code> for naming your files and directories.)</p>
210
211	<p>Currently, the build system only supports non-space characters in the
212	package name, as the space character is used as a delimiter between the
213	declaration label and its value. If there are spaces in the path name to
214	a file or directory, you should explicity re-define the package name of
215	that path to a package name with no space using the above method.
216	However, we recommend that only non-space characters are used for naming
217	directories and files to make life simple.</p>
218
219	<p>In the build system, the sub-package name also provides an
220	<em>inheritance</em> relationship for sub-packages. For instance, we may
221	have a sub-package called <samp>foo/bar/egg</samp>, which belongs to the
222	sub-package <samp>foo/bar</samp>, which belongs to the package
223	<samp>foo</samp>.</p>
224
225	<ul>
226	<li>If we declare a global build tool, it applies to all packages.</li>
227
228	<li>If we declare a build tool for <samp>foo</samp>, it applies also to
229	the sub-package <samp>foo/bar</samp> and <samp>foo/bar/egg</samp>.</li>
230
231	<li>If we declare a build tool for <samp>foo/bar</samp>, it applies
232	also to <samp>foo/bar/egg</samp>, but not to other sub-packages in
233	<samp>foo</samp>.</li>
234	</ul>
235	</dd>
236	</dl>
237
238	<h3 id="basic_extract">Build configuration via the extract system</h3>
239
240	<p>As mentioned earlier, you can obtain a build configuration file through
241	the extract system. The following example is what you may have in your
242	extract configuration in order to obtain a similar configuration as <a href=
243	"#example_1">example 1</a>:</p>
244	<pre id="example_2">
245	# Example 2
246	# ----------------------------------------------------------------------
247	cfg::type ext # line 1
248	cfg::version 1.0 # line 2
249
250	dest $HOME/example # line 4
251
252	bld::target foo.exe bar.exe # line 6
253
254	bld::tool::fc ifort # line 8
255	bld::tool::fflags -O3 # line 9
256	bld::tool::cc gcc # line 10
257	bld::tool::cflags -O3 # line 11
258
259	bld::tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
260
261	# ... and other declarations for source locations ...
262	</pre>
263
264	<p>It is easy to note the similarities and differences between <a href=
265	"#example_1">example 1</a> and <a href="#example_2">example 2</a>. <a href=
266	"#example_2">Example 2</a> is an extract configuration file. It extracts to a
267	destination root directory that will become the root directory of the build.
268	Line 6 to line 13 are the same declarations, except that they are now
269	prefixed with <code>BLD::</code>. In an extract configuration file, any lines
270	prefixed with <code>BLD::</code> means that they are build configuration
271	setting. These lines are ignored by the extract system but are parsed down to
272	the output build configuration file, with the <code>BLD::</code> prefix
273	removed. (Note: the <code>BLD::</code> prefix is optional for declarations in
274	a build configuration file.)</p>
275
276	<p>N.B. If you use the extract system to mirror an extract to an alternate
277	location, the extract system will assume that the root directory of the
278	alternate destination is the root directory of the build, and that the build
279	will be carried out in that destination.</p>
280
281	<h3 id="basic_exename">Naming of executables</h3>
282
283	<p>If a source file called <samp>foo.f90</samp> contains a main program, the
284	default behaviour of the system is to name its executable
285	<samp>foo.exe</samp>. The root name of the executable is the same as the
286	original file name, but its file extension is replaced with
287	<samp>.exe</samp>. The output extension can be altered by re-registering the
288	extension for output EXE files. How this can be done will be discussed later
289	in the sub-section <a href="#advanced_file-type">File Type</a>.</p>
290
291	<p>If you need to alter the full name of the executable, you can use the
292	<code>EXE_NAME::</code> declaration. For example, the declaration:</p>
293	<pre>
294	bld::exe_name::foo bar
295	</pre>
296
297	<p>will rename the executable of <samp>foo.f90</samp> from
298	<samp>foo.exe</samp> to <samp>bar</samp>.</p>
299
300	<p>Note: the declaration label is <code>bld::exe_name::foo</code> (not
301	<code>bld::exe_name::foo.exe</code>) and the executable will be named
302	<samp>bar</samp> (not <samp>bar.exe</samp>).</p>
303
304	<h3 id="basic_flags">Setting the compiler flags</h3>
305
306	<p>As discussed in the first example, the compiler commands and their flags
307	can be set via the <code>TOOL::</code> declarations. A simple
308	<code>TOOL::FFLAGS</code> declaration, for example, alters the compiler
309	options for compiling all Fortran source files in the build. If you need to
310	alter the compiler options only for the source files in a particular
311	sub-package, it is possible to do so by adding the sub-package name to the
312	declaration label. For example, the declaration label
313	<code>TOOL::FFLAGS::foo/bar</code> will ensure that the declaration only
314	applies to the code in the sub-package <samp>foo/bar</samp>. You can even
315	make declarations down to the individual source file level. For example, the
316	declaration label <code>TOOL::FFLAGS::foo/bar/egg.f90</code> will ensure that
317	the declaration applies only for the file <samp>foo/bar/egg.f90</samp>.</p>
318
319	<p>N.B. Although the prefix <code>TOOL::</code> and the tool names are
320	case-insensitive, sub-package names are case sensitive in the declarations.
321	Internally, tool names are turned into uppercase, and the sub-package
322	delimiters are changed from the slash <code>/</code> (or double colons
323	<code>::</code>) to the double underscores <code>__</code>. When the system
324	generates the <samp>Makefile</samp> for the build, each <code>TOOL</code>
325	declaration will be exported as an environment variable. For example, the
326	declaration <code>tool::fflags/foo/bar</code> will be exported as
327	<samp>FFLAGS__foo__bar</samp>.</p>
328
329	<p>N.B. <code>TOOL</code> declarations for sub-packages are only accepted by
330	the system when it is sensible to do so. For example, it allows you to
331	declare different compiler flags, linker commands and linker flags for
332	different sub-packages, but it does not accept different compilers for
333	different sub-packages. If you attempt to make a <code>TOOL</code>
334	declaration for a sub-package that does not exist, the build system will exit
335	with an error.</p>
336
337	<p>The following is an example setting in an extract configuration file based
338	on <a href="#example_2">example 2</a>:</p>
339	<pre id="example_3">
340	# Example 3
341	# ----------------------------------------------------------------------
342	cfg::type ext
343	cfg::version 1.0
344
345	dest $HOME/example
346
347	bld::target foo.exe bar.exe
348
349	bld::tool::fc ifort
350	bld::tool::fflags -O3 # line 9
351	bld::tool::cc gcc
352	bld::tool::cflags -O3
353
354	bld::tool::ldflags -L$(HOME)/lib -legg -lham
355
356	bld::tool::fflags::ops -O1 -C # line 15
357	bld::tool::fflags::gen -O2 # line 16
358
359	# ... and other declarations for repositories and source directories ...
360	</pre>
361
362	<p>In the example above, line 15 alters the Fortran compiler flags for
363	<samp>ops</samp>, so that all source files in <samp>ops</samp> will be
364	compiled with optimisation level 1 and will have runtime error checking
365	switched on. Line 16, alters the Fortran compiler flags for <samp>gen</samp>,
366	so that all source files in <samp>gen</samp> will be compiled with
367	optimisation level 2. All other Fortran source files will use the global
368	setting declared at line 9, so they they will all be compiled with
369	optimisation level 3.</p>
370
371	<dl>
372	<dt>Note - changing compiler flags in incremental builds</dt>
373
374	<dd>
375	<p>Suppose you have performed a successful build using the configuration
376	in <a href="#example_3">example 3</a>, and you have decided to change
377	some of the compiler flags, you can do so by altering the appropriate
378	flags in the build configuration file. When you trigger an incremental
379	build, the system will detect changes in compiler flags automatically,
380	and update only the required targets. The following hierarchy is
381	followed:</p>
382
383	<ul>
384	<li>If the compiler flags for a particular source file change, only
385	that source file and any targets depending on that source file are
386	re-built.</li>
387
388	<li>If the compiler flags for a container package change, only source
389	files within that container package and any targets depending on those
390	source files are re-built.</li>
391
392	<li>If the global compiler flags change, all source files are
393	re-built.</li>
394
395	<li>If the compiler command changes, all source files are
396	re-built.</li>
397	</ul>
398	</dd>
399	</dl>
400
401	<p>N.B. For a full list of build tools declarations, please see <a href=
402	"annex_bld_cfg.html#tools-list">Annex: Declarations in FCM build
403	configuration file > list of tools</a>.</p>
404
405	<h3 id="basic_interface">Automatic Fortran 9X interface block</h3>
406
407	<p>For each Fortran 9X source file containing standalone subroutines and/or
408	functions, the system generates an interface file and sends it to the
409	<samp>inc/</samp> sub-directory of the build root. An interface file contains
410	the interface blocks for the subroutines and functions in the original source
411	file. In an incremental build, if you have modified a Fortran 9X source file,
412	its interface file will only be re-generated if the content of the interface
413	has changed.</p>
414
415	<p>Consider a source file <samp>foo.f90</samp> containing a subroutine called
416	<samp>foo</samp>. In a normal operation, the system writes the interface file
417	to <samp>foo.interface</samp> in the <samp>inc/</samp> sub-directory of the
418	build root. By default, the root name of the interface file is the same as
419	that of the source file, and is case sensitive. You can change this behaviour
420	using a <code>TOOL::INTERFACE</code> declaration. E.g.:</p>
421	<pre>
422	bld::tool::interface program # The default is "file"
423	</pre>
424
425	<p>In such case, the root name of the interface file will be named in lower
426	case after the first program unit in the file.</p>
427
428	<p>The default extension for an interface file is <samp>.interface</samp>.
429	This can be modified through the input and output file type register, which
430	will be discussed in a later section on <a href="#advanced_file-type">File
431	Type</a>.</p>
432
433	<p>In most cases, we modify procedures without altering their calling
434	interfaces. Consider another source file <samp>bar.f90</samp> containing a
435	subroutine <samp>bar</samp>. If <samp>bar</samp> calls <samp>foo</samp>, it
436	is good practice for <samp>bar</samp> to have an explicit interface for
437	<samp>foo</samp>. This can be achieved if the subroutine <samp>bar</samp> has
438	the following within its declaration section:</p>
439	<pre>
440	INCLUDE 'foo.interface'
441	</pre>
442
443	<p>The source file <samp>bar.f90</samp> is now dependent on the interface
444	file <samp>foo.interface</samp>. This can make incremental build very
445	efficient, as changes in the <samp>foo.f90</samp> file will not normally
446	trigger the re-compilation of <samp>bar.f90</samp>, provided that the
447	interface of the <code>subroutine foo</code> remains unchanged. (However, the
448	system is clever enough to know that it needs to re-link any executables that
449	are dependent on the object file for the <code>subroutine bar</code>.)</p>
450
451	<p>By default, the system uses its own internal logic to extract the calling
452	interfaces of top level subroutines and functions in a Fortran source file to
453	generate an interface block. However, the system can also work with the
454	interface generator <code>f90aib</code>, which is a freeware obtained from
455	<a href=
456	"http://www.ifremer.fr/ditigo/molagnon/fortran90/contenu.html">Fortran 90
457	texts and programs, assembled by Michel Olagnon</a> at the French Research
458	Institute for Exploitation of the Sea. To do so, you need to make a
459	declaration in the build configuration file using the label
460	<code>TOOL::GENINTERFACE</code>. As for any other <code>TOOL</code>
461	declarations, you can attach a sub-package name to the label. The change will
462	then apply only to source files within that sub-package. If
463	<code>TOOL::GENINTERFACE</code> is declared to have the value
464	<code>NONE</code>, interface generation will be switched off. The following
465	are some examples:</p>
466	<pre id="example_4">
467	# Example 4
468	# ----------------------------------------------------------------------
469	# This is an EXTRACT configuration file ...
470
471	# ... some other declarations ...
472
473	bld::tool::geninterface f90aib # line 5
474	bld::tool::geninterface::bar none # line 6
475
476	# ... some other declarations ...
477	</pre>
478
479	<p>In line 5, the global interface generator is now set to
480	<code>f90aib</code>. In line 6, by setting the interface generator for the
481	package <samp>bar</samp> to the <code>none</code> keyword, no interface file
482	will be generated for source files under the package <samp>bar</samp>.</p>
483
484	<p>Switching off the interface block generator can be useful in many
485	circumstances. For example, if the interface block is already provided
486	manually within the source tree, or if the interface block is never used by
487	other program units, it is worth switching off the interface generator for
488	the source file to speed up the build process.</p>
489
490	<h3 id="basic_dependency">Automatic dependency</h3>
491
492	<p>The build system has a built-in dependency scanner, which works out the
493	dependency relationship between source files, so that they can be built in
494	the correct order. The system scans all source files of known types for all
495	supported dependency patterns. Dependencies of source files in a sub-package
496	are written in a cache, which can be retrieved for incremental builds. (In an
497	incremental build, only changed source files need to be re-scanned for
498	dependency information. Dependency information for other files are retrieved
499	from the cache.) The dependency information is passed to the
500	<code>make</code> rule generator, which writes the <samp>Makefile</samp>.</p>
501
502	<p>The <code>make</code> rule generator generates different <code>make</code>
503	rules for different dependency types. The following dependency patterns are
504	automatically detected by the current system:</p>
505
506	<ul>
507	<li>The <code>USE <module></code> statement in a Fortran source file
508	is the first pattern. The statement has two implications: 1) The current
509	file compiles only if the module has been successfully compiled, and needs
510	to be re-compiled if the module has changed. 2) The executable depending on
511	the current file can only resolve all its externals by linking with the
512	object file of the compiled module. The executable needs to be re-linked if
513	the module and its dependencies has changed.</li>
514
515	<li>The <code>INCLUDE '<name>.interface'</code> statement in a
516	Fortran source file is the second pattern. (The default extension for an
517	interface file is <samp>.interface</samp>. This can be modified through the
518	input and output file type register, which will be discussed in a later
519	section on <a href="#advanced_file-type">File Type</a>.) It has two
520	implications: 1) The current file compiles only if the included interface
521	file is in the INCLUDE search path, and needs to be re-compiled if the
522	interface file changes. 2) The executable depending on the current file can
523	only resolve all its externals by linking with the object file of the
524	source file that generates the interface file. The executable needs to be
525	re-linked if the source file (and its dependencies) associated with the
526	interface file has changed. It is worth noting that for this dependency to
527	work, the root <name> of the interface file should match with that of
528	the source file associated with the interface file. (Please note that you
529	can use pre-processor [#include "<name>.interface] instead of Fortran
530	INCLUDE, but it will not work if you switch on the <a href=
531	"#advanced_pp">pre-processing</a> stage, which will be discussed in a later
532	section.)</li>
533
534	<li>The <code>INCLUDE '<file>'</code> statement (excluding the
535	INCLUDE interface file statement) in a Fortran source file is the third
536	pattern. It has two implications: 1) The current file compiles only if the
537	included file is in the INCLUDE search path, and needs to be re-compiled if
538	the include file changes. 2) The executable needs to be linked with any
539	objects the include file is dependent on. It needs to be re-linked if these
540	objects have changed.</li>
541
542	<li>The <code>#include '<file>'</code> statement in a Fortran/C
543	source or header file is the fourth pattern. It has similar implications as
544	the Fortran INCLUDE statement. However, they have to be handled differently
545	because <code>#include</code> statements are processed by the
546	pre-processor, which may be performed in a separate stage of the FCM build
547	process. This will be further discussed in a later sub-section on <a href=
548	"#advanced_pp">Pre-processing</a>.</li>
549	</ul>
550
551	<p>If you want your code to be built automatically by the FCM build system,
552	you should also design your code to conform to the following rules:</p>
553
554	<ol>
555	<li>Single compilable program unit, (i.e. program, subroutine, function or
556	module), per file.</li>
557
558	<li>Unique name for each compilable program unit.</li>
559
560	<li>Always supply an interface for subroutines and functions, i.e.:
561
562	<ul>
563	<li>Put them in modules.</li>
564
565	<li>Put them in the CONTAINS section within the main program unit.</li>
566
567	<li>Use interface files.</li>
568	</ul>
569	</li>
570
571	<li>If interface files are used, it is good practice to name each source
572	file after the program unit it contains. It will make life a lot simpler
573	when using the <a href="#basic_interface">Automatic Fortran 9X interface
574	block</a> feature, which has already been discussed in the previous
575	section.
576
577	<ul>
578	<li>The problem is that, by default, the root name of the interface
579	file is the same as that of the source file rather than the program
580	unit. If they differ then the build system will create a dependency on
581	the wrong object file (since the object files are named according to
582	the program unit).</li>
583
584	<li>This problem can be avoided by changing the behaviour of the
585	interface file generator to use the name of the program unit instead
586	(using a <code>TOOL::INTERFACE</code> declaration).</li>
587	</ul>
588	</li>
589	</ol>
590
591	<dl>
592	<dt>Note - setting build targets</dt>
593
594	<dd>
595	<p>The <samp>Makefile</samp> generated by the build system contains a
596	list of targets that can be built. The build system allows you to build
597	(or perform the actions of) any targets that are present in the generated
598	<samp>Makefile</samp>. There are two ways to specify the targets to be
599	built.</p>
600
601	<p>Firstly, you can use the <code>TARGET</code> declarations in your
602	build configuration file to specify the default targets to be built.
603	These targets will be set as dependencies of the <samp>all</samp> target
604	in the generated <samp>Makefile</samp>, which is the default target to be
605	built when <code>make</code> is invoked by FCM. It is worth noting that
606	<code>TARGET</code> declarations are cumulative. A later declaration does
607	not override an earlier one - it simply adds more targets to the
608	list.</p>
609
610	<p>Alternatively, you can use the <code>-t</code> option when you invoke
611	the <code>fcm build</code> command. The option takes an argument, which
612	should be a colon <code>:</code> separated list of targets to be built.
613	When the <code>-t</code> option is set, FCM invokes <code>make</code> to
614	build these targets instead. (E.g. if we invoke the build system with the
615	command <code>fcm build -t foo.exe:bar.exe</code>, it will invoke
616	<code>make</code> to build <samp>foo.exe</samp> and
617	<samp>bar.exe</samp>.)</p>
618
619	<p>If you do not specify any explicit targets, the system will search
620	your source tree for main programs:</p>
621
622	<ul>
623	<li>If there are main programs in your source tree, they will be set as
624	the default targets automatically.</li>
625
626	<li>Otherwise, the default is to build the top level library archive
627	containing objects compiled from the source files in the current source
628	tree. (For more information on building library archives, please see
629	the section on <a href="#advanced_library">Creating library
630	archives</a>.)</li>
631	</ul>
632	</dd>
633	</dl>
634
635	<h2 id="advanced">Advanced Features</h2>
636
637	<h3 id="advanced_dependency">Further dependency features</h3>
638
639	<p>Apart from the usual dependency patterns described in the previous
640	sub-section, the automatic dependency scanner also recognises two special
641	directives when they are inserted into a source file:</p>
642
643	<ul>
644	<li>The directive <code>DEPENDS ON: <object></code> in a comment line
645	of a Fortran/C source file: It states that the current file is dependent on
646	the declared external object. The executable depending on the current file
647	needs to link with this external object in order to resolve all its
648	external references. It needs to be re-linked if the declared external
649	object (and its dependencies) has changed.</li>
650
651	<li>The directive <code>CALLS: <executable></code> in a comment line
652	of a script: It states that the current script is dependent on the declared
653	executable file, which can be another script or a binary executable. The
654	current script can only function correctly if the declared executable is
655	found in the search path. This directive is useful to ensure that all
656	dependent executables are built or copied to the correct path.</li>
657	</ul>
658
659	<p>Another way to specify external dependency is to use the
660	<code>EXE_DEP</code> declaration to declare extra dependencies. The
661	declaration normally applies to all main programs, but if the form
662	<code>EXE_DEP::<target></code> is used, it will only apply to
663	<target>, (which must be the name of a main program target). If the
664	declaration is made without a value, the main programs will be set to depend
665	on all object files. Otherwise, the value can be supplied as a space
666	delimited list of items. Each item can be either the name of a sub-package or
667	an object target. For the former, the main programs will be set to depend on
668	all object files within the sub-package. For the latter, the main programs
669	will be set to depend on the object target. The following are some
670	examples:</p>
671	<pre id="example_5">
672	# Example 5
673	# ----------------------------------------------------------------------
674	cfg::type ext
675	cfg::version 1.0
676
677	bld::exe_dep::foo.exe foo/bar egg.o # line 4
678	bld::exe_dep # line 5
679	# ... some other declarations ...
680	</pre>
681
682	<p>Here is an explanation of what each line does:</p>
683
684	<ul>
685	<li><dfn>line 4</dfn>: this line declares the dependency on the sub-package
686	<samp>foo/bar</samp> and the object target <samp>egg.o</samp> for building
687	the main program target <samp>foo.exe</samp>. The target
688	<samp>foo.exe</samp> will now depends on all object files in the
689	<samp>foo/bar</samp> sub-package as well as the object target
690	<samp>egg.o</samp>.</li>
691
692	<li><dfn>line 5</dfn>: this line declares that all other main program
693	targets will depend on all (non-program) object files in the build.</li>
694	</ul>
695
696	<dl>
697	<dt>Note - naming of object files</dt>
698
699	<dd>
700	<p>By default, object files are named with the suffix <samp>.o</samp>.
701	For a Fortran source file, the build system uses the lower case name of
702	the first program unit within the file to name its object file. For
703	example, if the first program unit in the Fortran source file
704	<samp>foo.f90</samp> is <code>PROGRAM Bar</code>, the object file will be
705	<samp>bar.o</samp>. For a C source file, the build system uses the lower
706	case root name of the source file to name its object file. For example, a
707	C source file called <samp>egg.c</samp> will have its object file named
708	<samp>egg.o</samp>.</p>
709
710	<p>The reason for using lower case to name the object files is because
711	Fortran is a case insensitive language. Its symbols can either be in
712	lower or upper case. E.g. the <code>SUBROUTINE Foo</code> is the same as
713	the <code>SUBROUTINE foo</code>. It can be rather confusing if the
714	subroutines are stored in different files. When they are compiled and
715	archived into a library, there will be a clash of namespace, as the
716	Fortran compiler thinks they are the same. However, this type of error
717	does not normally get reported. If <samp>Foo</samp> and <samp>foo</samp>
718	are very different code, the user may end up using the wrong subroutine,
719	which may lead to a very long debugging session. By naming all object
720	files in lower case, this type of situation can be avoided. If there is a
721	clash in names due to the use of upper/lower cases, it will be reported
722	as warnings by the build system, (as <em>duplicated targets</em> for
723	building <samp>foo.o</samp>).</p>
724	</dd>
725	</dl>
726
727	<p>It is realised that there are situations when an automatically detected
728	dependency should not be written into the <samp>Makefile</samp>. For example,
729	the dependency may be a standard module provided by the Fortran compiler, and
730	does not need to be built in the usual way. In such case, we need to have a
731	way to exclude this module during an automatic dependency scan.</p>
732
733	<p>The <code>EXCL_DEP</code> declaration can be used to do just that. The
734	following extract configuration contains some examples of the basic usage of
735	the <code>EXCL_DEP</code> declaration:</p>
736	<pre id="example_6">
737	# Example 6
738	# ----------------------------------------------------------------------
739	cfg::type ext
740	cfg::version 1.0
741
742	bld::excl_dep USE::YourFortranMod # line 4
743	bld::excl_dep INTERFACE::HerFortran.interface # line 5
744	bld::excl_dep INC::HisFortranInc.inc # line 6
745	bld::excl_dep H::TheirHeader.h # line 7
746	bld::excl_dep OBJ::ItsObject.o # line 8
747
748	# ... some other declarations ...
749	</pre>
750
751	<p>Here is an explanation of what each line does:</p>
752
753	<ul>
754	<li><dfn>line 4</dfn>: this line declares that the Fortran module
755	<samp>YourFortranMod</samp> should be excluded. The value of each
756	<code>EXCL_DEP</code> declaration has two parts. The first part is a label
757	that is used to define the type of dependency to be excluded. For a full
758	list of these labels, please see the <a href=
759	"annex_bld_cfg.html#dependency-types">dependency types table</a> in the
760	<a href="annex_bld_cfg.html">Annex: Declarations in FCM build configuration
761	file</a>. The label <code>USE</code> denotes a Fortran module. The second
762	part of the label is the dependency itself. For instance, if a Fortran
763	source file contains the line: <code>USE YourFortranMod</code>, the
764	dependency scanner will ignore it.</li>
765
766	<li><dfn>line 5</dfn>: this line declares that the include statement for
767	the Fortran 9X interface file <samp>HerFortran.interface</samp> should be
768	excluded. The label <code>INTERFACE</code> denotes a Fortran INCLUDE
769	statement for a Fortran 9X interface block file. For example, if a Fortran
770	source file contains the line: <code>INCLUDE 'HerFortran.interface'</code>,
771	the dependency scanner will ignore it.</li>
772
773	<li><dfn>line 6</dfn>: this line declares that the include statement for
774	<samp>HisFortranInc.inc</samp> should be excluded. The label
775	<code>INC</code> denotes a Fortran INCLUDE statement other than an INCLUDE
776	statement for an interface block file. For example, if a Fortran source
777	file contains the line: <code>INCLUDE 'HisFortranInc.inc'</code>, the
778	dependency scanner will ignore it.</li>
779
780	<li><dfn>line 7</dfn>: this line declares that the header include statement
781	<samp>TheirHeader.h</samp> should be excluded. The label <code>H</code>
782	denotes a pre-processing #include statement. For example, if a source file
783	contains the line: <code>#include 'TheirHeader.h'</code>, the dependency
784	scanner will ignore it.</li>
785
786	<li><dfn>line 8</dfn>: this line declares that the external dependency for
787	<samp>ItsObject.o</samp> should be excluded. The label <code>OBJ</code>
788	denotes a compiled binary object. These dependencies are normally inserted
789	into the source files as special comments. For example, if a source file
790	contains the line: <code>! depends on: ItsObject.o</code>, the dependency
791	scanner will ignore it.</li>
792	</ul>
793
794	<p>An <code>EXCL_DEP</code> declaration normally applies to all files in the
795	build. However, you can suffix it with the name of a sub-package, i.e.
796	<code>EXCL_DEP::<pcks></code>. In such case, the declaration will only
797	apply while scanning for dependencies in the source files in the sub-package
798	named <pcks>.</p>
799
800	<p>You can also exclude all dependency scan of a particular type. To do so,
801	simply declare the type in the value. For example, if you do not want the
802	build system to scan for the <code>CALLS: <executable></code> directive
803	in the comment lines of your scripts, you can make the following
804	declaration:</p>
805	<pre>
806	bld::excl_dep EXE
807	</pre>
808
809	<p>The opposite of the <code>EXCL_DEP</code> declaration is the
810	<code>DEP::<pcks></code> declaration, which you can use to add a
811	dependency to a source file (in the package name <code><pcks></code>).
812	The syntax of the declaration is similar to that of <code>EXCL_DEP</code>,
813	but you must specify the package name of a source file for DEP declarations.
814	Please also note that a <code>DEP</code> declaration only works if the
815	particular dependency is supported for the particular source file - as it
816	makes no sense, for example, to specify a USE dependency for a shell
817	script.</p>
818
819	<p>If you need to switch off dependency checking completely, you can use the
820	<code>NO_DEP</code> declaration. For example, to switch off dependency
821	checking for all but the <samp>foo/bar</samp> sub-package, you can do:</p>
822	<pre>
823	bld::no_dep true
824	bld::no_dep::foo/bar false
825	</pre>
826
827	<h3 id="advanced_blockdata">Linking a Fortran executable with a BLOCKDATA
828	program unit</h3>
829
830	<p>If it is required to link Fortran executables with BLOCKDATA program
831	units, you must declare the executable targets and the objects containing the
832	BLOCKDATA program units using the <code>BLOCKDATA::<target></code>
833	declarations. For example, if <samp>foo.exe</samp> is an executable target
834	depending on the objects of the BLOCKDATA program units
835	<samp>blkdata.o</samp> and <samp>fbk.o</samp>, you will make the following
836	declarations:</p>
837	<pre>
838	bld::blockdata::foo.exe blkdata fbk
839	</pre>
840
841	<p>If all your executables are dependent on <samp>blkdata.o</samp> and
842	<samp>fbk.o</samp>, you will make the following declarations:</p>
843	<pre>
844	bld::blockdata blkdata fbk
845	</pre>
846
847	<h3 id="advanced_library">Creating library archives</h3>
848
849	<p>If you are interested in building library archives, the build system
850	allows you to do it in a relatively simple way. For each sub-package in the
851	source tree, there is a target to build a library containing all the objects
852	compiled from the source files (that are not main programs) within the
853	sub-package. If the sub-package contains children sub-packages, the object
854	files of the children will also be included recursively. By default, the
855	library archive is named after the sub-package, in the format
856	<code>lib<pcks>.a</code>. (For example, the library archive for the
857	package <samp>foo/bar/egg</samp> will be named
858	<samp>libfoo__bar__egg.a</samp> by default.) If you do not like the default
859	name for the sub-package library, you can use the
860	<code>LIB::<pcks></code> declaration to rename it, as long as the new
861	name does not clash with other targets. For example, to rename
862	<samp>libfoo__bar__egg.a</samp> to <samp>libham.a</samp>, you will make the
863	following declaration in your extract configuration file:</p>
864	<pre>
865	bld::lib::foo/bar/egg ham
866	</pre>
867
868	<p>In addition to sub-package libraries, you can also build a global library
869	archive for the whole source tree. By default, the library is named
870	<samp>libfcm_default.a</samp>, but you can rename it using the
871	<code>LIB</code> declaration as above. For example, to rename the library to
872	<samp>libmy-lib.a</samp>, you will make the following declaration in your
873	extract configuration file:</p>
874	<pre>
875	bld::lib my-lib
876	</pre>
877
878	<p>When a library archive is created successfully, the build system will
879	automatically generate the relevant exclude dependency configurations in the
880	<samp>etc/</samp> sub-directory of the build root. You will be able to
881	include these configurations in subsequent builds that utilise the library.
882	The root names of the configuration files match those of the library archives
883	that you can create in the current build, but the extension <samp>*.a</samp>
884	is replaced with <samp>*.cfg</samp>. For example, the exclude dependency
885	configuration for <samp>libmy-lib.a</samp> is <samp>libmy-lib.cfg</samp>.</p>
886
887	<h3 id="advanced_pp">Pre-processing</h3>
888
889	<p>As most modern compilers can handle pre-processing, the build system
890	leaves pre-processing to the compiler by default. However, it is recognised
891	that there are code written with pre-processor directives that can alter the
892	argument list of procedures and/or their dependencies. If a source file
893	requires pre-processing in such a way, we have to pre-process before running
894	the interface block generator and the dependency scanner. The <code>PP</code>
895	declaration can be used to switch on this pre-processing stage. The
896	pre-processing stage can be switched on globally or for individual
897	sub-packages only. The following is an example, using an extract
898	configuration file:</p>
899	<pre id="example_7">
900	# Example 7
901	# ----------------------------------------------------------------------
902	cfg::type ext
903	cfg::version 1.0
904
905	bld::pp::gen true # line 4
906	bld::pp::var/foo true # line 5
907
908	bld::tool::cppkeys GOOD WEATHER FORECAST # line 7
909	bld::tool::fppkeys FOO BAR EGG HAM # line 8
910
911	# ... some other declarations ...
912	</pre>
913
914	<p>Here is an explanation of what each line does:</p>
915
916	<ul>
917	<li><dfn>line 4-5</dfn>: these switches on the pre-processing stage for all
918	sub-packages under <samp>gen</samp> and <samp>var/foo</samp>.</li>
919
920	<li><dfn>line 7</dfn>: this declares a list of pre-defined macros
921	<samp>GOOD</samp>, <samp>WEATHER</samp> and <samp>FORECAST</samp> for
922	pre-processing all C files.</li>
923
924	<li><dfn>line 8</dfn>: this declares a list of pre-defined macros
925	<samp>FOO</samp>, <samp>BAR</samp>, <samp>EGG</samp> and <samp>HAM</samp>
926	for pre-processing all Fortran files that require processing.</li>
927	</ul>
928
929	<p>Source files requiring pre-processing may contain <code>#include</code>
930	statements to include header files. For including a local file, its name
931	should be embedded within a pair of quotes, i.e. <samp>'file.h'</samp> or
932	<samp>"file.h"</samp>. If the header file is embedded within a pair of
933	<file.h> angle brackets, the system will assume that the file can be
934	found in a standard location.</p>
935
936	<p>The build system allows header files to be placed anywhere within the
937	declared source tree. The system uses the dependency scanner, as described in
938	the previous sub-section to scan for any header file dependencies. All source
939	files requiring pre-processing and all header files are scanned. Header files
940	that are required are copied to the <samp>inc/</samp> subdirectory of the
941	build root, which is automatically added to the pre-processor search path via
942	the <code>-I<dir></code> option. The build system uses an internal
943	logic similar to <code>make</code> to perform pre-processing. Header files
944	are only copied to the <samp>inc/</samp> sub-directory if they are used in
945	<code>#include</code> statements.</p>
946
947	<p>Unlike <code>make</code>, which only uses the timestamp to determine
948	whether an item is out of date, the internal logic of the build system does
949	this by inspecting the content of the file as well. In an incremental build,
950	the pre-processed file is only updated if its content has changed. This
951	avoids unnecessary updates (and hence unnecessary re-compilation) in an
952	incremental build if the changed section of the code does not affect the
953	output file.</p>
954
955	<p>Pre-processed code generated during the pre-processing stage are sent to
956	the <samp>ppsrc/</samp> sub-directory of the build root. It will have a
957	relative path that reflects the name of the declared sub-package. The
958	pre-processed source file will have the same root name as the original source
959	file. For C files, the same extension <samp>.c</samp> will be used. For
960	Fortran files, the case of the extension will normally be dropped, e.g. from
961	<samp>.F90</samp> to <samp>.f90</samp>.</p>
962
963	<p>Following pre-processing, the system will use the pre-processed source
964	file as if it is the original source file. The interface generator will
965	generate the interface file using the pre-processed file, the dependency
966	scanner will scan the pre-processed file for dependencies, and the compiler
967	will compile the pre-processed source.</p>
968
969	<p>The <code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code> declarations
970	are used to pre-define macros in the C and Fortran pre-processor
971	respectively. This is implemented by the build system using the pre-processor
972	<code>-D</code> option on each word in the list. The use of these
973	declarations are not confined to the pre-process stage. If any source files
974	requiring pre-processing are left to the compiler, the declarations will be
975	used to set up the commands for compiling these source files.</p>
976
977	<p>The <code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code> declarations
978	normally applies globally, but like any other <code>TOOL</code> declarations,
979	they can be suffixed with sub-package names. In such cases, the declarations
980	will apply only to the specified sub-packages.</p>
981
982	<dl>
983	<dt>Note - changing pre-processor flags</dt>
984
985	<dd>
986	<p>As for compiler flags, the build system detects changes in
987	pre-processor flags (<code>TOOL::CPPFLAGS</code> and
988	<code>TOOL::FPPFLAGS</code>) and macro definitions
989	(<code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code>). If the
990	pre-processor flags or the macro definitions have changed in an
991	incremental build, the system will re-do all the necessary
992	pre-processing. The following hierarchy is followed:</p>
993
994	<ul>
995	<li>If the pre-processor flags or macro definitions for a particular
996	source file change, only that source file will be pre-processed
997	again.</li>
998
999	<li>If the pre-processor flags or macro definitions for a particular
1000	container package change, only source files within that container will
1001	be pre-processed again.</li>
1002
1003	<li>If the global pre-processor flags or macro definitions change, all
1004	source files will be pre-processed again.</li>
1005
1006	<li>If the pre-processor command changes, all source files are
1007	pre-processed again.</li>
1008	</ul>
1009	</dd>
1010	</dl>
1011
1012	<h3 id="advanced_file-type">File type</h3>
1013
1014	<p>The build system only knows what to do with an input source file if it
1015	knows what type of file it is. The type of a source file is normally
1016	determined automatically using one of the following three methods (in
1017	order):</p>
1018
1019	<ol>
1020	<li>If the file is named with an extension, its extension will be matched
1021	against a set of registered file extensions. If a match is found, the file
1022	type will be set according to the register.</li>
1023
1024	<li>If a file does not have an extension or does not match with a
1025	registered extension, its name is compared with a set of pre-defined
1026	patterns. If a match is found, the file type will be set according to the
1027	file type associated with the pattern.</li>
1028
1029	<li>If the above two methods failed and if the file is a text file, the
1030	system will attempt to read the first line of the file. If the first line
1031	begins with a <code>#!</code> pattern, the line will be compared with a set
1032	of pre-defined patterns. If a match is found, the file type will be set
1033	according to the file type associated with the pattern.</li>
1034	</ol>
1035
1036	<p>In addition to the above, if a file is a Fortran or C source file, the
1037	system will attempt to open the source file to determine whether it contains
1038	a main program, module (Fortran only) or just standalone procedures. All
1039	these information will be used later by the build system to process the
1040	source file.</p>
1041
1042	<p>The build system registers a file type with a set of type flags delimited
1043	by the double colons <code>::</code>. For example, a Fortran 9X source file
1044	is registered as <code>FORTRAN::FORTRAN9X::SOURCE</code>. (Please note that
1045	the order of the type flags in the list is insignificant. For example,
1046	<code>FORTRAN::SOURCE</code> is the same as <code>SOURCE::FORTRAN</code>.)
1047	For a list of all the type flags used by the build system, please see the
1048	<a href="annex_bld_cfg.html#infile-ext-types">input file extension type flags
1049	table</a> in the <a href="annex_bld_cfg.html">Annex: Declarations in FCM
1050	build configuration file</a>.</p>
1051
1052	<p>The following is a list of default input file extensions and their
1053	associated types:</p>
1054
1055	<dl>
1056	<dt><samp>.f .for .ftn .f77</samp></dt>
1057
1058	<dd><code>FORTRAN::SOURCE</code> Fortran 77 source file (assumed to be
1059	fixed format)</dd>
1060
1061	<dt><samp>.f90 .f95</samp></dt>
1062
1063	<dd><code>FORTRAN::FORTRAN9X::SOURCE</code> Fortran 9X source file (assumed
1064	to be free format)</dd>
1065
1066	<dt><samp>.F .FOR .FTN .F77</samp></dt>
1067
1068	<dd><code>FPP::SOURCE</code> Fortran 77 source file (assumed to be fixed
1069	format) that requires pre-processing</dd>
1070
1071	<dt><samp>.F90 .F95</samp></dt>
1072
1073	<dd><code>FPP::FPP9X::SOURCE</code> Fortran 9X source file (assumed to be
1074	free format) that requires pre-processing</dd>
1075
1076	<dt><samp>.c</samp></dt>
1077
1078	<dd><code>C::SOURCE</code> C source file</dd>
1079
1080	<dt><samp>.h .h90</samp></dt>
1081
1082	<dd><code>CPP::INCLUDE</code> Pre-processor <code>#include</code> header
1083	file</dd>
1084
1085	<dt><samp>.o .obj</samp></dt>
1086
1087	<dd><code>BINARY::OBJ</code> Compiled binary object</dd>
1088
1089	<dt><samp>.exe</samp></dt>
1090
1091	<dd><code>BINARY::EXE</code> Binary executable</dd>
1092
1093	<dt><samp>.a</samp></dt>
1094
1095	<dd><code>BINARY::LIB</code> Binary object library archive</dd>
1096
1097	<dt><samp>.sh .ksh .bash .csh</samp></dt>
1098
1099	<dd><code>SHELL::SCRIPT</code> Unix shell script</dd>
1100
1101	<dt><samp>.pl .pm</samp></dt>
1102
1103	<dd><code>PERL::SCRIPT</code> Perl script</dd>
1104
1105	<dt><samp>.py</samp></dt>
1106
1107	<dd><code>PYTHON::SCRIPT</code> Python script</dd>
1108
1109	<dt><samp>.tcl</samp></dt>
1110
1111	<dd><code>TCL::SCRIPT</code> Tcl/Tk script</dd>
1112
1113	<dt><samp>.pro</samp></dt>
1114
1115	<dd><code>PVWAVE::SCRIPT</code> IDL/PVWave program</dd>
1116
1117	<dt><samp>.cfg</samp></dt>
1118
1119	<dd><code>CFGFILE</code> FCM configuration file</dd>
1120
1121	<dt><samp>.inc</samp></dt>
1122
1123	<dd><code>FORTRAN::FORTRAN9X::INCLUDE</code> Fortran INCLUDE file</dd>
1124
1125	<dt><samp>.interface</samp></dt>
1126
1127	<dd><code>FORTRAN::FORTRAN9X::INCLUDE::INTERFACE</code> Fortran 9X INCLUDE
1128	interface block file</dd>
1129	</dl>
1130
1131	<p>N.B. The extension must be unique. For example, the system does not
1132	support the use of <samp>.inc</samp> files for both <code>#include</code> and
1133	Fortran <code>INCLUDE</code>.</p>
1134
1135	<p>The following is a list of supported file name patterns and their
1136	associated types:</p>
1137
1138	<dl>
1139	<dt><samp>Scr_ Comp_ IF_ Suite_ Interface_</samp></dt>
1140
1141	<dd><code>SHELL::SCRIPT</code> Unix shell script, GEN-based project naming
1142	conventions</dd>
1143
1144	<dt><samp>List_</samp></dt>
1145
1146	<dd><code>SHELL::SCRIPT::GENLIST</code> Unix shell script, GEN list
1147	file</dd>
1148
1149	<dt><samp>Sql_</samp></dt>
1150
1151	<dd><code>SCRIPT::SQL</code> SQL script, GEN-based project naming
1152	conventions</dd>
1153	</dl>
1154
1155	<p>The following is a list of supported <code>#!</code> line patterns and
1156	their associated types:</p>
1157
1158	<dl>
1159	<dt><samp>sh ksh bash csh</samp></dt>
1160
1161	<dd><code>SHELL::SCRIPT</code> Unix shell script</dd>
1162
1163	<dt><samp>perl</samp></dt>
1164
1165	<dd><code>PERL::SCRIPT</code> Perl script</dd>
1166
1167	<dt><samp>python</samp></dt>
1168
1169	<dd><code>PYTHON::SCRIPT</code> Python script</dd>
1170
1171	<dt><samp>tclsh wish</samp></dt>
1172
1173	<dd><code>TCL::SCRIPT</code> Tcl/Tk script</dd>
1174	</dl>
1175
1176	<p>The build system allows you to add or modify the register for input file
1177	extensions and their associated type using the
1178	<code>INFILE_EXT::<ext></code> declaration, where <ext> is a file
1179	name extension without the leading dot. If file extension alone is
1180	insufficient for defining the type of your source file, you can use the
1181	<code>SRC_TYPE::<pcks></code> declaration, (where <pcks> is the
1182	package name of the source file). For example, in an extract configuration
1183	file, you may have:</p>
1184	<pre id="example_8">
1185	# Example 8
1186	# ----------------------------------------------------------------------
1187	cfg::type ext
1188	cfg::version 1.0
1189
1190	bld::infile_ext::foo CPP::INCLUDE # line 4
1191	bld::infile_ext::bar FORTRAN::FORTRAN9X::INCLUDE # line 5
1192	bld::src_type::egg/ham.f FORTRAN::FORTRAN9X::INCLUDE # line 6
1193
1194	# ... some other declarations ...
1195	</pre>
1196
1197	<p>Here is an explanation of what each line does:</p>
1198
1199	<ul>
1200	<li><dfn>line 4</dfn>: this line registers the extension <samp>.foo</samp>
1201	to be of type <code>CPP::INCLUDE</code>. This means that any input files
1202	with <samp>.foo</samp> extension will be treated as if they are
1203	pre-processor header files.</li>
1204
1205	<li><dfn>line 5</dfn>: this line registers the extension <samp>.bar</samp>
1206	to be of type <code>FORTRAN::FORTRAN9X::INCLUDE</code>. This means that any
1207	input file with <samp>.bar</samp> extension will be treated as if they are
1208	Fortran 9X INCLUDE files.</li>
1209
1210	<li><dfn>line 6</dfn>: this line declares the type for the source file in
1211	the package <samp>egg::ham.f</samp> to be
1212	<code>FORTRAN::FORTRAN9X::INCLUDE</code>. Without this declaration, this
1213	file would normally be given the type <code>FORTRAN::SOURCE</code>.</li>
1214	</ul>
1215
1216	<p>The <code>INFILE_EXT</code> declarations deal with extensions of input
1217	files. There is also a <code>OUTFILE_EXT::<type></code> declaration
1218	that deals with extensions of output files. The declaration is opposite that
1219	of <code>INFILE_EXT</code>. The file <type> is now declared with the
1220	label, and the extension is declared as the value. It is worth noting that
1221	<code>OUTFILE_EXT</code> declarations use very different syntax for
1222	<type>, and the declared extension must include the leading dot. For a
1223	list of output types used by the build system, please see the <a href=
1224	"annex_bld_cfg.html#outfile-ext-types">output file extension types table</a>
1225	in the <a href="annex_bld_cfg.html">Annex: Declarations in FCM build
1226	configuration file</a>. An example is given below:</p>
1227	<pre id="example_9">
1228	# Example 9
1229	# ----------------------------------------------------------------------
1230	cfg::type ext
1231	cfg::version 1.0
1232
1233	bld::outfile_ext::mod .MOD # line 4
1234	bld::outfile_ext::interface .intfb # line 5
1235
1236	# ... some other declarations ...
1237	</pre>
1238
1239	<p>Here is an explanation of what each line does:</p>
1240
1241	<ul>
1242	<li><dfn>line 4</dfn>: this line modifies the extension of compiled Fortran
1243	9X module information files from the default <samp>.mod</samp> to
1244	<samp>.MOD</samp>.</li>
1245
1246	<li><dfn>line 5</dfn>: this line modifies the extension of INCLUDE Fortran
1247	9X interface block files from the default <samp>.interface</samp> to
1248	<samp>.intfb</samp>.</li>
1249	</ul>
1250
1251	<p>N.B. If you have made changes to the file type registers, whether it is
1252	for input files or output files, it is always worth re-building your code in
1253	full-build mode to avoid unexpected behaviour.</p>
1254
1255	<h3 id="advanced_inherit">Inherit from a previous build</h3>
1256
1257	<p>As you can inherit from previous extracts, you can inherit from previous
1258	builds. The very same <code>USE</code> statement can be used to declare a
1259	build, which the current build will depend on. The only difference is that
1260	the declared location must contain a valid build configuration file. In fact,
1261	if you use the extract system to obtain your build configuration file, any
1262	<code>USE</code> declarations in the extract configuration file will also be
1263	<code>USE</code> declarations in the output build configuration file.</p>
1264
1265	<p>By declaring a previous build with a <code>USE</code> statement, the
1266	current build automatically inherits settings from it. The following points
1267	are worth noting:</p>
1268
1269	<ul>
1270	<li>Build targets are not normally inherited. However, you can switch on
1271	inheritance of build targets using an <code>INHERIT::TARGET</code>
1272	declaration, such as:
1273	<pre>
1274	inherit::target true
1275	</pre>
1276	</li>
1277
1278	<li>The build root directory and its sub-directories of the inherited build
1279	are placed into the search paths. For example, if we have an inherited
1280	build at <samp>/path/to/inherited</samp>, and it is used by a build at
1281	<samp>/path/to/my_build</samp>, the search path of executable files will
1282	become <samp>/path/to/my_build/bin:/path/to/inherited/bin</samp>, so that
1283	the <samp>bin/</samp> sub-directory of the current build is searched before
1284	the <samp>bin/</samp> sub-directory of the inherited build. If two or more
1285	<code>USE</code> statements are declared, the <code>USE</code> statement
1286	declared last will have higher priority. For example, if the current build
1287	is <var>C</var>, and it USEs build <var>A</var> before build <var>B</var>,
1288	the search path will be <samp>C:B:A</samp>.</li>
1289
1290	<li>Source files are inherited by default. If a source file is declared in
1291	the current build that has the same package name as a source file of the
1292	inherited build, it will override that in the inherited build. Any source
1293	files missing from the current build will be taken from the inherited
1294	build.
1295
1296	<p>You can switch off inheritance of source files using an
1297	<code>INHERIT::SRC</code> declaration. This declaration can be suffixed
1298	with the name of a sub-package. In such case, the declaration applies
1299	only to the inheritance of the sub-package. Otherwise, it applies
1300	globally. For example:</p>
1301	<pre>
1302	# Switch off inheritance of source files in the <samp>gen</samp> sub-package
1303	inherit::src::gen false
1304	</pre>
1305	</li>
1306
1307	<li><code>BLOCKDATA</code>, <code>DEP</code>, <code>EXCL_DEP</code>,
1308	<code>EXE_DEP</code>, <code>INFILE_EXT</code>, <code>LIB</code>,
1309	<code>OUTFILE_EXT</code>, <code>PP</code>, <code>TOOL</code> and
1310	<code>SRC_TYPE</code> declarations are automatically inherited. If the same
1311	setting is declared in the current incremental build, it overrides the
1312	inherited declaration.</li>
1313	</ul>
1314
1315	<p>As an example, suppose we have already performed an extract and build
1316	based on the configuration in <a href="#example_2">example 2</a>, we can set
1317	up an extract configuration file as follows:</p>
1318	<pre id="example_10">
1319	# Example 10
1320	# ----------------------------------------------------------------------
1321	cfg::type ext
1322	cfg::version 1.0
1323
1324	use $HOME/example # line 4
1325
1326	dest $HOME/example10 # line 6
1327
1328	bld::inherit::target true # line 8
1329	bld::target ham.exe egg.exe # line 9
1330
1331	bld::tool::fflags -O2 -w # line 11
1332	bld::tool::cflags -O2 # line 12
1333
1334	# ... and other declarations for repositories and source directories ...
1335	</pre>
1336
1337	<p>Here is an explanation of what each line does:</p>
1338
1339	<ul>
1340	<li><dfn>line 4</dfn>: this line declares a previous extract at
1341	<samp>$HOME/example</samp> which the current extract will inherit from. The
1342	same line will be written to the output build configuration file. The
1343	subsequent build will then inherit from the build at
1344	<samp>$HOME/example</samp>.</li>
1345
1346	<li><dfn>line 6</dfn>: this declares the destination root directory of the
1347	current extract, which will become the root directory of the current build.
1348	Search paths of the build sub-directories will be set automatically. For
1349	example, the search path for executable files created by the current build
1350	will be <samp>$HOME/example10/bin:$HOME/example/bin</samp>.</li>
1351
1352	<li><dfn>line 8</dfn>: this line switches on inheritance of build targets.
1353	The build targets in <a href="#example_1">example 1</a>, i.e.
1354	<samp>foo.exe</samp> and <samp>bar.exe</samp> will be built as part of the
1355	current build.</li>
1356
1357	<li><dfn>line 9</dfn>: this declares two new build targets
1358	<samp>ham.exe</samp> and <samp>egg.exe</samp> to be added to the inherited
1359	ones. The default build targets of the current build will now be
1360	<samp>foo.exe</samp>, <samp>bar.exe</samp>, <samp>ham.exe</samp> and
1361	<samp>egg.exe</samp>.</li>
1362
1363	<li><dfn>line 11-12</dfn>: these lines modify options used by the Fortran
1364	and the C compilers, overriding those inherited from <a href=
1365	"#example_1">example 1</a>.</li>
1366	</ul>
1367
1368	<dl>
1369	<dt>Build inheritance limitation: handling of include files</dt>
1370
1371	<dd>
1372	<p>The build system uses the compiler/pre-processor's <code>-I</code>
1373	option to specify the search path for include files. For example, it uses
1374	the option to specify the <samp>inc/</samp> sub-directories of the
1375	current build and its inherited build.</p>
1376
1377	<p>However, some compilers/pre-processors (e.g. <code>cpp</code>) search
1378	for include files from the container directory of the source file before
1379	searching for the paths specified by the <code>-I</code> options. This
1380	behaviour may cause the build to behave incorrectly.</p>
1381
1382	<p>Consider a source file <samp>egg/hen.c</samp> that includes
1383	<samp>fried.h</samp>. If the directory structure looks like:</p>
1384	<pre>
1385	# Sources in inherited build:
1386	egg/hen.c
1387	egg/fried.h
1388
1389	# Sources in current build:
1390	egg/fried.h
1391	</pre>
1392
1393	<p>The system will correctly identify that <samp>fried.h</samp> is out of
1394	date, and trigger a re-compilation of <samp>egg/hen.c</samp>. However, if
1395	the compiler searches for the include files from the container directory
1396	of the source file first, it will wrongly use the include file in the
1397	inherited build instead of the current one.</p>
1398
1399	<p>Some compilers (e.g. <code>gfortran</code>) do not behave this way and
1400	others (e.g. <code>ifort</code>) have options to prevent include file
1401	search in the container directory of the source file. If you are using
1402	such a compiler you can avoid the problem for Fortran compilation
1403	although this does not fix the problem entirely if you have switched on
1404	the pre-processing stage. Otherwise you may have to work around the
1405	problem, (e.g. by making a comment change in the source file, or by not
1406	using an inherited build at all).</p>
1407	</dd>
1408	</dl>
1409
1410	<h3 id="advanced_data">Building data files</h3>
1411
1412	<p>While the usual targets to be built are the executables associated with
1413	source files containing main programs, libraries or scripts, the build system
1414	also allows you to build <em>data</em> files. All files with no registered
1415	type are considered to be <em>data</em> files. For each container
1416	sub-package, there is an automatic target for copying all <em>data</em> files
1417	to the <samp>etc/</samp> sub-directory of the build root. The name of the
1418	target has the form <code><pcks>.etc</code>, where <pcks> is the
1419	name of the sub-package (with package names delimited by the double
1420	underscore <code>__</code>). For example, the target name for sub-package
1421	<samp>foo/bar</samp> is <samp>foo__bar.etc</samp>. This target is
1422	particularly useful for copying, say, all namelists in a sub-package to the
1423	<samp>etc/</samp> sub-directory of the build root.</p>
1424
1425	<p>At the end of a successful build, if the <samp>etc/</samp> sub-directory
1426	is not empty, the <samp>fcm_env.sh</samp> script will export the environment
1427	variable <var>FCM_ETCDIR</var> to point to the <samp>etc/</samp>
1428	sub-directory. You should be able to use this environment variable to locate
1429	your data files.</p>
1430
1431	<h2 id="verbose">Diagnostic verbose level</h2>
1432
1433	<p>The amount of diagnostic messages generated by the build system is
1434	normally set to a level suitable for normal everyday operation. This is the
1435	default diagnostic verbose level 1. If you want a minimum amount of
1436	diagnostic messages, you should set the verbose level to 0. If you want more
1437	diagnostic messages, you can set the verbose level to 2 or 3. You can modify
1438	the verbose level in two ways. The first way is to set the environment
1439	variable <var>FCM_VERBOSE</var> to the desired verbose level. The second way
1440	is to invoke the build system with the <code>-v <level></code> option.
1441	(If set, the command line option overrides the environment variable.)</p>
1442
1443	<p>The following is a list of diagnostic output at each verbose level:</p>
1444
1445	<dl>
1446	<dt>Level 0</dt>
1447
1448	<dd>
1449	<ul>
1450	<li>Report the time taken at the end of each stage of the build
1451	process.</li>
1452
1453	<li>Run the <code>make</code> command in silent mode.</li>
1454	</ul>
1455	</dd>
1456
1457	<dt>Level 1</dt>
1458
1459	<dd>
1460	<ul>
1461	<li>Everything at verbose level 0.</li>
1462
1463	<li>Report the name of the build configuration file.</li>
1464
1465	<li>Report the location of the build destination.</li>
1466
1467	<li>Report date/time at the beginning of each stage of the build
1468	process.</li>
1469
1470	<li>Report removed directories.</li>
1471
1472	<li>Report number of pre-processed files.</li>
1473
1474	<li>Report number of generated F9X interface files.</li>
1475
1476	<li>Report number of source files scanned for dependencies.</li>
1477
1478	<li>Report name of updated <samp>Makefile</samp>.</li>
1479
1480	<li>Print compiler/linker commands.</li>
1481
1482	<li>Report total time.</li>
1483	</ul>
1484	</dd>
1485
1486	<dt>Level 2</dt>
1487
1488	<dd>
1489	<ul>
1490	<li>Everything at verbose level 1.</li>
1491
1492	<li>For incremental build in archive mode, report the commands used to
1493	extract the archives.</li>
1494
1495	<li>Report creation and removal of directories.</li>
1496
1497	<li>Report pre-processor commands.</li>
1498
1499	<li>Print compiler/linker commands with timestamps.</li>
1500	</ul>
1501	</dd>
1502
1503	<dt>Level 3</dt>
1504
1505	<dd>
1506	<ul>
1507	<li>Everything at verbose level 2.</li>
1508
1509	<li>Report update of dummy files.</li>
1510
1511	<li>Report all shell commands.</li>
1512
1513	<li>Report pre-processor commands with timestamps.</li>
1514
1515	<li>Report any F9X interface files generated.</li>
1516
1517	<li>Report number of lines and number of automatic dependencies for
1518	each source file which is scanned.</li>
1519
1520	<li>Run <code>make</code> on normal mode (as opposed to silent
1521	mode).</li>
1522
1523	<li>Report start date/time and time taken of <code>make</code>
1524	commands.</li>
1525	</ul>
1526	</dd>
1527	</dl>
1528
1529	<h2 id="overview">Overview of the build process</h2>
1530
1531	<p>The FCM build process can be summarised in five stages. Here is a summary
1532	of what is done in each stage:</p>
1533
1534	<ol>
1535	<li><dfn>Parse configuration and setup destination</dfn>: in this
1536	pre-requisite stage, the build system parses the configuration file. The
1537	<samp>src/</samp> sub-directory is searched recursively for source files.
1538	For full builds, it ensures that the sub-directories and files created by
1539	the build system are removed. If you invoke <code>fcm build</code> with a
1540	<code>--clean</code> option, the system will not go any further.</li>
1541
1542	<li><dfn>Setup build</dfn>: in this first stage, the system determines
1543	whether any settings have changed by using the cache. If so, the cache is
1544	updated with the current settings.</li>
1545
1546	<li><dfn>Pre-process</dfn>: if any files in any source files require
1547	pre-processing, they will be pre-processed at this stage. The resulting
1548	pre-processed source files will be sent to the <samp>ppsrc/</samp>
1549	sub-directory of the build root.</li>
1550
1551	<li><dfn>Generate dependency</dfn>: the system scans source files of
1552	registered types for dependency information. For an incremental build, the
1553	information is only updated if a source file is changed. The system then
1554	uses the information to write a <samp>Makefile</samp> for the main
1555	build.</li>
1556
1557	<li><dfn>Generate interface</dfn>: if there are Fortran 9X source files
1558	with standalone subroutines and functions, the build system generates
1559	interface blocks for them. The result of which will be written to the
1560	interface files in the <samp>inc/</samp> sub-directory of the build
1561	root.</li>
1562
1563	<li>
1564	<dfn>Make</dfn>: the system invokes <code>make</code> on the
1565	<samp>Makefile</samp> generated in the previous stage to perform the main
1566	build. Following a build, the <em>root</em> directory of the build may
1567	contain the following sub-directories (empty ones are removed
1568	automatically at the end of the build process):
1569
1570	<dl>
1571	<dt><samp>.cache/.bld/</samp></dt>
1572
1573	<dd>Cache files, used internally by FCM.</dd>
1574
1575	<dt><samp>bin/</samp></dt>
1576
1577	<dd>Executable binaries and scripts.</dd>
1578
1579	<dt><samp>cfg/</samp></dt>
1580
1581	<dd>Configuration files.</dd>
1582
1583	<dt><samp>done/</samp></dt>
1584
1585	<dd>Dummy <em>done</em> files used internally by the
1586	<samp>Makefile</samp> generated by FCM.</dd>
1587
1588	<dt><samp>etc/</samp></dt>
1589
1590	<dd>Miscellaneous data files.</dd>
1591
1592	<dt><samp>flags/</samp></dt>
1593
1594	<dd>Dummy <em>flags</em> files used internally by the
1595	<samp>Makefile</samp> generated by FCM.</dd>
1596
1597	<dt><samp>inc/</samp></dt>
1598
1599	<dd>Include files, such as <samp>.h</samp>, <samp>.inc</samp>,
1600	<samp>.interface</samp>, and <samp>.mod</samp>.</dd>
1601
1602	<dt><samp>lib/</samp></dt>
1603
1604	<dd>Object library archives.</dd>
1605
1606	<dt><samp>obj/</samp></dt>
1607
1608	<dd>Compiled object files.</dd>
1609
1610	<dt><samp>ppsrc/</samp></dt>
1611
1612	<dd>Source directories with pre-processed files.</dd>
1613
1614	<dt><samp>src/</samp></dt>
1615
1616	<dd>Source directories. This directory is not changed by the build
1617	system.</dd>
1618
1619	<dt><samp>tmp/</samp></dt>
1620
1621	<dd>Temporary objects and binaries. Files generated by the
1622	compiler/linker may be left here.</dd>
1623	</dl>
1624	</li>
1625	</ol>
1626
1627	</div>
1628	</div>
1629	</div>
1630
1631	<hr/>
1632	<div class="container-fluid text-center">
1633	<div class="row"><div class="col-md-12">
1634	<address><small>
1635	© British Crown Copyright 2006-16
1636	<a href="http://www.metoffice.gov.uk">Met Office</a>.
1637	See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
1638	This document is released under the British <a href=
1639	"http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
1640	"license">Open Government Licence</a>.<br />
1641	</small></address>
1642	</div></div>
1643	</div>
1644
1645	<script type="text/javascript" src="../etc/jquery.min.js"></script>
1646	<script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
1647	<script type="text/javascript" src="../etc/fcm.js"></script>
1648	<script type="text/javascript" src="../etc/fcm-version.js"></script>
1649	</body>
1650	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: