[Pkg-tcltk-commits] r279 - in tcltk-defaults/trunk: . debian
frankie at alioth.debian.org
frankie at alioth.debian.org
Thu Oct 18 13:22:46 UTC 2007
Author: frankie
Date: 2007-10-18 13:22:46 +0000 (Thu, 18 Oct 2007)
New Revision: 279
Added:
tcltk-defaults/trunk/tcltk-policy.sgml
Modified:
tcltk-defaults/trunk/debian/control
tcltk-defaults/trunk/debian/rules
Log:
Added policy document generation.
Modified: tcltk-defaults/trunk/debian/control
===================================================================
--- tcltk-defaults/trunk/debian/control 2007-10-18 11:57:39 UTC (rev 278)
+++ tcltk-defaults/trunk/debian/control 2007-10-18 13:22:46 UTC (rev 279)
@@ -3,7 +3,7 @@
Priority: optional
Maintainer: Tcl/Tk Debian Packagers <pkg-tcltk-devel at lists.alioth.debian.org>
Uploaders: Francesco Paolo Lovergine <frankie at debian.org>, Sergei Golovan <sgolovan at debian.org>
-Build-Depends: debhelper (>= 5.0.0)
+Build-Depends: debhelper (>= 5.0.0), debiandoc-sgml, subversion
Standards-Version: 3.7.2
Package: tcl
Modified: tcltk-defaults/trunk/debian/rules
===================================================================
--- tcltk-defaults/trunk/debian/rules 2007-10-18 11:57:39 UTC (rev 278)
+++ tcltk-defaults/trunk/debian/rules 2007-10-18 13:22:46 UTC (rev 279)
@@ -9,7 +9,29 @@
TCLVER := 8.4.16-2
TKVER := 8.4.16-2
PRIO := 841
+DOCS = tcltk-policy.html tcltk-policy.txt tcltk-policy.pdf
+#
+# A new policy should be get manually and only after freezing
+#
+get-policy:
+ svn export svn://svn.debian.org/svn/pkg-tcltk/policy/tcltk-policy.sgml
+
+tcltk-policy.html: tcltk-policy.sgml
+ LANG=C debiandoc2html -1 -x tcltk-policy.sgml
+ mv tcltk-policy.html/index.html index.html
+ rm -rf tcltk-policy.html
+ mv index.html tcltk-policy.html
+
+tcltk-policy.txt: tcltk-policy.sgml
+ LANG=C debiandoc2text tcltk-policy.sgml
+
+tcltk-policy.pdf: tcltk-policy.sgml
+ LANG=C debiandoc2pdf tcltk-policy.sgml
+ rm -f tcltk-policy.tpt
+
+build-policy: $(DOCS)
+
debian/control: debian/control.in
sed -e "s/@VER@/$(VER)/g" \
-e "s/@TCLVER@/$(TCLVER)/g" \
@@ -24,11 +46,12 @@
rm -f debian/*.links
rm -f debian/*.postinst
rm -f debian/*.prerm
+ rm -f $(DOCS)
dh_clean
build: build-stamp
-build-stamp: debian/control
+build-stamp: debian/control build-policy
touch build-stamp
install: install-stamp
@@ -69,4 +92,4 @@
binary: binary-indep binary-arch
-.PHONY: configure build clean binary-indep binary-arch binary install
+.PHONY: configure build clean binary-indep binary-arch binary install get-policy build-policy
Added: tcltk-defaults/trunk/tcltk-policy.sgml
===================================================================
--- tcltk-defaults/trunk/tcltk-policy.sgml (rev 0)
+++ tcltk-defaults/trunk/tcltk-policy.sgml 2007-10-18 13:22:46 UTC (rev 279)
@@ -0,0 +1,446 @@
+<!doctype debiandoc system>
+<debiandoc>
+ <book>
+ <titlepag>
+ <title>Debian Tcl/Tk Policy</title>
+ <author>
+ <name>Fracesco Paolo Lovergine</name>
+ </author>
+ <author>
+ <name>Sergei Golovan</name>
+ </author>
+ <version>version 0.0.0</version>
+
+ <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 Lenny release
+ cycle, so pre-Lenny releases can violate this policy in one or
+ more aspects. Backporters are warned.
+
+ THIS IS A DRAFT DOCUMENT, NOT AN OFFICIAL POLICY.
+ </abstract>
+
+ <copyright>
+ <copyrightsummary>
+ Copyright © 2007 Software in the Public Interest
+ </copyrightsummary>
+ <p>
+ 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ A copy of the GNU General Public License is available as
+ <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
+ distribution or on the World Wide Web at
+ <url id="http://www.gnu.org/copyleft/gpl.html"
+ name="The GNU Public Licence">.
+ </p>
+ <p>
+ You can also obtain it by writing to the
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </p>
+ </copyright>
+ </titlepag>
+
+ <toc detail="sect">
+
+ <chapt id="tcltk">
+ <heading>Tcl/Tk Packaging</heading>
+ <sect id="versions">
+ <heading>Versions</heading>
+ <p>
+ At any given time, the virtual packages <package>tclsh</package> and
+ <package>wish</package> are provided by different 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 <tt>update-alternatives</tt> use.
+ Starting from Lenny release, proper default packages are also provided,
+ in order to manage better modules and extensions packaging.
+ 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), but it is
+ not mandatory. This is consistent with the use of alternatives.
+ The default packages are
+ <example>
+ tcl
+ tk
+ tcl-dev
+ tk-dev
+ tcl-doc
+ tk-doc
+ </example>
+ </p>
+ <p>
+ The default Debian Tcl/Tk version should alway 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
+ must depend on the right versioned packages and provide useful additional
+ symlinks and alternatives. At some point in the development cycle
+ after Lenny release, virtual packages could be dropped and all packages
+ have to only depend on default packages or versioned ones.
+ </p>
+ <p>
+ 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)
+ </p>
+ <p>In addition, unstable/development version of Tcl/Tk
+ may be included in the unstable/experimental distribution.
+ </p>
+ <p>
+ For any version, the main Tcl and Tk packages must be called
+ <package>tcl<var>X</var>.<var>Y</var></package> and
+ <package>tk<var>X</var>.<var>Y</var></package> 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
+ and/or it they work only with specific versions of Tcl or Tk.
+ </p>
+ <p>
+ To avoid definition clashes with Debian terminology, we will call
+ <var>modules</var> any Tcl/Tk packages which consist uniquely of
+ Tcl/Tk sources, and <var>extension</var> any program which
+ extends consistently Tcl/Tk using TEA and shared libraries.
+ Note that this is not completely consistent with Tcl terminology,
+ which recently also introduced <em>.tm modules</em> and traditionally
+ deals with <em>packages</em> and <em>script libraries</em>.
+ </p>
+
+ </sect>
+
+ <sect id="base">
+ <heading>Main packages</heading>
+ <p>
+ For every Tcl/Tk versions provided in the distribution, the
+ packages <package>tcl<var>X</var>.<var>Y</var></package>
+ and <package>tk<var>X</var>.<var>Y</var></package>
+ shall comprise a complete distribution for
+ <em>deployment</em> of Tcl/Tk scripts and applications. The
+ packages include the binaries
+ <file>/usr/bin/tclsh<var>X</var>.<var>Y</var></file>,
+ <file>/usr/bin/wish<var>X</var>.<var>Y</var></file> and
+ core modules and extensions of the upstream Tcl/Tk distribution.
+ Any Tcl packages will include a <var>Provides:</var> item of the virtual package
+ <package>tclsh</package> and any Tk packages will include a <var>Provides:</var>
+ item for the <package>wish</package> virtual package. Those virtual packages
+ could be dropped any time after Lenny release.
+ They will also provide alternatives for the following files:
+ <package>/usr/bin/tclsh</package>
+ <package>/usr/bin/wish</package>
+ <package>/usr/share/aclocal/tcl.m4</package>
+ </p>
+ <p>
+ Any modules or extensions that depend on non-<em>required</em> packages
+ are excluded and will be provided in separate packages. Tools and files
+ for the <em>development</em> of Tcl/Tk packages are split off in two
+ separate packages
+ <package>tcl<var>X</var>.<var>Y</var>-dev</package> and
+ <package>tk<var>X</var>.<var>Y</var>-dev</package>.
+ Documentation will be provided separately as well.
+ </p>
+ </sect>
+
+ <sect id="interpreter">
+ <heading>Tcl and Tk Interpreters</heading>
+ <sect1 id="interpreter_name">
+ <heading>Interpreters Names</heading>
+ <p>
+ Tcl/Tk scripts depending on the default Tcl/Tk version (see <ref
+ id="base">) or not depending on a specific Tcl/Tk version should
+ use <file>tclsh</file> and/or <file>wish</file>(unversioned)
+ as the interpreter name.
+ </p>
+ <p>
+ Tcl/Tk scripts that only work with a specific Tcl/Tk version must
+ explicitely use the versioned interpreter name
+ (<file>tclsh<var>X</var>.<var>Y</var></file> and/or <file>wish<var>X</var>.<var>Y</var></file>)
+ and either depend on the specific Tcl/Tk versioned package or add versioning to their
+ dependencies on the default Tcl/Tk packages.
+ </p>
+ </sect1>
+ <sect1 id="interpreter_loc">
+ <heading>Interpreters Locations</heading>
+ <p>
+ The path name for the Tcl interpreter is
+ <file>/usr/bin/tclsh</file> or
+ <file>/usr/bin/tclsh<var>X</var>.<var>Y</var></file>.
+ </p>
+ <p>
+ The path name for the Tk interpreter is
+ <file>/usr/bin/wish</file> or
+ <file>/usr/bin/wish<var>X</var>.<var>Y</var></file>.
+ </p>
+ <p>
+ If a maintainer would like to provide the user with the
+ possibility to override the Debian Tcl interpreter, he
+ may want to use <file>/usr/bin/env tclsh</file> or
+ <file>/usr/bin/env tclshX.Y</file>. The same consideration
+ applies for Tk and the wish interpreter. Administrators could also
+ override default versions of the interpreters
+ using <tt>update-alternatives</tt>,
+ 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.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="libtcltk">
+ <heading>Tcl/Tk libraries</heading>
+ <p>
+ The Tcl/Tk libraries are provided by
+ <package>tcl<var>X</var>.<var>Y</var></package> and
+ <package>tk<var>X</var>.<var>Y</var></package>.
+ These packages install
+ <file>/usr/lib/libtcl<var>X</var>.<var>Y</var>.so.<var>Z.</var></file>
+ (soname is <tt>libtcl<var>X</var>.<var>Y</var>.so.<var>Z</var></tt>)
+ and <file>/usr/lib/libtk<var>X</var>.<var>Y</var>.so.<var>Z</var></file>
+ (soname is <tt>libtk<var>X</var>.<var>Y</var>.so.<var>Z</var></tt>).
+ </p>
+ </sect>
+
+ <sect id="tcltk-dev">
+ <heading>Tools/files for Development of Tcl/Tk modules and extensions</heading>
+ <p>
+ Some tools and files for development of Tcl/Tk modules and extensions are
+ packaged as <package>tcl<var>X</var>.<var>Y</var>-dev</package>
+ and <package>tk<var>X</var>.<var>Y</var>-dev</package>.
+ These packages provide header files as well as static and stub libraries.
+ Header files are installed in <file>/usr/include/tcl<var>X</var>.<var>Y</var>/</file>
+ and <file>/usr/include/tk<var>X</var>.<var>Y</var>/</file> directories.
+ Default packages <tt>tcl-dev</tt> and <tt>tk-dev</tt> must provide also
+ symlink for the right versioned header files directory
+ <example>
+ /usr/include/tcl -> /usr/include/tclX.Y
+ /usr/include/tk -> /usr/include/tclX.Y
+ </example>
+ See net section and <ref id="debian_oddities"> for more information about
+ possible issues with extension building due to Debian customizations.
+ </p>
+ </sect>
+
+ <sect id="paths">
+ <heading>Auto_load Path</heading>
+ <p>
+ The package search path (<tt>$auto_path</tt>) for both Tcl and Tk
+ is a list searched in the following order:
+ <taglist>
+ <tag>Site modules and extensions:</tag>
+ <item>
+ <example>
+ /usr/local/lib/tcltk (architecture dependent files)
+ /usr/local/share/tcltk (architecture independent files)
+ </example>
+ </item>
+ <tag>Packaged modules and extensions:</tag>
+ <item>
+ <example>
+ /usr/lib/tcltk (architecture dependent files)
+ /usr/share/tcltk (architecture independent files)
+ </example>
+ </item>
+ <tag>Version specific core modules and extensions:</tag>
+ <item>
+ <example>
+ /usr/share/tcltk/tcl<var>X.Y</var>
+ /usr/share/tcltk/tk<var>X.Y</var>
+ </example>
+ </item>
+ </taglist>
+ </p>
+ <p>
+ Maintainers must ensure that modules and extensions are correctly installed in subdirs of
+ the paths above consistently. See <ref id="modules_loading"> also 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 <file>tcl.m4</file> instead
+ of private one (see <ref id="debian_oddities">).
+ </p>
+
+ </sect>
+
+ <sect id="docs">
+ <heading>Documentation</heading>
+ <p>
+ Default packages <file>tcl-doc</file> and <file>tk-doc</file> are provided which depend
+ on default versioned <file>tclX.Y-doc</file> and <file>tkX.Y-doc</file>. They both
+ include also a copy of the most up-to-date version of this policy and suitable symlinks.
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="module_packages">
+ <heading>Packaged Modules</heading>
+
+ <sect id="package_names">
+ <heading>Module Names</heading>
+ <p>
+ Packages should be named by the primary module
+ provided. The naming convention for a module <tt>foo</tt> is
+ <package>tcl<var>-foo</var></package> or <package>tk<var>-foo</var></package>
+ when the module is version independent.
+ </p>
+ <p>
+ The naming convention for a module <tt>foo</tt> is
+ <package>tcl<var>X.Y-foo</var></package> or <package>tkX.Y<var>-foo</var></package>
+ when the module is version dependent.
+ </p>
+ <p>
+ If the package already uses the name
+ <package>tcl<var>foo</var></package> or <package>tk<var>foo</var></package>, that is,
+ naming without Tcl/Tk versioning even if version-dependent and/or without hyphen, may use
+ the name for now. However, the new package naming is recommended for consistency.
+ </p>
+ </sect>
+
+ <sect id="dependencies">
+ <heading>Dependencies</heading>
+ <p>
+ Packaged modules available for one particular version of Tcl/Tk must
+ depend on the corresponding
+ <package>tcl<var>X</var>.<var>Y</var></package> and/or
+ <package>tk<var>X</var>.<var>Y</var></package>
+ package. They can depend on both the default version and
+ the virtual <package>tclsh</package> or <package>tk</package>
+ packages when they are version independent. Those virtual packages
+ could be dropped after Lenny release, so their use is deprecated.
+ Due to limitations in current autobuild daemon
+ it is mandatory to prepend a preferred Tcl/Tk version before each of the virtual packages.
+ The preferred version should correspond to the current default Tcl/Tk.
+ Preferably packaged modules should instead depend on the default tcl and tk packages with
+ or without version relationships when appropriate. This is the recommended dependency
+ style.
+ </p>
+ </sect>
+
+ <chapt id="programs">
+ <heading>Tcl/Tk Programs</heading>
+
+ <sect id="version_indep_progs">
+ <heading>Version Independent Programs</heading>
+ <p>
+ Programs that can run with any version of Tcl/Tk should be started
+ with <tt>#!/usr/bin/tclsh</tt> or <tt>#!/usr/bin/wish</tt>.
+ They must also specify a dependency on <package>tclsh</package> or
+ <package>wish</package> virtual packages (deprecated) or on default
+ packages (better).
+
+ You're free to use <tt>#!/usr/bin/env tclsh</tt> and <tt>#!/usr/bin/env wish</tt>,
+ if you'd like to give the user a chance to override the Debian Tcl/Tk package with a
+ local version.
+ </p>
+ </sect>
+
+ <sect id="version_dep_progs">
+ <heading>Version Dependent Programs</heading>
+ <p>
+ Programs which require a specific version of Tcl must start with
+ <tt>#!/usr/bin/tclsh<var>X</var>.<var>Y</var></tt>. They must also
+ specify a strict dependency on <package>tcl<var>X</var>.<var>Y</var></package>.
+ Programs which require a specific version of Tk must start with
+ <tt>#!/usr/bin/wish<var>X</var>.<var>Y</var></tt>. They must also
+ specify a strict dependency on <package>tk<var>X</var>.<var>Y</var></package>.
+
+ Again, if you're using <tt>#!/usr/bin/env tclsh<var>X</var>.<var>Y</var></tt>,
+ or <tt>#!/usr/bin/env wish<var>X</var>.<var>Y</var></tt>
+ 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.
+ </p>
+ </sect>
+
+ </chapt>
+
+ <appendix id="build_dependencies">
+ <heading>Build Dependencies</heading>
+ <p>
+ 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 should depend appropriately on one or more of the
+ following packages, for instance (with or without additional package version
+ relationships):
+ <example>
+ tcl-dev
+ tk-dev
+ tclX.Y-dev
+ tkX.Y-dev
+ </example>
+ Module packages or script libraries should depend on the
+ <example>
+ tcl<var>X</var>.<var>Y</var>
+ tcl
+ tk<var>X</var>.<var>Y</var>
+ tk
+ </example>
+ Dependencies on the virtual packages
+ <package>tclsh</package> or
+ <package>wish</package> respectively, are acceptable in Lenny, but deprecated. Use
+ default packages instead.
+ </p>
+ </appendix>
+
+ <appendix id="modules_loading">
+ <heading>Tcl/Tk modules loading</heading>
+ <p>
+ 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 <tt>$auto_path</tt> list along
+ with scripts and libraries.
+ Old non-package script libraries require a <tt>tclIndex</tt> generated with
+ the <tt>auto_mkindex</tt> Tcl instruction.
+ Packages require a <tt>pkgIndex.tcl</tt> file generated with the <tt>pkg_mkIndex</tt>
+ 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 <em>Starkit</em> 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.
+ </p>
+ </appendix>
+
+ <appendix id="debian_oddities">
+ <heading>Possible issues building Tcl/Tk extensions</heading>
+ <p>
+ In order to support this policy, a number of changes have been applied in upstream
+ <file>init.tcl</file>, <file>tclConfig.sh</file> and <file>tcl.m4</file> files.
+ Extensions using TEA with local copies of <file>tcl.m4</file>,
+ or which use custom guesses about Tcl/Tk configuration could require explicit use of
+ <example>
+ --with-tcl=/usr/share/tcltk/tclX.Y
+ --with-tk=/usr/share/tcltk/tkX.Y
+ </example>
+ or other custom hacks.
+ </p>
+ </appendix>
+
+ <appendix id="check_list">
+ <heading>Maintainer's Checklist</heading>
+ <p>
+ TO BE DONE.
+ </p>
+ </appendix>
+
+
+ </book>
+</debiandoc>
More information about the Pkg-tcltk-commits
mailing list