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