kettle_app(n) 1 doc "Kettle - The Quick Brew System"
Name
kettle_app - Kettle - Application - Build Interpreter
Synopsis
- package require Tcl 8.5
Description
Welcome to Kettle, an application and set of packages providing support for the easy building and installation of pure 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.
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.
Category
Build support