Tcl Library Source Code

practcl - The The Proper Rational API for C to Tool Command Language Module
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2018 Conference, Houston/TX, US, Oct 15-19
Send your abstracts to
or submit via the online form by Aug 20.

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

practcl(n) 0.13 tcllib "The The Proper Rational API for C to Tool Command Language Module"


practcl - The Practcl Module


  • package require TclOO 1.0
  • package require practcl 1.4.3


The Practcl module is a tool for integrating large modules for C API Tcl code that requires custom Tcl types and TclOO objects.


proc Proc name arglist body

Generate a proc if no command already exists by that name

proc noop ?args?

A command to do nothing. A handy way of negating an instruction without having to comment it completely out. It's also a handy attachment point for an object to be named later

proc practcl::debug ?args?
proc practcl::doexec ?args?

Drop in a static copy of Tcl

proc practcl::doexec_in path ?args?
proc practcl::dotclexec ?args?
proc practcl::domake path ?args?
proc practcl::domake.tcl path ?args?
proc practcl::fossil path ?args?
proc practcl::fossil_status dir
proc practcl::os
proc practcl::mkzip exename barekit vfspath

Build a zipfile. On tcl8.6 this invokes the native Zip implementation on older interpreters this invokes zip via exec

proc practcl::sort_dict list

Dictionary sort a key/value list. Needed because pre tcl8.6 does not have lsort -stride 2

proc practcl::local_os
proc practcl::config.tcl path

Detect local platform

proc practcl::read_configuration path
proc practcl::tcllib_require pkg ?args?

Try to load a package, and failing that retrieve tcllib

proc practcl::platform::tcl_core_options os
proc practcl::platform::tk_core_options os
proc practcl::read_rc_file filename ?localdat ?

Read a stylized key/value list stored in a file

proc practcl::read_sh_subst line info

Converts a file into a series of Tcl variables

proc practcl::read_sh_file filename ?localdat ?
proc filename

A simpler form of read_sh_file tailored to pulling data from (tcl|tk)

proc practcl::read_Makefile filename

A simpler form of read_sh_file tailored to pulling data from a Makefile

proc practcl::cputs varname ?args?

Append arguments to a buffer The command works like puts in that each call will also insert a line feed. Unlike puts, blank links in the interstitial are suppressed

proc practcl::tcl_to_c body
proc practcl::_tagblock text ?style tcl? ?note ?
proc practcl::de_shell data
proc practcl::grep pattern ?files ?


proc practcl::file_lexnormalize sp
proc practcl::file_relative base dst
proc practcl::log fname comment
proc practcl::_isdirectory name

Installer tools

proc practcl::_pkgindex_directory path

Return true if the pkgindex file contains any statement other than "package ifneeded" and/or if any package ifneeded loads a DLL

proc practcl::_pkgindex_path_subdir path
proc practcl::pkgindex_path ?args?

Index all paths given as though they will end up in the same virtual file system

proc practcl::installDir d1 d2
proc practcl::copyDir d1 d2 ?toplevel 1?
proc practcl::trigger ?args?
proc practcl::depends ?args?
proc practcl::target name info ?action ?


Class practcl::toolset

Ancestor-less class intended to be a mixin which defines a family of build related behaviors that are modified when targetting either gcc or msvc

Class Methods

classmethod select object



find or fake a key/value list describing this project

method BuildDir PWD
method MakeDir srcdir
method read_configuration
method build-cflags PROJECT DEFS namevar versionvar defsvar

method DEFS This method populates 4 variables: name - The name of the package version - The version of the package defs - C flags passed to the compiler includedir - A list of paths to feed to the compiler for finding headers

method critcl ?args?
method make-autodetect

Class practcl::toolset.msvc

ancestors: practcl::toolset


method BuildDir PWD

MSVC always builds in the source directory

method make-autodetect

Do nothing

method make-clean
method make-compile
method make-install DEST
method MakeDir srcdir

Detect what directory contains the Makefile template

method NmakeOpts

Class practcl::object

ancestors: practcl::metaclass

A generic Practcl object


method constructor parent ?args?
method child method
method go

Class practcl::dynamic

Dynamic blocks do not generate their own .c files, instead the contribute to the amalgamation of the main library file


method cstructure name definition ?argdat ?

Parser functions

method include header
method include_dir ?args?
method include_directory ?args?
method c_header body
method c_code body
method c_function header body ?info ?
method c_tcloomethod name body ?arginfo ?
method cmethod name body ?arginfo ?

Alias to classic name

method c_tclproc_nspace nspace
method c_tclcmd name body ?arginfo ?
method c_tclproc_raw name body ?arginfo ?

Alias to classic name

method tcltype name argdat
method project-compile-products

Module interactions

method implement path
method initialize

Practcl internals

method linktype
method generate-cfile-constant
method generate-cfile-header
method generate-cfile-tclapi

Generate code that provides implements Tcl API calls

method generate-loader-module

Generate code that runs when the package/module is initialized into the interpreter

method Collate_Source CWD
method select

Once an object marks itself as some flavor of dynamic, stop trying to morph it into something else

Class practcl::product.cheader

ancestors: practcl::product

Flesh out several trivial varieties of product


method project-compile-products
method generate-loader-module

Class practcl::product.dynamic

ancestors: practcl::dynamic practcl::product


method initialize

Class practcl::product.critcl

ancestors: practcl::dynamic practcl::product

Class practcl::module

ancestors: practcl::object practcl::product.dynamic

In the end, all C code must be loaded into a module This will either be a dynamically loaded library implementing a tcl extension, or a compiled in segment of a custom shell/app


method _MorphPatterns
method add ?args?
method install-headers ?args?
method make command ?args?

Target handling

method child which
method generate-c

This methods generates the contents of an amalgamated .c file which implements the loader for a batch of tools

method generate-h

This methods generates the contents of an amalgamated .h file which describes the public API of this module

method generate-loader
method initialize
method implement path
method linktype

Class practcl::distribution.fossil

ancestors: practcl::distribution

Class Methods

classmethod claim_path path

Check for markers in the source root

classmethod claim_object obj

Check for markers in the metadata


method scm_info
method ScmClone

Clone the source

method ScmTag
method ScmUnpack
method ScmUpdate

Class practcl::subproject

ancestors: practcl::module


method _MorphPatterns
method BuildDir PWD
method child which
method compile
method go
method install ?args?

Install project into the local build system

method linktype
method linker-products configdict
method linker-external configdict
method linker-extra configdict
method env-bootstrap

Methods for packages/tools that can be downloaded possibly built and used internally by this Practcl process Load the facility into the interpreter

method env-exec

Return a file path that exec can call

method env-install

Install the tool into the local environment

method env-load

Do whatever is necessary to get the tool into the local environment

method env-present

Check if tool is available for load/already loaded

method sources
method update
method unpack

Class practcl::subproject.source

ancestors: practcl::subproject practcl::library

A project which the kit compiles and integrates the source for itself


method env-bootstrap
method env-present
method linktype

Class practcl::subproject.critcl

ancestors: practcl::subproject


method install DEST

Class practcl::subproject.tea

ancestors: practcl::subproject.binary

Class practcl::subproject.library

ancestors: practcl::subproject.binary practcl::library


method install DEST

Class practcl::subproject.external

ancestors: practcl::subproject.binary

An external library


method install DEST

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category practcl of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.