tarcel - A Tcl packaging tool

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

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

Usage

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
    Files:
      tarcel-0.3.vfs/app/lib/commands.tcl
      tarcel-0.3.vfs/app/lib/compiler.tcl
      tarcel-0.3.vfs/app/lib/config.tcl
      tarcel-0.3.vfs/app/lib/embeddedchan.tcl
      tarcel-0.3.vfs/app/lib/parameters.tcl
      tarcel-0.3.vfs/app/lib/tar.tcl
      tarcel-0.3.vfs/app/lib/tararchive.tcl
      tarcel-0.3.vfs/app/lib/tvfs.tcl
      tarcel-0.3.vfs/app/lib/xplatform.tcl
      tarcel-0.3.vfs/app/tarcel.tcl
      tarcel-0.3.vfs/modules/configurator-0.1.tm

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:

file (only supports subcommands: dirname, join and tail)
foreach
glob
if
lassign
list
llength
lsort
regexp
regsub
set
string

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:

Downloads

Tarcel.tcl v0.3 packaged as a tarcel

Articles

Contributions

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.

Licence

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

vLife Systems

Quality Through Design