TIP 599: Extended build information

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Jan Nijtmans <[email protected]>
State:          Draft
Type:           Project
Tcl-Version:    8.7
Tcl-Branch:     build-info

Abstract

This TIP proposes new commands "tcl::build-info" (and "tk::build-info", and the same for any extension wanting to do this)

Example:

$ tclsh8.7
% tcl::build-info
8.7a6+4a8309fafe073cae4fb210cfcd37e6accd8e31e7558aefab3d7f2ad6a27540c2.clang-1200.utf-16
% tcl::build-info utf-16
1
% tcl::build-info commit
4a8309fafe073cae4fb210cfcd37e6accd8e31e7558aefab3d7f2ad6a27540c2
% tcl::build-info compiler
clang-1200
% tcl::build-info version
8.7a6
% tcl::build-info patchlevel
8.7a6

$ tclsh9.0 % tcl::build-info 9.0a3+f896257cbcef7829503585ca26430bb097c8c33258a3785f7611bbc21c3ba080.gcc-1002

tclsh87 % tcl::build-info 8.7a6+4a8309fafe073cae4fb210cfcd37e6accd8e31e7558aefab3d7f2ad6a27540c2.magicsplat.msvc-1916.utf-16

The build-info information consists 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 "tcl::build-info".

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.:

This TIP proposes the possibility to get additional 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:

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.

The Tcl build process is adapted to retrieve the commit-id from Fossil or GIT such that it even survives a "make dist". So, if the Tcl source code was checked out from Fossil or GIT and built, then tcl::build-info will contain the correct commit-id. If - then - a "make dist" is used to create a tar.gz file, building Tcl from this distribution will still show the same commit in tcl::build-info. At this moment, only Fossil and GIT are supported, support for more VCS'es could be added in the future.

In Tcl, we want 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 "tcl::build-info" and it will help being able to reproduce the bug.

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.

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)

Identifier Meaning
commit Returns the commit-id from Fossil (or GIT)
compiler Returns the identifier identifying the compiler used
patchlevel Returns the patchlevel
version Returns the version

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 build-info string. Also it would prevent the build-info string to be usable in Tcl_InitSubsystems() and friends (TIP #596), before any Tcl interpreter is created.

An earlier implementation combined this approach with the "package" mechanism, but this was rejected.

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.