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

FreeBSD Manual Pages

  
 
  

home | help
icmconf(7)	      configuration file for icmbuild(1)	    icmconf(7)

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

DESCRIPTION
       The icmconf configuration file is used to  specify  and	fine-tune  the
       program maintenance performed by	the icmbuild(1)	program	and script. It
       can be used to activate and specify various directives  that  determine
       how the program or library maintenance is performed.

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

       The  icmbuild(1)	 script	 ignores  empty	 lines	and  lines whose first
       non-blank characters are	two consecutive	 forward  slashes  (//).  Long
       lines  can  be  split  over multiple lines by writing a final backslash
       character at lines continuing at	the next line (refer to	the  icmake(1)
       man-page	for further details).

CLASS DEPENDENCIES
       Traditional  make-utilities recompile all dependent sources once	header
       files are modified. When	developing C++ programs	this  is  hardly  ever
       requird,	as adding new member functions to classes does not require you
       to recompile already existing source files. Recompilation  is  required
       when the	data member organization of classes is altered.

       To  handle  class dependencies in a more	sensible way, icmake(1)	checks
       class dependencies using	its support  program  /usr/lib/icmake/icm-dep,
       visiting	 the  classes  listed in the CLASSES file if icmconf's USE_ALL
       directive was specified.	If a directory mentioned in the	 CLASSES  file
       contains	a file having a	name that's equal to the name specified	at the
       USE_ALL parameter, then all sources of classes that depend on that par-
       ticular class are also recompiled. In practice this means that when you
       change the data organization of a class you only	need to	touch it  that
       directory  the  file whose name was specified by	the USE_ALL directive.
       E.g., if	your class is named Data, its sources are in the sub-directory
       ./data,	and #define USE_ALL "a"	was specified then after modifying the
       data organization of the	class Data you only need to issue the  command
       touch  data/a.  Subsequently,  at the next icmbuild call	all sources in
       ./data as well as all sources in	directories whose (header)  files  in-
       clude data.h are	recompiled as well.

       Likewise,  if  PRECOMP  was defined, then a similar action is performed
       for the precompiled headers: if a local header file that's (directly or
       indirectly)  included  by  a  class's internal header file has changed,
       then that class's precompiled header as well as all precompiled headers
       of dependent classes are	recompiled.

       The  icmbuild(1)	script itself does not inspect these dependencies, but
       calls /usr/lib/icmake/icm-dep to	perform	the requird tests. The program
       icm-dep's  short	usage summary is written to the	standard output	stream
       when calling icmake -d (or directly: /usr/lib/icmake/icm-dep).

DEFINES	IN ICMCONF
       All of the following #defines are required except those that are	 shown
       as commented #defines (e.g., //#define REFRESH).

       o      //#define	ADD_LIBRARIES	    ""
	      when  a  program	must  be  linked  against additional libraries
	      (other than the name of the program's library itself  (specified
	      at LIBRARY) then those libraries should be specified here. E.g.,
	      when a program is	linked against libbobcat then  the  specifica-
	      tion is:

		  #define ADD_LIBRARIES	 "bobcat"

	      If your program is linked	against	multiple libraries, then use a
	      blank-separated list of libraries	 (like	#define	 ADD_LIBRARIES
	      "math bobcat");

       o      //#define	ADD_LIBRARY_PATHS  ""
	      this directtive must be specified	if ADD_LIBRARIES is also spec-
	      ified, although it may be	specified as an	 empty	string.	  When
	      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)	speci-
	      fied here. Specify only the paths, not the -L flags.

	      It is stronly advised to specify full pathnames here.   Relative
	      path specifications can be used by specify paths relative	to the
	      directory	that is	specified at the TMP_DIR  directive  (see  be-
	      low);

       o      //#define	CLS
	      the  clear screen	directive. If defined clear is called to clear
	      the terminal screen before starting compilations.	By default  it
	      is  not  defined.	 Alternatively	the -c option can be passed to
	      icmbuild;

       o      #define CXX "g++"
	      the C++ compiler to use. For a C compiler	specify, e.g., #define
	      CC  "gcc". Their settings	are overruled by identically named en-
	      vironment	variables. If only C files are compiled	 then  #define
	      CXX can be omitted;

       o      #define CXXFLAGS "--std=c++2a -Wall -O2"
	      C++  compiler options to use (here showing the default options).
	      When the C compiler is used,  use	 #define  CFLAGS  rather  than
	      CXXFLAGS.	 Their settings	are overruled by identically named en-
	      vironment	variables. If only C files are compiled	 then  #define
	      CXXFLAGS can be omitted;

       o      //#define	DEFCOM	"..."
	      a	 DEFCOM	 directive  may	be added to the	icmconf	file (the icm-
	      start(1) script can do this for you). It can be specified	as:

		  #define DEFCOM  "program"

	      in which case icmbuild does program maintenance, or as

		  #define DEFCOM  "library"

	      in which case icmbuild does library maintenance.;

       o      //#define	ICM_DEP		  "-V go"
	      the existence and	implied	existence of USE_ALL  files  (see  the
	      description  of  the  USE_ALL directive),	as well	as the correct
	      ages of precompiled headers can be checked by  icmake's  support
	      program icm_dep. By default icm_dep is called with the shown de-
	      fault arguments. If icm_dep should not be	called define  ICM_DEP
	      as  an  empty string (""). Icmake(1)'s man-page contains a sepa-
	      rate section about the icm_dep support program;

       o      //#define	IH		    ".ih"
	      the extension used for internal header files. See	 #define  PRE-
	      COMP  below.  If	PRECOMP	is specified ttIH) must	also be	speci-
	      fied;

       o      //#define	LDFLAGS		    ""
	      linker options to	use. By	default	no options are passed  to  the
	      linker.  Its  setting is overruled by an identically named envi-
	      ronment variable;

       o      //#define	LIBRARY		  "modules"
	      by defining this directive a local library is constructed.  When
	      a	 binary	 program  is  built  it	is linked against this library
	      rather than to the individual object modules.

	      If a library instead of a	program	must be	constructed (see  also
	      the  DEFCOM directive), then the LIBRARY directive specifies the
	      library's	base name (without the lib prefix and without  the  .a
	      extension). In that case source files are	expected in sub-direc-
	      tories of	the project's main directory (i.e., the	directory con-
	      taining  icmconf).  In  that case	avoid having source and	header
	      files in the project's main directory. Instead, move such	 files
	      to a separate sub-directory;

       o      //#define	MAIN		    "main.cc"
	      the  source file in which	the int	main function is defined. This
	      directive	is required when doing program (rather	than  library)
	      maintenance.

	      Note:  if	 source	files are located in the project's main	direc-
	      tory but library maintenance is intended	(e.g.,	by  specifying
	      #define  DEFCOM  library)	 then  define MAIN to specify a	pseudo
	      main source, whose base name is the base name of the header file
	      in  the project's	main directory.	This, however, is considered a
	      kludge, and should be avoided by moving those source and	header
	      files to a separate sub-directory;

       o      //#define	NO_PRECOMP_WARNING"
	      when  PRECOMP  is	defined	(see below) a warning is issued	when a
	      class-directory does not contain a IH file.  Such	 warnings  are
	      suppressed  by  defining NO_PRECOMP_WARNING. This	option is only
	      considered when PRECOMP has been defined;

       o      #define OBJ_EXT		  ".o"
	      this directive specifies the extension of	object modules created
	      by the compiler;

       o      //#define	PRECOMP		  "-x c++-header"
	      define this directive to construct precompiled headers (in which
	      case the IH) directive must also have been specified.  Dependen-
	      cies between (precompiled) headers are automatically considered.

       Existing	 precompiled headers are removed by icmbuild cleangch (or icm-
       build clean. When source	files of other languages are compiled the PRE-
       COMP's -x argument must be adapted to those languages;

       o      //#define	REFRESH
	      define  REFRESH  to relink the binary program when icmbuild pro-
	      gram is called, even though no file was  (re)compiled.  This  is
	      useful  when  the	program	links to external libraries which were
	      updated separately from the currrent project;

       o      //#define	SHARED
	      this directive is	only interpreted when LIBRARY is  also	speci-
	      fied.   If defined a shared library (extension .so*) is built in
	      addition to a static library (extension .a);

       The shared library receives VERSION as its version  number  while  soft
       links  using  VERSION's	(see below) major version number an no version
       number are also made available. E.g., if	VERSION	is defined as  1.02.03
       and  #define  LIBRARY  "demo"  then  the	 shared	 library  becomes lib-
       demo.so.1.02.03,	with libdemo.so.1 soft-linking to it,  and  libdemo.so
       soft-linking to libdemo.so.1;

       o      //#define	SHAREDREQ ""
	      when  creating a shared library SHAREDREQ	specifies the names of
	      libraries	and library paths that are required by the constructed
	      shared   library	itself.	  E.g.,	 if  a	library	 is  found  in
	      /usr/lib/special,	assuming that the name of the required library
	      is  libspecial.so,  then use the specification #define SHAREDREQ
	      "-L/usr/lib/special -lspecial".  The /lib	and /usr/lib paths are
	      usually  automatically visited by	the linker and do not have the
	      be specified. This directive is required (possibly as  an	 empty
	      string) if SHARED	is defined;

       o      #define SOURCES "*.cc"
	      the pattern to locate sources in directories;

       o      #define TMP_DIR "tmp"
	      the directory in which intermediate results are stored. To avoid
	      cross-device communications it's probably	best to	define TMP_DIR
	      as a sub-directory of the	project's main directory;

       o      //#define	USE_ALL	"a"
	      when defining this directive icmbuild looks for directories con-
	      taining files having the names defined by	the USE_ALL specifica-
	      tion.  All  source  files	 in  those  directories	as well	as all
	      source files in directories that (recursively) depend on the set
	      of  directories  under consideration are recompiled, after which
	      the USE_ALL files	are removed;

       o      //#define	USE_ECHO ON
	      when defined as ON (rather than OFF) (system) commands  executed
	      by icmbuild are echoed;

       o      //#define	USE_VERSION
	      when  defined  (it is defined by default)	a file VERSION is read
	      by icmconf to determine the program's or library's version,  and
	      the  project's release years. The	file VERSION must be available
	      in the project's main directory and should  contain  lines  like
	      these:

		  VERSION=9.03.00
		  YEARS=1992-2020

	      )

PARSER MAINTENANCE
       The following directives	are available in cases where  a	program	uses a
       parser generator	creating a parser class	from a grammar	specification.
       By default they're all commented	out.

       o      //#define	PARSER_DIR ""
	      the sub-directory	containing the parser's	specification file. If
	      the PARSER_DIR directory is specified then all other  directives
	      in this section must also	be specified;

       o      //#define	PARSFILES ""
	      if  the  parser  specification file named	at PARSSPEC itself in-
	      cludes 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
	      is created;

       o      //#define	PARSFLAGS "-V"
	      the  flags  that	are used when calling the program specified at
	      PARSGEN;

       o      //#define	PARSGEN	"bisonc++"
	      the name of the program generating the parser;

       o      //#define	PARSOUT	"parse.cc"
	      the name of the file generated by	the parser generator (used  by
	      icmbuild	when  checking	the timestamps of parser specification
	      s);

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

SCANNER	MAINTENANCE
       The following directives	are available in cases where  a	program	uses a
       scanner generator creating a lexical scanner class from a set of	 regu-
       lar expressions.	By default they're all commented out.

       o      #define SCANNER_DIR ""
	      the  subdirectory	 containing  the scanner's specification file.
	      If the SCANNER_DIR directory is specified	then all other	direc-
	      tives in this section must also be specified;

       o      #define SCANFILES	""
	      if  the lexical scanner specification file named at SCANSPEC it-
	      self 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 is created. By default no additional
	      specification files are used;

       o      #define SCANFLAGS	""
	      the flags	that are used when calling the	program	 specified  at
	      SCANGEN;

       o      #define SCANGEN "flexc++"
	      the name of the program generating the lexical scanner;

       o      #define SCANOUT  "lex.cc"
	      the  name	of the file generated by the lexical scanner (which is
	      used by icmbuild when checking the timestamps of scanner	speci-
	      fication s).

       o      #define SCANSPEC "lexer"
	      the name of the lexical scanner specification file. This file is
	      expected in the directory	specified by  the  SCANNER_DIR	direc-
	      tive.

FILES
       The  mentioned  paths are sugestive only	and may	be installation	depen-
       dent:

       o      /usr/share/icmake/CLASSES
	      :	example	of an icmconf CLASSES file;

       o      /usr/share/icmake/icmconf
	      :	default	(skeleton) icmbuild resource files, like main.cc,  us-
	      age.cc, etc.;

       o      /etc/icmake
	      :	 directory containing the default system-wide icmstart(1) con-
	      figuration file;

       o      $HOME/.icmake
	      :	optional user-defined directory	containing user-defined	speci-
	      fications	overruling the system-wide definitions.	This directory
	      is the proper location for a file	AUTHOR defining	the AUTHOR di-
	      rective  with the	user's name. E.g., my .icmake/AUTHOR file con-
	      tains:

	      #define AUTHOR  "Frank B.	Brokken	(f.b.brokken@rug.nl)";

SEE ALSO
       icmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).

BUGS
       icmbuild(1) ends, displaying a fatal  error  message,  if  the  current
       working directory does not contain a file icmconf.

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.03.01.tar.gz		   1992-2020			    icmconf(7)

NAME | DESCRIPTION | CLASS DEPENDENCIES | DEFINES IN ICMCONF | PARSER MAINTENANCE | SCANNER MAINTENANCE | FILES | SEE ALSO | BUGS | COPYRIGHT | AUTHOR

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

home | help