Provided by: icmake_7.16.00-1_i386 bug

NAME

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

DESCRIPTION

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

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

PROGRAM AND SOURCE CONFIGURATION

       o      #define MAIN "main.cc"
              The specification of the file defining the  int  main  function.
              This  specification may be left as-is if icmbuild(1) is used for
              library maintenance rather than program maintenance.

       o      #define BINARY "binary"
              The name of the binary program. Can be left as-is if the  intent
              is to construct a library rather than a program. Don't specify a
              path here.  The  installation  path  can  be  specified  at  the
              BIN_INSTALL directive (see below)

       o      #define REFRESH
              By  defining REFRESH the binary program is always relinked, even
              when no sources were modified. This can be useful  if,  e.g.,  a
              separate  library  was rebuilt against which the program must be
              linked. By default REFRESH is not defined.

       o      #define BIN_INSTALL         "/usr/local/bin"
              This directive specifies the  location  where  icmbuild  install
              will install the binary program.

LIBRARY CONSTRUCTION

       o      #define LIBRARY           "modules"
              By  default  this  directive  is not defined. If defined a local
              library is defined. When a binary program is built  it  will  be
              linked  against  the  library  rather than the individual object
              modules. If library construction is required (see below  at  the
              DEFCOM  directive),  then the LIBRARY directive defines the name
              of the library that is built. Change the library's name at  your
              own digression. Don't use lib or an extension like .a.

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

       o      #define SHAREDREQ           ""
              When  creating  a  shared  library:  Specify  the  names  of any
              libraries and library paths that  are  required  by  the  shared
              library  between  the double quotes. E.g., if a library is found
              in /usr/lib/special use "-L/usr/lib/special -lspecial"  assuming
              that  the  name  of  the required library is libspecial.so.  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 LIB_INSTALL         "/usr/local/lib"
              This directive specifies the  location  where  icmbuild  install
              will  install  the  library  (libraries).  By  default it is not
              specified. It should only  be  specified  if  LIBRARY  was  also
              specified.

COMPILING AND LINKING

       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 USE_ALL     "ALL"
              When   this  directive  is  specified  (by  default  it  is  not
              specified) a class dependency setup defined in the CLASSES  file
              will  be  used.  In  this case, when a directory contains a file
              named  at  the  USE_ALL  directive  (the  default  icmconf  file
              pre-specifies  the  filename ALL) then all sources of that class
              as well as all sources  of  all  classes  depending  on  it  are
              (re)compiled.

              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 directly depending on the line's
              first class name.

              Assuming that a program uses five classes One, Two, Three,  Four
              and  five  and  that  class Three depends on class Two, which in
              turn depends on class One, while class Five depends on Four  and
              Two, then the file CLASSES may reflect these dependencies:

                  one
                  two     one
                  three   two
                  four
                  five    two four

              Creating  the  file three/ALL (using e.g., touch three/ALL) will
              cause all sources of the  classes  Three,  Two  and  One  to  be
              recompiled.  Creating five/ALL will cause all sources of classes
              Five, Four, Two and One to be recompiled.

              This facility was added  to  the  icmbuild  script  because  C++
              header  files  are  often modified without the need to recompile
              all their depending sources. No recompilation is necessary  when
              a  new class member is declared. Recompilation is necessary when
              the  class's  internal  organization  changes,  e.g.,  when  the
              organization of its data members is modified. By simply creating
              a file ALL the required recompilations will be performed.

              Following the recompilation the ALL s are removed.

              Note also that when the USE_ALL directive is  used  the  command
              icmbuild  clean also removes any leftover USE_ALL files from the
              program's direct subdirectories.

       o      #define COMPILER            "g++"
              This directive defines the  compiler  to  use.  The  default  is
              shown.

       o      #define COMPILER_OPTIONS    "--std=c++0x -g -Wall -O2"
              This  directive defines the compiler options to use. The default
              flags are shown. To enable GNU extensions  in  addition  to  the
              compiler's C++0x extensions, add the --std=gnu++0x flag.

       o      #define SOURCES             "*.cc"
              This  directive  defines  the  pattern  to  locate  sources in a
              directory. Its default value is shown.

       o      #define LINKER_OPTIONS      "-s"
              This directive defines the options the compiler should  pass  to
              the linker. Its default value is shown.

       o      #define ADD_LIBRARIES       ""
              When  a  program  (see  BINARY  above)  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. Only the paths should  be  specified,
              not the -L flags.

LEXICAL SCANNERS

       When a program uses a lexical scanner, generated by a scanner generator
       like flex(1), the icmbuild script can be used  to  update  the  scanner
       source  whenever  the  scanner specification file is modified. Here are
       the directives that are  related  to  the  use  of  a  lexical  scanner
       generator:

       o      #define SCANNER_DIR         ""
              If a lexical scanner must be constructed, then  the subdirectory
              containing the scanner's specification file  is  specified  with
              this  directive.  If empty (the default) no scanner construction
              is monitored  by  icmbuild  and  all  remaining  scanner-related
              directives are ignored.

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

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

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

       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 SCANOUT             "yylex.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).

GRAMMAR PARSERS

       When  a  program uses a grammar parser, generated by a parser generator
       like bisonc++(1), the  icmbuild  script  can  be  used  to  update  the
       parser's sources whenever a parser specification file is modified. Here
       are the directives that are related to the use of a parser generator:

       o      #define PARSER_DIR          ""
              If  a  parser  must  be  constructed,  then   the   subdirectory
              containing  the  parser's  specification  file is specified with
              this directive. If empty (the default) no parser construction is
              monitored   by   icmbuild   and   all  remaining  parser-related
              directives are ignored.

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

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

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

       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 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 GRAMBUILD
              Since bisonc++ version 2.0.0 this directive is obsolete, but  is
              kept  for backward compatibility. It is removed from the icmconf
              skeleton file. The PARSEFILES directive  overrules  the  use  of
              GRAMBUILD.

ADDITIONAL DIRECTIVES

       o      #define USE_VERSION
              When this directive is specified (which is the default) the file
              VERSION will be read by icmconf to determine the version of  the
              program,  the  program  release  years  and the program's author
              name. The default VERSION file  generated  by  icmstart  defines
              AUTHOR, VERSION and YEARS.

       o      #define DEFCOM  "..."
              A DEFCOM directive may be added to the icmconf file by icmstart.
              If added, it may be defined as

                  #define DEFCOM  "program"

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

                  #define DEFCOM  "library"

              in which case icmbuild will de library maintenance.

              If  this  directive  was  not added by icmstart it can always be
              added to icmconf by hand.

       The following directives usually require no tweaking:

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

       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 OBJ_EXT             ".o"
              The extension of object modules created by the compiler.

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

       None reported

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