Provided by: icmake_9.02.06-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 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 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) checks  class  dependencies
       using  its  support  program  /usr/lib/icmake/icm-dep,  visiting the classes listed in the
       CLASSES file if icmconf’s USE_ALL directive was specified. If a directory mentioned in the
       CLASSES  file  contains  a  file  having  a name that’s equal to the name specified at the
       USE_ALL parameter, then all sources of classes that depend on that  particular  class  are
       also recompiled.

       Likewise,  if  the PRECOMP parameter was specified, then a similar action is performed for
       the precompiled headers: if a local header file that’s (directly or  indirectly)  included
       by  a  class’s  internal  header file has changed, then that class’s precompiled header as
       well as all precompiled headers of dependent classes are recompiled.

       The  icmbuild(1)  script  itself  does  not  inspect   these   dependencies,   but   calls
       /usr/lib/icmake/icm-dep  to  perform  the requird tests. The program icm-dep’s short usage
       summary is written to the standard output stream when  calling  icmake  -d  (or  directly:
       /usr/lib/icmake/icm-dep).

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"

              If your program is linked against multiple libraries, then  use  a  blank-separated
              list of libraries (like "math 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.

              It is stronly advised to specify full pathnames here, or remember that normally the
              location  of  the  icmconf  file is not the location where the compilation actually
              takes place, which is the location specified at the TMP_DIR parameter (see below).

       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 ICM_DEP           "-V go"
              The existence and implied existence of USE_ALL files (see the  description  of  the
              USE_ALL  directive),  as  well  as  the  correct ages of precompiled headers can be
              checked by icmake’s support program icm_dep. By default icm_dep is called with  the
              shown default arguments. If icm_dep should not be called define ICM_DEP as an empty
              string (""). Icmake(1)’s man-page contains a separate  section  about  the  icm_dep
              support program.

       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 NO_PRECOMP_WARNING"
              When PRECOMP is defined (see below) a warning is issued when a class-directory does
              not   contain   a   IH   file.   Such   warnings   are   suppressed  when  defining
              NO_PRECOMP_WARNING. This option is ignored unless PRECOMP has been defined.

       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. Also, when a precompiled header file
              is (re)compiled the precompiled header files of  all  dependent  classes  are  also
              recompiled.

              Precompiled headers are removed 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) class dependencies are
              interpreted. In this case, when a directory contains a file having  a  name  that’s
              equal  to  the  name  specified  at the USE_ALL directive, then all sources of that
              class as well as all sources of classes that depend on it are (re)compiled.

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

              When  the  USE_ALL  directive was specified the command icmbuild clean also removes
              any leftover USE_ALL files from the program’s 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).