Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 mainte-
       nance 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 re-
       quested.	 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 work-
       ing directory. The file icmconf in icmake(1)'s distribution provides an
       example of an icmconf file that can be used by icmbuild.	In that	 exam-
       ple  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 us-
       age-summary after which icm() ends.

       Icmbuild() handles the maintenance for all sources in each of the  sub-
       directories  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-compila-
       tion  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  li-
       braries 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 icm-
       conf  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 rele-
	      vant 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 icm-
	      build. 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-pre-
	      fixes 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 clear) before	starting  the  mainte-
	      nance 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.  lib-
	      special.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 icm-
	      conf 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 directo-
	      ries 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  Op-
       tion'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  ex-
       ists  in	 a directory then all sources of classes depending on that di-
       rectory'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 per-
       form 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	speci-
       fied 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	depen-
       dent:

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

icmake.9.02.07.tar.gz		   1992-2018			   icmbuild(1)

NAME | SYNOPSIS | DESCRIPTION | KICK-STARTING ICMBUILD | OPTIONS | ICM-DEP | FILES | EXAMPLES | SEE ALSO | BUGS | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=icmbuild&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help