critcl - CriTcl Application Reference

       The following options are understood:

       -v--version
              Print the version to stdout and exit.

       -I path
              Arranges for the compiler to search path for headers.  Uses of this option are cumulative.

       Ignored when generating a TEA package (see option -tea below).

       -L path
              Arranges for the linker to search path.  Uses of this option are cumulative.

       Ignored when generating a TEA package (see option -tea below).

       -cache path
              Sets  path  as the directory to use as the result cache. The default is "~/.critcl/<platform>", or
              "~/.critcl/<pid>.<epoch>" when generating a package.  See option -pkg, below.

       Ignored when generating a TEA package (see option -tea below).

       -clean Arranges for all files and directories in the  result  cache  to  be  deleted  before  compilation
              begins.

              Ignored  when  generating  a  package  because this mode starts out with a unique and empty result
              cache.  See option -pkg, below.

       Ignored when generating a TEA package (see option -tea below).

       -config path
              Provides a custom configuration file.  By default a configuration included in the system  core  is
              used.  When specified multiple times the last value is used.

       Ignored when generating a TEA package (see option -tea below).

       -debug mode
              Activates one of the following debugging modes:

              memory Track and report memory allocations made by the Tcl core.

              symbols
                     Compile all ".c" files with debugging symbols.

              all    Both memory and symbols.

       Ignored when generating a TEA package (see option -tea below).  Uses of this option are cumulative.

       -disable name
              Sets the value of the custom build configuration option name to false. It is equivalent to "-with-
              name 0".

       Validated  only  if one of the input files for the CriTclscript actually defines and uses a custom build
       configuration option with that name.

       Ignored when generating a TEA package (see option -tea below).

       -enable name
              Sets the value of the custom build configuration option name to true. It is equivalent to  "-with-
              name 1".

       Validated  only  if one of the input files for the CriTclscript actually defines and uses a custom build
       configuration option with that name.

       Ignored when generating a TEA package (see option -tea below).

       -force Forces compilation even if a shared library for the file  already  exists.   Unlike  cleaning  the
              cache, this is lazy in the destruction of files and only affects relevant files.

              Ignored  when  generating  a  package (see option -pkg, below), which starts out with a unique and
              empty result cache.

       Ignored when generating a TEA package (see option -tea below).

       -help  Prints a short description of command line syntax and options and then exits the application.

       -keep  Causes the system to cache compiled ".c" files.  Also prevents the deletion of the  unique  result
              cache used by the run when generating a package (see option -pkg below), Intended for debugging of
              critcl itself, where it may be necessary to inspect the generated C code.

       Ignored when generating a TEA package (see option -tea below).

       -libdir directory
              Adds  directory  to  the list of directories the linker searches for libraries in (like -L).  With
              -pkg, generated packages are saved in directory.  When specified multiple times the last value  is
              used.  The default is "lib", resolved relative to the current working directory.

       -includedir directory
              Adds  directory  to  the  list  of  directories  the  compiler searches for headers in. With -pkg,
              generated header files are saved in directory.  Uses of this  option  are  cumulative.   The  last
              value  is  used  as  the  destination  for  generated  header  files.  The default is the relative
              directory "include", resolved relative to the current working directory.

       Ignored when generating a TEA package (see option -tea below).

       -pkg   Generates a package from the CriTclscript files.  Input files are processed first as  usual,  but
              are then bundled into a single library, with additional generated files to form the library into a
              standard Tcl package.

              generation. If both options, i.e. -pkg and -tea are specified the last one specified wins.

              Options -clean and -force are ignored. -libdir is relevant in both this and -tea mode.

              The  basename  of  the  first  file  is the name of the package to generate. If its file extension
              indicates a shared library (".so", ".sl", ".dylib", and ".dll") it is also removed from the set of
              input files. Each CriTclscript file is kept as part of the input. A single file without a  suffix
              is  assumed  to  be  a  CriTclscript. A file without a suffix, but other input files following is
              treated like the name of a shared library proper, and removed from the set of input files.

              Examples:

                ... -pkg ... foo

                => Package name is: foo
                => Input file is:   foo.tcl

                ... -pkg ... foo bar.tcl

                => Package name is: foo
                => Input file is:   bar.tcl

                ... -pkg ... foo.tcl

                => Package name is: foo
                => Input file is:   foo.tcl

                ... -pkg ... foo.so bar.tcl

                => Package name is: foo
                => Input file is:   bar.tcl

       -show  Prints the configuration of the chosen target to stdout and then exits.  Set -target, below.

       -showall
              Prints the whole chosen configuration file to stdout and then exits.  See -config, above.

       -target name
              Overrides the default choice of build target.  Only the last occurrence of this  option  is  used.
              The  named  target must exist in the chosen configuration file.  Use -targets (see below) to get a
              list of the acceptable targets.  Use -config to select the configuration file.

       Ignored when generating a TEA package (see option -tea below).

       -targets
              Prints the list of all known targets from the chosen configuration file to stdout and then  exits.
              Use -config to select the configuration file.

       -tea   Like  -pkg,  except no binaries are generated. Creates a directory hierarchy containing the CriTclscript, its companion files, and a TEA-conformant build system with most  of  the  needed  support
              code, including copies of the critcl packages.

              If both -pkg and -tea are specified the last occurrence wins.

              -I,  -L,  -clean,  -force,  -cache,  -includedir, -enable, -disable, and -with-FOO are ignored. In
              contrast, the option -libdir is relevant in both this and -pkg mode.

              The basename of the first file is the name of the package  to  generate.  If  its  file  extension
              indicates a shared library (".so", ".sl", ".dylib", and ".dll") it is also removed from the set of
              input  files. Each CriTclscript file is kept as part of the input. A single file without a suffix
              is assumed to be a CriTclscript. A file without a suffix, but  other  input  files  following  is
              treated like the name of a shared library proper, and removed from the set of input files.

              Examples:

                ... -tea ... foo

                => Package name is: foo
                => Input file is:   foo.tcl

                ... -tea ... foo bar.tcl

                => Package name is: foo
                => Input file is:   bar.tcl

                ... -tea ... foo.tcl

                => Package name is: foo
                => Input file is:   foo.tcl

                ... -tea ... foo.so bar.tcl

                => Package name is: foo
                => Input file is:   bar.tcl

       -with-name value
              This option sets the value of the custom build configuration option name to value.

              The  information is validated only if one of the ".critcl" input files actually defines and uses a
              custom build configuration option with that name.

       Ignored when generating a TEA package (see option -tea below).

       Jean Claude Wippler, Steve Landers, Andreas Kupries

       This document, and the package it describes, will undoubtedly contain bugs and  other  problems.   Please
       report them at https://github.com/andreas-kupries/critcl/issues.  Ideas for enhancements you may have for
       either  package,  application,  and/or  the documentation are also very welcome and should be reported at
       https://github.com/andreas-kupries/critcl/issues as well.

       Glueing/Embedded C code

       Copyright (c) Jean-Claude Wippler
       Copyright (c) Steve Landers
       Copyright (c) 2011-2024 Andreas Kupries

doc                                                   3.3.1                                            critcl(1)

       Be  welcome  to the CRuntimeInTcl (short: CriTcl), a system for embedding and using C code from within
       Tcl [http://core.tcl-lang.org/tcl] scripts.

       This document is the reference manpage for the critcl command.  Its intended audience are  people  having
       to  build  packages using critcl for deployment. Writers of packages with embedded C code can ignore this
       document.  If you are in need of an overview of  the  whole  system  instead,  please  go  and  read  the
       IntroductionToCriTcl.

       This application resides in the Application Layer of CriTcl.

       *================*
       |Applications    |
       | critcl         |
       | critcl::app    |
       *================*

       +----------------+
       |Core Packages   |
       | critcl         |
       | critcl::util   |
       +----------------+

       +----------------+
       |Support Packages|
       | stubs::*       |
       | md5, platform  |
       |  ...           |
       +----------------+

       .  The application supports the following general command line:

       critcl ?option...? ?file...?
              The  exact  set  of  options  supported,  their  meaning,  and  interaction is detailed in section
              ApplicationOptions below.  For a larger set of  examples  please  see  section  "Building  CriTcl
              Packages" in the document about UsingCriTcl.

       C code, Embedded C Code, calling C code from Tcl, code generator, compile & run, compiler,  dynamic  code
       generation, dynamic compilation, generate package, linker, on demand compilation, on-the-fly compilation

       critcl - CriTcl Application Reference

       Packages generated by critcl have the following basic structure:

              <TOP>
              +- pkgIndex.tcl
              +- critcl-rt.tcl
              +- license.terms (optional)
              |
              +- tcl (optional)
              |  +- <tsources files>
              |
              +- <platform>
                 +- <shared library>

       Notes

       [1]    The file "pkgIndex.tcl" is the standard package index file expected by Tcl's  package  management.
              It  is  sourced  during a search for packages, and declares the package to Tcl with its files, and
              how to handle them.

       [2]    The file "critcl-rt.tcl" is a helper file containing the common code  used  by  "pkgIndex.tcl"  to
              perform its tasks.

       [3]    The  file  "license.terms"  is  optional  and  appears  only  if the ".critcl" file the package is
              generated from used the command critcl::license to declare package author and license.

       [4]    All files declared with the command critcl::tsources are put into the sub-directory "tcl".

       [5]    The shared library generated by critcl is put into a platform-specific sub-directory.

       The whole structure, and especially the last point, enable us to later merge the results  (for  the  same
       package,  and  version) for multiple target platforms into a single directory structure without conflict,
       by simply copying the top directories over each other. The only files which can conflict are in the <TOP>
       and "tcl" directories, and for these we know that they are identical across targets. The result of such a
       merge would look like:

              <TOP>
              +- pkgIndex.tcl
              +- critcl-rt.tcl
              +- license.terms (optional)
              |
              +- tcl (optional)
              |  +- <tsources files>
              |
              +- <platform1>
              |  +- <shared library1>
              +- <platform2>
              |  +- <shared library2>
              ...
              +- <platformN>
                 +- <shared libraryN>

critcl ?option...? ?file...?

________________________________________________________________________________________________________________