FCM System User Guide > Annex: Declarations in FCM build configuration file

Annex:
Declarations in FCM build configuration file

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:
    • OBJ::NONE
    • EXE::NONE
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

The following is a list of <label> fields that can be used with a TOOL declaration. Those marked with an asterisk (*) accept declarations at sub-package levels.

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