Skip to content

Getting Started

Jump to bottom Edit New page
Stefano Zaghi edited this page Nov 9, 2015 · 6 revisions

To start using FoBiS.py it is better to understand its Command Line Interface (CLI). Into your shell type

FoBiS.py -h

This will echo:

usage: FoBiS.py [-h] [-v] {rule,build,clean,doctests} ...

a Fortran Building System for poor men

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         Show version

Commands:
  Valid commands

  {rule,build,clean,doctests}
    build               Build all programs found or specific target(s)
    clean               Clean project: remove all OBJs and MODs files... use
                        carefully
    rule                Execute special rules or user's ones defined into a
                        fobos file
    doctests            Test all valid doctests snippets found

For more detailed commands help use
  FoBiS.py build -h,--help
  FoBiS.py clean -h,--help
  FoBiS.py rule -h,--help
  FoBiS.py doctests -h,--help

There are 4 main commands

  1. build build your projects;
  2. clean clean previously built projects (use carefully);
  3. rule execute rules not strictly related to the building process, e.g. build documentation, creating project archive, etc.
  4. doctests test all valid doctests snippets found.

Each command has its own options.

Build

Printing the build help message is simple

FoBiS.py build -h

This will echo

 usage: FoBiS.py build [-h] [-compiler {gnu,intel,g95,opencoarrays-gnu,custom}]
                      [-fc FC] [-cflags CFLAGS] [-lflags LFLAGS] [-p PREPROC]
                      [-modsw MODSW] [-mpi] [-openmp] [-coarray] [-coverage]
                      [-profile] [-mklib {static,shared}] [-ch] [-s SRC]
                      [-dbld BUILD_DIR] [-dobj OBJ_DIR] [-dmod MOD_DIR]
                      [-dlib LIB_DIR [LIB_DIR ...]] [-i INCLUDE [INCLUDE ...]]
                      [-t TARGET] [-o OUTPUT] [-e EXCLUDE [EXCLUDE ...]]
                      [-libs LIBS [LIBS ...]] [-vlibs VLIBS [VLIBS ...]]
                      [-ext_libs EXT_LIBS [EXT_LIBS ...]]
                      [-ext_vlibs EXT_VLIBS [EXT_VLIBS ...]]
                      [-dependon DEPENDON [DEPENDON ...]] [-inc INC [INC ...]]
                      [-extensions EXTENSIONS [EXTENSIONS ...]] [-f FOBOS]
                      [-fci] [-mode MODE] [-lmodes] [-pfm] [-dpfm PFM_DIR]
                      [-epfm PFM_EXT [PFM_EXT ...]] [-force_compile] [-colors]
                      [-l] [-graph] [-q] [-verbose] [-j JOBS]
                      [-m MAKEFILE_name]

optional arguments:
  -h, --help            show this help message and exit

compiler:
  -compiler {gnu,intel,g95,opencoarrays-gnu,custom}
                        Compiler used (value is case insensitive, default
                        intel)
  -fc FC                Specify the Fortran compiler statement, necessary for
                        custom compiler specification (-compiler Custom)
  -cflags CFLAGS        Compile flags
  -lflags LFLAGS        Link flags
  -p PREPROC, --preproc PREPROC
                        Preprocessor flags
  -modsw MODSW          Specify the switch for setting the module searching
                        path, necessary for custom compiler specification
                        (-compiler Custom)
  -mpi                  Use MPI enabled version of compiler
  -openmp               Use OpenMP pragmas
  -coarray              Use coarrays
  -coverage             Instrument the built code with coverage analysis tools
                        [default False]
  -profile              Instrument the built code with profiling analysis
                        tools [default False]
  -mklib {static,shared}
                        Build library instead of program (use with -target
                        switch)
  -ch, --cflags_heritage
                        Store cflags as a heritage for the next build: if
                        cflags change re-compile all

directories:
  -s SRC, --src SRC     Root-directory of source files [default: ./]
  -dbld BUILD_DIR, --build_dir BUILD_DIR
                        Directory containing executable objects [default: ./]
  -dobj OBJ_DIR, --obj_dir OBJ_DIR
                        Directory containing compiled objects [default:
                        ./obj/]
  -dmod MOD_DIR, --mod_dir MOD_DIR
                        Directory containing .mod files of compiled objects
                        [default: ./mod/]
  -dlib LIB_DIR [LIB_DIR ...], --lib_dir LIB_DIR [LIB_DIR ...]
                        List of directories searched for libraries [default:
                        None]
  -i INCLUDE [INCLUDE ...], --include INCLUDE [INCLUDE ...]
                        List of directories for searching included files

files:
  -t TARGET, --target TARGET
                        Specify a target file [default: all programs found]
  -o OUTPUT, --output OUTPUT
                        Specify the output file name is used with -target
                        switch [default: basename of target]
  -e EXCLUDE [EXCLUDE ...], --exclude EXCLUDE [EXCLUDE ...]
                        Exclude a list of files from the building process
  -libs LIBS [LIBS ...]
                        List of external libraries used that are not into the
                        path: specify with full paths [default: None]
  -vlibs VLIBS [VLIBS ...]
                        List of external libraries used that are not into the
                        path and that are volatile (can change thus triggering
                        re-building): specify with full paths [default: None]
  -ext_libs EXT_LIBS [EXT_LIBS ...]
                        List of external libraries used that are into compiler
                        path [default: None]
  -ext_vlibs EXT_VLIBS [EXT_VLIBS ...]
                        List of external libraries used that are into compiler
                        path and that are volatile (can change thus triggering
                        re-building) [default: None]
  -dependon DEPENDON [DEPENDON ...]
                        List of interdependent external fobos file (and mode)
                        for interdependent building [default: None]
  -inc INC [INC ...]    List of extensions for include files [default:
                        ['.inc', '.INC', '.h', '.H']]
  -extensions EXTENSIONS [EXTENSIONS ...]
                        List of extensions of parsed files [default: ['.inc',
                        '.INC', '.h', '.H', '.f', '.F', '.for', '.FOR',
                        '.fpp', '.FPP', '.fortran', '.f77', '.F77', '.f90',
                        '.F90', '.f95', '.F95', '.f03', '.F03', '.f08',
                        '.F08', '.f2k', '.F2K']]

fobos:
  -f FOBOS, --fobos FOBOS
                        Specify a "fobos" file named differently from "fobos"
  -fci, --fobos_case_insensitive
                        Assume fobos inputs as case insensitive [defaul:
                        False, case sensitive]
  -mode MODE            Select a mode defined into a fobos file
  -lmodes               List the modes defined into a fobos file

PreForM.py:
  -pfm, --preform       Use PreForM.py pre-processor for pre-processing
                        sources file
  -dpfm PFM_DIR, --pfm_dir PFM_DIR
                        Directory containing the sources processed with
                        PreForM.py [default: none, the processed files are
                        removed after used]
  -epfm PFM_EXT [PFM_EXT ...], --pfm_ext PFM_EXT [PFM_EXT ...]
                        List of custom-defined file extensions to be
                        preprocessed by PreForM.py [default: none, all files
                        are preprocessed if PreForM.py is used]

fancy:
  -force_compile        Force to (re-)compile all [default: False]
  -colors               Activate colors in shell prints [default: no colors]
  -l, --log             Activate the creation of a log file [default: no log
                        file]
  -graph                Generate a dependencies graph by means of graphviz
                        [default false]
  -q, --quiet           Less verbose than default [default false]
  -verbose              Extremely verbose outputs for debugging FoBiS.py
                        [default false]
  -j JOBS, --jobs JOBS  Specify the number of concurrent jobs used for
                        compiling dependencies [default 1]
  -m MAKEFILE_name, --makefile MAKEFILE_name
                        Generate a GNU Makefile for building the project

A lot of options! For the moment do not care about them, simply remember that FoBiS.py is highly customizable :-)

Clean

Printing the clean help message is simple

FoBiS.py clean -h

This will echo

usage: FoBiS.py clean [-h] [-only_obj] [-only_target] [-mklib MKLIB] [-ch]
                      [-coverage] [-dobj OBJ_DIR] [-dmod MOD_DIR]
                      [-dbld BUILD_DIR] [-t TARGET] [-o OUTPUT]
                      [-extensions EXTENSIONS [EXTENSIONS ...]] [-f FOBOS]
                      [-fci] [-mode MODE] [-lmodes] [-colors] [-q] [-verbose]

optional arguments:
  -h, --help            show this help message and exit

compiler:
  -only_obj             Clean only compiled objects and not also built targets
  -only_target          Clean only built targets and not also compiled objects
  -mklib MKLIB          Build library instead of program (use with -target
                        switch); usage: -mklib static or -mklib shared
  -ch, --cflags_heritage
                        Store cflags as a heritage for the next build: if
                        cflags change re-compile all
  -coverage             Clean files used for performing coverage analysis
                        [default False]

directories:
  -dobj OBJ_DIR, --obj_dir OBJ_DIR
                        Directory containing compiled objects [default:
                        ./obj/]
  -dmod MOD_DIR, --mod_dir MOD_DIR
                        Directory containing .mod files of compiled objects
                        [default: ./mod/]
  -dbld BUILD_DIR, --build_dir BUILD_DIR
                        Directory containing executable objects [default: ./]

files:
  -t TARGET, --target TARGET
                        Specify a target file [default: all programs found]
  -o OUTPUT, --output OUTPUT
                        Specify the output file name is used with -target
                        switch [default: basename of target]
  -extensions EXTENSIONS [EXTENSIONS ...]
                        List of extensions of parsed files [default: ['.inc',
                        '.INC', '.h', '.H', '.f', '.F', '.for', '.FOR',
                        '.fpp', '.FPP', '.fortran', '.f77', '.F77', '.f90',
                        '.F90', '.f95', '.F95', '.f03', '.F03', '.f08',
                        '.F08', '.f2k', '.F2K']]

fobos:
  -f FOBOS, --fobos FOBOS
                        Specify a "fobos" file named differently from "fobos"
  -fci, --fobos_case_insensitive
                        Assume fobos inputs as case insensitive [defaul:
                        False, case sensitive]
  -mode MODE            Select a mode defined into a fobos file
  -lmodes               List the modes defined into a fobos file

fancy:
  -colors               Activate colors in shell prints [default: no colors]
  -q, --quiet           Less verbose than default [default false]
  -verbose              Extremely verbose outputs for debugging FoBiS.py
                        [default false]

Less options than build... but again just remember they exist!

Rule

Printing the rule help message is simple

FoBiS.py rule -h

This will echo

usage: FoBiS.py rule [-h] [-f FOBOS] [-mode MODE] [-fci] [-ex RULE] [-ls]
                     [-get GET] [-get_output_name] [-ford project-file.md]
                     [-gcov_analyzer GCOV_REPORTS_DIR [REPORT_SUMMARY_FILE_NAME]
                     [GCOV_REPORTS_DIR [REPORT_SUMMARY_FILE_NAME] ...]] [-q]
                     [-verbose] [-colors]

optional arguments:
  -h, --help            show this help message and exit

fobos file:
  -f FOBOS, --fobos FOBOS
                        Specify a "fobos" file named differently from "fobos"
  -mode MODE            Select a mode defined into a fobos file
  -fci, --fobos_case_insensitive
                        Assume fobos inputs as case insensitive [defaul:
                        False, case sensitive]

rules:
  -ex RULE, --execute RULE
                        Specify a rule (defined into fobos file) to be
                        executed
  -ls, --list           List the rules defined into a fobos file

intrinsic rules:
  -get GET              Intrinsic rule for getting options defined into fobos,
                        e.g. -get build_dir
  -get_output_name      Intrinsic rule for getting the final output name
                        accordingly to options defined into fobos
  -ford project-file.md
                        Intrinsic rule for building documentation by means of
                        Ford tool
  -gcov_analyzer GCOV_REPORTS_DIR [REPORT_SUMMARY_FILE_NAME] [GCOV_REPORTS_DIR [REPORT_SUMMARY_FILE_NAME] ...]
                        Analyze .gcov coverage files saving a report for each
                        file found

fancy:
  -q, --quiet           Less verbose than default [default false]
  -verbose              Extremely verbose outputs for debugging FoBiS.py
                        [default false]
  -colors               Activate colors in shell prints [default: no colors]

Very few options, they should be auto-explicative. However, it is worth noting that the rule command is the only that strictly requires a fobos file where the rules are defined. What is a fobos file is explained here.

Doctests

Printing the doctests help message is simple

FoBiS.py build -h

This will echo

usage: FoBiS.py doctests [-h]
                         [-compiler {gnu,intel,g95,opencoarrays-gnu,custom}]
                         [-fc FC] [-cflags CFLAGS] [-lflags LFLAGS]
                         [-p PREPROC] [-modsw MODSW] [-mpi] [-openmp]
                         [-coarray] [-coverage] [-profile]
                         [-mklib {static,shared}] [-ch] [-s SRC]
                         [-dbld BUILD_DIR] [-dobj OBJ_DIR] [-dmod MOD_DIR]
                         [-dlib LIB_DIR [LIB_DIR ...]]
                         [-i INCLUDE [INCLUDE ...]] [-t TARGET] [-o OUTPUT]
                         [-e EXCLUDE [EXCLUDE ...]] [-libs LIBS [LIBS ...]]
                         [-vlibs VLIBS [VLIBS ...]]
                         [-ext_libs EXT_LIBS [EXT_LIBS ...]]
                         [-ext_vlibs EXT_VLIBS [EXT_VLIBS ...]]
                         [-dependon DEPENDON [DEPENDON ...]]
                         [-inc INC [INC ...]]
                         [-extensions EXTENSIONS [EXTENSIONS ...]]
                         [-keep_volatile_doctests] [-f FOBOS] [-fci]
                         [-mode MODE] [-lmodes] [-pfm] [-dpfm PFM_DIR]
                         [-epfm PFM_EXT [PFM_EXT ...]] [-force_compile]
                         [-colors] [-l] [-graph] [-q] [-verbose] [-j JOBS]

optional arguments:
  -h, --help            show this help message and exit

compiler:
  -compiler {gnu,intel,g95,opencoarrays-gnu,custom}
                        Compiler used (value is case insensitive, default
                        intel)
  -fc FC                Specify the Fortran compiler statement, necessary for
                        custom compiler specification (-compiler Custom)
  -cflags CFLAGS        Compile flags
  -lflags LFLAGS        Link flags
  -p PREPROC, --preproc PREPROC
                        Preprocessor flags
  -modsw MODSW          Specify the switch for setting the module searching
                        path, necessary for custom compiler specification
                        (-compiler Custom)
  -mpi                  Use MPI enabled version of compiler
  -openmp               Use OpenMP pragmas
  -coarray              Use coarrays
  -coverage             Instrument the built code with coverage analysis tools
                        [default False]
  -profile              Instrument the built code with profiling analysis
                        tools [default False]
  -mklib {static,shared}
                        Build library instead of program (use with -target
                        switch)
  -ch, --cflags_heritage
                        Store cflags as a heritage for the next build: if
                        cflags change re-compile all

directories:
  -s SRC, --src SRC     Root-directory of source files [default: ./]
  -dbld BUILD_DIR, --build_dir BUILD_DIR
                        Directory containing executable objects [default: ./]
  -dobj OBJ_DIR, --obj_dir OBJ_DIR
                        Directory containing compiled objects [default:
                        ./obj/]
  -dmod MOD_DIR, --mod_dir MOD_DIR
                        Directory containing .mod files of compiled objects
                        [default: ./mod/]
  -dlib LIB_DIR [LIB_DIR ...], --lib_dir LIB_DIR [LIB_DIR ...]
                        List of directories searched for libraries [default:
                        None]
  -i INCLUDE [INCLUDE ...], --include INCLUDE [INCLUDE ...]
                        List of directories for searching included files

files:
  -t TARGET, --target TARGET
                        Specify a target file [default: all programs found]
  -o OUTPUT, --output OUTPUT
                        Specify the output file name is used with -target
                        switch [default: basename of target]
  -e EXCLUDE [EXCLUDE ...], --exclude EXCLUDE [EXCLUDE ...]
                        Exclude a list of files from the building process
  -libs LIBS [LIBS ...]
                        List of external libraries used that are not into the
                        path: specify with full paths [default: None]
  -vlibs VLIBS [VLIBS ...]
                        List of external libraries used that are not into the
                        path and that are volatile (can change thus triggering
                        re-building): specify with full paths [default: None]
  -ext_libs EXT_LIBS [EXT_LIBS ...]
                        List of external libraries used that are into compiler
                        path [default: None]
  -ext_vlibs EXT_VLIBS [EXT_VLIBS ...]
                        List of external libraries used that are into compiler
                        path and that are volatile (can change thus triggering
                        re-building) [default: None]
  -dependon DEPENDON [DEPENDON ...]
                        List of interdependent external fobos file (and mode)
                        for interdependent building [default: None]
  -inc INC [INC ...]    List of extensions for include files [default:
                        ['.inc', '.INC', '.h', '.H']]
  -extensions EXTENSIONS [EXTENSIONS ...]
                        List of extensions of parsed files [default: ['.inc',
                        '.INC', '.h', '.H', '.f', '.F', '.for', '.FOR',
                        '.fpp', '.FPP', '.fortran', '.f77', '.F77', '.f90',
                        '.F90', '.f95', '.F95', '.f03', '.F03', '.f08',
                        '.F08', '.f2k', '.F2K']]
  -keep_volatile_doctests
                        Keep the volatile doctests programs [default False]

fobos:
  -f FOBOS, --fobos FOBOS
                        Specify a "fobos" file named differently from "fobos"
  -fci, --fobos_case_insensitive
                        Assume fobos inputs as case insensitive [defaul:
                        False, case sensitive]
  -mode MODE            Select a mode defined into a fobos file
  -lmodes               List the modes defined into a fobos file

PreForM.py:
  -pfm, --preform       Use PreForM.py pre-processor for pre-processing
                        sources file
  -dpfm PFM_DIR, --pfm_dir PFM_DIR
                        Directory containing the sources processed with
                        PreForM.py [default: none, the processed files are
                        removed after used]
  -epfm PFM_EXT [PFM_EXT ...], --pfm_ext PFM_EXT [PFM_EXT ...]
                        List of custom-defined file extensions to be
                        preprocessed by PreForM.py [default: none, all files
                        are preprocessed if PreForM.py is used]

fancy:
  -force_compile        Force to (re-)compile all [default: False]
  -colors               Activate colors in shell prints [default: no colors]
  -l, --log             Activate the creation of a log file [default: no log
                        file]
  -graph                Generate a dependencies graph by means of graphviz
                        [default false]
  -q, --quiet           Less verbose than default [default false]
  -verbose              Extremely verbose outputs for debugging FoBiS.py
                        [default false]
  -j JOBS, --jobs JOBS  Specify the number of concurrent jobs used for
                        compiling dependencies [default 1]

The same huge set of options as build mode. There is one more option, -keep_volatile_doctests specific of doctests mode, for more details see doctests feature usage.

A note on quoted string arguments

FoBiS.py relies for its CLI on the great module argparse. However, argparse has known bug with arguments passed as quoted strings. For example, it is very common to pass compile and link flags as quoted strings

FoBiS.py build -cflags "-c -fPIC" -lflags "-shared"...

This can make argparse confused and failing in recognizing the arguments. To avoid such a bad circumstance, simply prefix the string a white space

FoBiS.py build -cflags " -c -fPIC" -lflags " -shared"...

FoBiS.py at work!

To learn FoBiS.py usage the fastest is to see it in action. In the following table there are examples ordered for increasing level of complexity

Examples
[[A Taste of FoBiS.py
[[fobos: the FoBiS.py makefile
[[FoBiS.py in action

Home | About | Install | Usage | Copyright © 2015 szaghi

Home

Install

Usage

Clone this wiki locally