critcl_application_package(3tcl) C Runtime In Tcl (CriTcl) critcl_application_package(3tcl) 







critcl_application_package - CriTcl Application Package
  Reference








package require Tcl 8.6


package require critcl::app ?3.3.1?


package require critcl ?3.3.1?


package require platform ?1.0.2?


package require cmdline 


::critcl::app::main commandline












Be welcome to the C Runtime In Tcl (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::app
    package. Its intended audience are developers working on critcl's internals.
    These commands are not needed to simply write a CriTcl script. If you
    are in need of an overview of the whole system instead, please go and read
    the Introduction To CriTcl.


This package resides in the Application Layer of CriTcl.




*================*
|Applications    |
| critcl         |
| critcl::app    |
*================*
+----------------+
|Core Packages   |
| critcl         |
| critcl::util   |
+----------------+
+----------------+
|Support Packages|
| stubs::*       |
| md5, platform  |
|  ...           |
+----------------+



, implementing the functionality of the CriTcl Application,
    and through this, the mode generate package. The actual application
    is (only) a shim wrapping around this package. It itself is build on top of
    the core package critcl.








The package exports a single command



  
::critcl::app::main commandline

  
The commandline is a list of zero or more options followed by zero
      or more CriTcl script files. By default, the CriTcl script
      files are build and the results cached. This cuts down on the time needed
      to load the package. The last occurrence of -pkg and -tea,
      if provided, selects the corresponding alternative mode of operations. For
      a larger set of examples please see section "Building CriTcl
      Packages" in the document about Using CriTcl.




The options are:








The following options are understood:



  

  

  

  
Print the version to stdout and exit.

  

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



  

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




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



  

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



  

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



  

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



  

  
Activates one of the following debugging modes:







  

  
Track and report memory allocations made by the Tcl core.

  

  
Compile all ".c" files with debugging symbols.

  

  
Both memory and symbols.






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



  

  
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 CriTcl
    script actually defines and uses a custom build configuration option
    with that name.


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



  

  
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 CriTcl
    script actually defines and uses a custom build configuration option
    with that name.


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



  

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



  

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

  

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



  

  
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.

  

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



  

  
Generates a package from the CriTcl script 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 CriTcl script file is
        kept as part of the input. A single file without a suffix is assumed to
        be a CriTcl script. 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






  

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

  

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

  

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



  

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

  

  
Like -pkg, except no binaries are generated. Creates a directory
      hierarchy containing the CriTcl script, 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 CriTcl script file is
        kept as part of the input. A single file without a suffix is assumed to
        be a CriTcl script. 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






  

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








CriTcl can be used in three different modes of operation,
  called



  
[1]

  
Compile & Run, and

  
[2]

  
Generate Package

  
[3]

  
Generate TEA Package




Compile & Run was the original mode and is the default
    for critcl_pkg. Collects the C fragments from the CriTcl
    script, builds them as needed, and caches the results to improve load
    times later.


The second mode, Generate Package, was introduced to enable
    the creation of (prebuilt) deliverable packages which do not depend on the
    existence of a build system, i.e. C compiler, on the target machine. This
    was originally done through the experimental Critbind tool, and is
    now handled by the CriTcl Application, also named critcl.


Newly introduced with CriTcl version 3 is Generate TEA
    Package. This mode constructs a directory hierarchy from the package
    which can later be built like a regular TEA package, i.e. using




	.../configure --prefix ...
	make all isntall











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>











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.








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








Glueing/Embedded C code








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








  

    3.3.1
    doc