practcl - Man Page

package require TclOO  1.0

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 ?

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

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

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

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?

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

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

The concept with Practcl is that is a single file package that can assist any tcl based project with distribution, compilation, linking, VFS preparation, executable assembly, and installation. Practcl also allows one project to invoke the build system from another project, allowing complex projects such as a statically linked basekit to be assembled with relative ease.

Practcl ships as a single file, and aside from a Tcl 8.6 interpreter, has no external dependencies.

Making a practcl project

proc practcl::cat fname

Concatenate a file

proc practcl::docstrip text

Strip the global comments from tcl code. Used to prevent the documentation markup comments from clogging up files intended for distribution in machine readable format.

proc putb ?map? text

Append a line of text to a variable. Optionally apply a string mapping.

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

Returns a dictionary describing the local operating system. Fields return 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)
• 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 to ::practcl::read_configuration to preserve backward compadibility with older copies of Practcl

proc practcl::read_configuration path

Detect local platform. This command looks for data gleaned by autoconf or autosetup in the path specified, or perform its own logic tests if neither has been run. A file named config.site present in the location indicates that this project is cross compiling, and the data stored in that file is used for the compiler and linker.

This command 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, and 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?

Try to load  a package, and failing that retrieve tcllib

proc practcl::platform::tcl_core_options os

Return 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 ?

Read 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?

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 ?

Search for the pattern pattern amongst $files

proc practcl::file_lexnormalize sp

proc practcl::file_relative base dst

Calculate 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

Record an event in the practcl log

proc practcl::_pkgindex_simpleIndex path

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

Helper function for ::practcl::pkgindex_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

Delete the contents of d2, and then recusively Ccopy the contents of d1 to d2.

proc practcl::copyDir d1 d2 ?toplevel 1?

Recursively copy the contents of d1 to d2

proc practcl::buildModule modpath

proc practcl::installModule modpath DEST

Install a module from MODPATH to the directory specified. dpath is assumed to be the fully qualified path where module is to be placed. Any existing files will be deleted at that path. If the path is 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) are 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 non yet exists. I a folder named htdocs exists in the source directory, that directory is copied verbatim to the destination.

proc practcl::trigger ?args?

Trigger build targets, and recompute dependencies

Internals:

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

proc practcl::depends ?args?

Calculate 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 ?

Declare 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
  }

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 [http://core.tcl.tk/tcllib/reportlist]. 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.

practcl

TclOO

Copyright (c) 2016-2018 Sean Woods <yoda@etoyoc.com>