Man page - critcl_application(1)

Packages contains this manual

Package: critcl
apt-get install critcl

Manuals in package:

critcl_application(1)

Documentations in package:

critcl

Manual

critcl

NAME
SYNOPSIS
DESCRIPTION
APPLICATION OPTIONS
PACKAGE STRUCTURE
AUTHORS
BUGS, IDEAS, FEEDBACK
KEYWORDS
CATEGORY
COPYRIGHT

______________________________________________________________________________

NAME

critcl - CriTcl Application Reference

SYNOPSIS

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

DESCRIPTION

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 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 Introduction To CriTcl .

This application resides in the Application Layer of CriTcl.

+----------------+
|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 Application Options below. For a larger set of examples please see section "Building CriTcl Packages" in the document about Using CriTcl .

APPLICATION OPTIONS

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 CriTcl script 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 CriTcl script 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 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

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

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

PACKAGE STRUCTURE

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:

AUTHORS

Jean Claude Wippler, Steve Landers, Andreas Kupries

BUGS, IDEAS, FEEDBACK

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.

KEYWORDS

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