[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

kettle_app(n) 1 doc "Kettle - The Quick Brew System"

Name

kettle_app - Kettle - Application - Build Interpreter

Table Of Contents

Synopsis

  • package require Tcl 8.5
  • kettle ?-f buildfile? ?-trace? (goal|--option value)...

Description

Welcome to Kettle, a set of packages providing support for writing build code for 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 archtectural diagram below.

arch_app

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

  1. *~

  2. _FOSSIL_

  3. .fslckout

  4. .fos

  5. .git

  6. .svn

  7. CVS

  8. .hg

  9. RCS

  10. SCCS

  11. *.bak

  12. *.bzr

  13. *.cdv

  14. *.pc

  15. _MTN

  16. _build

  17. _darcs

  18. _sgbak

  19. blib

  20. autom4te.cache

  21. cover_db

  22. ~.dep

  23. ~.dot

  24. ~.nib

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

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.

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

  1. "critcl3",

  2. "critcl3.kit",

  3. "critcl3.tcl",

  4. "critcl3.exe",

  5. "critcl",

  6. "critcl.kit",

  7. "critcl.tcl", and

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

build tea

Category

Build support