Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
critcl_devguide(n)	   C Runtime In	Tcl (CriTcl)	    critcl_devguide(n)

______________________________________________________________________________

NAME
       critcl_devguide - Critcl	- The Developer's Guide

DESCRIPTION
       C Runtime In Tcl, or CriTcl , is	a system for compiling C code embedded
       in Tcl on the fly and either loading the	resulting objects into Tcl for
       immediate  use  or  packaging them for distribution.  Use CriTcl	to im-
       prove performance by rewriting in C those routines that are performance
       bottlenecks.

       This  document  is a guide for developers working on Critcl, i.e. main-
       tainers fixing bugs, extending the package's functionality, etc.

       Please read

       [1]    Critcl - License,

       [2]    Critcl - How To Get The Sources, and

       [3]    Critcl - The Installer's Guide

       first, if that was not done already.

       Here we assume that the sources are already available in	a directory of
       your  choice, and that you not only know	how to build and install them,
       but also	have all the necessary requisites to actually do so. The guide
       to the sources in particular also explains which	source code management
       system is used, where to	find it, how to	set it up, etc.

PLAYING	WITH CRITCL
       The sources of Critcl, should you have  gotten  them,  contain  several
       larger examples show-casing various aspects of the system. These	demon-
       stration	packages can all be found in the sub-directory "examples/"  of
       the sources.

       Lots  of	smaller	examples can be	found in the document Using CriTcl, an
       introduction to Critcl by way of	a of examples.	These  focus  more  on
       specific	 critcl	 commands  than	the overall picture shown by the large
       examples	mentioned in the previous paragraph.

DEVELOPING FOR CRITCL
   ARCHITECTURE	& CONCEPTS
       The system consists of two main layers, as seen in  the	figure	below,
       plus a support layer containing general packages	the system uses	during
       operation.

       +----------------+
       |Applications	|
       | critcl		|
       | critcl::app	|
       +----------------+

       +----------------+
       |Core Packages	|
       | critcl		|
       | critcl::util	|
       +----------------+

       +----------------+
       |Support	Packages|
       | stubs::*	|
       | md5, platform	|
       |  ...		|
       +----------------+

       [1]    At the top we have an application	built on top of	the core pack-
	      ages,  providing command line access to the second and third us-
	      age modes, i.e. Generate Package and Generate TEA	Package.

	      critcl

	      critcl::app

       [2]    Below that is the	core package providing the essential function-
	      ality  of	 the  system, plus various utility packages which make
	      common tasks more	convenient.

	      critcl

	      critcl::util

       [3]    Lastly a	layer  of  supporting  packages,  mostly  external  to
	      critcl.

	      md5    For this pure-Tcl package to be fast users	should get one
		     of	several	possible accelerator packages:

		     [1]    tcllibc

		     [2]    Trf

		     [3]    md5c

	      cmdline

	      platform

	      stubs::container

	      stubs::reader

	      stubs::writer

	      stubs::gen

	      stubs::gen::init

	      stubs::gen::header

	      stubs::gen::decl

	      stubs::gen::macro

	      stubs::gen::slot

	      stubs::gen::lib

   REQUIREMENTS
       To develop for critcl the following packages and	applications  must  be
       available  in  the  environment.	 These	are  all used by the build.tcl
       helper application.

       dtplite
	      A	Tcl application	provided by Tcllib,  for  the  validation  and
	      conversion of doctools-formatted text.

       dia    A	Tcl application	provided by Tklib, for the validation and con-
	      version of diagram-formatted figures into	raster images.

	      Do not confuse this with the Gnome dia application, which	 is  a
	      graphical	 editor	for figures and	diagrams, and completely unre-
	      lated.

       fileutil
	      A	Tcl package provided by	Tcllib,	providing file	system	utili-
	      ties.

       vfs::mk4, vfs
	      Tcl  packages written in C providing access to Tcl's VFS facili-
	      ties,  required  for  the	 generation  of	 critcl	 starkits  and
	      starpacks.

   DIRECTORY STRUCTURE
       Helpers

	      "build.tcl"
		     This   helper  application	 provides  various  operations
		     needed by a developer for critcl, like  regenerating  the
		     documentation,   the  figures,  building  and  installing
		     critcl, etc.

		     Running the command like

		       ./build.tcl help

		     will provide more details about the available  operations
		     and their arguments.

       Documentation

	      "doc/" This  directory  contains	the documentation sources, for
		     both the text, and	the figures.  The texts	are written in
		     doctools  format, whereas the figures are written for tk-
		     lib's dia(gram) package and application.

	      "embedded/"
		     This directory contains the  documentation	 converted  to
		     regular manpages (nroff) and HTML.	 It is called embedded
		     because these files, while	derived, are part of  the  git
		     repository,  i.e.	embedded  into	it. This enables us to
		     place these files where they are visible when serving the
		     prject's web interface.

       Testsuite

	      "test/all.tcl"

	      "test/testutilities.tcl"

	      "test/*.test"
		     These  files  are	a  standard  testsuite	based on Tcl's
		     tcltest package, with  some  utility  code	 snarfed  from
		     Tcllib.

		     This currently tests only some of the stubs::* packages.

	      "test/*.tcl"
		     These  files (but not "all.tcl", and "testutilities.tcl")
		     are example files (Tcl with embedded C) which can be  run
		     through critcl for	testing.

		     TODO: These should	be converted into a proper test	suite.

       Package Code, General structure

       Package Code, Per Package

	      critcl

		     "lib/critcl/critcl.tcl"
			    The	Tcl code implementing the package.

		     "lib/critcl/Config"
			    The	 configuration	file  for the standard targets
			    and	their settings.

		     "lib/critcl/critcl_c/"
			    Various C code snippets used by the	package.  This
			    directory  also  contains  the  copies  of the Tcl
			    header files used to compile the assembled C code,
			    for	 the major brnaches of Tcl, i.e. 8.4, 8.5, and
			    8.6.

	      critcl::util

		     "lib/critcl-util/util.tcl"
			    The	Tcl code implementing the package.

	      critcl::app

		     "lib/app-critcl/critcl.tcl"
			    The	Tcl code implementing the package.

	      critcl::iassoc

		     "lib/critcl-iassoc/iassoc.tcl"
			    The	Tcl code implementing the package.

		     "lib/critcl-iassoc/iassoc.h"
			    C code template used by the	package.

	      critcl::class

		     "lib/critcl-class/class.tcl"
			    The	Tcl code implementing the package.

		     "lib/critcl-class/class.h"
			    C code template used by the	package.

	      dict84

	      lassign84

		     "lib/util84/dict.tcl"

		     "lib/util84/lassign.tcl"
			    These are two packages implementing	 forward  com-
			    patibility emulations of the dict and lassign com-
			    mands introduced with Tcl 8.5.  These are used au-
			    tomatically	when critcl is run by Tcl 8.4.

	      stubs::*

		     "lib/stubs/*"
			    A set of non-public	(still)	packages which provide
			    read and write access to and represent  Tcl	 stubs
			    tables.  These  were  created  by taking the "gen-
			    Stubs.tcl" helper application coming with the  Tcl
			    core  sources  apart  along	 its  internal logical
			    lines.

	      critclf

		     "lib/critclf/"
			    Arjen Markus' work on a critcl/Fortran.  The  code
			    is	outdated  and  has  not	 been  adapted	to the
			    changes in critcl version 3	yet.

	      autoscroll

	      cmdline

	      md5

	      md5c

	      platform

	      snit

	      snitbutton

	      wikit  These are all external packages whose code	has  been  in-
		     lined  in the repository for easier development (less de-
		     pendencies	to pull),  and	quicker	 deployment  from  the
		     repository	(generation of starkit and -pack).

		     The  packages autoscroll, snit, snitbutton, and wikit are
		     for the support of	the Wikit GUI accessible from  starkit
		     and    -pack    when    the   application	 functionality
		     (critcl::app) is run with an empty	command	line.

		     TODO: These should	all be checked	against	 their	origin
		     for updates and changes since they	were inlined.

AUTHORS
       Jean Claude Wippler, Steve Landers, Andreas Kupries

BUGS, IDEAS, FEEDBACK
       This  document,	and the	package	it describes, will undoubtedly contain
       bugs and	other problems.	 Please	report them at	https://github.com/an-
       dreas-kupries/critcl/issues.   Ideas  for enhancements you may have for
       either package, application, and/or the	documentation  are  also  very
       welcome	 and  should  be  reported  at	https://github.com/andreas-ku-
       pries/critcl/issues as well.

KEYWORDS
       C code, Embedded	C Code,	code generator,	compile	& run,	compiler,  dy-
       namic  code  generation,	dynamic	compilation, generate package, linker,
       on demand compilation, on-the-fly compilation

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) Jean-Claude Wippler
       Copyright (c) Steve Landers
       Copyright (c) 2011-2018 Andreas Kupries

doc				   3.1.18.1		    critcl_devguide(n)

NAME | DESCRIPTION | PLAYING WITH CRITCL | DEVELOPING FOR CRITCL | AUTHORS | BUGS, IDEAS, FEEDBACK | KEYWORDS | CATEGORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=critcl_devguide&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help