Provided by: icmake_8.01.00-1_amd64 bug

NAME

       icmconf - Configuration file for the icmbuild(1) program maintenance script

DESCRIPTION

       The  icmconf  configuration  file  is used to specify and fine-tune the characteristics of
       program maintenance performed by the icmbuild(1) script. It can be used  to  activate  and
       specify  various  directives  that  determine  how  the  program or library maintenance is
       performed.

       The directives are  biased  towards  the  construction  of  a  C++  program,  but  program
       maintenance for other languages (e.g., C) can also easily be configured.

       The  icmbuild(1) script ignores empty lines and lines whose first non-blank character is a
       hash-mark (#) as well as lines  whose  first  non-blank  characters  are  two  consecutive
       forward  slashes  (//).  Long  lines  can  be  split  over multiple lines by using a final
       backslash character at lines continuing at the next line (refer to the icmake(1)  man-page
       for further details).

CLASS DEPENDENCIES

       Traditional make-utilities recompile all dependent sources once header files are modified.
       When developing C++ programs this is hardly ever requird, as adding a new member  function
       to  a class does not require you to recompile already existing source files. Recompilation
       is required when modifying the data member organization of classes.

       To handle class dependencies in a more sensible way, icmake(1)’s CLASSES file  may  define
       dependencies among classes.

       By  default,  class-dependencies  are  not  interpreted.  To  activate  class-dependencoes
       recognition then the line

       //#define USE_ALL             "a"

       in the icmconf file must be uncommented:

       #define USE_ALL             "a"

       If a class Y depends on class X as in:

         class Y: public X
           {
               ...
           };

       or as in:

           class Y
           {
               X d_y;
               ...
           };

       then the sources of class Y should be recompiled if X’s data organization has changed.  In
       such cases Y depends on X.

       Such class dependencies can be specified in the CLASSES file using the form:

         y   x

       where  x  and y are the names of the directories in which the respective class sources are
       found. If icmconf contains a line

       #define USE_ALL "a"

       then, after modifying X’s  data  organization,  do  ’touch  x/a’,  followed  by  ’icmbuild
       program’.  Icmbuild  now compiles all of x’s sources as well as the sources in directories
       (in)directly depending on x (in the example: the sources in the y directory).

       Multiple dependencies can also be specified. If the class organization looks like this:

           class Z: public Y
           {
               X d_x;
           };

       then Z depends on both Y and X. In the CLASSES file this is configured like this:

           z   x   y

       Indirect dependencies are automatically recognized. After changing X’s  data  organization
       where CLASSES contains the lines

           x
           y   x
           z   y

       then icmbuild recompiles all source files in directories x, y and z.

ICMCONF PARAMETERS

       o      #define ADD_LIBRARIES       ""
              When  a program must be linked against additional libraries (other than the name of
              the program’s library itself, if specified at LIBRARY) then those libraries  should
              be  specified,  blank space separated, here. E.g., when a program is linked against
              libbobcat then the specification is:

                  #define ADD_LIBRARIES   "bobcat"

       o      #define ADD_LIBRARY_PATHS  ""
              When  the  additional  libraries  (specified  at  ADD_LIBRARIES)  are  located   in
              non-standard  library  locations  (e.g.,  not  in  /lib  and  /usr/lib)  then these
              additional paths are (blank space  separated)  specified  here.  Specify  only  the
              paths, not the -L flags.

       o      #define CLS
              The  clear  screen directive. If defined tput clear is called to clear the terminal
              screen before starting the compilation. By default it is not defined.

       o      #define CXX                 "g++"
              The C++ compiler to use. For a C compiler use, e.g., #define CC "gcc". Its  setting
              is overruled by an identically named environment variable.

       o      #define CXXFLAGS            "--std=c++14 -Wall -O2"
              The  compiler options to use. The default options are shown. When the C compiler is
              used, use #define CFLAGS rather than CXXFLAGS.  Its  setting  is  overruled  by  an
              identically named environment variable.

       o      #define DEFCOM  "..."
              A  DEFCOM directive may be added to the icmconf file (the icmstart(1) script can do
              this for you). It may be defined as:

                  #define DEFCOM  "program"

              in which case icmbuild will do program maintenance.  It may also be defined as:

                  #define DEFCOM  "program strip"

              in which case  icmbuild  does  program  maintenance,  creating  a  stripped  binary
              program.

              Alternatively it may also be defined as:

                  #define DEFCOM  "library"

              in which case icmbuild does library maintenance.

       o      #define IH                  ".ih"
              The extension used for internal header files. See #define PRECOMP below.

       o      #define LDFLAGS             ""
              The  linker  options  to  use.  By default no options are passed to the linker. Its
              setting is overruled by an identically named environment variable.

       o      #define LIBRARY           "modules"
              By  default  this  directive  is  not  defined.  If  defined  a  local  library  is
              constructed.  When a binary program is built it will be linked against this library
              rather than to the individual object modules.

              If a library must be constructed (see also the DEFCOM directive), then the  LIBRARY
              directive  must specify the library’s base name (without the lib prefix and without
              the .a extension).

              After a library has been constructed  icmbuild  install  static  dir  installs  the
              static  library  at  dir,  while  icmbuild  install  shared dir installs the shared
              library (see below at #define SHARED) at dir.

       o      #define MAIN                "main.cc"
              The source file in which the int main function is defined. This  specification  may
              be  left  as-is  or  may  completely  be removed if icmbuild(1) is used for library
              maintenance rather than program maintenance.

       o      #define OBJ_EXT             ".o"
              The extension of object modules created by the compiler.

       o      //#define PRECOMP           "-x c++-header"
              When activated internal header files (see #define IH) are precompiled when they are
              more  recent  than  their  precompiled versions. They are removed again by icmbuild
              clean. To  specify  internal  header  files  for  other  languages  change  the  -x
              specification accordingly. By default this #define is not active.

       o      #define REFRESH
              Define  REFRESH  to  relink  the  binary program at every icmbuild program call. By
              default REFRESH is not defined.

       o      #define SHARED
              This directive is only interpreted if LIBRARY was also  specified.   If  defined  a
              static  library  (extension  .a)  as  well  as a shared library (extension .so*) is
              built. If not specified, but LIBRARY was specified,  only  the  static  library  is
              built. By default SHARED is not defined.

              The  shared  library  receives  as its major version number VERSION’s major version
              number, and receives VERSION as its  full  version  number.  E.g.,  if  VERSION  is
              defined  as  1.02.03  and  LIBRARY  is  defined  as  demo  then  the shared library
              libdemo.so.1.02.03 is constructed,  with  libdemo.so.1  soft-linking  to  it,  with
              libdemo.so in turn soft-linking to libdemo.so.1.

       o      #define SHAREDREQ           ""
              When  creating  a  shared  library  SHAREDREQ  specifies the names of libraries and
              library paths that are required by the shared library.  E.g., if a library is found
              in   /usr/lib/special,   assuming   that  the  name  of  the  required  library  is
              libspecial.so, then use the specification "-L/usr/lib/special -lspecial".  The /lib
              and /usr/lib paths are usually predefined and need not be specified. This directive
              is only interpreted if SHARED and LIBRARY were also defined.

       o      #define SOURCES             "*.cc"
              The pattern to locate sources in a directory. The default value is shown.

       o      #define TMP_DIR             "tmp"
              The directory in which intermediate results are stored.  Relative  to  the  current
              working directory unless an absolute path is specified.

       o      #define USE_ALL     "a"
              After  defining  this  directive  (by default it is not defined) a class dependency
              setup defined in the CLASSES file is interpreted. In this case,  when  a  directory
              contains  a  file named at the USE_ALL directive, then all sources of that class as
              well as all sources of all classes depending on it are (re)compiled. The  program’s
              root directory is assumed to depend on all other directories.

              Class  dependencies  in  CLASSES  consist of the class name (as the first word on a
              line) optionally followed by additional class names, which are the classes on which
              the line’s first class name depends.

              Assuming  that  a  program  uses five classes One, Two, Three, Four and Five, whose
              sources are in, respectively, directories one, two, three, four, and five. If class
              Three  depends  on  class Two, which in turn depends on class One, while class Five
              depends on Three and Four, then the file CLASSES may reflect these dependencies  as
              follows:

                  one
                  two     one
                  three   two
                  four
                  five three four

              Afer  touching  (creating) the file two/a (using e.g., the command touch two/a) all
              sources of the classes Two, Three and Five as  well  as  all  the  sources  in  the
              program’s root directory are recompiled: Two is recompiled because of the existence
              of two/a, Three is recompiled because it depends on Two, Five is recompiled because
              it  depends  on  Three,  the sources in the program’s root directory are recompiled
              because at least one directory was recompiled.

              Following the recompilations the s specified at #define USE_ALL are removed.

              When the USE_ALL directive was defined the command icmbuild clean also removes  any
              leftover USE_ALL files from the program’s direct subdirectories.

       o      #define USE_ECHO              ON
              When specified as ON (rather than OFF) commands executed by icmbuild are echoed.

       o      #define USE_VERSION
              If  defined (which is the default) the file VERSION is read by icmconf to determine
              the program/library’s version, and the project’s release years.

PARSER MAINTENANCE

       The following directives are available in cases where  a program uses a  parser  generator
       creating a parser class from a grammar specification:

       o      #define PARSER_DIR          ""
              The subdirectory containing the parser’s specification file.

              If  parser  maintenance  is  not  required,  then this directive can be omitted. If
              omitted, then all other directives, that begin with PARS, can also be omitted.

       o      #define PARSFILES           ""
              If the parser specification file  named  at  PARSSPEC  itself  includes  additional
              specification  files, then patterns matching these additional grammar specification
              files should be specified  here.  The  pattern  is  interpreted  in  the  directory
              specified  at PARSER_DIR and could contain a subdirectory name (e.g. specs/*). When
              files matching the pattern are modified then a  new  parser  will  be  created.  By
              default no additional specification files are used.

       o      #define PARSFLAGS           "-V"
              The flags to use when calling the program specified at PARSGEN.

       o      #define PARSGEN             "bisonc++"
              The name of the program generating the parser.

       o      #define PARSOUT             "parse.cc"
              The  name  of the file generated by the parser generator (which is used by icmbuild
              to compare the timestamps of the parser specification s against).

       o      #define PARSSPEC            "grammar"
              The name of the parser specification file. This file is expected in  the  directory
              specified at PARSER_DIR.

SCANNER MAINTENANCE

       The  following directives are available in cases where  a program uses a scanner generator
       creating a lexical scanner class from a set of regular expressions:

       o      #define SCANNER_DIR         ""
              The subdirectory containing the scanner’s specification file.

              If lexical scanner maintenance is not required, then this directive can be omitted.
              If omitted, then all other directives, that begin with SCAN, can also be omitted.

       o      #define SCANFILES            ""
              If  the  lexical  scanner  specification  file  named  at  SCANSPEC itself includes
              additional specification files,  then  patterns  matching  these  additional  lexer
              specification  files  should  be  specified here. The pattern is interpreted in the
              directory specified at SCANNER_DIR and could  contain  a  subdirectory  name  (e.g.
              specs/*).  When  files matching the pattern are modified then a new lexical scanner
              will be created. By default no additional specification files are used.

       o      #define SCANFLAGS           ""
              The flags to use when calling the program specified at SCANGEN.

       o      #define SCANGEN             "flexc++"
              The name of the program generating the lexical scanner.

       o      #define SCANOUT             "lex.cc"
              The name of the file generated by the lexical scanner (which is used by icmbuild to
              compare the timestamps of the scanner specification s against).

       o      #define SCANSPEC            "lexer"
              The  name  of  the lexical scanner specification file. This file is expected in the
              directory specified at SCANNER_DIR.

FILES

       The mentioned paths are sugestive only and may be installation dependent:

       o      /usr/share/icmake/CLASSES
              Example of an icmconf CLASSES file.

       o      /usr/share/icmake/icmconf
              Default skeleton icmbuild resource file.

       o      /etc/icmake
              Directory containing the default system-wide icmake(1)  configuration  files  (like
              VERSION and icmstart.rc)

       o      $HOME/.icmake
              Optional   directory   containing   user-defined   specifications   overruling  the
              system-wide definitions. This directory is the proper location for  a  file  AUTHOR
              defining  the  AUTHOR  directive with the user’s name. E.g., my .icmake/AUTHOR file
              contains:

              #define AUTHOR  "Frank B. Brokken (f.b.brokken@rug.nl)";

SEE ALSO

       icmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).

BUGS

       icmbuild(1) ends displaying a fatal error message if the current  working  directory  does
       not contain a file icmconf.

COPYRIGHT

       This  is  free  software,  distributed  under  the terms of the GNU General Public License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).