Provided by: icmake_9.02.08-2_amd64 bug

NAME

       icmbuild - A generic, C++/C program maintenance facility

SYNOPSIS

       icmbuild [-h] [-c] args

DESCRIPTION

       Icmbuild  is  a  small C program calling icmake(1) to do program maintenance as defined in
       the icmbuild script that’s (commonly) found in /usr/lib/icmake.

       Icmbuild’s actions are tailored through a  configuration  file  (icmconf)  which  must  be
       present   in   the  directory  where  program  maintenance  is  requested.  This  file  is
       automatically installed by icmstart(1). Refer to icmconf(7)’s man-page for  details  about
       this file.

       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.  If
       icmbuild  is  called, but icmconf is not available it displays a usage-summary after which
       icm() ends.

       Icmbuild() handles the maintenance for all sources in each of the subdirectories named  in
       the  file  CLASSES,  and in addition the maintenance of all sources in the current working
       directory.  `Maintenance’  involves  compiling  all  as  yet  uncompiled   source   files,
       recompilation  of  modified  source  files,  and  optionally  library  maintenance and the
       pre-compilation of header files, which commonly results in a marked  reduction  of  source
       compilation times.

       When  source  files  are  compiled  object  modules  are produced which may be stored in a
       library, against which the object module of the program’s main function 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 replaces the old one  that  is  found  in  the
       library. At that point the separate object files are no longer required and are removed by
       icmbuild.

       Up to icmake version 9.01.00 icmbuild was installed as  an  executable  icmake  script  in
       (commonly)  /usr/bin.  The dependency of this script on the file icmconf made it difficult
       to provide usage information if icmconf was absent. Since  version  9.02.00  the  icmbuild
       script  has  been  moved  to  (commonly)  /usr/lib/icmake,  and icmbuild now is a little C
       program providing the  usage  information  when  necessary  or  requested,  but  otherwise
       executes icmake to process the icmbuild script.

KICK-STARTING ICMBUILD

       To use icmbuild do as follows:

       o      Install  icmbuild in your path (icmake’s installation procedure should already have
              taken care of that);

       o      Copy icmconf (and probably a file CLASSES) to your project’s base directory  (i.e.,
              the  directory  in  which and where below the project’s sources are found). Usually
              this has already been taken care of by the icmstart script;

       Next:

       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 in that new
              class (subdirectory) names can always be added at the end of the file CLASSES,  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 that were 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  because  of the number-prefixes replacement of a file x.o from
              class A by file x.o from class B is prevented;

       o      Start icmbuild.

       The next section covers icmbuild’s  modes of operation.

OPTIONS

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

       o      -h: Display a usage summary (also automatically shown when  the  current  directory
              does not contain a file icmconf);

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

       Next  (after  optionally  specifying  -c)  icmbuild  can  be  provided  with the following
       arguments:

       o      No arguments at all: if icmconf contains the line

                  #define DEFCOM "program"

              then this is quivalent to the command icmbuild program;
              if icmconf contains the line

                  #define DEFCOM "strip"

              then this is quivalent to the command icmbuild strip;
              if if icmconf contains the line

                  #define DEFCOM "library"

              then this is quivalent to the command icmbuild library.
              (these commands are further elaborated in this section.)  DEFCOM specifications are
              ignored when an explicit argument is passed to icmbuild.

       o      clean
              clean up remnants of previous actions;

       o      install program <path>
              install  the  constructed program in the specified <path> (to be used after issuing
              icmbuild program, see below). Example:

                  icmbuild install ~/bin/program

              This installs the constructed binary program in the user’s bin direcotry  with  the
              name program;

       o      install static <path>
              install  the  constructed  static  library  in the specified path (to be used after
              issuing icmbuild library, see below). Example:

                  icmbuild static /usr/lib/

              This installs the constructed static library (e.g.  libspecial.a)  in  /usr/lib  as
              /usr/lib/libspecial.a.

       o      install  shared  path  install the constructed shared library in the specified path
              (to be used after issuing icmbuild  library),  when  icmconf  defines  SHARED  (cf.
              icmconf(7)). Example:

                  icmbuild shared /usr/lib/

              This  installs  the  constructed  binary  shared  library  (e.g.  libspecial.so) in
              /usr/lib as /usr/lib/libspecial.so. In addition, the soft-links

                  libspecial.so -> libspecial.so.X
                  libspecial.so.X -> libspecial.so.X.Y.Y.Z

              are defined in /usr/lib, where X.Y.Z are the major,  minor  and  subminor  versions
              defined in the file VERSION.

       o      library
              do  library maintenance (builds a static and optionally (if icmconf defines SHARED)
              a shared (dynamic) library);

       o      program
              do program maintenance (builds a program from the sources in  the  current  working
              directory and from the sources in the directories specified in the file CLASSES);

       o      program strip
              same as program, but the final program is stripped (using the linker’s -s option);

ICM-DEP

       Class  dependencies are handled by icmake’s support program icm-dep. It can be called from
       icmake by passing it the option -d. All options and arguments following -d are forwared to
       icm-dep.

       The  program  icm-dep  is  automatically  called by icmbuild to handle class dependencies.
       Consider two classes Options and Process. If  Process  uses  Options  and  if  precompiled
       header  files  are  used,  then in addition to Option’s header file, Process’s header must
       also  be  precompiled  if  Option’s  header  file  changes.  Likewise,  if  Option’s  data
       organization  is  changed  and  Option  defines  inline members used by Process or Process
       defines an Option data member then, in addition  to  Option’s  sources  sources  Process’s
       sources must also be compiled. For the latter case icmconf uses the USE_ALL specification:
       if a `USE_ALL’ file exists in  a  directory,  then  all  sources  of  that  directory  are
       recompiled.

       The  program  icm_dep  determines  all  such  class dependencies, and will recompile class
       header files of all classes depending on classes whose header files  must  be  recompiled.
       Furthermore,  if  a  `USE_ALL’  file  exists  in  a  directory then all sources of classes
       depending on that directory’s class are also recompiled.

       Icm-dep’s options are described in icmake(1)’s man-page.

       To start its work, icm_dep needs one command-line argument: go. Any other argument results
       in  icm_dep  performing  a `dry run’: it will perform all its duties (and verbose messages
       are displayed as if go had been specified), but no files (precompiled headers  or  USE_ALL
       files)  will be touched or removed. If neither options nor arguments are specified icm_dep
       writes its usage summary to the standard output.

       By default icmbuild calls icmake -d -V go: icm_dep is called to perform its duties and  to
       show  its actions on the standard output stream. By specifying a #define ICM_DEP parameter
       in the icmconf file this default can be overruled (cf. icmconf(7)).

FILES

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

       o      /usr/share/icmake/icmconf Unabbreviated example of an icmbuild configuration file;

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

EXAMPLES

       Here is an example of the  configuration  file  icmconf  for  a  concrete  program,  using
       facilities of the bobcat library:

           #define CLS
           #define LIBRARY             "modules"
           #define MAIN                "main.cc"
           #define SOURCES             "*.cc"
           #define OBJ_EXT             ".o"
           #define SHAREDREQ           ""
           #define TMP_DIR             "tmp"
           #define USE_ALL             "a"
           #define USE_ECHO              ON
           #define CXX                 "g++"
           #define CXXFLAGS            " --std=c++17 -Wall -O2 -pthread" " -fdiagnostics-color=never "
           #define IH                  ".ih"
           #define PRECOMP             "-x c++-header"
           #define REFRESH
           #define LDFLAGS             ""
           #define ADD_LIBRARIES       "bobcat"
           #define ADD_LIBRARY_PATHS   ""

           #define DEFCOM              "program"

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