Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Normal
Revision Log

build.html @ 5456

Last change on this file since 5456 was 1578, checked in by jghattas, 13 years ago

Add fcm in LMDZ5/tools directory

It is no longer needed to have fcm in your environement PATH variable.
Now makelmdz_fcm takes by default this fcm. It is still possible to use
another fcm, using -fcm_path argument in makelmdz_fcm.

File size: 77.7 KB

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

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

Context Navigation

source: LMDZ5/trunk/tools/fcm/doc/user_guide/build.html @ 5456

Download in other formats: