home | help 
icmbuild(1)	  Icmake's generic program maintenance facility      icmbuild(1)

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 by the icmbuild script that's (commonly) found	in  /usr/lib/ic-
     make.

     Icmbuild's  actions  are  tailored  through  a configuration file (icmconf)
     which must be present in the directory where  program  maintenance  is  re-
     quested. This file is automatically installed by icmstart(1). Refer to icm-
     conf(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 it is  as-
     sumed that C++ sources are maintained, but program maintenance for, e.g., C
     sources  can  also 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 subdirec-
     tories named in the file CLASSES, and also of all sources	in  the  current
     working  directory.  `Maintenance' involves compiling all as yet uncompiled
     source files, recompilation of modified source  files,  optionally  library
     maintenance  and optionally the pre-compilation of header files, which nor-
     mally 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
     in  the  library. At that point the separate object files are no longer re-
     quired and are removed by icmbuild.

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 where and below which  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  to  the
	    end  of  the  file	CLASSES, but reordering the lines in the CLASSES
	    file should be avoided as that  may  easily  result  in  overwriting
	    identically named object files from already existing directories.

	    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  recognizes  three options of which only one can be specified. See
     the following section for information about which option is  recognized  by
     by which icmbuild command.

     o	    -h:  display  usage  information  (which is also automatically shown
	    when the current directory does not contain a file icmconf) and ter-
	    minate icmbuild;

     o	    -c: clear the screen (by calling clear) before starting the compila-
	    tion process;

     o	    -s: strip the compiled program or library at its installation direc-
	    tory (see the various install modes below).

ICMBUILD COMMANDS
     Icmbuild recognizes the following commands (possible options are shown  be-
     tween  square  brackets). With the install commands a path argument must be
     specified, which must be an existing user-writable directory:

     o	    clean
	    clean up remnants of previous actions (the	directory  specified  by
	    the  TMP_DIR  define  in icmconf is removed). If precompiled headers
	    were created (i.e., PRECOMP in icmconf was specified) then all files
	    having extension .gch in the main directory and in	the  directories
	    listed  in	the CLASSES file are also removed. If USE_ALL was speci-
	    fied then those files are also removed;

     o	    cleangch
	    all .gch files that were precompiled are removed  (whether	existing
	    in	the gch subdirectory of the TMP_DIR directory (specified in icm-
	    conf), or in directories specified in the CLASSES file,  or  in  the
	    project's  main directory). If icmconf does not specify PRECOMP then
	    nothing happens;

     o	    cleantmp
	    same as icmbuild clean, but the .gch files and  files  specified  by
	    the USE_ALL define in icmconf are not removed;

     o	    [-s] install program path
	    install  the  constructed  program in the specified path (to be used
	    after issuing icmbuild program, see below). Path can be absolute  or
	    relative  and  may optionally specify the name of the installed pro-
	    gram. Example:

		icmbuild install program ~/bin/prog

	    This installs the constructed binary program in the user's	bin  di-
	    rectory with the name prog;

     o	    [-s] install static path
	    install  the constructed static library in the specified path (to be
	    used after issuing icmbuild library, see below).  Path  can  be  ab-
	    solute  or	relative  and may optionally specify the name of the in-
	    stalled library. Example:

		icmbuild install static /usr/lib/

	    This installs the constructed static library  (assume  its	name  is
	    libspecial.a) in /usr/lib as /usr/lib/libspecial.a.

     o	    [-s]  install shared path when using this installation command, icm-
	    conf must contain #define SHARED (cf. icmconf(7)). It  installs  the
	    constructed  shared  library in the specified path (to be used after
	    issuing icmbuild library). Path can be  absolute  or  relative,  and
	    must specify an existing directory. Example:

		icmbuild install shared /usr/lib/

	    This  installs  the  constructed binary shared library (e.g. libspe-
	    cial.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 submi-
	    nor versions defined in the file VERSION.

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

     o	    [-c] 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	    If no commands are specified (but optionally only -c) then the  DEF-
	    COM specification in the icmconf is inspected. Recognized specifica-
	    tions are:

		#define DEFCOM "program"

	    which is quivalent to the command icmbuild [-c] program;
	    if DEFCOM is specified as

		#define DEFCOM "library"

	    then this is quivalent to the command icmbuild [-c] library.

	    If	an explicit command is passed to icmbuild then DEFCOM specifica-
	    tions are ignored.

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 argu-
     ments following -d are forwared to icm-dep.

     The program icm-dep is automatically called by icmbuild to handle class de-
     pendencies. Consider two classes Options and Process. If Process  uses  Op-
     tions  and  if  precompiled  header files are used, then in addition to Op-
     tion's header file, Process's header must also be precompiled  if	Option's
     header file changes. Likewise, if Option's data organization is altered 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  provides  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 the program's class dependencies, and recom-
     piles class header files of all classes depending on classes  whose  header
     files  must be recompiled. Furthermore, if a `USE_ALL' file exists in a di-
     rectory 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 performs all its du-
     ties  (and verbose messages are displayed as if go had been specified), but
     no files (precompiled headers or USE_ALL files) are touched or removed.  If
     neither  options  nor arguments are specified icm_dep writes its usage sum-
     mary 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  over-
     ruled (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 con-
	    figuration 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  pro-
     gram, 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++2a -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 Pub-
     lic License (GPL).

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

icmake.9.03.01.tar.gz		    1992-2020			     icmbuild(1)
home | help