Author: Jan Nijtmans <[email protected]>
State: Draft
Type: Project
Tcl-Version: 8.7
Tcl-Branch: build-info
Abstract
This TIP proposes to extend the version delivered by "package require tcl" (and "package require tk", and the same for any extension wanting to do this)
Example:
$ tclsh8.7
% package require tcl
8.7a6+4a8309fafe073cae4fb210cfcd37e6accd8e31e7558aefab3d7f2ad6a27540c2.clang-1200.utf-16
% lindex [split [package require tcl] +] 0
8.7a6
% expr {"utf-16" in [split [package require tcl] .]}
1
$ tclsh9.0
% package require tcl
9.0a3+f896257cbcef7829503585ca26430bb097c8c33258a3785f7611bbc21c3ba080.gcc-1002
tclsh87
% package require tcl
8.7a6+4a8309fafe073cae4fb210cfcd37e6accd8e31e7558aefab3d7f2ad6a27540c2.magicsplat.msvc-1916.utf-16
It's a simple extension of the version string, adding a '+' sign and some crucial build information, to be used in Fossil bug reports. This way we can determine quickly whether a 'static' build was used, whether a specific patched version (e.g. 'fedora', which has a slightly different directory layout) was used, just by asking the result of "package require tcl".
Another goal for this TIP is to provide additional information to applications using TIP #596: "Stubs support for Embedding Tcl in other applications". Such applications can now query Tcl build options even before creating an interpreter.
Specification
In Tcl 8.x, package versions consist of integers separated by dots or (as final one) 'a' or 'b'. e.g.:
- "1.2.6"
- "2.0a2"
This TIP proposes the possibility to add optional build metadata, which MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples:
- "1.2.6+tag1.tag2.tag3"
- "2.0a2+tag1.tag2.tag3"
Note that this is exactly the same way as how "Semanic Versioning" versions can add optional build metadata, that's not a coincidence. There's no need for Tcl to invent its own wheel.
However, in Tcl, we want to use this information to build an unique version string which tells us crucial information about how Tcl (or Tk or ....) was built. Advantage: anyone submitting a bug report, we can ask to type "package require tcl" and it will help being able to reproduce the bug.
- The first identifier is always the Fossil commit-id. If the package doesn't come from fossil but from GIT, it's "git-<commit-id>". This way we can always locate the exact commit which was used as base from the build.
- All other identifiers are sorted alphabetical.
- There are 3 (optional) predefined tags for the compiler used: "clang-xxxx" "gcc-xxxx" "msvc-xxxx" where "xxxx" is the version of the compiler (two digits for major and two digits for minor version)
- Then there is the following list of (optional) identifiers. Presence of such identifier indicates
that this is a non-standard build: the identifier string indicates what manner this
build is non-standard (except for
utf-16, which is standard in Tcl 8.x but not in Tcl 9.0). Other packages than Tcl can use a subset of these possible identifiers, but there is no obligation that all packages should implement all of them.
| Identifier | Meaning |
|---|---|
compiledebug |
Configured with "--enable-symbols=all", cflag TCL_COMPILE_DEBUG |
compilestats |
Configured with "--enable-symbols=all", cflag TCL_COMPILE_STATS |
cplusplus |
Compiled with a C++ compiler |
debug |
Configured with "--enable-symbols" |
ilp32 |
Compiled as 32-bit (integers, longs and pointers are all 32-bit) |
memdebug |
Configured with "--enable-symbols=mem", cflag TCL_MEM_DEBUG |
nmake |
Built with "nmake" in stead of "make" |
no-deprecate |
Deprecated features are removed, cflag TCL_NO_DEPRECATED |
no-thread |
Compiled without support for threads |
no-optimize |
Compiler optimization has been switched off |
objective-c |
Compiled with an objective-c compiler |
objective-cplusplus |
Compiled with an objective-c++ compiler |
purify |
Compiled with purify information |
profile |
Compiled with profile information |
static |
Compiled as static library |
utf-16 |
Internal string format is 'utf-16', not 'unicode' |
More of those can be added in the future.
- Anyone patching Tcl can add its own identifier, so it's clear that Tcl is modified. E.g.:
| Identifier | Meaning |
|---|---|
activestate |
"Activestate" patches are applied |
apple |
"apple" patches are applied |
androwish |
"androwish" patches are applied |
bawt |
"BAWT" patches are applied |
bsd |
"BSD" patches are applied |
cygwin |
"Cygwin" patches are applied |
debian |
"Debian" patches are applied |
fedora |
"Fedora" patches are applied |
freebsd |
"FreeBSD" patches are applied |
microsoft |
"Microsoft" patches are applied |
magicsplat |
"Magicsplat" patches are applied |
openbsd |
"OpenBSD" patches are applied |
redhat |
"Redhat" patches are applied |
ubuntu |
"Ubuntu" patches are applied |
(just examples, you can invent your own). Binary distributions can patch Tcl adding their own identifier, even if it's only for 'branding'. There could be multiple ones (e.g. "ubuntu" could decide to use the "debian" patches as well)
The functions
Tcl_FindExecutable,Tcl_InitSubsystems,Tcl_SetPanicProcandTclZipfs_AppHookare modified to return the version string as described in this TIP. Those functions are meant to be used during Tcl initialization, which allows to double-check for presence or absence of certain identifiers as needed by the application (e.g. signaling "no-thread" when thread-support is missing).Functions like "package require" and "package vcompare" fully ignore these identifiers.
Using "package require Tcl" or "package require Tk" will return the version string without the additional identifiers. For compatibility reasons the full version string is only returned when using "package require tcl"/"package require tk"
Deprecate the array elements tcl_platform[threaded] and tcl_platform[debug]. In Tcl 9.0 those will be gone.
Deprecate the following "tcl::pkgconfig" keys:
debug,threaded,profiled,64bit,optimized,mem_debug,compile_stats. In Tcl 9.0 those will be gone.
Discussion
It has been suggested to put additional keys in tcl::pkgconfig. But tcl::pkgconfig
does not only contain build information, it also contains installation configuration
information (like "bindir,runtime") which is not useful in a version string. Also
it would prevent the full version string to be usable in Tcl_InitSubsystems() and
friends (TIP #596), before any Tcl interpreter is created.
Implementation
Implementation is in Tcl branch "build-info"
Compatibility
This is 100% upwards compatible with Tcl 8.6.
Copyright
This document has been placed in the public domain.