The following is a list of supported declarations for the configuration
file used by the FCM build system. Unless otherwise stated, the fields in
all declaration labels are not case sensitive. Build declarations can be
made either in a build configuration file or in an extract configuration
file. In the latter case, the prefix "BLD::" must be added at the beginning
of each label to inform the extract system that the declaration is a build
system declaration. (In a build configuration file, the prefix "BLD::" is
optional.)
| Label |
Content |
| CFG::TYPE |
Description |
The configuration file type, the value should always be "bld" for a
build configuration file. This declaration is compulsory for all
build configuration files. (This declaration is automatic when the
extract system creates a build configuration file.) |
| Example |
cfg::type bld
|
| CFG::VERSION |
Description |
The file format version, currently "1.0" - a version is included so
that we shall be able to read the configuration file correctly should we
decide to change its format in the future. (This declaration is automatic
when the extract system creates a build configuration file.) |
| Example |
cfg::version 1.0
|
| TARGET |
Description |
Specify the targets for the build. Multiple targets can be declared in
one or more declarations. These targets become the dependencies of the
default "all" target in the Makefile. |
| Example |
target VarScr_AnalysePF VarScr_CovAccStats
target VarScr_CovPFstats
|
| DIR::ROOT |
Description |
The root directory of the build. It must be declared for each build.
(This declaration is automatic when the extract system creates a build
configuration file. The value is normally the root path of the
extraction destination.) |
| Example |
dir::root $HOME/my_build
|
| Label |
Content |
| SRC::<pcks> |
Description |
This declares a source directory in the sub-package <pcks>.
The name of the sub-package <pcks> must be unique. Package names
are delimited by double colons "::" or double underscores "__". (This
declaration is automatic when the extract system creates the build
configuration file. The list of declared source directories will be the
list of extracted source directories.) |
| Example |
src::var::code::VarMod_PF $HOME/my_build/src/var/code/VarMod_PF
|
| SEARCH_SRC |
Description |
This declares a flag to determine whether the build system should
search the source sub-directory of the build root for a list of source
directories. The automatic search is useful if the build system is
invoked standalone and the source sub-directory contains the full source
tree of the build. The default is to search (1). Set the flag to 0 to
switch off the behaviour. (When the extract system creates a build
configuration file, it declares all source directories. Searching of the
source sub-directory should not be required, and so this flag is
automatically set to 0.) |
| Example |
search_src 0
|
| EXE_DEP[::<target>] |
Description |
This declares an extra dependency for either all main program targets
or only <target> if it is specified. If <target> is specified,
it must be the name of a main program target. The value of the declaration
is a space delimited list. Each item in the list can either be a valid
name of a sub-package or the name of a valid object target. If a
sub-package name is used, the make rule for the main program will
be set to depend on all (non-program) object files within the
sub-package. |
| Example |
# Only foo.exe to depend on the package foo::bar and egg.o
exe_dep::foo.exe foo::bar egg.o
# All executables to depend on the package foo::bar and egg.o
exe_dep foo::bar egg.o
# Only foo.exe to depend on all objects
exe_dep::foo.exe
# All executables to depend on all objects
exe_dep
|
| BLOCKDATA[::<target>] |
Description |
This declares a BLOCKDATA dependency for either all main program targets
or only <target> if it is specified. If <target> is specified,
it must be the name of a main program target. The value of the declaration
is a space delimited list. Each item in the list must be the name of a
valid object target containing a Fortran BLOCKDATA program unit. |
| Example |
# Only foo.exe to depend on blkdata.o
blockdata::foo.exe blkdata.o
# All executables to depend on fbd.o
blockdata fbd.o
|
| EXE_NAME::<name> |
Description |
This renames the executable target of a main program source file
<name> to the specified value. |
| Example |
# Rename the executable target name of foo.f90 from "foo.exe" to "bar"
exe_name::foo bar
|
| LIB[::<pcks>] |
Description |
This declares the name of a library archive target. If <pcks> is
specified in the label, the declaration applies to the library archive
target for that sub-package only. If set, the name of the library archive
target will be named "lib<value>.a", where <value> is the
value of the declaration. If not specified, the default is to name the
global library "libfcm_default.a". For a library archive of a sub-package,
the default is to name its library after the name of the sub-package. |
| Example |
# Rename the top level library "libfoo.a"
lib foo
# Rename the library for the sub-package "egg::ham"
# from "libegg__ham.a" to "libegg-ham.a"
lib::egg::ham egg-ham
|
| PP[::<pcks>] |
Description |
This declares whether a pre-processing stage is required. To switch on
pre-processing, set the value to 1. If <pcks> is specified
in the label, the flag applies to the files within that sub-package
only. Otherwise, the flag affects source directories in all packages.
The pre-processing stage is useful if the pre-processor changes the
dependency and/or the argument list of the source files. The default
behaviour is skip the pre-processing stage for all source
directories. |
| Example |
pp::gen 1 # switch on pre-processing for sub-packages in "gen"
pp 1 # switch on pre-processing globally
|
| TOOL::<label>[::<pcks>] |
Description |
This declaration is used to specify a build "tool" such as the Fortran
compiler or its flags. The <label> determines the "tool" you are
declaring. A TOOL declaration normally applies globally. However, where it
is sensible to do so, a sub-package <pcks> can be specified. In
which case, the declaration applies only to the files and directories
under the sub-package. A list of <label> fields is available later in this section. |
| Example |
tool::fc sxmpif90
tool::fflags -Chopt -Pstack
tool::cc sxmpic++
tool::cflags -O nomsg -pvctl nomsg
tool::ar sxar
|
| Label |
Content |
| EXCL_DEP[::<pcks>] |
Description |
This declaration is used to specify whether a particular dependency
should be ignored during the automatic dependency scan. If a sub-package
<pcks> is specified, the declaration applies only to the files and
directories under the sub-package. Otherwise, the declaration applies
globally. It is worth noting that the build system is not yet clever
enough to recognise changes in this declaration in incremental builds.
Therefore, users should manually trigger a full build if these
statements are modified. The value of this declaration must contain one
or two fields (separated by the double colon "::"). The first field
denotes the dependency type, and the second field is the dependency
target. If the second field is specified, it will only exclude the
dependency to the specified target. Otherwise, it will exclude all
dependency to the specified type. The following dependency types are
supported:
| Dependency type |
Description |
| USE |
The dependency target is a Fortran module. |
| INTERFACE |
The dependency target is a Fortran 9X interface block file. |
| INC |
The dependency target is a Fortran INCLUDE file. |
| H |
The dependency target is a pre-processor #include header
file. |
| OBJ |
The dependency target is a compiled binary object file. |
| EXE |
The dependency target is an executable binary or script. |
N.B. The following dependency targets are in the default list of
excluded dependencies:
-
Intrinsic Fortran modules:
- USE::ISO_C_BINDING
- USE::IEEE_EXCEPTIONS
- USE::IEEE_ARITHMETIC
- USE::IEEE_FEATURES
-
Intrinsic Fortran subroutines:
- OBJ::CPU_TIME
- OBJ::GET_COMMAND
- OBJ::GET_COMMAND_ARGUMENT
- OBJ::GET_ENVIRONMENT_VARIABLE
- OBJ::MOVE_ALLOC
- OBJ::MVBITS
- OBJ::RANDOM_NUMBER
- OBJ::RANDOM_SEED
- OBJ::SYSTEM_CLOCK
-
Dummy declarations:
|
| Example |
excl_dep USE::YourFortranMod
excl_dep INTERFACE::HerFortran.interface
excl_dep INC::HisFortranInc.inc
excl_dep H::TheirHeader.h
excl_dep OBJ
excl_dep EXE
|
| Label |
Content |
| INFILE_EXT::<ext> |
Description |
This declaration is used to re-register particular file name
extensions <ext> to associate with different file types. The
value of the declaration is a list of type flags delimited by the
double colon "::". Each type flag is used internally to describe the
nature of the file. For example, a Fortran free source form containing
a main program is registered as
"FORTRAN::FORTRAN9X::SOURCE::PROGRAM". The following is a
list of type flags that are currently in-use (or *
reserved) by the build system:
| Flag |
Description |
| SOURCE |
a source file containing program code of a supported language
(currently Fortran, FPP, C and CPP). |
| INCLUDE |
an include file containing program code of a supported language
(currently Fortran, FPP, C and CPP). |
| FORTRAN |
a file containing Fortran code. |
| FORTRAN9X |
a file containing the Fortran free source form. This word must be
used in conjunction with the word "FORTRAN". |
| FPP |
a file containing Fortran code requiring pre-processing. |
| FPP9X |
a file containing Fortran free source form requiring
pre-processing. This word must be used in conjunction with the word
"FPP". |
| C |
a file containing C code. |
| CPP |
a file containing CPP include header. |
| INTERFACE |
a file containing a Fortran 9X interface block. |
| PROGRAM |
a file containing a main program. |
| MODULE |
a file containing a Fortran 9X module. |
| BINARY |
a binary file. |
| EXE |
an executable file. This word must be used in conjunction with
the word "BINARY". |
| LIB |
an archive library. This word must be used in conjunction with
the word "BINARY". |
| SCRIPT |
a file containing source code of a scripting language. |
| PVWAVE |
a file containing executable PVWAVE scripts. This word must be
used in conjunction with the word "SCRIPT". |
| SQL |
a file containing SQL scripts. This word must be used in
conjunction with the word "SCRIPT". |
| GENLIST |
a GEN List file. |
| OBJ |
(* reserved) an object file. This word must be used in
conjunction with the word "BINARY". |
| SHELL |
(* reserved) a file containing executable shell scripts. This
word must be used in conjunction with the word "SCRIPT". |
| PERL |
(* reserved) a file containing executable Perl scripts. This
word must be used in conjunction with the word "SCRIPT". |
| PYTHON |
(* reserved) a file containing executable Python scripts. This
word must be used in conjunction with the word "SCRIPT". |
| TCL |
(* reserved) a file containing executable TCL scripts. This
word must be used in conjunction with the word "SCRIPT". |
|
| Example |
infile_ext::h90 CPP::INCLUDE
infile_ext::inc FORTRAN::FORTRAN9X::INCLUDE
|
| OUTFILE_EXT::<type> |
Description |
This declaration is used to re-register the output file extension
for a particular <type> of output files. The value must be a
valid file extension. The following is a list of output file types
in-use by the build system:
| Type |
Description |
Default |
| MK |
dependency files, Makefile fragments |
.mk |
| OBJ |
compiled object files |
.o |
| MOD |
compiled Fortran module information files |
.mod |
| EXE |
binary executables |
.exe |
| DONE |
"done" files for compiled source |
.done |
| IDONE |
"done" files for included source |
.idone |
| FLAGS |
"flags" files, compiler flags config |
.flags |
| INTERFACE |
interface files for F9X standalone subroutines/functions |
.interface |
| LIB |
archive object library |
.a |
| TAR |
TAR archive |
.tar |
|
| Example |
# Output F9X interface files will now have ".foo" extension
outfile_ext::interface .foo
|
| Label |
Content |
| INC |
Description |
This declares the name of a file containing build configuration. The
lines in the declared file will be included inline to the current build
configuration file. |
| Example |
inc ~frva/var_stable_22.0/cfg/bld.cfg
# ... and then your changes ...
|
| USE |
Description |
This declares a pre-compiled build, which the current build is
dependent on. The value must be must be either the configuration file or
the root directory of a successful build. Output of the pre-compiled
build, the build tools, the exclude dependency declarations, the file
type registers declarations are automatically inherited from the
pre-compiled build. Source directories, build targets and pre-processing
stage declarations may be inherited depending on the INHERIT
declarations. (If you have a USE declaration in an extraction, the
resulting build configuration file will contain an automatic USE
declaration, which expects a pre-compiled build at the destination of
the extraction.) |
| Example |
# Use VAR build 22.0
USE ~frva/var_22.0
|
| INHERIT::<name>[::<pcks>] |
Description |
This declares whether build targets (<name> = "target"),
source directories (<name> = "src") and pre-processing stage
declarations (<name> = "pp") are inherited from pre-compiled builds
declared by the USE statement. By default, source directories and
pre-processing stage declarations are inherited from pre-compiled
builds, while build targets are not. Use the value 1 to switch on
inheritance, or 0 to switch off. For source directories and
pre-processing stage declarations, the name of a sub-package
<pcks> can be specified. If a sub-package pcks is specified, the
declaration applies only to the files and directories under the
sub-package. Otherwise, the declaration applies globally. |
| Example |
inherit::target 1
inherit::src 0
inherit::pp::gen 0
|
| %<name> |
Description |
%<name> declares an internal variable <name> that
can later be re-used. |
| Example |
%my_variable foo
src::bar %my_variable
src::egg %my_variable
src::ham %my_variable
|
| Label |
Content |
| Label |
Description |
Default |
| FC |
The Fortran compiler. |
"f90" |
| FFLAGS * |
Options used by the Fortran compiler. |
"" |
| FC_COMPILE |
The option used by the Fortran compiler to suppress the
linking stage. |
"-c" |
| FC_INCLUDE |
The option used by the Fortran compiler to specify the
"include" search path. |
"-I" |
| FC_DEFINE |
The option used by the Fortran compiler to define a
pre-processor definition macro. |
"-D" |
| FC_OUTPUT |
The option used by the Fortran compiler to specify the output
file name. |
"-o" |
| CC |
The C compiler. |
"cc" |
| CFLAGS * |
Options used by the C compiler. |
"" |
| CC_COMPILE |
The option used by the C compiler to suppress the
linking stage. |
"-c" |
| CC_INCLUDE |
The option used by the C compiler to specify the
"include" search path. |
"-I" |
| CC_DEFINE |
The option used by the C compiler to define a
pre-processor definition macro. |
"-D" |
| CC_OUTPUT |
The option used by the C compiler to specify the output
file name. |
"-o" |
| LD * |
Name of the linker or loader for linking object files into an
executable. |
"ld" |
| LDFLAGS * |
The flags used by the linker or loader. |
"" |
| LD_OUTPUT |
The option used by the linker or loader for the output file name
(other than the default "a.out"). |
"-o" |
| LD_LIBSEARCH |
The option used by the linker or loader for specifying the
search path for link libraries. |
"-L" |
| LD_LIBLINK |
The option used by the linker or loader command for linking
with a library. |
"-l" |
| AR |
The archive command. |
"ar" |
| ARFLAGS |
The options used for the archive command to create a
library. |
"rs" |
| FPP |
The Fortran pre-processor command. |
"cpp" |
| FPPKEYS * |
The Fortran pre-processor will pre-define each word in this
setting as a macro. |
"" |
| FPPFLAGS * |
The options used by the Fortran pre-processor. |
"-P -traditional" |
| FPP_DEFINE |
The option used by the Fortran pre-processor to define a
macro. |
"-D" |
| FPP_INCLUDE |
The option used by the Fortran pre-processor to specify the
"include" search path. |
"-I" |
| CPP |
The C pre-processor command. |
"cpp" |
| CPPKEYS * |
The C pre-processor will pre-define each word in this
setting as a macro. |
"" |
| CPPFLAGS * |
The options used by the C pre-processor. |
"-C" |
| CPP_DEFINE |
The option used by the C pre-processor to define a
macro. |
"-D" |
| CPP_INCLUDE |
The option used by the C pre-processor to specify the
"include" search path. |
"-I" |
| MAKE |
The "make" command. |
"make" |
| MAKEFLAGS |
The options used by the "make" command |
"" |
| MAKE_SILENT |
The option used by the "make" command to specify silent
operation. |
"-s" |
| MAKE_JOB |
The option used by the "make" command to specify the number
jobs to run simultaneously. |
"-j" |
| GENINTERFACE * |
The command/method for generating interface for Fortran 9X
standalone subroutines/functions. Supported values are "ECMWF",
"f90aib" and "none". (The keyword "none" is used to switch off
interface generation.) |
"ECMWF" |
| INTERFACE * |
Generate Fortran 9X interface files with root names according to
either the root name of the source "file" or the name of the "program"
unit. |
"file" |
| Label |
Description |
Default |
The following declarations are for reference only. They
should not be used in normal operations of the FCM build system:
| Label |
Content |
| DIR::BIN |
Description |
This declaration is optional and is not normally required. It is the
"bin" directory, container of executable files created by the build. |
| Example |
dir::bin $HOME/my_build/bin
|
| DIR::BLD |
Description |
This declaration is optional and is not normally required. It is the
build directory, container of the Makefile and its fragments
created by the build system. |
| Example |
dir::bld $HOME/my_build/bld
|
| DIR::CACHE |
Description |
This declaration is optional and is not normally required. It is the
cache directory, container of internal cache files used by the build
system. |
| Example |
dir::cache $HOME/my_build/.cache
|
| DIR::CFG |
Description |
This declaration is optional and is not normally required. It is the
configuration directory, container of the build configuration file. Not
created by the build system. |
| Example |
dir::cfg $HOME/my_build/cfg
|
| DIR::DONE |
Description |
This declaration is optional and is not normally required. It is the
"done" file directory, container of dummy "done" files created by the
build process. A "done" file is used to indicate that all the external
objects of an object files are compiled and ready to be used by the link
process. |
| Example |
dir::done $HOME/my_build/done
|
| DIR::ETC |
Description |
This declaration is optional and is not normally required. It is the
miscellaneous file directory, container of "data" files. "Data" files
are files in the source sub-package without a registered type. It is
possible for the user to tell the build system to copy all "data" files
in a sub-package to this directory by "building" a dummy sub-package
data file target. |
| Example |
dir::etc $HOME/my_build/etc
|
| DIR::FLAGS |
Description |
This declaration is optional and is not normally required. It is the
"flags" file directory, container of dummy "flags" files created by the
build process. A "flags" file is used to indicate to make that
the compiler flags for a source file or a container package has
changed. |
| Example |
dir::flags $HOME/my_build/flags
|
| DIR::INC |
Description |
This declaration is optional and is not normally required. It is the
include directory, container of "include" files such as pre-processor
header files, Fortran INCLUDE files, Fortran 9X interface files, and
Fortran compiled module information files. |
| Example |
dir::inc $HOME/my_build/inc
|
| DIR::LIB |
Description |
This declaration is optional and is not normally required. It is the
library directory, container of object library achive files created by
the build. |
| Example |
dir::lib $HOME/my_build/lib
|
| DIR::OBJ |
Description |
This declaration is optional and is not normally required. It is the
object directory, container of compiled object files created by the
build process. |
| Example |
dir::obj $HOME/my_build/obj
|
| DIR::PPSRC |
Description |
This declaration is optional and is not normally required. It is the
pre-processed source directory, container of pre-processed source files
created by the build process. |
| Example |
dir::ppsrc $HOME/my_build/ppsrc
|
| DIR::SRC |
Description |
This declaration is optional and is not normally required. It is the
source directory, container of the source tree. Not created by the build
system. |
| Example |
dir::src $HOME/my_build/src
|
| DIR::TMP |
Description |
This declaration is optional and is not normally required. It is the
temporary directory, container of temporary files used by the wrapper to
the compiler and linker. |
| Example |
dir::tmp $HOME/my_build/tmp
|
| Label |
Content |