NAME

       icmbuild - A generic, easy configurable, program maintenance script

SYNOPSIS

       icmbuild [-h] [-c] args

DESCRIPTION

       The  icmbuild  script is a generic script that can be used to do program maintenance using
       icmake(1).

       Icmbuild requires that the  file icmconf is  available  in  the  directory  where  program
       maintenance is requested.

       Icmbuild  assumes  that your sources exist in and below the current working directory. The
       file icmconf in icmake(1)’s distribution provides an example of an icmconf file  that  can
       be  used  by  icmbuild.  In  that  example icmconf file it is assumed that C++ sources are
       maintained, but program maintenance for, e.g., C sources can easily be configured.

       Icmbuild() compiles all sources in each of the subdirectories named in the  file  CLASSES,
       and then compiles all sources in the current working directory.

       The  compiled  sources  result  in  object modules which may be kept in a library, against
       which the main-object module  is  linked.  It  is  also  possible  to  specify  additional
       libraries against which the program must be linked.

       If  a  library  is  constructed  it  is  kept  up  to  date  by icmbuild. When a source is
       successfully compiled its new object module will replace the old one that is found in  the
       library.  At  that  point  the  object  files  are  no  longer required and are removed by
       icmbuild.

KICK-STARTING ICMBUILD

       To use icmbuild do as follows:

       o      Install icmbuild in your path;

       o      copy icmconf (and probably the file  CLASSES)  to  your  project’s  base  directory
              (i.e., the directory in which and where below the project’s sources are found);

       o      Modify the #defines in the file icmconf to taste;

       o      Enter  the names of subdirectories containing sources on separate lines in the file
              CLASSES

              Note that the order of the classes mentioned in CLASSES  is  relevant.   New  class
              (subdirectory)  names  can always be added, but reordering the lines in the CLASSES
              file should be avoided. If reordering is necessary,  then  first  run  the  command
              icmbuild  clean  to remove all files thus far created by icmbuild. Recompilation is
              necessary as the  names  of  the  object  files  contain  class  order-numbers  for
              identification.   These class-order numbers prevent file-name collisions (e.g., two
              classes might use a file data.cc) and thus replacement of a file x.o from  class  A
              by file x.o from class B is prevented;

       o      Now simply run

                          icmbuild -h

              from  the project’s base directory and let the help-info tell you what your options
              are. See the next section for the modes of operation.

OPTIONS

       Icmbuild recognizes two options, at most one should be specified:

       o      -h: Provide a short usage overview.

       o      -c: Clear the screen (using tput clear) before starting the compilation process

       Following the optional -c  icmbuild() the following arguments may be passed to icmbuild:

       o      clean
              clean up remnants of previous activities

       o      library
              build the library (static and optionally the dynamic library)

       o      program
              build the binary program

       o      program strip
              build the stripped binary program

       o      install program path install the constructed program in the specified path  (to  be
              used after issuing icmbuild program)

       o      install  static  path  install the constructed static library in the specified path
              (to be used after issuing icmbuild library)

       o      install shared path install the constructed shared library in  the  specified  path
              (to  be  used  after  issuing  icmbuild  library)  After  adding  a line to icmconf
              containing

                  #define DEFCOM "program"

              icmbuild by default uses the argument program. After adding

                  #define DEFCOM "strip"

              icmbuild by default uses the argument strip. After adding

                  #define DEFCOM "library"

              icmbuild by default uses the argument library.

       DEFCOM is ignored when an explicit operational mode is passed to icmbuild.

FILES

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

       o      /usr/share/icmake/icmconf Example of a icmbuild configuration file;

       o      /usr/share/icmake/CLASSES Example of a icmbuild CLASSES file.

EXAMPLES

       Here is an example of the configuration file icmconf for a  concrete  program,  using  the
       library libbobcat1 as an additional library:

           // Inspect the following #defines. Change them to taste. If you don’t
           // need a particular option, change its value into an empty string

           // For more information about this file: ’man 7 icmconf’

       // MAINTENANCE RELATED DEFINES THAT ARE OFTEN ADAPTED:
       // ===================================================

           // Uncomment to clear the screen starting the compilation
       //#define CLS

           // Uncomment to construct a library. Optionally use another name (don’t
           // use lib or an extension like .a)
       //#define LIBRARY           "modules"

           // The source containing main():
       #define MAIN                "main.cc"

           // The pattern locating sources in a directory:
       #define SOURCES             "*.cc"

           //  The extension of object modules:
       #define OBJ_EXT             ".o"

           // Uncomment to construct a shared library
       //#define SHARED

           // If the constructed shared library requires additional libraries then
           // specify these here. E.g., if a library /usr/lib/special/libspecial.so
           // is required then specify  "-L/usr/lib/special -lspecial"
           // Predefined paths (e.g., /lib, /usr/lib) do not have to be specified
       #define SHAREDREQ           ""

           // Directory to contain temporary results
       #define TMP_DIR             "tmp"

           // Uncomment to use the ALL facility and a class dependency setup in the
           // CLASSES file. When a directory contains a file ALL (optionally rename
           // this filename by providing an alternative name) then all its sources
           // and all sources of all classes depending on it are also compiled.
           // Class dependencies are indicated by 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.
       //#define USE_ALL             "a"

           // should commands be echoed (ON) or not (OFF) ?
       #define USE_ECHO              ON

           //  Use the VERSION file
       #define USE_VERSION

           // When DEFCOM "program" is specified ’./icmbuild’ is shorthand for
           // ’./icmbuild program’
           // When DEFCOM "library" is specified ’./icmbuild’ is shorthand for
           // ’./icmbuild library’
           // The icmstart script may add a DEFCOM specification to this file.
       //#define DEFCOM "program"
       //#define DEFCOM "library"

       // COMPILATION AND LINKING RELATED DEFINES
       // =======================================

           // The compiler to use. Define CC instead if a C compiler should be used.
       #define CXX            "g++"
       //#define CC            "gcc"

           // The compiler options to use. Define CFLAGS instead if a C compiler is
           // used.
           // To suppress colored error messages add option -fdiagnostics-color=never
           // To add debug-code to object files add option  -g
       #define CXXFLAGS        " --std=c++14 -Wall -O2"
       //#define CFLAGS        " -Wall -g -O2"

           // The extension of internal header files. See PRECOMP below
       #define IH              ".ih"

           // Uncomment to generate precompiled headers. When activated internal
           // header files are precompiled when they are more recent than their
           // precompiled versions. PRECOMP requires IH
       //#define PRECOMP "-x c++-header"

           // Uncomment to relink the binary, even when no sources were changed
       //#define REFRESH

           // Options passed to the linker:
       #define LDFLAGS         ""

       // LIBRARIES REQUIRED BY THE CONSTRUCTED PROGRAM OR LIBRARY:
       // =========================================================

           // any additional libraries the program may need:
       #define ADD_LIBRARIES       ""

           // additional paths (other than the standard paths) to locate additional
           // libraries:
       #define ADD_LIBRARY_PATHS   ""

       // DEFINES RELATED TO USING A PARSER GENERATOR
       // ===========================================

           // The subdirectory containing the parser’s specification file
           // If this directive is REMOVED, then all parser-related #defines
           // can also be removed from icmconf.
       #define PARSER_DIR          ""

           // What is the program generating a parser?
       #define PARSGEN             "bisonc++"

           // Flags to pass to PARSGEN:
       #define PARSFLAGS           "-V"

           // What is the top-level (or only) grammar specification file?
       #define PARSSPEC            "grammar"

           // Optionally use patterns to specify additional grammar specification
           // files. These files are (in)directly included by PARSSPEC. Specify
           // patterns relative to PARSER_DIR
       //#define PARSFILES           ""

           // The source file generated by the parser generator
       #define PARSOUT             "parse.cc"

       // DEFINES RELATED TO USING A SCANNER GENERATOR
       // ============================================

           // The subdirectory containing the scanner’s specification file
           // If this directive is REMOVED, then all scanner-related #defines
           // can also be removed from icmconf.
       #define SCANNER_DIR         ""

           // What is the program generating the lexical scanner?
       #define SCANGEN             "flexc++"

           // Flags to provide SCANGEN with:
       #define SCANFLAGS           ""

           // Name of the lexical scanner specification file
       #define SCANSPEC            "lexer"

           // Optionally use patterns to specify additional scanner specification
           // files. These files are (in)directly included by SCANSPEC. Specify
           // patterns relative to SCANNER_DIR
       //#define SCANFILES            ""

           // The source file generated by the lexical scanner
       #define SCANOUT             "lex.cc"

SEE ALSO

       icmake(1), icmconf(7), 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).