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)	script.	It can be used
       to activate and specify various directives that determine how the  pro-
       gram 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 using a final backslash char-
       acter 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  a new member function to a	class does not require
       you to recompile	already	existing source	files.	Recompilation  is  re-
       quired when modifying the data member organization of classes.

       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.

       Likewise, if the	PRECOMP	parameter was specified, 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  precom-
       piled 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).

ICMCONF	PARAMETERS
       o      #define ADD_LIBRARIES	  ""
	      When a program  must  be	linked	against	 additional  libraries
	      (other  than the name of the program's library itself, if	speci-
	      fied at LIBRARY) then those libraries should be specified, blank
	      space  separated,	 here.	E.g., when a program is	linked against
	      libbobcat	then the specification is:

		  #define ADD_LIBRARIES	  "bobcat"

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

       o      #define ADD_LIBRARY_PATHS	 ""
	      When  the	 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 sepa-
	      rated) specified here. Specify only the paths, not the -L	flags.

	      It is stronly advised to specify full pathnames here, or	remem-
	      ber  that	 normally  the location	of the icmconf file is not the
	      location where the compilation actually takes  place,  which  is
	      the location specified at	the TMP_DIR parameter (see below).

       o      #define CLS
	      The  clear screen	directive. If defined clear is called to clear
	      the terminal screen before starting the compilation. By  default
	      it is not	defined.

       o      #define CXX		  "g++"
	      The  C++ compiler	to use.	For a C	compiler use, e.g., #define CC
	      "gcc". Its setting is overruled by an identically	named environ-
	      ment variable.

       o      #define CXXFLAGS		  "--std=c++14 -Wall -O2"
	      The compiler options to use. The default options are shown. When
	      the C compiler is	used, use #define CFLAGS rather	than CXXFLAGS.
	      Its  setting  is	overruled  by an identically named environment
	      variable.

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

		  #define DEFCOM  "program"

	      in which case icmbuild will do program maintenance.  It may also
	      be defined as:

		  #define DEFCOM  "program strip"

	      in which case icmbuild  does  program  maintenance,  creating  a
	      stripped binary program.

	      Alternatively it may also	be defined 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.

       o      #define LDFLAGS		  ""
	      The linker options to use. By default no options are  passed  to
	      the linker. Its setting is overruled by an identically named en-
	      vironment	variable.

       o      #define LIBRARY		"modules"
	      By default this directive	is not defined.	If defined a local li-
	      brary  is	constructed. When a binary program is built it will be
	      linked against this library rather than to the individual	object
	      modules.

	      If  a  library  must  be constructed (see	also the DEFCOM	direc-
	      tive), then the LIBRARY directive	 must  specify	the  library's
	      base name	(without the lib prefix	and without the	.a extension).

	      After a library has been constructed icmbuild install static dir
	      installs the static  library  at	dir,  while  icmbuild  install
	      shared  dir  installs  the  shared library (see below at #define
	      SHARED) at dir.

       o      #define MAIN		  "main.cc"
	      The source file in which the int main function is	defined.  This
	      specification  may be left as-is or may completely be removed if
	      icmbuild(1) is used for library maintenance rather than  program
	      maintenance.

       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  when defining	NO_PRECOMP_WARNING. This option	is ig-
	      nored unless PRECOMP has been defined.

       o      #define OBJ_EXT		  ".o"
	      The extension of object modules created by the compiler.

       o      //#define	PRECOMP		  "-x c++-header"
	      When activated internal header files (see	#define	IH)  are  pre-
	      compiled	when  they are more recent than	their precompiled ver-
	      sions. Also, when	a precompiled header file is (re)compiled  the
	      precompiled  header  files of all	dependent classes are also re-
	      compiled.

	      Precompiled headers are removed by icmbuild  clean.  To  specify
	      internal header files for	other languages	change the -x specifi-
	      cation accordingly. By default this #define is not active.

       o      #define REFRESH
	      Define REFRESH to	relink the binary program  at  every  icmbuild
	      program call. By default REFRESH is not defined.

       o      #define SHARED
	      This  directive  is  only	interpreted if LIBRARY was also	speci-
	      fied.  If	defined	a static library (extension .a)	as well	 as  a
	      shared  library (extension .so*) is built. If not	specified, but
	      LIBRARY was specified, only the static library is	built. By  de-
	      fault SHARED is not defined.

	      The  shared  library  receives  as its major version number VER-
	      SION's major version number, and receives	VERSION	 as  its  full
	      version  number.	E.g., if VERSION is defined as 1.02.03 and LI-
	      BRARY  is	 defined  as  demo  then  the  shared	library	  lib-
	      demo.so.1.02.03  is  constructed,	with libdemo.so.1 soft-linking
	      to it, with libdemo.so in	turn 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 shared li-
	      brary.  E.g., if a library is found in /usr/lib/special,	assum-
	      ing that the name	of the required	library	is libspecial.so, then
	      use the specification "-L/usr/lib/special	-lspecial".  The  /lib
	      and /usr/lib paths are usually predefined	and need not be	speci-
	      fied. This directive is only interpreted if SHARED  and  LIBRARY
	      were also	defined.

       o      #define SOURCES		  "*.cc"
	      The  pattern to locate sources in	a directory. The default value
	      is shown.

       o      #define TMP_DIR		  "tmp"
	      The directory in which intermediate results are stored. Relative
	      to  the  current	working	 directory  unless an absolute path is
	      specified.

       o      #define USE_ALL	  "a"
	      After defining this directive (by	default	 it  is	 not  defined)
	      class  dependencies are interpreted. In this case, when a	direc-
	      tory contains a file having a name  that's  equal	 to  the  name
	      specified	 at  the  USE_ALL  directive, then all sources of that
	      class as well as all sources of classes that depend  on  it  are
	      (re)compiled.

	      Following	 the successful	recompilations the s specified at #de-
	      fine USE_ALL are removed.

	      When the USE_ALL directive was specified	the  command  icmbuild
	      clean also removes any leftover USE_ALL files from the program's
	      subdirectories.

       o      #define USE_ECHO		    ON
	      When specified as	ON (rather than	OFF) commands executed by icm-
	      build are	echoed.

       o      #define USE_VERSION
	      If  defined  (which  is the default) the file VERSION is read by
	      icmconf to determine  the	 program/library's  version,  and  the
	      project's	release	years.

PARSER MAINTENANCE
       The following directives	are available in cases where  a	program	uses a
       parser generator	creating a parser class	from a grammar specification:

       o      #define PARSER_DIR	  ""
	      The subdirectory containing the parser's specification file.

	      If parser	maintenance is not required, then this	directive  can
	      be  omitted.  If	omitted, then all other	directives, that begin
	      with PARS, can also be omitted.

       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
	      will be created. By default no  additional  specification	 files
	      are used.

       o      #define PARSFLAGS		  "-V"
	      The flags	to use 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 (which is
	      used by icmbuild to compare the timestamps of the	parser	speci-
	      fication s against).

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

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:

       o      #define SCANNER_DIR	  ""
	      The subdirectory containing the scanner's	specification file.

	      If lexical scanner maintenance is	not required, then this	direc-
	      tive can be omitted. If omitted, then all	other directives, that
	      begin with SCAN, can also	be omitted.

       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 will be created. By default no	 addi-
	      tional specification files are used.

       o      #define SCANFLAGS		  ""
	      The flags	to use 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 to compare the timestamps of the	scanner	speci-
	      fication s against).

       o      #define SCANSPEC		  "lexer"
	      The name of the lexical scanner specification file. This file is
	      expected in the directory	specified at SCANNER_DIR.

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

       o      /etc/icmake
	      Directory	 containing the	default	system-wide icmake(1) configu-
	      ration files (like VERSION and icmstart.rc)

       o      $HOME/.icmake
	      Optional directory containing user-defined specifications	 over-
	      ruling the system-wide definitions. This directory is the	proper
	      location for a file AUTHOR defining the  AUTHOR  directive  with
	      the user's name. E.g., my	.icmake/AUTHOR file contains:

	      #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 work-
       ing 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.02.07.tar.gz		   1992-2018			    icmconf(7)

NAME | DESCRIPTION | CLASS DEPENDENCIES | ICMCONF PARAMETERS | 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