[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]
NAME
kettle_app - Kettle - Application - Build Interpreter
Table Of Contents
SYNOPSIS
package require Tcl 8.5 9
kettle ?-f buildfile? ?-trace? (goal|--option value)...
DESCRIPTION
Welcome to Kettle, an application and set of packages providing support for the easy building and installation of pure Tcl packages, and Critcl based Tcl packages.
Please read the document Kettle - Introduction to Kettle, if you have not done so already, to get an overview of the whole system.
Here we document the kettle application available to a user of kettle, i.e. a package developer using (or wishing to use) kettle as the build system for their code.
This application resides between the kettle core and the build script written by the package developer, as shown in the architectural diagram below.
For the build (declaration) commands available to build scripts based on kettle see Kettle - Build Declarations.
The kettle application
The kettle application is the main interpreter for build declarations. It can be used directly, or as a shell in the hash-bang line of build files.
Its general syntax is
kettle ?-f buildfile? ?-trace? (goal|--option value)...
In a hash-bang line for a build file the syntax is 'kettle -f', with the build file becoming the argument to -f, and the arguments to the build file then following, starting with the optional -trace.
Note: The application will look for a build file "build.tcl" in the current working, if no build file is specified.
Configuration options and recipes to run can be mixed on the commandline, with the options processed first, and then the recipes. For this to work all the options require a value.
The list of known options, help about them, and their state after option processing can be queried through the standard recipes list-options, help-options, and show-configuraton.
The list of known recipes and help about them can be queried through the standard recipes list-recipes, and help-recipes.
Note that the set of recipes is dynamically constructed based on the scans of source directory made by kettle at the direction of the build file. I.e. the options on the command line are processed first, then the build file is used to scan the sources and initialize the necessary recipes, at last the recipes on the command line are run.
The application understands one dot-file for configuration, "~/.kettle/config". This file is expected to contain user-specific standard options to use. Its contents are processed as part of the option processing, before the options found on the command line. For all other extensibility the user is reminded that build file are Tcl files, with the full power of the language behind them. Which includes the builtin command source.
If no recipe is specified on the command line a standard recipe is run. On unix platforms it is "help", whereas on windows "gui" is used.
Options
--bin-dir path
This configuration option specifies the path to the directory applications (binary and script) will be installed into.
The default value is the directory of the tclsh used to run the kettle application.
If the option --exec-prefix is modified the default value changes to "--exec-prefix/bin".
--color boolean
The value of this configuration option determines if output is colorized or not.
The default value is platform-dependent. On windows the default is off, disabling colorization. On unix the default is on, activating colorization. Except if it could be determined that the script's stdout is not a proper terminal, then the default is off.
For this last check the system attempts to use the package Tclx. If that package is not available then it cannot be determined if stdout is a proper terminal, thus colorization is active.
--config path
This is an internal option used by kettle for the communication between parent and child instances when handling a recursive invokation. The generated file specified as the value of the option holds the configuration of the parent, for the child to read and use.
--dry boolean
The value of this configuration option determines if (un)installation modifies the file system (off) or not (on == dry run).
The default value is off. This means that the system will modify the file system as instructed by recipes.
--exec-prefix path
This configuration option specifies the path to the root directory for all platform-dependent (binary) installation files.
The default value is "--prefix".
--html-dir path
This configuration option specifies the path to the directory package documentation in HTML format will be installed into.
The default value is "--prefix/html".
--ignore-glob list
This option specifies the set of files and directories to ignore during directory scans, as a Tcl list of glob patterns to match.
The default value is
- *~
- _FOSSIL_
- .fslckout
- .fos
- .git
- .svn
- CVS
- .hg
- RCS
- SCCS
- *.bak
- *.bzr
- *.cdv
- *.pc
- _MTN
- _build
- _darcs
- _sgbak
- blib
- autom4te.cache
- cover_db
- ~.dep
- ~.dot
- ~.nib
- ~.plst
matching the special files and directories of various source code control systems, the backup files of various editors, and the like.
--include-dir path
This configuration option specifies the path to the directory package C header files will be installed into.
The default value is "--prefix/include".
--lib-dir path
This configuration option specifies the path to the directory packages (binary and script) will be installed into.
The default value is the [info library] directory of the tclsh used to run the kettle application. In code:
set libdir [info library]An exception is made if the info library result refers to a zip archive instead of disk. In that case the default value is the "lib" directory which is sibling to the "bin" directory containing the tclsh used to run the kettle application. In code:
set libdir [file join [file dirname [file dirname [info nameofexecutable]]] lib]If the option --exec-prefix is modified the default value changes to "--exec-prefix/lib".
--log path
An option for recipe 'test', if defined. Its value is the path "stem" for a series of files testsuite information is saved into. The actual files use the specified stem and add their specifc file extension to it.
The default is the empty string, disabling the saving of testsuite information.
--log-mode compact|full
An option for recipe 'test', if defined. Its value determines the verbosity of test suite information printed to the terminal or log window.
The default is compact.
--man-dir path
This configuration option specifies the path to the directory package documentation (manpages, in *roff format) will be installed into.
The default value is "--prefix/man".
--prefix path
This configuration option specifies the path to the root directory for all platform-independent (non-binary) installation files.
The default value is the twice parent of the [info library] directory of the tclsh used to run the kettle application. In code:
set prefix [file dirname [file dirname [info library]]]An exception is made if the info library result refers to a zip archive instead of disk. In that case the default value is the "lib" directory which is sibling to the "bin" directory containing the tclsh used to run the kettle application. In code:
set prefix [file join [file dirname [file dirname [info nameofexecutable]]] lib]--state path
This is an internal option used by kettle for the communication between parent and child instances when handling a recursive invokation. The generated file specified as the value of the option holds the work state of the parent, for the child to read and extend.
--target string
The value of this option is the target name critcl should use to build C code.
The default value is the empty string, leaving the choice of target to critcl itself.
--verbose boolean
The value of this configuration option determines if tracing of system internals is done (on), or not (off). This is the option equivalent of the special flag -trace.
The default value is off, disabling tracing of internals.
--with-doc-destination path
This configuration option specifies the path to the directory the generated documentation should be placed into for the documentation installa recipes to pick up from.
This should be a relative path, which will interpreted relative to the package source directory.
The default value is "embedded".
A build declaration file can override this default with the kettle doc-destination command.
--with-critcl3 path
This configuration option specifies the path to the tool critcl3 for the compilation and installation of critcl-based C code.
The default value is the path to the first of
- "critcl3",
- "critcl3.kit",
- "critcl3.tcl",
- "critcl3.exe",
- "critcl",
- "critcl.kit",
- "critcl.tcl", and
- "critcl.exe"
found on the PATH. None of these matter however should the system find the package critcl version 3 or higher among the packages known to the tclsh running the kettle application. In that case kettle will run everything in itself, without invoking critcl child processes.
--with-dia path
This configuration option specifies the path to the tool dia for tklib/diagram-based diagram processing.
The default value is the path to the first of "dia", "dia.kit", "dia.tcl", and "dia.exe" found on the PATH.
--with-dtplite path
This configuration option specifies the path to the tool dtplite for doctools-based documentation processing.
The default value is the path to the first of "dtplite", "dtplite.kit", "dtplite.tcl", and "dtplite.exe" found on the PATH.
--with-shell path
Standard Recipes
The following recipes are understood by kettle regardless of build definitions. They are its standard recipes.
gui
Opens a standard graphical interface. This is the standard recipe run on windows if no recipe was specified on the command line.
help-options
Print the help for all known options.
help-recipes
Print the help for all defined recipes.
help
The combination of the previous two recipes. This is the standard recipe run on unix if no recipe was specified on the command line.
list-options
Print a list of all known options.
list-recipes
Print a list of all defined recipes.
list
The combination of the previous two recipes.
null
This recipe does nothing. It is generally only useful for kettle developers, in combination with option -trace.
show-configuration
Print the state of the option database after processing the dot-file and command line settings.
show-state
Print the state of various internal global settings after processing the dot-file and command line settings.
build.tcl Example
A simple example of a build.tcl script is that for kettle itself.
Stripping out the special code taking care of the fact that it cannot assume to have kettle installed already this reduces to the code below, and of that only the last two lines are relevant in terms of build declarations. The first three are the (bourne) shell magic to find and run the kettle application in the PATH environment variable. (The actual code assumes that kettle is found the working directory, again it cannot assume to be installed already).
#!/bin/sh
# -*- tcl -*- \
exec kettle -f "$0" "${1+$@}"
kettle tcl
kettle tclapp kettle
The code asks the system to search for and handle all Tcl script packages to be found in the directory of the "build.tcl" file, and declares that we have a script application named kettle in the same directory. As the documentation files and figures are in the standard locations, kettle tcl is allowed to handle them implicitly.
Done.
License
This package, written by Andreas Kupries, is BSD licensed.
Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Kettle Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.
KEYWORDS
CATEGORY
Build support