Author: FCM team

# FCM: User Guide: Annex: Declarations in FCM 1 build configuration file

The FCM 1 build system is deprecated. The documentation for the current build system can be found at FCM Make.

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.)

CFG::TYPE

  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

  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

%<name>

  `%<name>` declares an internal variable <name> that can later be re-used.

  Example:

      %my_variable  -foo -bar
      tool::fflags  %my_variable
      tool::cflags  %my_variable

INC

  This declares the name of a file containing build configuration. The lines in the declared file will be included inline to the current configuration file.

  Example:

      inc  ~frva/var_stable_22.0/cfg/bld.cfg
      # ... and then your changes ...

DEST[::ROOTDIR]
DIR::ROOT

  The destination 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 path of the extract destination.)

  Example:

      dest  $HOME/my_build

USE

  This inherits settings from a previous build. The value must be must be either the configuration file or the root directory of a successful build. Output of the build, the tools, the exclude dependency declarations, the file type registers declarations are automatically inherited from the declared build. Source directories and build targets declarations may be inherited depending on the INHERIT declarations. (If you have a USE declaration in an extract, the resulting build configuration file will contain an automatic USE declaration, which expects an inherited build at the extract destination.)

  Example:

      # Use VAR build 22.0
      USE  ~frva/var_22.0

INHERIT::<name>[::<pcks>]

  This declares whether build targets (<name> = `target`) or source directories (<name> = `src`) can be inherited using the USE statement. By default, source directories are inherited, while build targets are not. Use the value `true` to switch on inheritance, or `false` to switch off. For source directories 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   true
      inherit::src      false

SRC[::<pcks>]

  This declares a source file/directory. You must specify the sub-package <pcks> if the source file/directory is located outside of the `src/` sub-directory of the build destination or if you want to redefine the sub-package name of the source file/directory. The name of the sub-package <pcks> must be unique. Package names are delimited by double colons `::` or double underscores `__`. If you declare a relative path, it is assumed to be relative to the `src/` sub-directory of the build destination. (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/var/src/code/VarMod_PF

SEARCH_SRC

  This declares a flag to determine whether the build system should search the `src/` sub-directory of the build root for a list of source files. The automatic search is useful if the build system is invoked standalone and the `src/` sub-directory contains the full source tree of the build. The default is to search (`true`). Set the flag to `false` to switch off the behaviour. (When the extract system creates a build configuration file, it declares all source files. Searching of the source sub-directory should not be required, and so this flag is automatically set to `false`.)

  Example:

      search_src  false

TARGET

  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. It is worth noting that `TARGET` declarations are cumulative. A later declaration does not override an earlier one - it simply adds more targets to the list.

  Example:

      target  VarScr_AnalysePF VarScr_CovAccStats
      target  VarScr_CovPFstats

TOOL::<label>[::<pcks>]

  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 annex.

  Example:

      tool::fc      sxmpif90
      tool::fflags  -Chopt -Pstack

      tool::cc      sxmpic++
      tool::cflags  -O nomsg -pvctl nomsg

      tool::ar      sxar

EXE_DEP[::<target>]

  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>]

  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

EXCL_DEP[::<pcks>]

  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. 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:

  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

DEP::<pcks>

  This declaration is used to specify a dependency for a source file in <pcks>. The value of this declaration must contain two fields (separated by the double colon `::`). The first field denotes the dependency type, and the second field is the dependency target. The dependency types are the same as those for EXCL_DEP described above.

  Example:

      dep::foo/bar.f  USE::your_fortran_mod
      dep::foo/bar.f  INTERFACE::her_fortran.interface
      dep::foo/bar.f  INC::his_fortran_inc.inc
      dep::foo/bar.f  H::their_header.h
      dep::foo/bar.f  OBJ::its_object.o
      dep::foo/egg    EXE::ham

NO_DEP::<pcks>

  This declaration is used to switch off/on dependency checking. If <pcks> is specified in the label, the declaration applies to the specified sub-package only.

  Example:

      # Switch on dependency checking only for "foo"
      no_dep      true
      no_dep::foo false

EXE_NAME::<name>

  This renames the executable target of a main program source file <name> to the specified value.

  Example:

      # Rename executable target of foo.f90 from "foo.exe" to "bar"
      exe_name::foo  bar

LIB[::<pcks>]

  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>]

  This declares whether a pre-processing stage is required. To switch on pre-processing, set the value to `true`. 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.

  Example:

      pp::gen true  # switch on pre-processing for "gen" only
      pp      true  # switch on pre-processing globally

SRC_TYPE::<pcks>

  This declaration is used to (re-)register the file type of the sub-package <pcks> 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`. A list of type flags is available later in this annex.

  Example:

      src_type::foo/bar.f  FORTRAN::FORTRAN9X::SOURCE::PROGRAM

INFILE_EXT::<ext>

  This declaration is used to re-register particular file name extensions <ext> to associate with different file types. The value of the declaration has a similar format to that of SRC_TYPE declaration described above. A list of type flags is available later in this annex.

  Example:

      infile_ext::h90  CPP::INCLUDE
      infile_ext::inc  FORTRAN::FORTRAN9X::INCLUDE

OUTFILE_EXT::<type>

  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:

  OBJ
    compiled object files
    [default = .o]
  MOD
    compiled Fortran module information files
    [default = .mod]
  EXE
    binary executables
    [default = .exe]
  DONE
    done files for compiled source
    [default = .done]
  IDONE
    done files for included source
    [default = .idone]
  FLAGS
    flags files, compiler flags config
    [default = .flags]
  INTERFACE
    interface files for F9X standalone subroutines/functions
    [default = .interface]
  LIB
    archive object library
    [default = .a]
  TAR
    TAR archive
    [default = .tar]

  Example:

      # Output F9X interface files will now have ".foo" extension
      outfile_ext::interface  .foo

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.

FC
  The Fortran compiler.
  [default = `f90`]
FFLAGS *
  Options used by the Fortran compiler.
  [default = ""]
FC_COMPILE
  The option used by the Fortran compiler to suppress the linking stage.
  [default = `-c`]
FC_INCLUDE
  The option used by the Fortran compiler to specify the include search path.
  [default = `-I`]
FC_MODSEARCH
  The option used by the Fortran compiler to specify the search path for the compiled module definition files. This option is often unnecessary as it is normally covered by the include search path.
  [default = ""]
FC_DEFINE
  The option used by the Fortran compiler to define a pre-processor definition macro.
  [default = `-D`]
FC_OUTPUT
  The option used by the Fortran compiler to specify the output file name.
  [default = `-o`]
CC
  The C compiler.
  [default = `cc`]
CFLAGS *
  Options used by the C compiler.
  [default = ""]
CC_COMPILE
  The option used by the C compiler to suppress the linking stage.
  [default = `-c`]
CC_INCLUDE
  The option used by the C compiler to specify the include search path.
  [default = `-I`]
CC_DEFINE
  The option used by the C compiler to define a pre-processor definition macro.
  [default = `-D`]
CC_OUTPUT
  The option used by the C compiler to specify the output file name.
  [default = `-o`]
LD *
  Name of the linker or loader for linking object files into an executable. If not set, use the compiler of the source file containing the main program.
  [default = ""]
LDFLAGS *
  The flags used by the linker or loader.
  [default = ""]
LD_OUTPUT
  The option used by the linker or loader for the output file name (other than the default `a.out`).
  [default = `-o`]
LD_LIBSEARCH
  The option used by the linker or loader for specifying the search path for link libraries.
  [default = `-L`]
LD_LIBLINK
  The option used by the linker or loader command for linking with a library.
  [default = `-l`]
AR
  The archive command.
  [default = `ar`]
ARFLAGS
  The options used for the archive command to create a library.
  [default = `rs`]
FPP
  The Fortran pre-processor command.
  [default = `cpp`]
FPPKEYS *
  The Fortran pre-processor will pre-define each word in this setting as a macro.
  [default = ""]
FPPFLAGS *
  The options used by the Fortran pre-processor.
  [default = `-P -traditional`]
FPP_DEFINE
  The option used by the Fortran pre-processor to define a macro.
  [default = `-D`]
FPP_INCLUDE
  The option used by the Fortran pre-processor to specify the include search path.
  [default = `-I`]
CPP
  The C pre-processor command.
  [default = `cpp`]
CPPKEYS *
  The C pre-processor will pre-define each word in this setting as a macro.
  [default = ""]
CPPFLAGS *
  The options used by the C pre-processor.
  [default = `-C`]
CPP_DEFINE
  The option used by the C pre-processor to define a macro.
  [default = `-D`]
CPP_INCLUDE
  The option used by the C pre-processor to specify the include search path.
  [default = `-I`]
MAKE
  The `make` command.
  [default = `make`]
MAKEFLAGS
  The options used by the `make` command.
  [default = ""]
MAKE_SILENT
  The option used by the `make` command to specify silent operation.
  [default = `-s`]
MAKE_JOB
  The option used by the `make` command to specify the number jobs to run simultaneously.
  [default = `-j`]
GENINTERFACE *
  The command/method to extract the calling interfaces of top level subroutines and functions in a Fortran 9X source. Supported values are `f90aib` and `none` (to switch off interface generation). If not specified, the system will use its own internal logic.
  [default = (not specified)]
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.
  [default = `file`]

The following is a list of type flags that are currently in-use (or * reserved) by the build system for TYPE and INFILE_EXT declarations:

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`.