Provided by: icmake_12.00.01-1ubuntu1_amd64 bug

NAME

       icmake - A program maintenance (make) utility using a C-like grammar

SYNOPSIS

       icmake option(s) [source [dest]] [args]

DESCRIPTION

       Icmake(1)  is  a  generic  tool  handling  program  maintenance  that  can  be  used as an
       alternative for make(1). It’s a generic tool in that icmake-scripts, written in a language
       closely  resembling  the  C programming language, can perform tasks that are traditionally
       the domain of scripting languages. See also section ICMAKE V. 11.01.00 below  an  overview
       of the changes from version 10 to version 11.

       To  summarize the changes: since icmake version 11.00.00 icmake offers Single Pre-Compiled
       Headers  (SPCH)  and  multi-threaded  source-file  compilation,  commonly   reducing   the
       construction times of projects to around 30-40% of the original construction times.

       Icmake allows programmers to use a programming language (closely resembling the well-known
       C-programming language) to define the actions that  are  required  for  (complex)  program
       maintenance. For this, icmake offers various special operators as well as a set of support
       functions that have shown their usefulness in program maintenance.

       Although icmake scripts can be written from scratch, often  the  required  activities  are
       highly  comparable.  This  observation resulted in the construction of two icmake scripts,
       which are part of the standard icmake distribution: icmstart(1), initializing a  directory
       for  program  development  and  icmbuild(1),  handling  the actual program maintenance. By
       default both scripts are  tailored to initializing and maintaining C++ programs (or, after
       minimal adaptation, C programs), but can easily be adapted to other programming languages.

       This  man-page  covers  icmake  (the program), and its main support programs. Refer to the
       icmstart(1) man-page for information about how a directory can be initialized (created) in
       which  (by  default)  a  C++  or  C program can be developed, and refer to the icmbuild(1)
       man-page for information about how icmbuild can be used to handle program maintenance.

       The icmscript(7) man-page covers the syntax and facilities offered by  icmake’s  scripting
       language, allowing you to write your own icmake scripts.

       Icmake  should  not  be  confused with an Integrated Development Environment (IDE). Icmake
       merely performs tasks for which scripts can be written, and a minimal set  of  pre-defined
       scripts  (icmstart  and  icmbuild)  that  have proven their usefulness when developing and
       maintaining programs are included in icmake’s distribution.

       In its standard activation modes, icmake uses the following support programs:

       o      icm-pp     to pre-process the icmake file,

       o      icm-comp   to byte-code compile the icmake  s,

       o      icm-dep to handle class-dependencies (see the ICM-DEP section in this man-page  for
              more information about icm-dep),

       o      icm-exec to execute the byte-code file.

       In addition, since version 11.00.00, icmake uses two new support programs:

       o      icm-multicomp to use multi-threaded source file compilation,

       o      icm-spch  to  construct  a  project-wide  Single  Pre-Compiled Hbeader file (SPCH).
              Refer to the sections (below) ICMAKE V. 11.00.00, OPTIONS (for descriptions of  the
              options   --multicomp   and  spch);  MULTICOMP  and  SPCH  for,  respectively,  the
              descriptions  of  the  icm-multicomp  and  icm-spch  programs;  and  refer  to  the
              icmconf(7)  man-page  for details about the new #define directives MULTICOMP, SPCH,
              and SPCH_FILE.

       Furthermore, primarily used for illustration, education, and debugging, the program  icmun
       is available to disassemble compiled icmake byte-code (.bim) files (`bim-files’). Icmun is
       not installed in a standard PATH directory but in icmake’s lib directory,  which  commonly
       is /usr/libexec/icmake (see also section ICMUN below).

       Traditional  make-utilities  recompile  sources  once  header  files  are  modified.  When
       developing C++ programs this is often not required, as  adding  new  member  functions  to
       classes  does  not  require  you to recompile all source files of those classes. To handle
       class  dependencies  icmbuld(1)  optionally  inspects  class  dependencies,  (re)compiling
       sources  of  dependent  classes  when  necessary.  By  default, class-dependencies are not
       considered, but they  are  when  the  USE_ALL,  SPCH,  and/or  (deprecated  since  version
       11.00.00)  PRECOMP  #define directives, found in the icmconf file, are activated. Refer to
       the icmconf(7) man-page for details about these directives.

       This manpage describes icmake’s options in section OPTIONS, followed by sections  covering
       the support programs

       o      ICM-DEP
              the icm-dep dependency analyzer;

       o      ICM-MULTICOMP
              the icm-multicomp multi-threaded compiler program.

       o      ICM-SPCH
              the icm-spch SPCH construction support program

       o      ICMUN
              icmake’s unassembler.

       Refer  to  the  icmscript(7)  man-page  for  a  description  of  icmake’s C-like scripting
       language.

ICMAKE V. 11.01.00

       Since icmake version 11.00.00 icmake may construct and  use  Single  Pre-Compiled  Headers
       (SPCH) and also offers multi-threaded source-file compilations.

       The  icmake support program icm-spch (callable via icmake --spch ..., see section ICM-SPCH
       for details) handles the construction of SPCHs; the icmake support  program  icm-multicomp
       (callable  via  icmake  --multicomp  ...,  see  section ICM-MULTICOMP for details) handles
       multi-threaded source-file compilations. See also the icmconf(7) manpage.

       When developing C++ programs the environment variable ICMAKE_CXXFLAGS is no  longer  used.
       Instead  the  environment  variable  ICMAKE_CPPSTD  is  used.  Use this latter environment
       variable to have one point of maintenance specifying the version of the  C++  standard  to
       use when compiling your sources.

OPTIONS

       Where  available,  single  letter  options  are  listed  between  parentheses beyond their
       associated long-option variants. Icmake defines action options and non-action options. The
       first action option that is encountered is used.

       When  using  icmbuild(1)  for  program maintenance icmake is called automatically, and the
       user doesn’t have to specify any icmake options.

       The following action options write some text to the  standard  output  stream,  whereafter
       icmake ends:

       o      --about (-a)
              Shows some information about icmake;

       o      --help (-h)
              Provides usage info, returning 0 to the operating system. Usage information is also
              provided if icmake is started without  providing  arguments.  In  that  case  1  is
              returned to the operating system;

       o      --version (-v)
              Displays icmake’s version.

       The remaining action options require additional options and/or arguments, and most of them
       process icmake source- or bim-files. Several of these action options write  output  files.
       By  default  these  files  are  located  in  the  same  directories  as  the source files’
       directories.

       The remaining action options are:

       o      --compile (-c) [options] source [bim-file]
              The source file is first pre-processed (by  icm-pp)  whereafter  the  pre-processed
              file  is compiled (by icm-comp), producing a bim-file.  If the bim-file name is not
              specified then source’s base-name, receiving extension .bim, is used.
              If the bim-file exists and is younger than source then source is not compiled.
              With this option pre-processor symbol-defining options can be used: symbols  having
              values 1 which can be used in source. E.g., when issuing the command

                  icmake -c -d one --define two source dest.bim

              then  icmake  compiles  source, defines the pre-processor symbols one and two (each
              having value 1), and produces the bim-file dest.bim. Note  that  instead  of  using
              long options --define short options -d can also be used.
              If  source  is  a previously pre-processed file then option -P must be specified to
              compile it. E.g.,

                  icmake -c -P source dest.bim

       o      --dependencies (-d) [options] action
              Icmake calls icm-dep to determine the dependencies among classes. All  options  and
              arguments  following  this  option  are  forwarded to icm-dep. Refer to the ICM-DEP
              section of this man-page for information about icm-dep;

       o      --execute (-e) [option] bim-file [arguments]
              Executes the bim-file, specified  as  icmake’s  first  file  argument.  Before  the
              bim-file  option  --no-version-check  (or  the  equivalent  short option -n) can be
              specified to allow mismatches between icmake’s main version and the icmake  version
              that   was  used  to  compile  the  bim-file.  See  also  the  description  of  the
              --no-version-check option at the description of the non-action options below.
              Options and arguments specified beyond the bim-file are forwarded as  arguments  to
              the  bim-file’s main function (refer to the icmscript(7) man-page for details about
              how to write icmake-scripts);

       o      --force (-f) [options] source [bim-file]
              Acts like option --compile, but  compilation  is  always  performed,  even  if  the
              bim-file  is up-to-date. As with --compile, if source is a previously pre-processed
              file then option -P must be specified to compile it. E.g.,

                  icmake -f -P source dest.bim

       o      --multicomp (-m) [options] jobs ’compiler-spec’
              The optional options are the options of the icm-multicomp program:  --threads  (-t)
              and/or  --quiet  (-q).  The  ’compiler-spec’ argument is the (quoted) compiler call
              specification, using $1 to refer to the source file to compile, $2 to refer to  the
              object  file’s  path,  like  ’/usr/bin/g++  -c  -o  $2  --Wall -Werror $1’ Threaded
              compilation is automatically used when the #define MULTICOMP directive is specified
              in projects’ icmconf files.
              Refer  to  section  ICM-MULTICOMP (below) for a description of icm-spch’s usage and
              arguments.

       o      --preprocess (-p)  [options] source [pim-file]
              The file specified as first argument is pre-processed, producing a `.pim’ file.  If
              a second filename argument is provided then that file becomes the .pim file. If not
              specified, then the first filename, using the extension .pim, is used.
              With this option pre-processor symbol-defining options can be used: symbols  having
              values 1 which can be used in source. E.g., when issuing the command

                  icmake -p -d one --define two source dest.pim

              then  icmake  pre-processes  source,  defines the pre-processor symbols one and two
              (each having value 1), and produces the pim-file dest.pim.  Note  that  instead  of
              using long options --define short options -d can also be used;

       o      --spch (-S) ...
              A  SPCH  is  built. All options and arguments following --spch are forwarded to the
              icm-spch support program.
              A SPCH is automatically constructed when the #define SPCH directive is specified in
              projects’ icmconf files.
              Refer  to  section  ICM-SPCH  (below)  for  a  description  of icm-spch’s usage and
              arguments.

       o      --source (-s)  [options] source [arguments]
              Icmake uses --compile to compile the icmake source file specified as first argument
              (constructing the default bim-file if necessary) and then uses --execute to execute
              the bim-file, forwarding any subsequent arguments  as-is  to  the  bim-file’s  main
              function.
              With  this  option  pre-processor options as well as the --no-version-check execute
              option can be used. When using the latter option it must follow  the  pre-processor
              options  (if  specified)  and  it must be preceded by --execute (or -e). E.g., when
              issuing the command

                  icmake -s -d one -en source

              then icmake first compiles source, defining the pre-processor symbol one, and  then
              executes the bim-file, passing --no-version-check to icm-exec;

       o      -t tmpspec [options] source [arguments]
              This  option  is  intended  for  icmake-scripts  although  it can also be used in a
              command-line icmake call. Its argument tmpspec is either a single dot (as  in  -t.)
              in  which  case  icmake determines the name of the bim-file in the directory icmake
              uses for temporary files (see option --tmpdir below), or it  uses  tmpspec  as  the
              filename  to  write  the  bim-file to (which file is also removed once the script’s
              execution ends).
              At the options pre-processor options as  well  as  the  --no-version-check  execute
              option  can  be  specified.  When  using  the  latter  option  it  must  follow the
              pre-processor options (if specified) and it must be preceded by --execute (or -e).
              The argument source is the name of the icmake script to  process,  and  source  may
              optionally  be  followed  by  arguments. Those arguments are forwarded as-is to the
              script’s main function, where they appear as elements of its list argv parameter.

              Rather than using the explicit command-line call icmake -t. ... the  -t  option  is
              normally  used in the first line of an (executable) (so usually chmod +x source has
              been specified before calling the script),  where  its  pre-processor  and  execute
              options  can  also  be  specified.  For example after writing the executable script
              hello:

                  #!/usr/bin/icmake -t.

                  int main(int argc, list argv)
                  {
                      printf << "hello: " << argv << ’\n’;
                  }

              it can be called as hello one -two --three, producing output like:

                  hello: /tmp/10434.bim.MKqvAb one -two --three

              (the name following hello: will be different, as it is the  name  of  the  compiled
              temporary bim-file). If icmake pre-process and/or execute options are required they
              can be specified in the first line, following the -t option. E.g.,

                  #!/usr/bin/icmake -t. -d one --define two

       o      --unassemble (-u)
              The file specified as first argument is an icmake bim-file, which  is  unassembled.
              Refer  to  the  icmun section further down this man-page for more information about
              icmun;

              The  program  icmun  unassembles  bim-files.  This  program   also   supports   the
              --no-version-check (-n) option.

       Finally,  there  are  some  (non-action)  options  that can be specified before specifying
       action options:

       o      --no-process (-N)
              Implies option --verbose. This option may precede options -d, -e, -s and -t (either
              as  two  separate  options  or  by  `gluing’ both options together, like -Ne). When
              specified, the actions are not activated, but the command(s) that would  have  been
              used are shown to the standard output;

       o      --no-version-check (-n)
              This option is available with the action options --execute, --source, --unassemble,
              and -t. When specified the main versions of icm-bim files  and  icmake  itself  may
              differ.  This  option  should  normally  not be used, and was added for development
              purposes only;

       o      --tmpdir=directory (-T)
              The specified directory is used for storing temporary files. E.g.,  when  compiling
              an  icmake  script,  the  output of icmake’s preprocessor is written to a temporary
              file which is removed when icmake ends. By default /tmp is used, unless /tmp is not
              a writable directory, in which case the current user’s $HOME directory is used;

       o      --verbose (-V)
              The  child  processes and their arguments are written to the standard output stream
              before they are called. This option may precede options -d, -e, -s and  -t  (either
              as two separate options or by `gluing’ both options together, like -Ve).

ICM-DEP

       Icm-dep  is a support program called by icmake to determine source- and precompiled-header
       file dependencies. Icm-dep can be  used  for  software  projects  that  are  developed  as
       described in the C++ Annotations, section Header file organization in chapter Classes. For
       those  projects  classes  are  developed  in  their  own  directories,  which  are  direct
       sub-directories  of  the  project’s  main  program  directory.  Their class interfaces are
       provided in class-header files bearing the names of the class-directories, and all headers
       that are required by the class’s sources are declared in a separate internal header files,
       commonly having extensions .ih.

       Icmake automatically calls icm-dep when USE_ALL, SPCH, or PRECOMP is specified in  icmconf
       files.    By   default   it   is   called  with  arguments  -V  go.  The  #define  ICM_DEP
       define-specification in the icmconf file can  be  used  to  specify  a  different  set  of
       options.

       By  default,  when  called  by  icmake directory dependencies are determined, touching all
       files in directories that depend on directories containing files whose names are specified
       by the icmconf’s #define USE_ALL direcctive.

       When icmconf files contain the #define SPCH directive icm-dep does not inspect precompiled
       headers: Single  Pre-Compiled  Headers  are  automatically  inspected  (and  updated  when
       necessary) by icm-precompile (also automatically called by icmake.

       By  providing  another  argument  than  go  icm-dep  performs  a  `dry  run’:  it analyzes
       dependencies, but it won’t remove or touch files.

       Options of icm-dep may be specified immediately following icmake’s --dependencies  option.
       Icm-dep accepts the following options:

       o      --classes=filename (-c)
              By  default, icm-dep inspects dependencies of the directories mentioned in the file
              CLASSES. Furthermore, if the icmconf(7) file specifies PARSER_DIR  and  SCANNER_DIR
              then  those  directories  are also considered.  Use this option to specify the file
              containing the names of directories to be inspected by icm-dep.

       o      --gch
              If icmconf files contain #define PRECOMP directives  then  icm-dep  checks  whether
              precompiled  headers  must  be  refreshed.   If  an icmconf file does not contain a
              #define PRECOMP diretive, but precompiled headers should nonetheless be  inspected,
              then option --gch can be specified;

       o      --help (-h)
              Icm-dep  writes  a  summary  of  its  usage  to the standard output and terminates,
              returning 0 to the operating system;

       o      --icmconf=filename (-i)
              By default icm-dep inspects the content of icmconf files, This option  is  used  if
              instead of icmconf another file should be inspected;

       o      --mainih=mainheader (-m)
              In the icmconf file the #define IH directive is used to specify the suffix of class
              header files that should be precompiled, assuming that their filenames are equal to
              the names of the directories which are listed in the CLASSES file. But CLASSES does
              not specify the name of the program’s top-level directory. This option is  used  to
              specify  the name of the top-level header file to precompile. By default main.ih is
              used;

       o      --no-gch
              If icmconf files contain #define PRECOMP directives but icm-dep  should  not  check
              whether  precompiled  headers  must  be  refreshed  then  option --no-gch should be
              specified;

       o      --no-use-all
              If icmconf files contain #define USE_ALL  "filename"  directives  then  all  source
              files   in  directories  containing  files  named  filename  are  recompiled.  When
              specifying this option inspections of `USE_ALL’ specifications is suppressed;

       o      --use-all=filename
              If icmconf files contain #define USE_ALL  "filename"  directives  then  all  source
              files  in  directories containing files named filename are recompiled. Specify this
              option to inspect the presence of filename files if  icmconf  does  not  contain  a
              #define USE_ALL directive;

       o      --verbose (-V)
              This  option  can  be specified multiple times. The number of times it is specified
              determines icm-dep’s verbosity. If not used  then  icm-dep  silently  performs  its
              duties. If specified once, then icm-dep reports to the standard output what actions
              it  performs;  if  specified  twice  it  also  reports  non-default   options   and
              automatically  included directories; if specified three times it also reports class
              dependencies; if specified more often it reports what files it encountered and what
              decision it would make when go would be specified;

       o      --version (-v)
              Icm-dep reports its version number to the standard output and terminates, returning
              0 to the operating system.

       As an example, for icmake itself the class dependencies, obtained using  the  option  -VVV
       are shown as:

           Direct class dependencies:
           --------------------------
                         uses:
                         ------------
               class:     1  2  3  4
           --------------------------
                    .  1  x  x  x  x
              options  2     x     x
              handler  3     x  x
           argoptions  4           x
           --------------------------
                          1  2  3  4
           --------------------------

           Implied class dependencies:
           --------------------------
                         uses:
                         ------------
               class:     1  2  3  4
           --------------------------
                    .  1  -  x  x  x
              handler  2     -  x  x
              options  3        -  x
           argoptions  4           -
           --------------------------
                          1  2  3  4
           --------------------------

       The  second  table  immediately  shows  that there are no circular dependencies: its lower
       triangle remains empty.

ICM-MULTICOMP

       Icmake supports multi-threaded source-file compilation, often significantly  reducing  the
       compilation  time  of  the  source  files  of  projects.  When  using  the standard icmake
       icmbuild(1) program  multi-threaded  compilation  is  automatically  used  when  projects’
       icmconf  files  contain  the  #define MULTICOMP directive (cf. icmconf(7)). It can also be
       called independently from icmconf using icmake’s --multicomp (or -m) option.

       Icm-multicomp accepts the following options:

       o      --help (-h)
              Icm-multicomp writes a summary of its usage to the standard output and  terminates,
              returning 0 to the operating system;

       o      --nr (-n)
              When  compiling  source  files  and option --nr is specified then the thread number
              compiling a source file is written to the standard output stream.

       o      --quiet (-q)
              When this options is not specified then the path names of the compiled  object  and
              source  files  are written to the standard output stream. When it is specified once
              only the source files’ directories and filenames are written to the standard output
              stream,  and  when it is specified more than once no information about the compiled
              files is written to the standard output stream.

       o      --threads=nThreads (-t)
              By default the computer’s number of cores determines the number  of  threads  being
              used  when compiling the source files. Optionally a different number of threads can
              be requested using this option, e.g., --threads 5.

       o      --version (-v)
              Icm-multicomp reports its version number to the  standard  output  and  terminates,
              returning 0 to the operating system.

       Icm-multicomp needs one command-line argument and an optional second argument:

       o      the first argument is the name of the file specifying which files must be compiled.
              Use icmbuild(1) to write this file. It  can  also  be  constructed  otherwise.   It
              ccontains  groups of file specifications where each group starts with a line like :
              support tmp/o 5 where the 2nd element specifies the  location  (directory)  of  the
              source files (use . to refer to the project’s top-level directory); the 3rd element
              specifies the destination directory of the compiled files (which is created if  not
              existing); and the 4th element specifies the prefix to add in front of the compiled
              object files.
              Following this line the remaining lines of a group specify the names of the  source
              files to compile.
              Once the compilation ends (either because all files were successfully ccompiled, or
              because a compilation failed) the specification file is removed;

       o      the second argument is optional. By default the  following  specification  is  used
              (all on one line)

                  g++ -c -o $2 ${ICMAKE_CPPSTD} --Wall -Werror $1

              In  this specification $1 is replaced by the location of the source file to compile
              and $2 is replaced by the location of the compiled object file. If the  environment
              variable  ICMAKE_CPPSTD  is  defined  (specifying  the  C++  standard to use, e.g.,
              ICMAKE_CPPSTD=--std=c++23)  then  its  value  replaces  ${ICMAKE_CPPSTD}   in   the
              specification.
              Alternatively,  the  command  compiling  source  files  can  be  provided as second
              command-line argument, which should be quoted, like

                  ’g++ -c -o $2 ’${ICMAKE_CPPSTD}’ --Wall -Werror $1’

              or the second command-line argument can be f:file, where file is the name of a file
              whose  first  line contains the specification of the command compiling source files
              (which must specify $1 and $2 and optionally $ICMAKE_CPPSTD).
              The PATH environment variable is  used  to  locate  the  compiler;  the  compiler’s
              absolute path can also be used.

ICM-SPCH

              icmake --spch calls icm-spch.
              icmake --spch is followed by icm-spch’s options and arguments.

       Pre-compiled  headers  have  been  available  for quite some time, and usually result in a
       significant reduction of the compilation  time.  Traditionally  pre-compiled  headers  are
       defined  for  directories  containing  the  sources of components of programs or libraries
       (e.g., in C++ directories commonly contain the sources of classes). However,  there  is  a
       disadvantage  to  this  approach:  the  combined  sizes  of  such  separately  constructed
       pre-compiled headers can be huge, often requiring many Giga-Bytes of disk space. But often
       headers  of  separate  components themselves include identical (e.g., system-based) header
       files, like  (in  C++)  iostream,  string  and  vector.  As  a  result,  these  separately
       constructed pre-compiled headers contain large identical sections.

       Icm-spch  accepts  the  following  options  (after  covering the options, a more extensive
       description of icm-spch is provided):

       o      --classes=file (-c)
              this option can only be used in combination with the --list option.  File  contains
              the  list  of  directories inspected by the --list option (by default CLASSES). The
              project’s top directory is automatically inspected unless the option --no-topdir is
              specified;

       o      --guard=name (-g)
              this  option  can  only be used in combination with the --list option.  Name is the
              name of the include-guards used in internal headers.  By default name is SPCH_;

       o      --help (-h)
              Icm-multicomp writes a summary of its usage to the standard output and  terminates,
              returning 0 to the operating system;

       o      --internal=.ext (-i)
              this  option  can  only be used in combination with the --list option.  .ext is the
              extension used for the internal headers (including the dot) by default: .ih;

       o      --keep=regex (-k)
              this option can only be used in combination with the --list option.  It keeps  (and
              does  not  inspect) include-specification(s) in the internal header matching (POSIX
              extended) regular expressions in  regex.   Use  (...)|(...)   to  specify  multiple
              regexes. Use f:file to specify a file whose non-empty lines contain regexex;

       o      --list (-l)
              write  the filenames of the files to process when constructing a single precompiled
              header (SPCH) to the file (dest) specified as the command line argument. Dest  must
              specify a filename (without extension) in the current working directory.

       o      --no-topdir (-n)
              this  option  can  only  be used in combination with the --list option.  Ignore the
              internal header found in the project’s top directory.  This  option  is  used  when
              merely constructing a library instead of a program;

       o      --precompile=file (-p)
              precompile  file  (which is the name of the file specified at the option --list) to
              the SPCH file dest, specified as icm-spch’s first command-line  argument.  If  dest
              ends in / then the SPCH is the file ’dest’file.gch.
              By default the SPCH is constructed using the following command (all on one line):

                  g++ -c -o $2 ${ICMAKE_CPPSTD} -Wall -Werror -O2 -x c++-header $1

              Here,  $1  refers  to ’file’, $2 refers to ’dest’, and $ICMAKE_CPPSTD refers to the
              value of the ICMAKE_CPPSTD environment variable (specifying  the  C++  standard  to
              use, e.g., ICMAKE_CPPSTD=--std=c++23).
              Alternatively,  the  command  constructing  the  SPCH  can  be  provided  as second
              command-line argument, which should be quoted like

                  ’g++ -c -o $2 ’${ICMAKE_CPPSTD}’ -Wall -Werror -O2 -x c++-header $1’

              or the second command-line argument can be f:file, where file is the name of a file
              whose first line specifies the command constructing the SPCH (which must specify $1
              and $2 and optionally $ICMAKE_CPPSTD).
              The PATH environment variable is  used  to  locate  the  compiler;  the  compiler’s
              absolute path can also be used.

       o      --soft-links=file (-s)
              this  option  uses  the  same arguments as the arguments used with the --precompile
              option. This option creates .gch soft-links from the header files listed in file to
              the SPCH-file specified as the program’s command-line argument dest;

       o      --version (-v)
              Icm-multicomp  reports  its  version  number to the standard output and terminates,
              returning 0 to the operating system;

       o      --warn (-w)
              interactively warn when existing header files are about to be  modified,  accepting
              or refusing the modifications. Once refused icm-spch ends.

       Pre-compiled  headers  have  been  available  for quite some time, and usually result in a
       significant reduction of the compilation time. Using single precompiled headers results in
       a  large  reduction  of  required  disk-space  compared  to  using precompiled headers for
       separate directories.

       When using SPCHs  almost  identical  precompiled  headers  for  separate  directories  are
       avoided:  only  one precompiled header is constructed which is then used by all components
       of a project. As identical sections are avoided the  sizes  (and  construction  times)  of
       SPCHs  are  much  smaller, usually requiring only 5 to 10 % of the space (and construction
       time) ccompared to using separately constructed pre-compiled headers.

       When bfIicm-spch) is used for the  first  time  on  a  project  it  visits  the  project’s
       (internal) header files, and modifies them slightly to avoid namespace declarations inside
       the SPCH that might  otherwise  arise  when  identical  names  are  defined  in  different
       namespaces. Suppose an internal header file looks like this:

           #include "class.h"
           #include <ctype>
           #include <iostream>
           using namespace std;
           inline void Class::capitalize(string &text)
           {
               for (char &ch: text)
                   ch = toupper(ch);
           }

       then this header file is modified to

           #include "class.h"
           #include <ctype>
           #include <iostream>
           inline void Class::capitalize(string &text)
           {
               for (char &ch: text)
                   ch = toupper(ch);
           }
           #ifndef SPCH_
           using namespace std;
           #endif

       The  name SPCH_ is the ’guard’-name, which can be configured using the --guard option, but
       notice that following this modification the header file cannot be compiled  anymore  since
       the  inline  function  is  now positioned above the namespace declaration. Definitions and
       declarations which are positioned above the  #ifndef  SPCH_  declaration  must  therefore,
       where  necessary,  specify  their appropriate namespaces. E.g., for Class::capitalize this
       means:

           inline void Class::capitalize(std::string &text)
           {
               for (char &ch: text)
                   ch = toupper(ch);
           }

       The first line of the file specifying which headers to process  (which is specified as the
       command-line argument when using the --list option) contains the directive

           #define SPCH_

       and  at  the  end  the  namespaces  encountered  when  processing the internal headers are
       declared, e.g.,

           using namespace std;

       To use SPCHs in combination with icmbuild specify #define SPCH and maybe #define SPCH_FILE
       in  the  icmconf  file  (cf.  icmconf(7)). SPCHs can also be used independently from using
       icmbuild by using icmake’s --spch (or -S) option.

       Icm-spch, except when calling it with the --help or --version options, always requires one
       command  line argument (dest) (described at options --list, --precompile and --soft-link),
       and with option --precompile a second (optional) command-line argument  may  be  specified
       (destribed at that option).

       When  using icm-spch automatically (through icmbuild(1)) the following commands are issued
       (showing defaults):
           icm-spch -l spch
           icm-spch -p spch tmp/
           icm-spch -s spch tmp/

ICMUN

       The icmun support program expects one argument, a bim-file.  It  disassembles  the  binary
       file  an  shows the assembler instructions and the structure of the bim-file. Note that in
       standard installations icmun is not  located  in  one  of  the  directories  of  the  PATH
       environment  variable,  but  it is available in the /usr/libexec/icmake directory, and the
       command icmake -u bim-file is normally used to unassemble the bim-file.

       As an illustration, assume the following script is compiled by icmake  (e.g.,  by  calling
       icmake -c demo.im):

           void main()
           {
               printf("hello world");
           }

       the    resulting    demo.bim   file   can   be   processed   by   icmun   (e.g.,   calling
       /usr/libexec/icmake/icmun demo.bim). Icmun then  writes  the  following  to  the  standard
       output fle:

           icmun by Frank B. Brokken (f.b.brokken@rug.nl)
           icmun V10.00.00
           Copyright (c) GPL 1992-2021. NO WARRANTY.

           Binary file statistics:
                   strings      at offset  0x0025
                   variables    at offset  0x0032
                   filename     at offset  0x0032
                   code         at offset  0x0014
                   first opcode at offset  0x0021

           String constants dump:
                   [0025 (0000)] ""
                   [0026 (0001)] "hello world"

           Disassembled code:
                   [0014] 06 01 00   push string "hello world"
                   [0017] 05 01 00   push int 0001
                   [001a] 1b 1d      callrss 1d (printf)
                   [001c] 1c 02      add sp, 02
                   [001e] 04         push int 0
                   [001f] 24         pop reg
                   [0020] 23         ret
                   [0021] 21 14 00   call [0014]
                   [0024] 1d         exit

       Offsets are shown using the hexadecimal number system and are absolute byte offsets in the
       bim-file. The string constants dump also shows, between parentheses, the  offsets  of  the
       individual strings relative to the beginning of the strings section. The disassembled code
       shows the opcodes of the instructions of the compiled icmake source files. If opcodes  use
       arguments  then  these argument values are shown following their opcodes. Each opcode line
       ends by showing the opcode’s mnemonic plus (if applicable) the nature of its argument.

FILES

       The mentioned paths are the ones that are used in the source distribution and are used  by
       the  Debian  Linux  distribution.  However,  they  are  sugestive  only  and may have been
       configured differently:

       o      /usr/bin/icmake: the main icmake program;

       o      /usr/bin/icmbuild: the wrapper program around the icmbuild script handling standard
              program maintenance;

       o      /usr/bin/icmstart: an icmake-script that is can be used to create the startup-files
              of new projects;

       o      /usr/libexec/icmake/icm-comp: the compiler called by icmake;

       o      /usr/libexec/icmake/icm-exec: the byte-code interpreter called by icmake;

       o      /usr/libexec/icmake/icm-dep: the support program handling  class-  and  precompiled
              header dependencies;

       o      /usr/libexec/icmake/icm-pp: the preprocessor called by icmake;

       o      /usr/libexec/icmake/icmun: the icmake unassembler.

EXAMPLES

       The   distribution  (usually  in  /usr/share/doc/icmake)  contains  a  directory  examples
       containing additional examples of icmake script. The icmstart script is an  icmake  script
       as  is /usr/libexec/icmake/icmbuild, which is called by the /usr/bin/icmbuild program. See
       also the EXAMPLE section in the icmscript(7) man-page.

SEE ALSO

       chmod(1), icmbuild(1), icmconf(7), icmscript(7), icmstart(1), icmstart.rc(7), make(1)

BUGS

       Be advised that starting icmake version 10.00.00

       o      the --summary (-F) option has been discontinued;

       o      the --source short option -i has been replaced by -s;

       o      long option --icm-dep has been replaced by --dependencies;

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