[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
This document describes the packaging of Tcl/Tk within the Debian distribution and the policy requirements for Tcl/Tk extensions and packages. This policy has been defined during Lenny release cycle, so pre-Lenny releases can violate this policy in one or more aspects. Backporters are warned.
Copyright © 2007 Software in the Public Interest
This manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as
/usr/share/common-licenses/GPL in the Debian GNU/Linux
distribution or on the World Wide Web at The GNU Public Licence.
You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
At any given time, the virtual packages tclsh and
wish are provided by all source package versions of Tcl and Tk.
So pseudo-default Tcl and Tk exist, but they are generally a choice of the
administrator by means of update-alternatives use. Starting from
Lenny release, proper default packages are also provided by the Debian
tcltk-defaults source package, in order to manage modules and
extensions packaging and upgrading better. Modules should preferably use those
packages when appropriate (i.e. they are either version independent or
properly versioned to inhibit the use of a non compatible versions, see Dependencies, Section 2.2), but it is not mandatory.
This is consistent with the use of alternatives. The default packages are
tcl
tk
tcl-dev
tk-dev
tcl-doc
tk-doc
The default Debian Tcl/Tk version should always be the latest stable upstream release that can be integrated in the distribution. Starting from 8.0, Tcl and Tk share the same version numbering. The default packages depend on the appropriate versioned packages and provide useful additional symlinks and alternatives. Default packages versions follow upstream versions, so that packages can use appropriate versioning constraints on them when it is needed.
Apart from the default version, legacy versions of Tcl/Tk may be included as well in the distribution, as long as they are needed by other packages, or as long as it seems reasonable to provide them. (Note: For the scope of this document, Tcl/Tk versions mean the result of 'info tclversion' command, i.e. Tcl/Tk 8.4 and 8.4.16 are subminor versions of the same Tcl/Tk version 8.4, but Tcl 8.5 and 8.3 are indeed different versions. The patchlevel intends the result of the 'info patchlevel' command, i.e. Tcl/Tk 8.4.16 and 8.4.15 have the same version but different patchlevels).
In addition, unstable/development version of Tcl/Tk may be included in the unstable/experimental distribution.
For any version, the main Tcl and Tk packages are called
tclX.Y and
tkX.Y respectively. They are always
packaged as separate sources, as for upstream. Names of related packages or
extensions must follow the same convention if the inclusion of multiple
versions make sense or if they work only with specific versions of Tcl or Tk.
To avoid definition clashes with Debian terminology, we will call modules any Tcl/Tk packages which consist uniquely of Tcl/Tk sources, and extension any program which extends consistently Tcl/Tk using TEA and shared libraries. Note that this is not completely consistent with Tcl terminology, which started from version 8.5 also introduces .tm modules and traditionally deals with packages and script libraries.
For every Tcl/Tk versions provided in the distribution, the packages
tclX.Y and
tkX.Y comprise a complete distribution for
deployment of Tcl/Tk scripts and applications. The packages include
the binaries /usr/bin/tclshX.Y,
/usr/bin/wishX.Y and core modules and
extensions of the upstream Tcl/Tk distribution. Any Tcl package includes a
Provides: item of the virtual package tclsh and any Tk
package includes a Provides: item for the wish virtual
package. They also provide alternatives for files /usr/bin/tclsh
and /usr/bin/wish.
Tools and files for the development of Tcl/Tk packages are split off
in two separate packages tclX.Y-dev and
tkX.Y-dev. Documentation is provided
separately in packages tclX.Y-doc and
tkX.Y-doc.
Tcl/Tk scripts depending on the default Tcl/Tk version (see Main packages, Section 1.2) or not depending on a specific
Tcl/Tk version should use tclsh and/or
wish(unversioned) as the interpreter name.
Tcl/Tk scripts that only work with a specific Tcl/Tk version must explicitely
use the versioned interpreter name (tclshX.Y
and/or wishX.Y) and must depend on the
specific Tcl/Tk versioned package.
The path name for the Tcl interpreter is /usr/bin/tclsh or
/usr/bin/tclshX.Y.
The path name for the Tk interpreter is /usr/bin/wish or
/usr/bin/wishX.Y.
If a maintainer would like to provide the user a possibility to override the
Debian Tcl interpreter, he may want to use /usr/bin/env tclsh or
/usr/bin/env tclshX.Y. The same
consideration applies for Tk and the wish interpreter.
Administrators could also override default versions of the interpreters using
update-alternatives, so maintainers must always consider that the
default Tcl/Tk interpreters could be altered by administrators, so packages
should always require a compatible version to avoid issues, when appropriate.
The Tcl and Tk libraries are provided by
tclX.Y and
tkX.Y respectively. These packages install
/usr/lib/libtclX.Y.so.Z (soname
is libtclX.Y.so.Z) and
/usr/lib/libtkX.Y.so.Z (soname is
libtkX.Y.so.Z).
Some tools and files for development of Tcl/Tk modules and extensions are
packaged as tclX.Y-dev and
tkX.Y-dev. These packages provide header
files as well as static and stub libraries. Header files are installed in
/usr/include/tclX.Y directory (for both Tcl
and Tk). Default packages tcl-dev and tk-dev provide
symlinks to the right versioned header files directory
/usr/include/tcl -> /usr/include/tclX.Y
/usr/include/tk -> /usr/include/tclX.Y
See net section and Possible issues building Tcl/Tk extensions, Appendix C for more information about possible issues with extension building due to Debian customizations.
The package search path (auto_path) for both Tcl and Tk is a list searched in the following order:
/usr/local/lib/tcltk (architecture dependent files)
/usr/local/share/tcltk (architecture independent files)
/usr/lib/tcltk (architecture dependent files)
/usr/share/tcltk (architecture independent files)
/usr/share/tcltk/tclX.Y
/usr/share/tcltk/tkX.Y (for Tk only)
Maintainers must ensure that modules and extensions are correctly installed in
subdirs of the paths above consistently. See Tcl/Tk modules loading, Appendix B for more
information about Tcl/Tk specific ways of dealing with modules and extensions
loading. Developers must consider that these defaults impact TEA-based modules
and use preferably system-wide tcl.m4 (it isn't TEA-compatible
though) instead of private one (see Possible
issues building Tcl/Tk extensions, Appendix C).
Default packages tcl-doc and tk-doc which depend on
default versioned tclX.Y-doc and
tkX.Y-doc are provided. Since different
tclX.Y-doc and
tkX.Y-doc conflict in files and cannot be
installed simultaneously, tcl-doc and tk-doc only
recommend tclX.Y-doc and
tkX.Y-doc to allow administrators to install
any desirable package with Tcl/Tk manual pages. The package
tcl-doc also includes a copy of the up-to-date version of this
policy.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
Packages should be named by the primary module provided. The naming convention
for a module foo is tcl-foo or
tk-foo when the module is version independent.
The naming convention for a module foo is
tclX.Y-foo or tkX.Y-foo when
the module is version dependent.
If the package already uses the name tclfoo or
tkfoo, that is, naming without Tcl/Tk versioning even
if version-dependent and/or without hyphen, may use the name for now. However,
the package naming proposed above is recommended for consistency.
Packaged modules available for one particular version of Tcl/Tk must depend on
the corresponding tclX.Y and/or
tkX.Y package.
The recommended dependencies of version-independent packages are the following:
If the package works in all available Tcl/Tk versions it should depend on
tcl (>= X.Y) | tclsh or
tk (>= X.Y) | wish (version
in parentheses is optional). If the package works with current and future
Tcl/Tk versions it should depend on the default packages tcl or
tk. It is not recommended to use dependency on virtual packages
tclsh and wish because it would make transition to a
newer default Tcl/Tk version less convenient, and because they cannot be used
to express any versioning constraints (strict or relaxed). In one cases they
still could be useful: an administrator could be interested in not installing
the default Tcl/Tk versions and use a local package or some older version
instead. The administrator can do that at his/her own risk, due to the missing
version control, and in the hypothesis that modules and extensions are able to
manage nicely unexpected versions.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
Programs that can run with any version of Tcl/Tk should be started with
#!/usr/bin/tclsh or #!/usr/bin/wish. They must also
specify a dependency on default packages tcl and/or
tk with possible alternatives tclsh and/or
wish virtual packages. You're free to use #!/usr/bin/env
tclsh and #!/usr/bin/env wish, if you'd like to give the
user a chance to override the Debian Tcl/Tk package with a local version.
Programs which require a specific version of Tcl must start with
#!/usr/bin/tclshX.Y. They must also specify
a strict dependency on tclX.Y. Programs
which require a specific version of Tk must start with
#!/usr/bin/wishX.Y. They must also specify
a strict dependency on tkX.Y. Again, if
you're using #!/usr/bin/env tclshX.Y, or
#!/usr/bin/env wishX.Y please be aware that
a user might override the Debian Tcl/Tk packages with a local version and that
release default packages can change also.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
Build dependencies for Tcl/Tk dependent packages must be declared for every Tcl/Tk version, that the package is built for. In order to build for a specific version, add the versioned Tcl/Tk packages dependencies; it is generally better and recommended depending on the appropriate default packages with an eventual strict or relaxed versioning.
Extension packages and applications which link to Tcl/Tk libraries should depend appropriately on one or more of the following packages (with or without additional package version relationships):
tcl-dev
tk-dev
tclX.Y-dev
tkX.Y-dev
For example, tclreadline build dependencies are the following:
Build-Depends: debhelper (>= 5.0.0), tcl-dev,
libreadline5-dev, autotools-dev, quilt
Module packages, script libraries and Tcl-only applications should depend on the
tcl
tk
tclX.Y
tkX.Y
For example, tcllib build dependencies are the following:
Build-Depends: debhelper (>= 5.0.0), quilt
Build-Depends-Indep: tcl
Due to limitations of current autobuild daemon it is forbidden to use build
dependencies on the virtual packages tclsh or wish
only. These dependencies cannot guarantee consistent build environment, so it
is mandatory to prepend a preferred Tcl/Tk version before each of the virtual
packages.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
Tcl/Tk supports a few alternative ways for modules loading. Modules can be implemented as shared libraries, Tcl/Tk scripts or a combination of them. Generally, specific index scripts are used for that and they need to be placed in a directory included in the auto_path list along with scripts and libraries. Old non-package script libraries require a tclIndex generated with the auto_mkindex Tcl instruction. Packages require a pkgIndex.tcl file generated with the pkg_mkIndex Tcl instruction. Tcl 8.5 introduced Tcl Modules scripts (.tm) which do not require an index script for single file implementations. Another peculiar way of modules providing is based on Starkit and the use of the Tcl Virtual File System (TclVFS). In each of those cases, the maintainer must ensure that the all required files are included and installed in the right place to allow using of the module.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
In order to support this policy, a number of changes have been applied in
upstream init.tcl, tclConfig.sh,
tkConfig.sh and tcl.m4 files. Extensions using TEA
with local copies of tcl.m4, or which use custom guesses about
Tcl/Tk configuration could require explicit use of
--with-tcl=/usr/share/tcltk/tclX.Y
--with-tk=/usr/share/tcltk/tkX.Y
or other custom hacks.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
Tcl/Tk has in general a very backward compatible API both at C and commands set
levels. When packaging a module or extension, verify if it requires a specific
minimal version and if it includes run-time checks about that, possibly (which
is always convenient). Scripts can include a package require ?-exact?
Tcl X.Y or package require ?-exact? Tk X.Y, for instance.
In those cases, use a versioned dependency on one of the default packages
(tcl, tk, tcl-dev or
tk-dev), e.g. tcl (>= X.Y).
That is recommend instead of versioned packages dependencies, which are anyway
supported for compatibility with past conventions. Note also that
tk depends on tcl and tk-dev depends on
tcl-dev.
Always install your package stuff in a per-package sub-directory of
/usr/share/tcltk (for scripted modules) and/or
/usr/lib/tcltk (for shared library extensions) along with the
needed index file (see Tcl/Tk modules loading,
Appendix B).
This policy customizes auto_path differently with respect to generic
upstream UNIX platforms, so that you should use preferably system provided
tcl.m4. Occasionally that could either require custom hacks for
non TEA-based building systems, or using --with-tcl or
--with-tk argument for TEA scripts.
Current policy still allows administrators to change default tclsh
and wish interpreters to different versions. Your packaged
modules and extensions should always be able to cope with that, and eventually
to complain and terminate nicely.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ A ] [ B ] [ C ] [ D ] [ next ]
Debian Tcl/Tk Policy
version 0.2.0mailto:frankie@debian.orgmailto:sgolovan@debian.org