kettle_devguide(n) 1 doc "Kettle - The Quick Brew System"
Name
kettle_devguide - Kettle - The Developer's Guide
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.
This document is a guide for developers working on Kettle, i.e. maintainers fixing bugs, extending the functionality of application or package, etc.
Users of kettle wishing to write their own high-level commands linking into the existing foundations should read the Kettle - Core document instead, as that is the reference manpage to the whole functionality available to them, and likely enough to get going.
Please read
first, if that was not done already.
Here we assume that the sources are already available in a directory of your choice, and that you not only know how to build and install them, but also have all the necessary requisites to actually do so. The guide to the sources in particular also explains which source code management system is used, where to find it, how to set it up, etc.
Developing for Kettle
Architecture
The high-level architecture is shown in the image below:
This document is concerned with the lowest level shown, the core kettle package itself. The inner boxes of that architectural box show the parts which are user-visible, i.e. providing the DSL commands explained in Kettle - Build Declarations. For the details we have
In this image we now see all the components found inside of the kettle package, their organization into layers and their dependencies. The latter is actually a bit simplified, showing only the dependencies between adjacent layers and leaving out the dependencies crossing layers. Adding them would make the image quite a bit more crowded.
The green boxes are again the user-visible parts, either for the build declarations. The rest is internal. Note how and that the components found in the blue box are all dependent on each other, i.e. these are in circular dependencies.
The names in the boxes directly refer to the file names containing the code of the component, without the extension, ".tcl". The only file not mentioned is "kettle.tcl" which is the entrypoint to the package and sources all the others.
More information about the functionality made available by each component is found in Kettle - Core, the reference to all commands.
Directory structure
- Helpers
- Documentation
- "doc/"
This directory contains the documentation sources. The texts are written in doctools format, whereas the figures are a mixture of TeX (math formulas), and tklib's dia(gram) package and application.
- "embedded/"
This directory contains the documentation converted to regular manpages (nroff) and HTML. It is called embedded because these files, while derived, are part of the fossil repository, i.e. embedded into it. This enables fossil to access and display these files when serving the repositories' web interface. The "Command Reference" link at http://chiselapp.com/user/andreas_kupries/repository/Kettle/home is, for example, accessing the generated HTML.
- Package Code, General structure
See the second image in section Architecture, and the associated explanations.
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