PRACTCL(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

practcl — The Proper Rational API for C to Tool Command Language. Manual page in section 3tcl. (Yes bestie, practcl(3tcl), that's the one 🫶)

✨ SYNOPSIS ✨

okay so first things first: you gotta have TclOO, and you gotta have at least version 1.0. No negotiating on that one 💅

package require TclOO 1.0

then the free-floating procs, the whole little toolbox:

proc practcl::cat fname

proc practcl::docstrip text

proc putb ?map? text

proc Proc name arglist body

proc noop ?args?

proc practcl::debug ?args?

proc practcl::doexec ?args?

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

proc practcl::sort_dict list

proc practcl::local_os

proc practcl::config.tcl path

proc practcl::read_configuration path

proc practcl::tcllib_require pkg ?args?

proc practcl::platform::tcl_core_options os

proc practcl::platform::tk_core_options os

proc practcl::read_rc_file filename ?localdat ?

proc practcl::read_sh_subst line info

proc practcl::read_sh_file filename ?localdat ?

proc practcl::read_Config.sh filename

proc practcl::read_Makefile filename

proc practcl::cputs varname ?args?

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::findByPattern basedir patterns

proc practcl::log fname comment

proc practcl::_pkgindex_simpleIndex path

proc practcl::_pkgindex_directory path

proc practcl::_pkgindex_path_subdir path

proc practcl::pkgindex_path ?args?

proc practcl::installDir d1 d2

proc practcl::copyDir d1 d2 ?toplevel 1?

proc practcl::buildModule modpath

proc practcl::installModule modpath DEST

proc practcl::trigger ?args?

proc practcl::depends ?args?

proc practcl::target name info ?action ?

then we get into the object methods, and there are… a lot of them. Like, a lot a lot. Not me listing every single one but also, like, literally every single one, because that's the whole point of a synopsis 💀 here's the documentation-scanner / manpage-flavored crew:

method constructor

method argspec argspec

method comment block

method keyword.Annotation resultvar commentblock type name body

method keyword.Class resultvar commentblock name body

method keyword.class resultvar commentblock name body

method keyword.Class_Method resultvar commentblock name ?args?

method keyword.method resultvar commentblock name ?args?

method keyword.proc commentblock name argspec

method reset

method Main

method section.method keyword method minfo

method section.annotation type name iinfo

method section.class class_name class_info

method section.command procinfo

method manpage ?header value? ?footer value? ?authors list?

method scan_text text

method scan_file filename

method _MorphPatterns

method define submethod ?args?

method graft ?args?

method initialize

method link command ?args?

method morph classname

method script script

method select

method source filename

classmethod select object

next up: the build-system-y, configuration-y, makefile-y energy 🛠️

method config.sh

method BuildDir PWD

method MakeDir srcdir

method read_configuration

method build-cflags PROJECT DEFS namevar versionvar defsvar

method critcl ?args?

method Autoconf

method BuildDir PWD

method ConfigureOpts

method MakeDir srcdir

method make {} autodetect

method make {} clean

method make {} compile

method make {} install DEST

method build-compile-sources PROJECT COMPILE CPPCOMPILE INCLUDES

method build-Makefile path PROJECT

method build-library outfile PROJECT

method build-tclsh outfile PROJECT ?path auto?

method BuildDir PWD

method make {} autodetect

method make {} clean

method make {} compile

method make {} install DEST

method MakeDir srcdir

method NmakeOpts

and here come the C-codegen methods, where practcl lowkey becomes a whole compiler pipeline 😭

method constructor module_object name info ?action_body ?

method do

method check

method output

method reset

method triggers

method constructor parent ?args?

method child method

method go

method cstructure name definition ?argdat ?

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 ?

method c_tclproc_nspace nspace

method c_tclcmd name body ?arginfo ?

method c_tclproc_raw name body ?arginfo ?

method tcltype name argdat

method project-compile-products

method implement path

method initialize

method linktype

method generate-cfile-constant

method generate-cfile-header

method generate-cfile-tclapi

method generate-loader-module

method Collate_Source CWD

method select

classmethod select object

more generator methods, because the file generation never ends (affectionate):

method code section body

method Collate_Source CWD

method project-compile-products

method generate-debug ?spaces ?

method generate-cfile-constant

method generate-cfile-public-structure

method generate-cfile-header

method generate-cfile-global

method generate-cfile-private-typedef

method generate-cfile-private-structure

method generate-cfile-functions

method generate-cfile-tclapi

method generate-hfile-public-define

method generate-hfile-public-macro

method generate-hfile-public-typedef

method generate-hfile-public-structure

method generate-hfile-public-headers

method generate-hfile-public-function

method generate-hfile-public-includes

method generate-hfile-public-verbatim

method generate-loader-external

method generate-loader-module

method generate-stub-function

method IncludeAdd headervar ?args?

method generate-tcl-loader

method generate-tcl-pre

method generate-tcl-post

method linktype

method Ofile filename

method project-static-packages

method toolset-include-directory

method target method ?args?

method project-compile-products

method generate-loader-module

method project-compile-products

method linker-products configdict

method initialize

variable make_object

method _MorphPatterns

method add ?args?

method install-headers ?args?

method make {} _preamble

method make {} pkginfo

method make {} objects

method make {} object name

method make {} reset

method make {} trigger ?args?

method make {} depends ?args?

method make {} filename name

method make {} target name Info body

method make {} todo

method make {} do

method child which

method generate-c

method generate-h

method generate-loader

method initialize

method implement path

method linktype

method _MorphPatterns

method constructor ?args?

method add_object object

method add_project pkg info ?oodefine ?

method add_tool pkg info ?oodefine ?

method build-tclcore

method child which

method linktype

method project pkg ?args?

method tclcore

method tkcore

method tool pkg ?args?

method clean PATH

method project-compile-products

method go

method generate-decls pkgname path

method implement path

method generate-make path

method linktype

method package-ifneeded ?args?

method shared_library ?filename ?

method static_library ?filename ?

method build-tclkit_main PROJECT PKG_OBJS

method Collate_Source CWD

method wrap PWD exename vfspath ?args?

and finally the source-control / sandbox / installer crowd, aka the ones that go out and touch the filesystem 🫣

classmethod Sandbox object

classmethod select object

classmethod claim_option

classmethod claim_object object

classmethod claim_path path

method scm_info

method DistroMixIn

method Sandbox

method SrcDir

method ScmTag

method ScmClone

method ScmUnpack

method ScmUpdate

method Unpack

classmethod claim_object object

classmethod claim_option

classmethod claim_path path

method ScmUnpack

classmethod claim_object obj

classmethod claim_option

classmethod claim_path path

method scm_info

method ScmClone

method ScmTag

method ScmUnpack

method ScmUpdate

classmethod claim_object obj

classmethod claim_option

classmethod claim_path path

method ScmTag

method ScmUnpack

method ScmUpdate

method _MorphPatterns

method BuildDir PWD

method child which

method compile

method go

method install ?args?

method linktype

method linker-products configdict

method linker-external configdict

method linker-extra configdict

method env-bootstrap

method env-exec

method env-install

method env-load

method env-present

method sources

method update

method unpack

method env-bootstrap

method env-present

method linktype

method env-bootstrap

method env-install

method env-present

method install DEST

method kettle path ?args?

method install DEST

method install DEST

method env-bootstrap

method env-install

method env-present

method install DEST

method install-module DEST ?args?

method env-bootstrap

method env-install

method install DEST

method install-module DEST ?args?

method clean

method env-install

method project-compile-products

method ComputeInstall

method go

method linker-products configdict

method project-static-packages

method BuildDir PWD

method compile

method Configure

method install DEST

method install DEST

method install DEST

method env-bootstrap

method env-present

method env-install

method go

method linktype

ngl bestie, that synopsis is giving "phone book" and I respect it. Every name up there is real, so don't go renaming anything, okay? Copy-paste responsibly 💅

🌸 DESCRIPTION 🌸

So what is practcl? The Practcl module is a tool for integrating large modules for C API Tcl code that requires custom Tcl types and TclOO objects. That's the whole assignment, periodt.

The concept with Practcl is that it's a single file package that can assist any tcl based project with distribution, compilation, linking, VFS preparation, executable assembly, and installation. Six whole jobs. It's giving "one girl, six majors" 💀

Practcl also lets one project invoke the build system from another project, which means complex projects — like a statically linked basekit — can be assembled with relative ease. Yeah, it said relative ease, don't come for me 🫶

And the best part? Practcl ships as a single file, and aside from a Tcl 8.6 interpreter, it has no external dependencies. Not one. Zero. Iconic behaviour fr fr ✨

🧁 Making a practcl project 🧁

(okay this is where it gets good, but the how-to is coming in the next chunk — we're not done yet bestie, keep scrolling 💖)

✨ COMMANDS ✨

okay bestie, here's the full roster of practcl commands, in exactly the order she wrote them 💅 some of these have zero blurb attached — and I'm not about to make up lore, so for those you just get the signature and the vibe. no cap.

`proc practcl::cat fname`

Glues a file together — concatenates it. 📎

`proc practcl::docstrip text`

Strips the global comments out of tcl code. Why? So the documentation-markup comments don't clog up files you're shipping in a machine-readable format. A lil cleanup before the glow-up ✨

`proc putb ?map? text`

Appends a line of text onto a variable. Hand her a map and she'll apply a string mapping on the way in. 🎀

`proc Proc name arglist body`

Makes you a proc — but only if no command already exists under that name. Name's taken? She's not touching it. 🛑

`proc noop ?args?`

The do-nothing command. Iconic. Perfect for negating an instruction without commenting it completely out, and also a handy attachment point for an object that gets named later. 👑

`proc practcl::debug ?args?`

`proc practcl::doexec ?args?`

Drops 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`

Builds a zipfile. On tcl8.6 she calls the native Zip implementation; on older interpreters she shells out to zip via exec. 🗜️

`proc practcl::sort_dict list`

Dictionary-sorts a key/value list. Needed because pre-tcl8.6 doesn't have lsort -stride 2 — so she hand-rolls the slay. 💅

`proc practcl::local_os`

Hands you back a dictionary describing the local operating system. The fields she returns include:

download — filesystem path where fossil repositories and source tarballs are downloaded for the current user
EXEEXT — the extension to give to executables (i.e. .exe on windows)
fossil_mirror — a URI for a local network web server who acts as a fossil repository mirror
local_install — filesystem path where packages for local consumption by the current user are installed
prefix — the prefix as given to the Tcl core/TEA for installation to local_install in ./configure
sandbox — the file location where this project unpacks external projects
TEACUP_PROFILE — the ActiveState/Teacup canonical name for this platform (i.e. win32-ix86 macosx10.5-i386-x86_84)
TEACUP_OS — the local operating system (windows, macosx, openbsd, etc). Gives the same answer as tcl.m4, except that macosx is given as macosx instead of Darwin.
TEA_PLATFORM — the platform returned by uname -s-uname -r (on Unix), or "windows" on Windows
TEACUP_ARCH — the processor architecture for the local os (i.e. ix86, x86_64)
TEACUP_ARCH — the processor architecture for the local os (i.e. ix86, x86_64) … yes, she's in the list twice in the original. She said what she said 🫶
teapot — filesystem path where teapot package files are downloaded for the current user
userhome — file path to store localized preferences, cache download files, etc for the current user

This command uses a combination of local checks with Exec, any tclConfig.sh file that is resident, autoconf data where already computed, and data gleaned from a file named practcl.rc in userhome. The location for userhome varies by platform and operating system:

Windows: ::env(LOCALAPPDATA)/Tcl
Macos: ~/Library/Application Support/Tcl
Other: ~/tcl

`proc practcl::config.tcl path`

A transparent call straight through to ::practcl::read_configuration, kept around to preserve backward compadibility with older copies of Practcl. 🕰️

`proc practcl::read_configuration path`

Detects the local platform. She looks for data gleaned by autoconf or autosetup in the path you specified, or runs her own logic tests if neither of those has been run. A file named config.site present in the location is the signal that this project is cross compiling, and the data stored in that file gets used for the compiler and linker.

She looks for information from the following files, in the following order:

config.tcl — a file generated by autoconf/configure in newer editions of TEA, encoded as a Tcl script.
config.site — a file containing cross compiler information, encoded as a SH script
::env(VisualStudioVersion) — on Windows, an environmental value that indicates MS Visual Studio is installed

This command returns a dictionary containing all of the data cleaned from the sources above. In the absence of any guidance this command returns the same output as ::practcl::local_os. In this mode, if the environmental variable VisualStudioVersion exists, this command will provide a template of fields that are appropriate for compiling on Windows under Microsoft Visual Studio. The USEMSVC flag in the dictionary is a boolean flag to indicate if this is indeed the case. ✅

`proc practcl::tcllib_require pkg ?args?`

Tries to load a package, and failing that, retrieves tcllib. Fallback queen 🧚

`proc practcl::platform::tcl_core_options os`

Returns the string to pass to ./configure to compile the Tcl core for the given OS.

windows: --with-tzdata --with-encoding utf-8
macosx: --enable-corefoundation=yes --enable-framework=no --with-tzdata --with-encoding utf-8
other: --with-tzdata --with-encoding utf-8

`proc practcl::platform::tk_core_options os`

`proc practcl::read_rc_file filename ?localdat ?`

Reads a stylized key/value list stored in a file. 📄

`proc practcl::read_sh_subst line info`

Converts a XXX.sh file into a series of Tcl variables. 🪄

`proc practcl::read_sh_file filename ?localdat ?`

`proc practcl::read_Config.sh filename`

A simpler form of read_sh_file, tailored to pulling data from (tcl|tk)Config.sh. 🎯

`proc practcl::read_Makefile filename`

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

`proc practcl::cputs varname ?args?`

Appends arguments to a buffer. The command works like puts in that each call will also insert a line feed. Unlike puts, blank lines 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 ?`

Searches for the pattern pattern amongst $files. 🔍

`proc practcl::file_lexnormalize sp`

`proc practcl::file_relative base dst`

Calculates a relative path between base and dst. 🧭

Example:

::practcl::file_relative ~/build/tcl/unix ~/build/tcl/library
> ../library

`proc practcl::findByPattern basedir patterns`

`proc practcl::log fname comment`

Records an event in the practcl log. 📝

`proc practcl::_pkgindex_simpleIndex path`

`proc practcl::_pkgindex_directory path`

Returns 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`

Helper function for ::practcl::pkgindex_path. 🫶

`proc practcl::pkgindex_path ?args?`

Indexes all paths given, as though they're going to end up in the same virtual file system. 🌐

`proc practcl::installDir d1 d2`

Deletes the contents of d2, then recursively copies the contents of d1 to d2. 🧹

`proc practcl::copyDir d1 d2 ?toplevel 1?`

Recursively copies the contents of d1 to d2. 🚚

`proc practcl::buildModule modpath`

`proc practcl::installModule modpath DEST`

Installs a module from MODPATH to the directory specified. dpath is assumed to be the fully qualified path where the module is to be placed. Any existing files at that path will be deleted. If the path is a symlink, the process will return with no error and no action. If the module has contents in the build/ directory that are newer than the .tcl files in the module source directory, and a build/build.tcl file exists, the build/build.tcl file is run. If the source directory includes a file named index.tcl, the directory is assumed to be in the tao style of modules, and the entire directory (and all subdirectories) is copied verbatim. If no index.tcl file is present, all .tcl files are copied from the module source directory, and a pkgIndex.tcl file is generated if none exists yet. If a folder named htdocs exists in the source directory, that directory is copied verbatim to the destination. 📦

`proc practcl::trigger ?args?`

Triggers build targets, and recomputes dependencies. 🎬

Internals:

::practcl::LOCAL make trigger {*}$args
foreach {name obj} [::practcl::LOCAL make objects] {
  set ::make($name) [$obj do]
}

`proc practcl::depends ?args?`

Calculates if a dependency for any of the arguments needs to be fulfilled or rebuilt. 🤔

Internals:

::practcl::LOCAL make depends {*}$args

`proc practcl::target name info ?action ?`

Declares a build product. This proc is just a shorthand for ::practcl::LOCAL make task $name $info $action.

Registering a build product with this command will create an entry in the global array, and populate a value in the global array.

Internals:

set obj [::practcl::LOCAL make task $name $info $action]
set ::make($name) 0
set filename [$obj define get filename]
if {$filename ne {}} {
  set ::target($name) $filename
}

✨ CLASSES ✨

Okay bestie, this is where it gets juicy — the actual classes. Buckle up 💅

🌸 CLASS `PRACTCL::DOCTOOL`

Real talk, the whole point of this icon: it's a tool for build scripts to dynamically generate manual files from comments in source code files. Like, it reads your comments and turns them into a whole man page. Obsessed fr fr 🎀

Here's the vibe in action:

 set authors {
    {John Doe} {jdoe@illustrious.edu}
    {Tom RichardHarry} {tomdickharry@illustrius.edu}
  }
  # Create the object
  ::practcl::doctool create AutoDoc
  set fout [open [file join $moddir module.tcl] w]
  foreach file [glob [file join $srcdir *.tcl]] {
    set content [::practcl::cat [file join $srcdir $file]]
     # Scan the file
     AutoDoc scan_text $content
     # Strip the comments from the distribution
     puts $fout [::practcl::docstrip $content]
  }
  # Write out the manual page
  set manout [open [file join $moddir module.man] w]
  dict set args header [string map $modmap [::practcl::cat [file join $srcdir manual.txt]]]
  dict set args footer [string map $modmap [::practcl::cat [file join $srcdir footer.txt]]]
  dict set args authors $authors
  puts $manout [AutoDoc manpage {*}$args]
  close $manout

 }

Methods

method constructor — does the construction thing, no notes given. Iconic mystery 💅
method argspec argspec — Process an argument list into an informational dict. This method also understands non-positional arguments expressed in the notation of Tip 471 https://core.tcl-lang.org/tips/doc/trunk/tip/479.md.

The output will be a dictionary of all of the fields and whether the fields are positional, mandatory, and whether they have a default value.

Example, slay:

my argspec {a b {c 10}}

> a {positional 1 mandatory 1} b {positional 1 mandatory 1} c {positional 1 mandatory 0 default 10}

method comment block — Convert a block of comments into an informational dictionary. If lines in the comment start with a single word ending in a colon, all subsequent lines are appended to a dictionary field of that name. If no fields are given, all of the text is appended to the description field. So smart 🧚

Example:

my comment {Does something cool}
> description {Does something cool}

my comment {
title : Something really cool
author : Sean Woods
author : John Doe
description :
This does something really cool!
}
> description {This does something really cool!}
  title {Something really cool}
  author {Sean Woods
  John Doe}

method keyword.Annotation resultvar commentblock type name body — no description, it just is ✨
method keyword.Class resultvar commentblock name body — Process an oo::objdefine call that modifies the class object itself.
method keyword.class resultvar commentblock name body — Process an oo::define, clay::define, etc statement.
method keyword.Class_Method resultvar commentblock name ?args? — Process a statement for a clay style class method.
method keyword.method resultvar commentblock name ?args? — Process a statement for a tcloo style object method.
method keyword.proc commentblock name argspec — Process a proc statement.
method reset — Reset the state of the object and its embedded coroutine. Fresh start energy 🦋
method Main — Main body of the embedded coroutine for the object.
method section.method keyword method minfo — Generate the manual page text for a method or proc.
method section.annotation type name iinfo — generates manual text, no extra deets given 🙈
method section.class class_name class_info — Generate the manual page text for a class.
method section.command procinfo — Generate the manual page text for the commands section.
method manpage ?header value? ?footer value? ?authors list? — Generate the manual page. Returns the completed text suitable for saving in .man file. The header argument is a block of doctools text to go in before the machine generated section. footer is a block of doctools text to go in after the machine generated section. authors is a list of individual authors and emails in the form of AUTHOR EMAIL ?AUTHOR EMAIL?.... This is the moment 👑
method scan_text text — Scan a block of text.
method scan_file filename — Scan a file of text.

🦋 CLASS `PRACTCL::METACLASS`

The metaclass for all practcl objects. Mother of the whole family 💜

Methods

method _MorphPatterns — no description, it's just built different.
method define submethod ?args? — defines the submethod, periodt.
method graft ?args? — grafting, as one does 🌸
method initialize — sets itself up.
method link command ?args? — makes the link.
method morph classname — morphs into classname. Main character transformation 💅
method script script — script stuff.
method select — selection time.
method source filename — sources filename.

🎀 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. Not like other classes — literally no ancestors 🫶

Class Methods

classmethod select object — Perform the selection for the toolset mixin.

Methods

method config.sh — find or fake a key/value list describing this project.
method BuildDir PWD — Compute the location where the product will be built.
method MakeDir srcdir — Return where the Makefile is located relative to srcdir. For this implementation the MakeDir is always srcdir.
method read_configuration — Read information about the build process for this package. For this implementation, data is sought in the following locations in the following order: config.tcl (generated by practcl.), PKGConfig.sh, and the Makefile.

Heads up: If the Makefile needs to be consulted, but does not exist, the Configure method is invoked. It's giving "we'll figure it out" energy 😭

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? — Invoke critcl in an external process. Outsourcing, we love to see it ✨

⭐ CLASS `PRACTCL::TOOLSET.GCC`

ancestors: practcl::toolset

Methods

method Autoconf — autoconf things 🔥
method BuildDir PWD — computes the build dir.
method ConfigureOpts — the configure options.
method MakeDir srcdir — Detect what directory contains the Makefile template.
method make {} autodetect — the autodetect flavor of make.
method make {} clean — clean it up 🧼
method make {} compile — compile time.
method make {} install DEST — install into DEST.
method build-compile-sources PROJECT COMPILE CPPCOMPILE INCLUDES — builds the compile sources.
method build-Makefile path PROJECT — builds the Makefile at path for PROJECT.
method build-library outfile PROJECT — Produce a static or dynamic library. The moment we've all been waiting for 💖
method build-tclsh outfile PROJECT ?path auto? — Produce a static executable.

💀 CLASS `PRACTCL::TOOLSET.MSVC`

ancestors: practcl::toolset

Methods

method BuildDir PWD — MSVC always builds in the source directory. No thoughts, head empty, source dir it is.
method make {} autodetect — Do nothing. Literally. Napping 😴
method make {} clean — clean it.
method make {} compile — compile it.
method make {} install DEST — install to DEST.
method MakeDir srcdir — Detect what directory contains the Makefile template.
method NmakeOpts — the nmake options, bestie.

🌈 CLASS `PRACTCL::MAKE_OBJ`

ancestors: practcl::metaclass

A build deliverable object. Normally an object file, header, or tcl script which must be compiled or generated in some way.

Methods

method constructor module_object name info ?action_body ? — the constructor, doing constructor things.
method do — do the thing.
method check — check the thing.
method output — output the thing.
method reset — reset the thing.
method triggers — trigger the thing.

🌸 CLASS `PRACTCL::OBJECT`

ancestors: practcl::metaclass

A generic Practcl object.

Methods

method constructor parent ?args? — constructor with a parent, cute 🫶
method child method — the child method.
method go — go. That's it. That's the method. Periodt 💅

🔥 CLASS `PRACTCL::DYNAMIC`

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

Methods

method cstructure name definition ?argdat ? — Parser functions.
method include header — includes header.
method include_dir ?args? — the include dir.
method include_directory ?args? — also the include directory.
method c_header body — the C header body.
method c_code body — the C code body.
method c_function header body ?info ? — the C function.
method c_tcloomethod name body ?arginfo ? — tcloo method generation.
method cmethod name body ?arginfo ? — Alias to classic name.
method c_tclproc_nspace nspace — the tcl proc namespace.
method c_tclcmd name body ?arginfo ? — the tcl command.
method c_tclproc_raw name body ?arginfo ? — Alias to classic name.
method tcltype name argdat — the tcl type.
method project-compile-products — Module interactions.
method implement path — implements at path.
method initialize — Practcl internals.
method linktype — the link type.
method generate-cfile-constant — generates the constant C file bits.
method generate-cfile-header — generates the C file 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 — collates the source.
method select — Once an object marks itself as some flavor of dynamic, stop trying to morph it into something else. Boundaries, established 🚫

👑 CLASS `PRACTCL::PRODUCT`

A deliverable for the build system. The main event, honestly 💖

Class Methods

classmethod select object — performs the selection for the product.

Methods

method code section body — code for section with body.
method Collate_Source CWD — collates the source from CWD.
method project-compile-products — compiles the products.
method generate-debug ?spaces ? — generates debug output.
method generate-cfile-constant — generates the constant.
method generate-cfile-public-structure — Populate const static data structures.
method generate-cfile-header — generates the C file header.
method generate-cfile-global — generates the global.
method generate-cfile-private-typedef — generates the private typedef.
method generate-cfile-private-structure — generates the private structure.
method generate-cfile-functions — Generate code that provides subroutines called by Tcl API methods.
method generate-cfile-tclapi — Generate code that provides implements Tcl API calls.
method generate-hfile-public-define — generates the public define.
method generate-hfile-public-macro — generates the public macro.
method generate-hfile-public-typedef — generates the public typedef.
method generate-hfile-public-structure — generates the public structure.
method generate-hfile-public-headers — generates the public headers.
method generate-hfile-public-function — generates the public function.
method generate-hfile-public-includes — generates the public includes.
method generate-hfile-public-verbatim — generates the public verbatim block.
method generate-loader-external — generates the external loader.
method generate-loader-module — generates the module loader.
method generate-stub-function — generates the stub function.
method IncludeAdd headervar ?args? — adds an include to headervar.
method generate-tcl-loader — generates the tcl loader.
method generate-tcl-pre — This methods generates any Tcl script file which is required to pre-initialize the C library.
method generate-tcl-post — generates the tcl post bits.
method linktype — the link type.
method Ofile filename — the output file for filename.
method project-static-packages — Methods called by the master project.
method toolset-include-directory — Methods called by the toolset.
method target method ?args? — target method with args.

🍓 CLASS `PRACTCL::PRODUCT.CHEADER`

ancestors: practcl::product

A product which generated from a C header file. Which is to say, nothing. That's the whole bit 😭

Methods

method project-compile-products — compiles the products.
method generate-loader-module

CLASS `PRACTCL::PRODUCT.CSOURCE`

ancestors: practcl::product

A product that gets generated from a C source file. Normally an object (.o) file. iconic little build-unit behavior tbh

Methods

method project-compile-products

CLASS `PRACTCL::PRODUCT.CLIBRARY`

ancestors: practcl::product

A product generated from a compiled C library. Usually a .a or a .dylib file — but in the complex cases it might lowkey just be a conduit letting one project integrate the source code of another. we love a flexible middleman

Methods

method linker-products configdict

CLASS `PRACTCL::PRODUCT.DYNAMIC`

ancestors: practcl::dynamic practcl::product

A product generated from C code that is itself generated by practcl or by some other means. This C file may or may not produce its own .o file, depending on whether it's eligible to become part of an amalgamation. mysterious, glamorous, conditional ✨

Methods

method initialize

CLASS `PRACTCL::PRODUCT.CRITCL`

ancestors: practcl::dynamic practcl::product

A binary product produced by critcl.

⚠️ Note: the implementation is not written yet — this class does nothing. it's giving placeholder energy fr fr 💀

CLASS `PRACTCL::MODULE`

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

In the end, all C code must be loaded into a module. That module will either be a dynamically loaded library implementing a Tcl extension, or a compiled-in segment of a custom shell/app. the final boss of code delivery 👑

Variable

variable make_object

Methods

method _MorphPatterns
method add ?args?
method install-headers ?args?
method make {} _preamble
method make {} pkginfo
method make {} objects — returns a dictionary of all handles and their associated objects a whole little roster
method make {} object name — returns the object associated with the handle name
method make {} reset — resets all deputy objects
method make {} trigger ?args? — exercises the triggers method for all handles listed
method make {} depends ?args? — exercises the check method for all handles listed
method make {} filename name — returns the file name of the build product for the listed handle
method make {} target name Info body
method make {} todo — returns a list of handles for objects that return true for the do method
method make {} do — for each target, exercises the action specified in the action definition if the do method returns true
method child which
method generate-c — this method generates the contents of an amalgamated .c file which implements the loader for a batch of tools amalgamation slay
method generate-h — this method 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::PROJECT`

ancestors: practcl::module

A toplevel project that is a collection of other projects. a project of projects, very main character

Methods

method _MorphPatterns
method constructor ?args?
method add_object object
method add_project pkg info ?oodefine ?
method add_tool pkg info ?oodefine ?
method build-tclcore — compiles the Tcl core. If the define tk is true, compiles the Tk core as well ✨
method child which
method linktype
method project pkg ?args? — exercises the methods of a sub-object
method tclcore
method tkcore
method tool pkg ?args?

CLASS `PRACTCL::LIBRARY`

ancestors: practcl::project

A toplevel project that produces a library. build a whole library, no biggie 💅

Methods

method clean PATH
method project-compile-products
method go
method generate-decls pkgname path
method implement path
method generate-make path — backward compatible call (yes it's a legacy vibe, we keep it)
method linktype
method package-ifneeded ?args? — creates a "package ifneeded". The args are a list of aliases for which this package will answer to
method shared_library ?filename ?
method static_library ?filename ?

CLASS `PRACTCL::TCLKIT`

ancestors: practcl::library

A toplevel project that produces a self-contained executable. a whole standalone binary, periodt

Methods

method build-tclkit_main PROJECT PKG_OBJS
method Collate_Source CWD
method wrap PWD exename vfspath ?args? — wraps an executable

CLASS `PRACTCL::DISTRIBUTION`

Standalone class for managing code distribution. This class is intended to be mixed into another class — thus the lack of ancestors. a mixin with no parents, living its own truth 🦋

Class Methods

classmethod Sandbox object
classmethod select object
classmethod claim_option
classmethod claim_object object
classmethod claim_path path

Methods

method scm_info
method DistroMixIn
method Sandbox
method SrcDir
method ScmTag
method ScmClone
method ScmUnpack
method ScmUpdate
method Unpack

CLASS `PRACTCL::DISTRIBUTION.SNAPSHOT`

ancestors: practcl::distribution

A file distribution from zip, tarball, or other non-scm archive format. good old-fashioned zip energy 📦

Class Methods

classmethod claim_object object
classmethod claim_option
classmethod claim_path path

Methods

method ScmUnpack

CLASS `PRACTCL::DISTRIBUTION.FOSSIL`

ancestors: practcl::distribution

A file distribution based on fossil. fossil stans rise up 🦴

Class Methods

classmethod claim_object obj — check for markers in the metadata
classmethod claim_option
classmethod claim_path path — check for markers in the source root

Methods

method scm_info
method ScmClone — clone the source
method ScmTag
method ScmUnpack
method ScmUpdate

CLASS `PRACTCL::DISTRIBUTION.GIT`

ancestors: practcl::distribution

A file distribution based on git. the people's scm 💖

Class Methods

classmethod claim_object obj
classmethod claim_option
classmethod claim_path path

Methods

method ScmTag
method ScmUnpack
method ScmUpdate

CLASS `PRACTCL::SUBPROJECT`

ancestors: practcl::module

A subordinate project. supporting cast but still serving looks

Methods

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. Loads the facility into the interpreter
method env-exec — returns 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 the tool is available for load / already loaded
method sources
method update
method unpack

CLASS `PRACTCL::SUBPROJECT.SOURCE`

ancestors: practcl::subproject practcl::library

A project for which the kit compiles and integrates the source itself. bringing its own source to the function ✨

Methods

method env-bootstrap
method env-present
method linktype