Provided by: icmake_10.04.01-2_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.

       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.
       Both icmstart and icmbuild can be run without explicitly calling icmake.

       This  man-page  covers  icmake  (the  program),  and  its  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.
       Refer  to  the  bv(icmscript)(7)  man-page  for a description of the syntax and facilities
       offered by icmake’s scripting language.

       Icmake does not offer an Integrated Development Environment (IDE). Icmake merely  performs
       tasks  for  which  scripts  can  be written, and only a minimal set of pre-defined scripts
       (icmstart and icmbuild) that have shown 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, 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/lib/icmake (see also section ICMUN in this man-page).

       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) may optionally  inspect  class  dependencies,  (re)compiling
       sources  of  dependent  classes  when  necessary.  By  default, class-dependencies are not
       interpreted, but they are when the PRECOMP and/or  USE_ALL  defines,  found  in  the  file
       icmconf file, are activated. Refer to the icmconf(7) man-page for details.

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

       o      ICM-DEP
              - the icm-dep dependency analyzer;

       o      ICMUN
              - icmake’s unassembler.

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

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.

       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      --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      --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-directory 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 filed, commonly
       having extensions .ih.

       Icmake automatically calls icm-depd when USE_ALL 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.

       When icm-dep is activated (i.e., its argument go is  specified)  then  icm-dep  determines
       directory  dependencies,  touching  all  files  in  directories that depend on directories
       containing modified files, and/or removing precompiled headers  if  they  include  headers
       from  other  directories that were modified. 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 supports 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      --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 parameter 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      --gch
              If icmconf files contain #define PRECOMP specifications then icm-dep checks whether
              precompiled headers must be refreshed.  If an  icmconf  file  does  not  contain  a
              #define  PRECOMP  specifications,  but  precompiled  headers  should nonetheless be
              inspected, then option --gch can be specified;

       o      --no-gch
              If icmconf files contain #define PRECOMP  specifications  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" specifications 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" specifications 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
              `USE_ALL’ specification;

       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.

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/lib/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/lib/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/lib/icmake/icm-comp: the compiler called by icmake;

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

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

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

       o      /usr/lib/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/lib/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).