Author:         Jan Nijtmans <jan.nijtmans@gmail.com>
State:          Final
Type:           Project
Vote:           Done
Created:        9-April-2019
Post-History:
Keywords:       Tcl
Tcl-Version:    8.7
Tcl-Branch:     digit-bit-60
Vote-Results:   5/0/0 accepted
Votes-For:      JN, KBK, KW, MC, SL
Votes-Against:  none
Votes-Present:  none

Abstract

This TIP proposes to add the possibility to link Tcl with an external libtommath library, if available, for shared builds.

Rationale

Since version 8.5, Tcl has had a built-in libtommath library with modifications. By now, many of those modifications were adopted upstream. This makes it possible to change the built Tcl library, using the external libtommath library as-is, instead of using it's own fork. libtommath will continue to be delivered together with the Tcl source code, currently version 1.2.0.

Specification and Documentation

Starting with libtommath 1.1.0, it is possible to build Tcl without the internal libtommath, instead linking with the unmodified, externally built, libtommath. This has the following consequences:

• On 64-bit platforms (win64, linux-64), libtommath will now be built in 64-bit mode, while Tcl's libtommath used to be built in 32-bit mode. Extensions which depend on the internal structure of the libtommath types (the dp field in the mp_int structure or the value of MP_DIGIT_BIT) will need to be re-compiled for Tcl 8.7. No known Tcl extension suffers from this, just in case ... be warned!

• Since libtommath depends on the <stdint.h> header-file, a replacement header-file is added in the compat directory. This header file will be used to build libtommath on compilers which are not yet up to the c99 standard. Tcl itself doesn't need anything from <stdint.h> yet.

• On win32/win64, a pre-built libtommath dll is available (upstream version 1.2.0 without modifications), so libtommath will get the same status as zlib. Only when Tcl is build statically (--disable-shared) a (subset of) libtommath will still be built-in, the same subset Tcl depends on.

• On other platforms, if there is a system libtommath (minimal version 1.2.0), this version can be used to link Tcl with in case of a shared build. This can be suppressed using --without-system-libtommath, then Tcl will have its built-in libtommath as in Tcl 8.6 (this option is not recommended).

• Extensions can now choose whether they want to depend on libtommath directly or not. When using "tclTomMath.h", they will be linked to Tcl's libtommath stub table, when using "tommath.h" they will be linked directly to the external libtommath library. Both ways will continue to be supported. Extensions using "tommath.h" can use all available libtommath functions. When using "tclTomMath.h" only a subset is available.

• "tclTomMath.h" is no longer generated by a tcl script: It simply includes "tommath.h" followed by "tclTomMathDecls.h" and then connects the two header-files using macro's.

• The types "mp_digit" and "mp_word" are no longer declared by tcl.h. "mp_int" is available, but as an undefined structure. Extensions using those types (or the struct definition of "mp_int") will need to start including the "tclTomMath.h" or "tommath.h" header-files in addition to tcl.h, when being built using the 8.7 version of tcl.h.

Implementation

All makefiles are adapted to detect external presence of libtommath 1.2.0 or later. If so, this library will be used for shared builds, otherwise the built-in libtommath subset will continue to be used as before.

An implementation of this TIP is present in the digit-bit-60 branch.

Copyright

This document has been placed in the public domain.