Debian Tcl/Tk Policy
--------------------
Francesco Paolo Lovergine <frankie@debian.org>
Sergei Golovan <sgolovan@debian.org>
version 0.3.0
-------------------------------------------------------------------------------
Abstract
--------
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 Jessie release cycle,
so pre-Jessie releases can violate this policy in one or more aspects.
Backporters are warned.
Copyright Notice
----------------
Copyright (C) 2007-2013 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
(http://www.gnu.org/copyleft/gpl.html).
You can also obtain it by writing to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-------------------------------------------------------------------------------
Contents
--------
1. Tcl/Tk Packaging
1.1. Versions
1.2. Main packages
1.3. Tcl and Tk Interpreters
1.4. Tcl/Tk libraries
1.5. Tools/files for Development of Tcl/Tk modules and extensions
1.6. Multiarch support
1.7. Auto_load Path
1.8. Documentation
2. Packaged Modules
2.1. Module Names
2.2. Dependencies
3. Tcl/Tk Programs
3.1. Version Independent Programs
3.2. Version Dependent Programs
A. Build Dependencies
B. Tcl/Tk modules loading
C. Possible issues building Tcl/Tk extensions
D. Maintainer's Checklist
-------------------------------------------------------------------------------
1. Tcl/Tk Packaging
-------------------
1.1. Versions
-------------
At any given time, the binary packages `tcl' and `tk' represent the
current default Debian Tcl/Tk version. They contain Tcl and Tk shells
`/usr/bin/tclsh' and `/usr/bin/wish' which are symlinks to the current
default version binaries. For backward compatibility they provide the
virtual packages `tclsh' and `wish' but it isn't recommended to
reference them in packages dependencies anymore. The packages `tcl'
and `tk' are 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 Section 2.2,
`Dependencies'), but it is not mandatory. 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. 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.5 and 8.5.14 are subminor
versions of the same Tcl/Tk version 8.5, but Tcl 8.6 and 8.5 are
indeed different versions. The patchlevel intends the result of the
'info patchlevel' command, i.e. Tcl/Tk 8.5.14 and 8.5.13 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 `tcl<X>.<Y>'
and `tk<X>.<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_.
1.2. Main packages
------------------
For every Tcl/Tk versions provided in the distribution, the packages
`libtcl<X>.<Y>' and `libtk<X>.<Y>' comprise a corresponding Tcl/Tk
libraries, core modules and extensions of the upstream Tcl/Tk
distribution. They provide infrastructure for embedding Tcl into
external programs. Any such packages includes a <Provides:> item of
the virtual package `libtcl' and a <Provides:> item for the `libtk'
virtual package.
Also, the packages `tcl<X>.<Y>' and `tk<X>.<Y>' ship the binaries
`/usr/bin/tclsh<X>.<Y>', `/usr/bin/wish<X>.<Y>'. Starting from Jessie
they don't provide alternatives for files `/usr/bin/tclsh' and
`/usr/bin/wish'. If an application uses one of those, it has to
depend on `tcl' or `tk' package.
Tools and files for the _development_ of Tcl/Tk extensions are split
off in two separate packages `tcl<X>.<Y>-dev' and `tk<X>.<Y>-dev'.
Documentation is provided separately in packages `tcl<X>.<Y>-doc' and
`tk<X>.<Y>-doc'.
1.3. Tcl and Tk Interpreters
----------------------------
1.3.1. Interpreters Names
-------------------------
Tcl/Tk scripts depending on the default Tcl/Tk version (see Section
1.2, `Main packages') or not depending on a specific Tcl/Tk version
must use `tclsh' and/or `wish' (unversioned) as the interpreter name
and must depend on `tcl' and/or `tk' package.
Tcl/Tk scripts that only work with a specific Tcl/Tk version must
explicitly use the versioned interpreter name (`tclsh<X>.<Y>' and/or
`wish<X>.<Y>') and must depend on the specific Tcl/Tk versioned
package (`tcl<X>.<Y>' and/or `tk<X>.<Y>' respectively).
1.3.2. Interpreters Locations
-----------------------------
The path name for the Tcl interpreter is `/usr/bin/tclsh' or
`/usr/bin/tclsh<X>.<Y>'.
The path name for the Tk interpreter is `/usr/bin/wish' or
`/usr/bin/wish<X>.<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 tclsh<X>.<Y>'. The same consideration applies
for Tk and the `wish' interpreter. Starting from Jessie
administrators no longer can override default versions of the
interpreters using `update-alternatives', which provided some
flexibility but caused confusion for program maintainers before.
1.4. Tcl/Tk libraries
---------------------
The Tcl and Tk libraries are provided by `libtcl<X>.<Y>' and
`libtk<X>.<Y>' respectively. These packages install
`/usr/lib/$(DEB_HOST_MULTIARCH)/libtcl<X>.<Y>.so' (soname is
`libtcl<X>.<Y>.so') and
`/usr/lib/$(DEB_HOST_MULTIARCH)/libtk<X>.<Y>.so' (soname is
`libtk<X>.<Y>.so').
1.5. Tools/files for Development of Tcl/Tk modules and extensions
-----------------------------------------------------------------
Some tools and files for development of Tcl/Tk modules and extensions
are packaged as `tcl<X>.<Y>-dev' and `tk<X>.<Y>-dev'. These packages
provide header files as well as static and stub libraries. Header
files are installed in `/usr/include/tcl<X>.<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/tcl<X>.<Y>
/usr/include/tk -> /usr/include/tcl<X>.<Y>
See net section and Appendix C, `Possible issues building Tcl/Tk
extensions' for more information about possible issues with extension
building due to Debian customizations.
1.6. Multiarch support
----------------------
The Tcl and Tk libraries and development packages can be installed for
several architectures simultaneously. They ship architecture
dependent files in `/usr/lib/$(DEB_HOST_MULTIARCH)' directory. See
also section Appendix C, `Possible issues building Tcl/Tk extensions'
for information on how to package multiarchified Tcl/Tk extension.
1.7. Auto_load Path
-------------------
The package search path (<auto_path>) for both Tcl and Tk is a list
searched in the following order:
Site modules and extensions:
/usr/local/lib/tcltk (architecture dependent files)
/usr/local/share/tcltk (architecture independent files)
Packaged modules and extensions:
/usr/lib/tcltk/$(DEB_HOST_MULTIARCH) (architecture dependent files)
/usr/lib/tcltk (architecture dependent files)
/usr/share/tcltk (architecture independent files)
Version specific core modules and extensions:
/usr/share/tcltk/tcl<X>.<Y>
/usr/share/tcltk/tk<X>.<Y> (for Tk only)
Maintainers must ensure that modules and extensions are correctly
installed in subdirs of the paths above consistently. See Appendix B,
`Tcl/Tk modules loading' 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 Appendix C, `Possible issues building
Tcl/Tk extensions').
1.8. Documentation
------------------
Default packages `tcl-doc' and `tk-doc' which depend on default
versioned `tcl<X>.<Y>-doc' and `tk<X>.<Y>-doc' are provided. Since
different `tcl<X>.<Y>-doc' and `tk<X>.<Y>-doc' conflict in files and
cannot be installed simultaneously, `tcl-doc' and `tk-doc' only
recommend `tcl<X>.<Y>-doc' and `tk<X>.<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.
-------------------------------------------------------------------------------
2. Packaged Modules
-------------------
2.1. Module Names
-----------------
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 `tcl<X.Y-foo>' or
`tkX.Y<-foo>' when the module is version dependent.
If the package already uses the name `tcl<foo>' or `tk<foo>', 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.
2.2. Dependencies
-----------------
Packaged modules available for one particular version of Tcl/Tk must
depend on the corresponding `libtcl<X>.<Y>' and/or `libtk<X>.<Y>'
package if they don't contain Tcl/Tk scripts, and on `tcl<X>.<Y>'
and/or `tk<X>.<Y>' package if they do.
The recommended dependencies of version-independent packages are the
following: If the package works in all available Tcl/Tk versions it
should depend on `libtcl' or `libtk' (`tcl' or `tk' if it includes
Tcl/Tk scripts). If the package works for several Tcl/Tk versions
(but not for all) it should depend on all of them alternatively (e.g.
`libtcl8.5' | `libtcl8.4').
-------------------------------------------------------------------------------
3. Tcl/Tk Programs
------------------
3.1. Version Independent Programs
---------------------------------
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'. 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.
3.2. Version Dependent Programs
-------------------------------
Programs which require a specific version of Tcl must start with
`#!/usr/bin/tclsh<X>.<Y>'. They must also specify a strict dependency
on `tcl<X>.<Y>'. Programs which require a specific version of Tk must
start with `#!/usr/bin/wish<X>.<Y>'. They must also specify a strict
dependency on `tk<X>.<Y>'. Again, if you're using `#!/usr/bin/env
tclsh<X>.<Y>', or `#!/usr/bin/env wish<X>.<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.
-------------------------------------------------------------------------------
A. Build Dependencies
---------------------
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
tcl<X>.<Y>-dev
tk<X>.<Y>-dev
For example, `tclreadline' build dependencies are the following:
Build-Depends: debhelper (>= 8.0.0), dpkg-dev (>= 1.16.1~), <tcl-dev>,
libreadline5-dev, autotools-dev
Module packages, script libraries and Tcl-only applications should
depend on the
tcl
tk
tcl<X>.<Y>
tk<X>.<Y>
For example, `tcllib' build dependencies are the following:
Build-Depends: debhelper (>= 8.9.7)
Build-Depends-Indep: <tcl>
Due to limitations of current autobuild daemon it is forbidden to use
build dependencies on the virtual packages `libtcl' or `libtk' 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.
-------------------------------------------------------------------------------
B. Tcl/Tk modules loading
-------------------------
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.
-------------------------------------------------------------------------------
C. Possible issues building Tcl/Tk extensions
---------------------------------------------
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/lib/tcl<X>.<Y>
--with-tk=/usr/lib/tk<X>.<Y>
--with-tclincludes=/usr/include/tcl<X>.<Y>
or other custom hacks.
-------------------------------------------------------------------------------
D. Maintainer's Checklist
-------------------------
1. 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'.
2. 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 Appendix B, `Tcl/Tk modules loading').
3. If your package supports multiarch install its index file into a
subdirectory of `/usr/lib/tcltk/$(DEB_HOST_MULTIARCH)' directory.
Tcl/Tk cannot determine multiarch triplet in runtime, so package
indices for different architectures must differ.
4. 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.
-------------------------------------------------------------------------------
Debian Tcl/Tk Policy
Francesco Paolo Lovergine <frankie@debian.org>
Sergei Golovan <sgolovan@debian.org>
version 0.3.0
Generated by dwww version 1.14 on Wed Jan 22 04:47:26 CET 2025.