source: codes/icosagcm/trunk/tools/FCM/doc/user_guide/annex_bld_cfg.html @ 10

Last change on this file since 10 was 10, checked in by ymipsl, 12 years ago

dynamico tree creation

YM
File size: 35.8 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <title>FCM System User Guide Annex: Declarations in FCM build
6  configuration file</title>
7  <meta name="author" content="FCM development team">
8  <meta name="descriptions" content="User Guide Annex">
9  <meta name="keywords" content="FCM, user guide, annex">
10  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11  <link rel="stylesheet" type="text/css" href="style.css">
12</head>
13
14<body>
15  <address>
16    <a href="index.html">FCM System User Guide</a> &gt; Annex: Declarations in
17    FCM build configuration file
18  </address>
19
20  <h1>Annex:<br>
21  Declarations in FCM build configuration file</h1>
22
23  <p>The following is a list of supported declarations for the configuration
24  file used by the FCM build system. Unless otherwise stated, the fields in
25  all declaration labels are not case sensitive. Build declarations can be
26  made either in a build configuration file or in an extract configuration
27  file. In the latter case, the prefix "BLD::" must be added at the beginning
28  of each label to inform the extract system that the declaration is a build
29  system declaration. (In a build configuration file, the prefix "BLD::" is
30  optional.)</p>
31
32  <table class="pad" summary="Declarations in build configuration file"
33  width="100%" border="1">
34    <tr>
35      <th>Label</th>
36
37      <th colspan="2">Content</th>
38    </tr>
39
40    <tr>
41      <th rowspan="2">CFG::TYPE</th>
42
43      <th>Description</th>
44
45      <td>The configuration file type, the value should always be "bld" for a
46      build configuration file. This declaration is compulsory for all
47      build configuration files. (This declaration is automatic when the
48      extract system creates a build configuration file.)</td>
49    </tr>
50
51    <tr>
52      <th>Example</th>
53
54      <td>
55        <pre>
56cfg::type  bld
57</pre>
58      </td>
59    </tr>
60
61    <tr>
62      <th rowspan="2">CFG::VERSION</th>
63
64      <th>Description</th>
65
66      <td>The file format version, currently "1.0" - a version is included so
67      that we shall be able to read the configuration file correctly should we
68      decide to change its format in the future. (This declaration is automatic
69      when the extract system creates a build configuration file.)</td>
70    </tr>
71
72    <tr>
73      <th>Example</th>
74
75      <td>
76        <pre>
77cfg::version  1.0
78</pre>
79      </td>
80    </tr>
81
82    <tr>
83      <th rowspan="2">TARGET</th>
84
85      <th>Description</th>
86
87      <td>Specify the targets for the build. Multiple targets can be declared in
88      one or more declarations. These targets become the dependencies of the
89      default "all" target in the <em>Makefile</em>.</td>
90    </tr>
91
92    <tr>
93      <th>Example</th>
94
95      <td>
96        <pre>
97target  VarScr_AnalysePF VarScr_CovAccStats
98target  VarScr_CovPFstats
99</pre>
100      </td>
101    </tr>
102
103    <tr>
104      <th rowspan="2">DIR::ROOT</th>
105
106      <th>Description</th>
107
108      <td>The root directory of the build. It must be declared for each build.
109      (This declaration is automatic when the extract system creates a build
110      configuration file. The value is normally the root path of the
111      extraction destination.)</td>
112    </tr>
113
114    <tr>
115      <th>Example</th>
116
117      <td>
118        <pre>
119dir::root  $HOME/my_build
120</pre>
121      </td>
122    </tr>
123
124    <tr>
125      <th>Label</th>
126
127      <th colspan="2">Content</th>
128    </tr>
129
130    <tr>
131      <th rowspan="2">SRC::&lt;pcks&gt;</th>
132
133      <th>Description</th>
134
135      <td>This declares a source directory in the sub-package &lt;pcks&gt;.
136      The name of the sub-package &lt;pcks&gt; must be unique. Package names
137      are delimited by double colons "::" or double underscores "__". (This
138      declaration is automatic when the extract system creates the build
139      configuration file. The list of declared source directories will be the
140      list of extracted source directories.)</td>
141    </tr>
142
143    <tr>
144      <th>Example</th>
145
146      <td>
147        <pre>
148src::var::code::VarMod_PF  $HOME/my_build/src/var/code/VarMod_PF
149</pre>
150      </td>
151    </tr>
152
153    <tr>
154      <th rowspan="2">SEARCH_SRC</th>
155
156      <th>Description</th>
157
158      <td>This declares a flag to determine whether the build system should
159      search the source sub-directory of the build root for a list of source
160      directories. The automatic search is useful if the build system is
161      invoked standalone and the source sub-directory contains the full source
162      tree of the build. The default is to search (1). Set the flag to 0 to
163      switch off the behaviour. (When the extract system creates a build
164      configuration file, it declares all source directories. Searching of the
165      source sub-directory should not be required, and so this flag is
166      automatically set to 0.)</td>
167    </tr>
168
169    <tr>
170      <th>Example</th>
171
172      <td>
173        <pre>
174search_src  0
175</pre>
176      </td>
177    </tr>
178
179    <tr>
180      <th rowspan="2">EXE_DEP[::&lt;target&gt;]</th>
181
182      <th>Description</th>
183
184      <td>This declares an extra dependency for either all main program targets
185      or only &lt;target&gt; if it is specified. If &lt;target&gt; is specified,
186      it must be the name of a main program target. The value of the declaration
187      is a space delimited list. Each item in the list can either be a valid
188      name of a sub-package or the name of a valid object target. If a
189      sub-package name is used, the <em>make</em> rule for the main program will
190      be set to depend on all (non-program) object files within the
191      sub-package.</td>
192    </tr>
193
194    <tr>
195      <th>Example</th>
196
197      <td>
198        <pre>
199# Only foo.exe to depend on the package foo::bar and egg.o
200exe_dep::foo.exe  foo::bar egg.o
201
202# All executables to depend on the package foo::bar and egg.o
203exe_dep  foo::bar egg.o
204
205# Only foo.exe to depend on all objects
206exe_dep::foo.exe
207
208# All executables to depend on all objects
209exe_dep
210</pre>
211      </td>
212    </tr>
213
214    <tr>
215      <th rowspan="2">BLOCKDATA[::&lt;target&gt;]</th>
216
217      <th>Description</th>
218
219      <td>This declares a BLOCKDATA dependency for either all main program targets
220      or only &lt;target&gt; if it is specified. If &lt;target&gt; is specified,
221      it must be the name of a main program target. The value of the declaration
222      is a space delimited list. Each item in the list must be the name of a
223      valid object target containing a Fortran BLOCKDATA program unit.</td>
224    </tr>
225
226    <tr>
227      <th>Example</th>
228
229      <td>
230        <pre>
231# Only foo.exe to depend on blkdata.o
232blockdata::foo.exe  blkdata.o
233
234# All executables to depend on fbd.o
235blockdata  fbd.o
236</pre>
237      </td>
238    </tr>
239
240    <tr>
241      <th rowspan="2">EXE_NAME::&lt;name&gt;</th>
242
243      <th>Description</th>
244
245      <td>This renames the executable target of a main program source file
246      &lt;name&gt; to the specified value.</td>
247    </tr>
248
249    <tr>
250      <th>Example</th>
251
252      <td>
253        <pre>
254# Rename the executable target name of foo.f90 from "foo.exe" to "bar"
255exe_name::foo  bar
256</pre>
257      </td>
258    </tr>
259
260    <tr>
261      <th rowspan="2">LIB[::&lt;pcks&gt;]</th>
262
263      <th>Description</th>
264
265      <td>This declares the name of a library archive target. If &lt;pcks&gt; is
266      specified in the label, the declaration applies to the library archive
267      target for that sub-package only. If set, the name of the library archive
268      target will be named "lib&lt;value&gt;.a", where &lt;value&gt; is the
269      value of the declaration. If not specified, the default is to name the
270      global library "libfcm_default.a". For a library archive of a sub-package,
271      the default is to name its library after the name of the sub-package.</td>
272    </tr>
273
274    <tr>
275      <th>Example</th>
276
277      <td>
278        <pre>
279# Rename the top level library "libfoo.a"
280lib  foo
281
282# Rename the library for the sub-package "egg::ham"
283# from "libegg__ham.a" to "libegg-ham.a"
284lib::egg::ham  egg-ham
285</pre>
286      </td>
287    </tr>
288
289    <tr>
290      <th rowspan="2">PP[::&lt;pcks&gt;]</th>
291
292      <th>Description</th>
293
294      <td>This declares whether a pre-processing stage is required. To switch on
295      pre-processing, set the value to 1. If &lt;pcks&gt; is specified
296      in the label, the flag applies to the files within that sub-package
297      only. Otherwise, the flag affects source directories in all packages.
298      The pre-processing stage is useful if the pre-processor changes the
299      dependency and/or the argument list of the source files. The default
300      behaviour is skip the pre-processing stage for all source
301      directories.</td>
302    </tr>
303
304    <tr>
305      <th>Example</th>
306
307      <td>
308        <pre>
309pp::gen 1  # switch on pre-processing for sub-packages in "gen"
310pp      1  # switch on pre-processing globally
311</pre>
312      </td>
313    </tr>
314
315    <tr>
316      <th rowspan="2">TOOL::&lt;label&gt;[::&lt;pcks&gt;]</th>
317
318      <th>Description</th>
319
320      <td>This declaration is used to specify a build "tool" such as the
321      Fortran compiler or its flags. The &lt;label&gt; determines the "tool"
322      you are declaring. If a sub-package &lt;pcks&gt; is specified, the
323      declaration applies only to the files and directories under the
324      sub-package.  Otherwise, the declaration applies globally. A list of
325      &lt;label&gt; fields is available <a href="#tools-list">later in this
326      section</a>.</td>
327    </tr>
328
329    <tr>
330      <th>Example</th>
331
332      <td>
333        <pre>
334tool::fc      sxmpif90
335tool::fflags  -Chopt -Pstack
336
337tool::cc      sxmpic++
338tool::cflags  -O nomsg -pvctl nomsg
339
340tool::ar      sxar
341</pre>
342      </td>
343    </tr>
344
345    <tr>
346      <th>Label</th>
347
348      <th colspan="2">Content</th>
349    </tr>
350
351    <tr>
352      <th rowspan="2">EXCL_DEP[::&lt;pcks&gt;]</th>
353
354      <th>Description</th>
355
356      <td>
357        This declaration is used to specify whether a particular dependency
358        should be ignored during the automatic dependency scan. If a sub-package
359        &lt;pcks&gt; is specified, the declaration applies only to the files and
360        directories under the sub-package. Otherwise, the declaration applies
361        globally. It is worth noting that the build system is not yet clever
362        enough to recognise changes in this declaration in incremental builds.
363        Therefore, users should manually trigger a full build if these
364        statements are modified. The value of this declaration must contain one
365        or two fields (separated by the double colon "::"). The first field
366        denotes the dependency type, and the second field is the dependency
367        target. If the second field is specified, it will only exclude the
368        dependency to the specified target. Otherwise, it will exclude all
369        dependency to the specified type. The following dependency types are
370        supported:
371
372        <a name="dependency-types"></a>
373
374        <table summary="dependency types" border="1">
375          <tr>
376            <th>Dependency type</th>
377
378            <th>Description</th>
379          </tr>
380
381          <tr>
382            <th>USE</th>
383
384            <td>The dependency target is a Fortran module.</td>
385          </tr>
386
387          <tr>
388            <th>INTERFACE</th>
389
390            <td>The dependency target is a Fortran 9X interface block file.</td>
391          </tr>
392
393          <tr>
394            <th>INC</th>
395
396            <td>The dependency target is a Fortran INCLUDE file.</td>
397          </tr>
398
399          <tr>
400            <th>H</th>
401
402            <td>The dependency target is a pre-processor #include header
403            file.</td>
404          </tr>
405
406          <tr>
407            <th>OBJ</th>
408
409            <td>The dependency target is a compiled binary object file.</td>
410          </tr>
411
412          <tr>
413            <th>EXE</th>
414
415            <td>The dependency target is an executable binary or script.</td>
416          </tr>
417        </table>
418
419        <p>N.B. The following dependency targets are in the default list of
420        excluded dependencies:</p>
421
422        <ul>
423          <li>
424            Intrinsic Fortran modules:
425
426            <ul>
427              <li>USE::ISO_C_BINDING</li>
428
429              <li>USE::IEEE_EXCEPTIONS</li>
430
431              <li>USE::IEEE_ARITHMETIC</li>
432
433              <li>USE::IEEE_FEATURES</li>
434            </ul>
435          </li>
436
437          <li>
438            Intrinsic Fortran subroutines:
439
440            <ul>
441              <li>OBJ::CPU_TIME</li>
442
443              <li>OBJ::GET_COMMAND</li>
444
445              <li>OBJ::GET_COMMAND_ARGUMENT</li>
446
447              <li>OBJ::GET_ENVIRONMENT_VARIABLE</li>
448
449              <li>OBJ::MOVE_ALLOC</li>
450
451              <li>OBJ::MVBITS</li>
452
453              <li>OBJ::RANDOM_NUMBER</li>
454
455              <li>OBJ::RANDOM_SEED</li>
456
457              <li>OBJ::SYSTEM_CLOCK</li>
458            </ul>
459          </li>
460
461          <li>
462            Dummy declarations:
463
464            <ul>
465              <li>OBJ::NONE</li>
466
467              <li>EXE::NONE</li>
468            </ul>
469          </li>
470        </ul>
471      </td>
472    </tr>
473
474    <tr>
475      <th>Example</th>
476
477      <td>
478        <pre>
479excl_dep  USE::YourFortranMod
480excl_dep  INTERFACE::HerFortran.interface
481excl_dep  INC::HisFortranInc.inc
482excl_dep  H::TheirHeader.h
483excl_dep  OBJ
484excl_dep  EXE
485</pre>
486      </td>
487    </tr>
488
489    <tr>
490      <th>Label</th>
491
492      <th colspan="2">Content</th>
493    </tr>
494
495    <tr>
496      <th rowspan="2">INFILE_EXT::&lt;ext&gt;</th>
497
498      <th>Description</th>
499
500      <td>
501        This declaration is used to re-register particular file name
502        extensions &lt;ext&gt; to associate with different file types. The
503        value of the declaration is a list of type flags delimited by the
504        double colon "::". Each type flag is used internally to describe the
505        nature of the file. For example, a Fortran free source form containing
506        a main program is registered as
507        <tt>"FORTRAN::FORTRAN9X::SOURCE::PROGRAM"</tt>. The following is a
508        list of type flags that are currently in-use (or <span class="gray">*
509        reserved</span>) by the build system:
510
511        <a name="infile-ext-types"></a>
512
513        <table summary="input file extension type flags" border="1">
514          <tr>
515            <th>Flag</th>
516
517            <th>Description</th>
518          </tr>
519
520          <tr>
521            <td class="mono">SOURCE</td>
522
523            <td>a source file containing program code of a supported language
524            (currently Fortran, FPP, C and CPP).</td>
525          </tr>
526
527          <tr>
528            <td class="mono">INCLUDE</td>
529
530            <td>an include file containing program code of a supported language
531            (currently Fortran, FPP, C and CPP).</td>
532          </tr>
533
534          <tr>
535            <td class="mono">FORTRAN</td>
536
537            <td>a file containing Fortran code.</td>
538          </tr>
539
540          <tr>
541            <td class="mono">FORTRAN9X</td>
542
543            <td>a file containing the Fortran free source form. This word must be
544            used in conjunction with the word "FORTRAN".</td>
545          </tr>
546
547          <tr>
548            <td class="mono">FPP</td>
549
550            <td>a file containing Fortran code requiring pre-processing.</td>
551          </tr>
552
553          <tr>
554            <td class="mono">FPP9X</td>
555
556            <td>a file containing Fortran free source form requiring
557            pre-processing. This word must be used in conjunction with the word
558            "FPP".</td>
559          </tr>
560
561          <tr>
562            <td class="mono">C</td>
563
564            <td>a file containing C code.</td>
565          </tr>
566
567          <tr>
568            <td class="mono">CPP</td>
569
570            <td>a file containing CPP include header.</td>
571          </tr>
572
573          <tr>
574            <td class="mono">INTERFACE</td>
575
576            <td>a file containing a Fortran 9X interface block.</td>
577          </tr>
578
579          <tr>
580            <td class="mono">PROGRAM</td>
581
582            <td>a file containing a main program.</td>
583          </tr>
584
585          <tr>
586            <td class="mono">MODULE</td>
587
588            <td>a file containing a Fortran 9X module.</td>
589          </tr>
590
591          <tr>
592            <td class="mono">BINARY</td>
593
594            <td>a binary file.</td>
595          </tr>
596
597          <tr>
598            <td class="mono">EXE</td>
599
600            <td>an executable file. This word must be used in conjunction with
601            the word "BINARY".</td>
602          </tr>
603
604          <tr>
605            <td class="mono">LIB</td>
606
607            <td>an archive library. This word must be used in conjunction with
608            the word "BINARY".</td>
609          </tr>
610
611          <tr>
612            <td class="mono">SCRIPT</td>
613
614            <td>a file containing source code of a scripting language.</td>
615          </tr>
616
617          <tr>
618            <td class="mono">PVWAVE</td>
619
620            <td>a file containing executable PVWAVE scripts. This word must be
621            used in conjunction with the word "SCRIPT".</td>
622          </tr>
623
624          <tr>
625            <td class="mono">SQL</td>
626
627            <td>a file containing SQL scripts. This word must be used in
628            conjunction with the word "SCRIPT".</td>
629          </tr>
630
631          <tr>
632            <td class="mono">GENLIST</td>
633
634            <td>a GEN List file.</td>
635          </tr>
636
637          <tr class="gray">
638            <td class="mono">OBJ</td>
639
640            <td>(* reserved) an object file. This word must be used in
641            conjunction with the word "BINARY".</td>
642          </tr>
643
644          <tr class="gray">
645            <td class="mono">SHELL</td>
646
647            <td>(* reserved) a file containing executable shell scripts. This
648            word must be used in conjunction with the word "SCRIPT".</td>
649          </tr>
650
651          <tr class="gray">
652            <td class="mono">PERL</td>
653
654            <td>(* reserved) a file containing executable Perl scripts. This
655            word must be used in conjunction with the word "SCRIPT".</td>
656          </tr>
657
658          <tr class="gray">
659            <td class="mono">PYTHON</td>
660
661            <td>(* reserved) a file containing executable Python scripts. This
662            word must be used in conjunction with the word "SCRIPT".</td>
663          </tr>
664
665          <tr class="gray">
666            <td class="mono">TCL</td>
667
668            <td>(* reserved) a file containing executable TCL scripts. This
669            word must be used in conjunction with the word "SCRIPT".</td>
670          </tr>
671        </table>
672      </td>
673    </tr>
674
675    <tr>
676      <th>Example</th>
677
678      <td>
679        <pre>
680infile_ext::h90  CPP::INCLUDE
681infile_ext::inc  FORTRAN::FORTRAN9X::INCLUDE
682</pre>
683      </td>
684    </tr>
685
686    <tr>
687      <th rowspan="2">OUTFILE_EXT::&lt;type&gt;</th>
688
689      <th>Description</th>
690
691      <td>
692        This declaration is used to re-register the output file extension
693        for a particular &lt;type&gt; of output files. The value must be a
694        valid file extension. The following is a list of output file types
695        in-use by the build system:
696
697        <a name="outfile-ext-types"></a>
698
699        <table summary="output file extension types" border="1">
700          <tr>
701            <th>Type</th>
702
703            <th>Description</th>
704
705            <th>Default</th>
706          </tr>
707
708          <tr>
709            <td class="mono">MK</td>
710
711            <td>dependency files, <em>Makefile</em> fragments</td>
712
713            <td class="mono">.mk</td>
714          </tr>
715
716          <tr>
717            <td class="mono">OBJ</td>
718
719            <td>compiled object files</td>
720
721            <td class="mono">.o</td>
722          </tr>
723
724          <tr>
725            <td class="mono">MOD</td>
726
727            <td>compiled Fortran module information files</td>
728
729            <td class="mono">.mod</td>
730          </tr>
731
732          <tr>
733            <td class="mono">EXE</td>
734
735            <td>binary executables</td>
736
737            <td class="mono">.exe</td>
738          </tr>
739
740          <tr>
741            <td class="mono">DONE</td>
742
743            <td>"done" files for compiled source</td>
744
745            <td class="mono">.done</td>
746          </tr>
747
748          <tr>
749            <td class="mono">IDONE</td>
750
751            <td>"done" files for included source</td>
752
753            <td class="mono">.idone</td>
754          </tr>
755
756          <tr>
757            <td class="mono">FLAGS</td>
758
759            <td>"flags" files, compiler flags config</td>
760
761            <td class="mono">.flags</td>
762          </tr>
763
764          <tr>
765            <td class="mono">INTERFACE</td>
766
767            <td>interface files for F9X standalone subroutines/functions</td>
768
769            <td class="mono">.interface</td>
770          </tr>
771
772          <tr>
773            <td class="mono">LIB</td>
774
775            <td>archive object library</td>
776
777            <td class="mono">.a</td>
778          </tr>
779
780          <tr>
781            <td class="mono">TAR</td>
782
783            <td>TAR archive</td>
784
785            <td class="mono">.tar</td>
786          </tr>
787        </table>
788      </td>
789    </tr>
790
791    <tr>
792      <th>Example</th>
793
794      <td>
795        <pre>
796# Output F9X interface files will now have ".foo" extension
797outfile_ext::interface  .foo
798</pre>
799      </td>
800    </tr>
801
802    <tr>
803      <th>Label</th>
804
805      <th colspan="2">Content</th>
806    </tr>
807
808    <tr>
809      <th rowspan="2">INC</th>
810
811      <th>Description</th>
812
813      <td>This declares the name of a file containing build configuration. The
814      lines in the declared file will be included inline to the current build
815      configuration file.</td>
816    </tr>
817
818    <tr>
819      <th>Example</th>
820
821      <td>
822        <pre>
823inc  ~frva/var_stable_22.0/cfg/bld.cfg
824# ... and then your changes ...
825</pre>
826      </td>
827    </tr>
828
829    <tr>
830      <th rowspan="2">USE</th>
831
832      <th>Description</th>
833
834      <td>This declares a pre-compiled build, which the current build is
835      dependent on. The value must be must be either the configuration file or
836      the root directory of a successful build. Output of the pre-compiled
837      build, the build tools, the exclude dependency declarations, the file
838      type registers declarations are automatically inherited from the
839      pre-compiled build. Source directories, build targets and pre-processing
840      stage declarations may be inherited depending on the INHERIT
841      declarations. (If you have a USE declaration in an extraction, the
842      resulting build configuration file will contain an automatic USE
843      declaration, which expects a pre-compiled build at the destination of
844      the extraction.)</td>
845    </tr>
846
847    <tr>
848      <th>Example</th>
849
850      <td>
851        <pre>
852# Use VAR build 22.0
853USE  ~frva/var_22.0
854</pre>
855      </td>
856    </tr>
857
858    <tr>
859      <th rowspan="2">INHERIT::&lt;name&gt;[::&lt;pcks&gt;]</th>
860
861      <th>Description</th>
862
863      <td>This declares whether build targets (&lt;name&gt; = "target"),
864      source directories (&lt;name&gt; = "src") and pre-processing stage
865      declarations (&lt;name&gt; = "pp") are inherited from pre-compiled builds
866      declared by the USE statement. By default, source directories and
867      pre-processing stage declarations are inherited from pre-compiled
868      builds, while build targets are not. Use the value 1 to switch on
869      inheritance, or 0 to switch off. For source directories and
870      pre-processing stage declarations, the name of a sub-package
871      &lt;pcks&gt; can be specified. If a sub-package pcks is specified, the
872      declaration applies only to the files and directories under the
873      sub-package. Otherwise, the declaration applies globally.</td>
874    </tr>
875
876    <tr>
877      <th>Example</th>
878
879      <td>
880        <pre>
881inherit::target   1
882inherit::src      0
883inherit::pp::gen  0
884</pre>
885      </td>
886    </tr>
887
888    <tr>
889      <th rowspan="2">%&lt;name&gt;</th>
890
891      <th>Description</th>
892
893      <td>%&lt;name&gt; declares an internal variable &lt;name&gt; that
894      can later be re-used.</td>
895    </tr>
896
897    <tr>
898      <th>Example</th>
899
900      <td>
901        <pre>
902%my_variable  foo
903src::bar      %my_variable
904src::egg      %my_variable
905src::ham      %my_variable
906</pre>
907      </td>
908    </tr>
909
910    <tr>
911      <th>Label</th>
912
913      <th colspan="2">Content</th>
914    </tr>
915  </table>
916
917  <p><a name="tools-list"></a>The following is a list of &lt;label&gt; fields
918  that can be used with a TOOL::&lt;label&gt;[::&lt;pcks&gt;]
919  declaration:</p>
920
921  <table class="pad" summary="list of tools" width="100%" border="1">
922    <tr>
923      <th>Label</th>
924
925      <th>Description</th>
926
927      <th>Default</th>
928    </tr>
929
930    <tr>
931      <th>FC</th>
932
933      <td>The Fortran compiler.</td>
934
935      <td class="mono">"f90"</td>
936    </tr>
937
938    <tr>
939      <th>FFLAGS</th>
940
941      <td>Options used by the Fortran compiler.</td>
942
943      <td class="mono">""</td>
944    </tr>
945
946    <tr>
947      <th>FC_COMPILE</th>
948
949      <td>The option used by the Fortran compiler to suppress the
950      linking stage.</td>
951
952      <td class="mono">"-c"</td>
953    </tr>
954
955    <tr>
956      <th>FC_INCLUDE</th>
957
958      <td>The option used by the Fortran compiler to specify the
959      "include" search path.</td>
960
961      <td class="mono">"-I"</td>
962    </tr>
963
964    <tr>
965      <th>FC_DEFINE</th>
966
967      <td>The option used by the Fortran compiler to define a
968      pre-processor definition macro.</td>
969
970      <td class="mono">"-D"</td>
971    </tr>
972
973    <tr>
974      <th>FC_OUTPUT</th>
975
976      <td>The option used by the Fortran compiler to specify the output
977      file name.</td>
978
979      <td class="mono">"-o"</td>
980    </tr>
981
982    <tr>
983      <th>CC</th>
984
985      <td>The C compiler.</td>
986
987      <td class="mono">"cc"</td>
988    </tr>
989
990    <tr>
991      <th>CFLAGS</th>
992
993      <td>Options used by the C compiler.</td>
994
995      <td class="mono">""</td>
996    </tr>
997
998    <tr>
999      <th>CC_COMPILE</th>
1000
1001      <td>The option used by the C compiler to suppress the
1002      linking stage.</td>
1003
1004      <td class="mono">"-c"</td>
1005    </tr>
1006
1007    <tr>
1008      <th>CC_INCLUDE</th>
1009
1010      <td>The option used by the C compiler to specify the
1011      "include" search path.</td>
1012
1013      <td class="mono">"-I"</td>
1014    </tr>
1015
1016    <tr>
1017      <th>CC_DEFINE</th>
1018
1019      <td>The option used by the C compiler to define a
1020      pre-processor definition macro.</td>
1021
1022      <td class="mono">"-D"</td>
1023    </tr>
1024
1025    <tr>
1026      <th>CC_OUTPUT</th>
1027
1028      <td>The option used by the C compiler to specify the output
1029      file name.</td>
1030
1031      <td class="mono">"-o"</td>
1032    </tr>
1033
1034    <tr>
1035      <th>LD</th>
1036
1037      <td>Name of the linker or loader for linking object files into an
1038      executable.</td>
1039
1040      <td class="mono">"ld"</td>
1041    </tr>
1042
1043    <tr>
1044      <th>LDFLAGS</th>
1045
1046      <td>The flags used by the linker or loader.</td>
1047
1048      <td class="mono">""</td>
1049    </tr>
1050
1051    <tr>
1052      <th>LD_OUTPUT</th>
1053
1054      <td>The option used by the linker or loader for the output file name
1055      (other than the default "a.out").</td>
1056
1057      <td class="mono">"-o"</td>
1058    </tr>
1059
1060    <tr>
1061      <th>LD_LIBSEARCH</th>
1062
1063      <td>The option used by the linker or loader for specifying the
1064      search path for link libraries.</td>
1065
1066      <td class="mono">"-L"</td>
1067    </tr>
1068
1069    <tr>
1070      <th>LD_LIBLINK</th>
1071
1072      <td>The option used by the linker or loader command for linking
1073      with a library.</td>
1074
1075      <td class="mono">"-l"</td>
1076    </tr>
1077
1078    <tr>
1079      <th>AR</th>
1080
1081      <td>The archive command.</td>
1082
1083      <td class="mono">"ar"</td>
1084    </tr>
1085
1086    <tr>
1087      <th>ARFLAGS</th>
1088
1089      <td>The options used for the archive command to create a
1090      library.</td>
1091
1092      <td class="mono">"rs"</td>
1093    </tr>
1094
1095    <tr>
1096      <th>FPP</th>
1097
1098      <td>The Fortran pre-processor command.</td>
1099
1100      <td class="mono">"cpp"</td>
1101    </tr>
1102
1103    <tr>
1104      <th>FPPKEYS</th>
1105
1106      <td>The Fortran pre-processor will pre-define each word in this
1107      setting as a macro.</td>
1108
1109      <td class="mono">""</td>
1110    </tr>
1111
1112    <tr>
1113      <th>FPPFLAGS</th>
1114
1115      <td>The options used by the Fortran pre-processor.</td>
1116
1117      <td class="mono">"-P -traditional"</td>
1118    </tr>
1119
1120    <tr>
1121      <th>FPP_DEFINE</th>
1122
1123      <td>The option used by the Fortran pre-processor to define a
1124      macro.</td>
1125
1126      <td class="mono">"-D"</td>
1127    </tr>
1128
1129    <tr>
1130      <th>FPP_INCLUDE</th>
1131
1132      <td>The option used by the Fortran pre-processor to specify the
1133      "include" search path.</td>
1134
1135      <td class="mono">"-I"</td>
1136    </tr>
1137
1138    <tr>
1139      <th>CPP</th>
1140
1141      <td>The C pre-processor command.</td>
1142
1143      <td class="mono">"cpp"</td>
1144    </tr>
1145
1146    <tr>
1147      <th>CPPKEYS</th>
1148
1149      <td>The C pre-processor will pre-define each word in this
1150      setting as a macro.</td>
1151
1152      <td class="mono">""</td>
1153    </tr>
1154
1155    <tr>
1156      <th>CPPFLAGS</th>
1157
1158      <td>The options used by the C pre-processor.</td>
1159
1160      <td class="mono">"-C"</td>
1161    </tr>
1162
1163    <tr>
1164      <th>CPP_DEFINE</th>
1165
1166      <td>The option used by the C pre-processor to define a
1167      macro.</td>
1168
1169      <td class="mono">"-D"</td>
1170    </tr>
1171
1172    <tr>
1173      <th>CPP_INCLUDE</th>
1174
1175      <td>The option used by the C pre-processor to specify the
1176      "include" search path.</td>
1177
1178      <td class="mono">"-I"</td>
1179    </tr>
1180
1181    <tr>
1182      <th>MAKE</th>
1183
1184      <td>The "make" command.</td>
1185
1186      <td class="mono">"make"</td>
1187    </tr>
1188
1189    <tr>
1190      <th>MAKEFLAGS</th>
1191
1192      <td>The options used by the "make" command</td>
1193
1194      <td class="mono">""</td>
1195    </tr>
1196
1197    <tr>
1198      <th>MAKE_SILENT</th>
1199
1200      <td>The option used by the "make" command to specify silent
1201      operation.</td>
1202
1203      <td class="mono">"-s"</td>
1204    </tr>
1205
1206    <tr>
1207      <th>MAKE_JOB</th>
1208
1209      <td>The option used by the "make" command to specify the number
1210      jobs to run simultaneously.</td>
1211
1212      <td class="mono">"-j"</td>
1213    </tr>
1214
1215    <tr>
1216      <th>GENINTERFACE</th>
1217
1218      <td>The command/method for generating interface for Fortran 9X
1219      standalone subroutines/functions. Supported values are "ECMWF",
1220      "f90aib" and "none". (The keyword "none" is used to switch off
1221      interface generation.)</td>
1222
1223      <td class="mono">"ECMWF"</td>
1224    </tr>
1225
1226    <tr>
1227      <th>INTERFACE</th>
1228
1229      <td>Generate Fortran 9X interface files with root names according to
1230      either the root name of the source "file" or the name of the "program"
1231      unit.</td>
1232
1233      <td class="mono">"file"</td>
1234    </tr>
1235
1236    <tr>
1237      <th>Label</th>
1238
1239      <th>Description</th>
1240
1241      <th>Default</th>
1242    </tr>
1243  </table>
1244
1245  <p class="gray">The following declarations are for reference only. They
1246  should not be used in normal operations of the FCM build system:</p>
1247
1248  <table class="pad" summary="Unused declarations in build configuration file"
1249  width="100%" border="1">
1250    <tr class="gray">
1251      <th>Label</th>
1252
1253      <th colspan="2">Content</th>
1254    </tr>
1255
1256    <tr class="gray">
1257      <th rowspan="2">DIR::BIN</th>
1258
1259      <th>Description</th>
1260
1261      <td>This declaration is optional and is not normally required. It is the
1262      "bin" directory, container of executable files created by the build.</td>
1263    </tr>
1264
1265    <tr class="gray">
1266      <th>Example</th>
1267
1268      <td>
1269        <pre>
1270dir::bin  $HOME/my_build/bin
1271</pre>
1272      </td>
1273    </tr>
1274
1275    <tr class="gray">
1276      <th rowspan="2">DIR::BLD</th>
1277
1278      <th>Description</th>
1279
1280      <td>This declaration is optional and is not normally required. It is the
1281      build directory, container of the <em>Makefile</em> and its fragments
1282      created by the build system.</td>
1283    </tr>
1284
1285    <tr class="gray">
1286      <th>Example</th>
1287
1288      <td>
1289        <pre>
1290dir::bld  $HOME/my_build/bld
1291</pre>
1292      </td>
1293    </tr>
1294
1295    <tr class="gray">
1296      <th rowspan="2">DIR::CACHE</th>
1297
1298      <th>Description</th>
1299
1300      <td>This declaration is optional and is not normally required. It is the
1301      cache directory, container of internal cache files used by the build
1302      system.</td>
1303    </tr>
1304
1305    <tr class="gray">
1306      <th>Example</th>
1307
1308      <td>
1309        <pre>
1310dir::cache $HOME/my_build/.cache
1311</pre>
1312      </td>
1313    </tr>
1314
1315    <tr class="gray">
1316      <th rowspan="2">DIR::CFG</th>
1317
1318      <th>Description</th>
1319
1320      <td>This declaration is optional and is not normally required. It is the
1321      configuration directory, container of the build configuration file. Not
1322      created by the build system.</td>
1323    </tr>
1324
1325    <tr class="gray">
1326      <th>Example</th>
1327
1328      <td>
1329        <pre>
1330dir::cfg $HOME/my_build/cfg
1331</pre>
1332      </td>
1333    </tr>
1334
1335    <tr class="gray">
1336      <th rowspan="2">DIR::DONE</th>
1337
1338      <th>Description</th>
1339
1340      <td>This declaration is optional and is not normally required. It is the
1341      "done" file directory, container of dummy "done" files created by the
1342      build process. A "done" file is used to indicate that all the external
1343      objects of an object files are compiled and ready to be used by the link
1344      process.</td>
1345    </tr>
1346
1347    <tr class="gray">
1348      <th>Example</th>
1349
1350      <td>
1351        <pre>
1352dir::done $HOME/my_build/done
1353</pre>
1354      </td>
1355    </tr>
1356
1357    <tr class="gray">
1358      <th rowspan="2">DIR::ETC</th>
1359
1360      <th>Description</th>
1361
1362      <td>This declaration is optional and is not normally required. It is the
1363      miscellaneous file directory, container of "data" files. "Data" files
1364      are files in the source sub-package without a registered type. It is
1365      possible for the user to tell the build system to copy all "data" files
1366      in a sub-package to this directory by "building" a dummy sub-package
1367      data file target.</td>
1368    </tr>
1369
1370    <tr class="gray">
1371      <th>Example</th>
1372
1373      <td>
1374        <pre>
1375dir::etc $HOME/my_build/etc
1376</pre>
1377      </td>
1378    </tr>
1379
1380    <tr class="gray">
1381      <th rowspan="2">DIR::FLAGS</th>
1382
1383      <th>Description</th>
1384
1385      <td>This declaration is optional and is not normally required. It is the
1386      "flags" file directory, container of dummy "flags" files created by the
1387      build process. A "flags" file is used to indicate to <em>make</em> that
1388      the compiler flags for a source file or a container package has
1389      changed.</td>
1390    </tr>
1391
1392    <tr class="gray">
1393      <th>Example</th>
1394
1395      <td>
1396        <pre>
1397dir::flags $HOME/my_build/flags
1398</pre>
1399      </td>
1400    </tr>
1401
1402    <tr class="gray">
1403      <th rowspan="2">DIR::INC</th>
1404
1405      <th>Description</th>
1406
1407      <td>This declaration is optional and is not normally required. It is the
1408      include directory, container of "include" files such as pre-processor
1409      header files, Fortran INCLUDE files, Fortran 9X interface files, and
1410      Fortran compiled module information files.</td>
1411    </tr>
1412
1413    <tr class="gray">
1414      <th>Example</th>
1415
1416      <td>
1417        <pre>
1418dir::inc $HOME/my_build/inc
1419</pre>
1420      </td>
1421    </tr>
1422
1423    <tr class="gray">
1424      <th rowspan="2">DIR::LIB</th>
1425
1426      <th>Description</th>
1427
1428      <td>This declaration is optional and is not normally required. It is the
1429      library directory, container of object library achive files created by
1430      the build.</td>
1431    </tr>
1432
1433    <tr class="gray">
1434      <th>Example</th>
1435
1436      <td>
1437        <pre>
1438dir::lib $HOME/my_build/lib
1439</pre>
1440      </td>
1441    </tr>
1442
1443    <tr class="gray">
1444      <th rowspan="2">DIR::OBJ</th>
1445
1446      <th>Description</th>
1447
1448      <td>This declaration is optional and is not normally required. It is the
1449      object directory, container of compiled object files created by the
1450      build process.</td>
1451    </tr>
1452
1453    <tr class="gray">
1454      <th>Example</th>
1455
1456      <td>
1457        <pre>
1458dir::obj $HOME/my_build/obj
1459</pre>
1460      </td>
1461    </tr>
1462
1463    <tr class="gray">
1464      <th rowspan="2">DIR::PPSRC</th>
1465
1466      <th>Description</th>
1467
1468      <td>This declaration is optional and is not normally required. It is the
1469      pre-processed source directory, container of pre-processed source files
1470      created by the build process.</td>
1471    </tr>
1472
1473    <tr class="gray">
1474      <th>Example</th>
1475
1476      <td>
1477        <pre>
1478dir::ppsrc $HOME/my_build/ppsrc
1479</pre>
1480      </td>
1481    </tr>
1482
1483    <tr class="gray">
1484      <th rowspan="2">DIR::SRC</th>
1485
1486      <th>Description</th>
1487
1488      <td>This declaration is optional and is not normally required. It is the
1489      source directory, container of the source tree. Not created by the build
1490      system.</td>
1491    </tr>
1492
1493    <tr class="gray">
1494      <th>Example</th>
1495
1496      <td>
1497        <pre>
1498dir::src $HOME/my_build/src
1499</pre>
1500      </td>
1501    </tr>
1502
1503    <tr class="gray">
1504      <th rowspan="2">DIR::TMP</th>
1505
1506      <th>Description</th>
1507
1508      <td>This declaration is optional and is not normally required. It is the
1509      temporary directory, container of temporary files used by the wrapper to
1510      the compiler and linker.</td>
1511    </tr>
1512
1513    <tr class="gray">
1514      <th>Example</th>
1515
1516      <td>
1517        <pre>
1518dir::tmp $HOME/my_build/tmp
1519</pre>
1520      </td>
1521    </tr>
1522
1523    <tr class="gray">
1524      <th>Label</th>
1525
1526      <th colspan="2">Content</th>
1527    </tr>
1528  </table>
1529
1530  <script type="text/javascript" src="maintain.js">
1531  </script>
1532</body>
1533</html>
Note: See TracBrowser for help on using the repository browser.