vLife Systems

Quality Through Design

  Home   |   Projects > Tarcel   |   Articles   |   Archive   |  

Tarcel A Tcl Packaging Tool

Tarcel allows you to combine a number of files together to create a single tarcel file that can be run by tclsh, wish, or can be sourced into another Tcl script. This makes it easy to distribute your applications as a single file. In addition it allows you to easily create Tcl modules made up of several files including shared libraries, and then take advantage of the extra benefits that Tcl modules provide such as faster loading time.

Definition of Terms

A file that has been packaged with the tarcel script. This is pronounced to rhyme with parcel.
The file that describes how to create the tarcel file. Pronounced 'dot tarcel'.
The packaging tool script.


Tarcel is quite easy to use and implements just enough functionality to work for the tasks it has been put to so far.

Creating a tarcel

To create a tarcel file you begin by creating a .tarcel file to describe how to package the tarcel file. See below for what to put in this file. You then use the wrap command of tarcel.tcl to create the package. To create a tarcel called t.tcl out of tarcel.tcl and its associated files using tarcel.tarcel run:
  $ tclsh tarcel.tcl wrap -o t.tcl tarcel.tarcel
The .tarcel file may specifiy the output filename, in which case you don't need to supply -o outputFilename.

Getting Information About a Package

To find out some information about a package use the info command of tarcel.tcl. For the example above, to look at t.tcl run:
  $ tclsh tarcel.tcl info t.tcl
This will output something like the following:
  Information for tarcel: t.tcl
  Created with tarcel.tcl version: 0.3

    Homepage: https://github.com/LawrenceWoodman/tarcel
    Version: 0.3

Defining a .tarcel File

To begin with it is worth looking at the tarcel.tarcel file supplied in the repo. This .tarcel file is used to wrap tarcel.tcl. A .tarcel file is a Tcl script which has the following Tcl commands available to it: In addition it has the following commands to control packaging:
config set varName value
Sets variables such as version, hashbang, homepage, outputFilename and init. The latter is used to set the initialization code for the package to load the rest of the code.
error msg
Quit processing a .tarcel with an error message.
fetch importPoint files
Gets the specified files and places them all at the directory specified by importPoint in the package. The relative directory structure of the files will not be preserved.
import importPoint files
Gets the specified files and places them at the directory specified by importPoint in the package relative to their original directory structure.
find module moduleName [requirement] ...
Find the location of a Tcl module. You can also specify the version requirements for the module.
get packageLoadCommands packageName [requirement] ...
Returns the commands to load the package from package ifneeded. The result is returned as a two element list, the first element contains the load commands and the second element contains the version found.
tarcel destination .tarcelFile [arg] ...
Use the .tarcelFile file to package some other code and include the resulting tarcel file at destination in the calling tarcel file. If you pass any further arguments, then the Tcl variable args will be set with these.

Find out More

To find out more have a look at the following articles:


Tarcel.tcl v0.3 packaged as a tarcel


If you want to improve this program make a pull request to the repo on github. Please put any pull requests in a separate branch to ease integration and add a test to prove that it works. If you find a bug, please report it at the Tarcel project's issues tracker also on github.


Copyright (C) 2015, Lawrence Woodman lwoodman@vlifesystems.com
This software is licensed under an MIT Licence. Please see the file, LICENCE.md, for details.