2
'\" Generated from file '/home/aku/Projects/Packages/Critcl/dev-master/embedded/man/files/critcl_introduction\&.n' by tcllib/doctools with format 'nroff'
3
'\" Copyright (c) Jean-Claude Wippler
4
'\" Copyright (c) Steve Landers
5
'\" Copyright (c) 2011-2013 Andreas Kupries
7
'\" The definitions below are for supplemental macros used in Tcl/Tk
10
'\" .AP type name in/out ?indent?
11
'\" Start paragraph describing an argument to a library procedure.
12
'\" type is type of argument (int, etc.), in/out is either "in", "out",
13
'\" or "in/out" to describe whether procedure reads or modifies arg,
14
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
15
'\" needed; use .AS below instead)
18
'\" Give maximum sizes of arguments for setting tab stops. Type and
19
'\" name are examples of largest possible arguments that will be passed
20
'\" to .AP later. If args are omitted, default tab stops are used.
23
'\" Start box enclosure. From here until next .BE, everything will be
24
'\" enclosed in one large box.
27
'\" End of box enclosure.
30
'\" Begin code excerpt.
35
'\" .VS ?version? ?br?
36
'\" Begin vertical sidebar, for use in marking newly-changed parts
37
'\" of man pages. The first argument is ignored and used for recording
38
'\" the version when the .VS was added, so that the sidebars can be
39
'\" found and removed when they reach a certain age. If another argument
40
'\" is present, then a line break is forced before starting the sidebar.
43
'\" End of vertical sidebar.
46
'\" Begin an indented unfilled display.
49
'\" End of indented unfilled display.
52
'\" Start of list of standard options for a Tk widget. The
53
'\" options follow on successive lines, in four columns separated
57
'\" End of list of standard options for a Tk widget.
59
'\" .OP cmdName dbName dbClass
60
'\" Start of description of a specific option. cmdName gives the
61
'\" option's name as specified in the class command, dbName gives
62
'\" the option's name in the option database, and dbClass gives
63
'\" the option's class in the option database.
66
'\" Print arg1 underlined, then print arg2 normally.
68
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
70
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
74
'\" # Start an argument description
78
. ie !"\\$2"" .TP \\n()Cu
83
\&\\$1 \\fI\\$2\\fP (\\$3)
96
'\" # define tabbing values for .AP
99
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
102
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
103
.nr )C \\n()Bu+\\w'(in/out)'u+2n
105
.AS Tcl_Interp Tcl_CreateInterp in/out
106
'\" # BS - start boxed text
107
'\" # ^y = starting y location
115
.if n \l'\\n(.lu\(ul'
118
'\" # BE - end boxed text (draw box now)
123
.ie n \l'\\n(^lu\(ul'
125
.\" Draw four-sided box normally, but don't draw top of
126
.\" box if the box started on an earlier page.
128
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
131
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138
'\" # VS - start vertical sidebar
139
'\" # ^Y = starting y location
140
'\" # ^v = 1 (for troff; for nroff this doesn't matter)
144
.ie n 'mc \s12\(br\s0
147
'\" # VE - end of vertical sidebar
155
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
162
'\" # Special macro to handle page bottom: finish off current
163
'\" # box/sidebar if in box/sidebar mode, then invoked standard
164
'\" # page bottom macro.
171
.\" Draw three-sided box if this is the box's first page,
172
.\" draw two sides but no top otherwise.
173
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
174
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
177
.nr ^x \\n(^tu+1v-\\n(^Yu
178
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
191
'\" # DS - begin display
197
'\" # DE - end display
203
'\" # SO - start of list of standard options
205
.SH "STANDARD OPTIONS"
211
'\" # SE - end of list of standard options
216
See the \\fBoptions\\fR manual entry for details on the standard options.
218
'\" # OP - start of full description for a single option
223
Command-Line Name: \\fB\\$1\\fR
224
Database Name: \\fB\\$2\\fR
225
Database Class: \\fB\\$3\\fR
229
'\" # CS - begin code excerpt
235
'\" # CE - end code excerpt
243
.TH "critcl_introduction" n 3\&.1\&.8 doc "C Runtime In Tcl (CriTcl)"
246
critcl_introduction \- Introduction To CriTcl
249
Welcome to the \fIC Runtime In Tcl\fR, \fICriTcl\fR for short, a
250
system to build C extension packages for Tcl on the fly, from C code
251
embedded within Tcl scripts, for all who wish to make their code go
254
CriTcl started life as an experiment by Jean-Claude Wippler and was a
255
self-contained Tcl package to build C code into a Tcl/Tk extension on
256
the fly\&. It was somewhat inspired by Brian Ingerson's \fIInline\fR
257
for \fIPerl\fR, but is considerably more lightweight\&.
259
It is for the last 5% to 10% when pure Tcl, which does go a long way,
260
is not sufficient anymore\&. I\&.e\&. for
262
when the last bits of performance are needed,
264
access to 3rd party libraries,
266
hiding critical pieces of your library or application, and
268
simply needing features provided only by C\&.
271
The following sections first reference a few related documents
272
which may or may not be of interest to you, depending on if you are
273
just a plain user of the system, trying to get and build/install it,
274
or are going deep into the internals for either edification or
277
This is followed by an introduction to the modes of operation
278
supported by the system, and its general architecture as seen by a
280
.SH "RELATED DOCUMENTS"
282
\fICritcl - License\fR\&.
286
\fICritcl - How To Get The Sources\fR\&.
288
\fICritcl - The Installer's Guide\fR\&.
290
\fICritcl - Application Package Reference\fR
292
\fICritcl - Package Reference\fR
294
\fICritcl - The Developer's Guide\fR\&.
296
.SH "MODES OF OPERATION/USE"
297
CriTcl can be used in three different modes of operation, called
299
\fICompile & Run\fR, and
301
\fIGenerate Package\fR
303
\fIGenerate TEA Package\fR
305
Of these three \fICompile & Run\fR came first and is the default
306
when using the package directly\&. In that case the package collects the
307
C fragments, builds them as needed, and caches the results for quick
308
reuse when the same code is used in the future again\&.
310
The second mode, \fIGenerate Package\fR, was introduced to enable
311
the creation of (prebuilt) deliverable packages which do not depend on
312
the existence of a build system, i\&.e\&. C compiler, on the target
314
This was originally done through the experimental \fBCritbind\fR tool,
315
and is now handled by the \fICriTcl Application\fR, also named
318
Newly introduced with Critcl version 3 is
319
\fIGenerate TEA Package\fR\&. This mode constructs a directory
320
hierarchy from the package which can later be built like a regular TEA
321
package, i\&.e\&. using
325
\&.\&.\&./configure --prefix \&.\&.\&.
329
.SH "SYSTEM ARCHITECTURE"
330
The system consists of two main layers, as seen in the figure below,
331
plus a support layer containing general packages the system uses during
359
At the top we have an application built on top of the core packages,
360
providing command line access to the second and third usage modes,
361
i\&.e\&. \fIGenerate Package\fR and \fIGenerate TEA Package\fR\&.
369
Below that is the core package providing the essential functionality
370
of the system, plus various utility packages which make common tasks
379
Lastly a layer of supporting packages, mostly external to critcl\&.
383
For this pure-Tcl package to be fast users should get one of several
384
possible accelerator packages:
398
\fBstubs::container\fR
406
\fBstubs::gen::init\fR
408
\fBstubs::gen::header\fR
410
\fBstubs::gen::decl\fR
412
\fBstubs::gen::macro\fR
414
\fBstubs::gen::slot\fR
416
\fBstubs::gen::lib\fR
421
The sources of Critcl, should you have gotten them, contain
422
several larger examples show-casing various aspects of the
423
system\&. These demonstration packages can all be found in the
424
sub-directory "\fIexamples/\fR" of the sources\&.
426
Lots of smaller examples can be found in the document
427
\fIUsing CriTcl\fR, an introduction to Critcl by way of a of
428
examples\&. These focus more on specific critcl commands than the
429
overall picture shown by the large examples mentioned in the previous
431
.SH "CHANGES FOR VERSION 2\&.1"
433
Fixed bug where \fBcritcl::tsources\fR interpreted relative
434
paths as relative to the current working directory instead of
435
relative to the "\fI\&.critcl\fR" file using the command, as all other
436
commands of this type do\&.
438
Fixed internals, preventing information collected for multiple
439
"\fI\&.critcl\fR" files to leak between them\&. Notably, \fBcritcl::tk\fR
440
is not a global configuration option anymore\&.
442
Fixed the command \fBcritcl::license\fR to be a null-operation
443
in mode "compile & run", instead of throwing an error\&.
445
Fixed the critcl application's interference with the "compile &
446
run" result cache in \fB-pkg\fR mode by having it use a wholly
447
separate (and by default transient) directory for that mode\&.
449
Fixed bug where changes to a "\fI\&.critcl\fR" file did not result
450
in a rebuild for mode "compile & run"\&. All relevant API commands now
451
ensure UUID changes\&.
453
Fixed bug in the backend handling of \fBcritcl::debug\fR where
454
the companion c-sources of a "\fI\&.critcl\fR" file were not compiled
455
with debug options, although the "\fI\&.critcl\fR" file was\&.
457
Fixed bug in \fBcritcl::debug\fR which prevented recognition of
458
mode "all" when it was not the first argument to the command\&.
460
Fixed bug in "\fIpreload\&.c\fR" preventing its compilation on
461
non-windows platforms\&.
463
Fixed long-standing bug in the handling of namespace qualifiers
464
in the command name argument of \fBcritcl::cproc\fR and
465
\fBcritcl::ccommand\fR\&. It is now possible to specify a fully
466
qualified command name without issues\&.
468
Extended/reworked \fBcritcl::tsources\fR to be the canonical
469
way of declaring "\fI\&.tcl\fR" companion files even for mode "compile &
472
Extended/reworked \fBcritcl::tsources\fR to allow the use of a
473
"\fI\&.critcl\fR" file as its own Tcl companion file\&.
475
Extended \fBcritcl::framework\fR to internally check for OS X
476
build target, and to ignore the declaration if its not\&.
478
Extended \fBcritcl::failed\fR to be callable more than once in
479
a "\fI\&.critcl\fR" file\&. The first call forces the build, if it was not
480
done already, to get the result\&. Further calls return the cached
481
result of the first call\&.
483
Extended the handling of environment variable CC in the code
484
determining the compiler to use to deal with (i\&.e\&. remove) paths to
485
the compiler, compiler file extensions, and compiler options specified
486
after the compiler itself, leaving only the bare name of the compiler\&.
488
Extended the code handling the search for preloaded libraries
489
to print the paths it searched, making debugging of a search failure
492
A new command \fBcritcl::tcl\fR can be used to declare the
493
version of Tcl minimally needed to build and run the "\fI\&.critcl\fR"
494
file and package\&. Defaults to 8\&.4 if not declared\&. Extended critcl to
495
have the stubs and headers for all of Tcl 8\&.4, 8\&.5, and 8\&.6\&.
497
A new command \fBcritcl::load\fR forces the build and load of a
498
"\fI\&.critcl\fR" file\&. This is the official way for overriding critcl's
499
default lazy-build-&-load-on-demand scheme for mode "compile & run"\&.
501
\fINote\fR that after using \fBcritcl::load\fR /
502
\fBcritcl::failed\fR in a "\fI\&.critcl\fR" file it is not possible to
503
use critcl commands in that file anymore\&. Doing so will throw an
506
Extended the generation of '#line' pragmas to use
507
\fBinfo frame\fR (if available) to provide the C compiler with exact
508
line numbers into the "\fI\&.critcl\fR" file for the reporting of
509
warnings and errors\&.
511
Extended \fBcritcl::check\fR with logging to help with
512
debugging build-time checks of the environment, plus an additional
513
optional argument to provide labeling\&.
515
Added a new command \fBcritcl::checklink\fR which not only
516
tries to check the environment via compiling the code, but also
519
Added a new command \fBcritcl::msg\fR for messaging, like
520
command \fBcritcl::error\fR is for error reporting\&. Likewise this is a
521
hook a user of the package is allowed to override\&. The default
522
implementation, used by mode \fIcompile & run\fR does nothing\&. The
523
implementation for mode \fIgenerate package\fR prints the message
526
Envisioned use is for the reporting of results determined by
527
\fBcritcl::check\fR and \fBcritcl::checklink\fR during building, to
528
help with debugging when something goes wrong with a check\&.
530
Exposed the argument processing internals of \fBcritcl::proc\fR
531
for use by advanced users\&. The new commands are
534
\fBcritcl::argnames\fR
536
\fBcritcl::argcnames\fR
538
\fBcritcl::argcsignature\fR
540
\fBcritcl::argvardecls\fR
542
\fBcritcl::argconversion\fR
545
Please see section \fIAdvanced Embedded C Code\fR of the
546
\fBcritcl\fR package documentation for details\&.
548
Extended the critcl package to intercept \fBpackage
549
provide\fR and record the file -> package name mapping\&. Plus other
550
internal changes now allow the use of namespaced package names while
551
still using proper path names and init function\&.
553
Dropped the unused commands \fBcritcl::optimize\fR and
554
\fBcritcl::include\fR\&.
556
Dropped \fB-lib\fR mode from the critcl application\&.
558
Dropped remnants of support for Tcl 8\&.3 and before\&.
560
.SH "CHANGES FOR VERSION 3"
562
The command \fBcritcl::platform\fR was deprecated in version
563
2\&.1, superceded by \fBcritcl::targetplatform\fR, yet kept for
564
compatibility\&. Now it has been removed\&.
566
The command \fBcritcl::compiled\fR was kept with in version 2\&.1
567
with semantics in contradiction to its, for compatibility\&. This
568
contradiction has been removed, changing the visible semantics of the
569
command to be in line with its name\&.
571
The change to version 3 became necessary because of the two
572
incompatible visible changes above\&.
574
Extended the application package with code handling a new
575
option \fB-tea\fR\&. Specifying this option invokes a special mode
576
where critcl generates a TEA package, i\&.e\&. wraps the input into a
577
directory hierarchy and support files which provide it TEA-lookalike
580
This new option, and \fB-pkg\fR, exclude each other\&. If
581
both are specified the last used option takes precedence\&.
583
The generated package directory hierarchy is mostly
584
self-contained, but not fully\&. It requires not only a working
585
installation of Tcl, but also working installations of the packages
586
\fBmd5\fR and \fBcmdline\fR\&. Both of these are provided by the
587
\fBTcllib\fR bundle\&. Not required, but recommended to have
588
installed are any of the packages which can accelerate md5's
589
operation, i\&.e\&. \fBcryptkit\fR, \fBtcllibc\fR, or
592
Extended the critcl package with a new command
593
\fBcritcl::scan\fR taking the path to a "\fI\&.critcl\fR" file,
594
statically scanning it, and returning license, version, a list of its
595
companion files, list of imported APIs, and list of
596
developer-specified custom configuration options\&. This data is the
597
foundation for the TEA wrapping described above\&.
599
Note that this is a \fIstatic\fR scan\&. While the other build
600
modes can (must) execute the "\fI\&.critcl\fR" file and make
601
platform-specific decisions regarding the assembled C code, companion
602
files, etc\&. the TEA wrap mode is not in a position to make
603
platform-specific decisions\&. It has to wrap everything which might
604
conceivably be needed when actually building\&. Hence the static scan\&.
605
This has however its own set of problems, namely the inability to
606
figure out any dynamic construction of companion file paths, at least
609
Extended the API used by critcl-based packages with the command
610
\fBcritcl::owns\fR\&. While this command is ignored by the regular build
611
modes the static scanner described above takes its arguments as the
612
names of companion files which have to be wrapped into the TEA package
613
and could not be figured by the scanner otherwise, like because of
614
dynamic paths to \fBcritcl::tsources\fR, \fBcritcl::csources\fR,
615
getting sourced directly, or simply being adjunct datafiles\&.
617
Extended the API used by critcl-based packages with the command
618
\fBcritcl::api\fR for the management of stubs tables, be it their use,
619
and/or declaration and export\&.
621
Please see section \fIStubs Table Management\fR of the
622
\fBcritcl\fR package documentation for details\&.
624
Extended the API used by critcl-based packages with the command
625
\fBcritcl::userconfig\fR for the management of developer-specified
626
custom configuration options, be it their use and/or declaration\&.
628
Please see section \fICustom Build Configuration\fR of the
629
\fBcritcl\fR package documentation for details\&.
631
Extended the API used by critcl-based packages with the
632
commands \fBcritcl::description\fR, \fBcritcl::summary\fR,
633
\fBcritcl::subject\fR, \fBcritcl::meta\fR, and
634
\fBcritcl::buildrequirement\fR for the declaration of TEApot meta data
635
for/about the package\&.
637
Please see section \fIPackage Meta Data\fR of the
638
\fBcritcl\fR package documentation for details\&.
640
.SH "CHANGES FOR VERSION 3\&.0\&.1"
642
Bugfixes all around\&. In detail:
644
Fixed recording of Tcl version requirements\&. Keep package name
645
and version together, unbreaking generated meta data and generated
646
package load command\&.
648
Fixed the build scripts: When installing, or wrapping for TEA,
649
generate any missing directories
651
Modified the build scripts to properly exit the application
652
when the window of their GUI is closed through the (X) button\&.
654
Removed an 8\&.5-ism (open wb) which had slipped into the main
657
Modified the example build scripts to separate the output for
658
the different examples (and packages) by adding empty lines\&.
660
stack::c example bugfix: Include API declarations for use in
661
the companion files\&.
663
Extended the documentation: Noted the need for a working
664
installation of a C compiler\&.
666
Extended the Windows target definitions and code to handle the
667
manifest files used by modern MS development environments\&. Note that
668
this code handles both possibilities, environment using manifests, and
669
(old(er)) environments without\&.
671
Extended the Windows 64bit target definitions and code to
672
auto-detect the need for the helper library "bufferoverflowU\&.lib" and
673
reconfigure the compile and link commands appropriately\&. We assume
674
that the library must be linked when present\&. This should be no harm
675
if the library is present, yet not needed\&. Just superfluous\&. We search
676
for the library in the paths specified by the environment variable
679
.SH "CHANGES FOR VERSION 3\&.0\&.2"
681
Fixed issue in compile-and-run mode where commands put into the
682
auto_index are not found by Tcl's [unknown] command\&.
684
Fixed an array key mismatch breaking usage of client data and
685
delete function for procedure\&. Reported by Jos DeCoster, with patch\&.
687
Implemented a command line option \fB-L\fR, an equivalent of
688
option \fB-I\fR, just for library search paths\&.
690
Fixed github issues 5 and 8\&. Working around a missing variable
691
::errorInfo\&. It should always be present, however there seem to be
692
revisions of Tcl around which violate this assumption\&.
694
.SH "CHANGES FOR VERSION 3\&.0\&.3"
696
Fixed github issues 5 and 8, for the example build\&.tcl
697
scripts\&. Working around a missing variable ::errorInfo\&. It should
698
always be present, however there seem to be revisions of Tcl around
699
which violate this assumption\&.
701
.SH "CHANGES FOR VERSION 3\&.0\&.4"
703
Fixed generation of the package's initname when the incoming
704
code is read from stdin and has no proper path\&.
706
Fixed github issue 11\&. Now using /LIBPATH instead of -L
707
on Windows (libinclude configuration setting)\&.
709
Extended critcl to handle -l:path format of -l options\&.
710
GNU ld 2\&.22+ handles this by searching for the path as
711
is\&. Good when specifying static libraries, as plain -l looks
712
for shared libraries in preference over static\&. critcl handles
713
it now, as older GNU ld's do not understand it, nor the
714
various vendor-specific linkers\&.
716
Fixed github issue #12\&. Critcl now determines the version of
717
MSVC in use and uses it to switch between various link debug
718
options\&. Simplified the handling of bufferoverflowU\&.lib also,
719
making use of the same mechanism and collapsing the two
720
configurations sections we had back into one\&.
722
Reworked the insertion of #line pragmas into the generated C
723
code to avoid limitations on the line number argument imposed
724
by various compilers, and be more accurate\&.
726
Modified argument processing\&. Option -libdir now also
727
implies -L for its argument\&.
729
Extended handling of option -show (\fBcritcl::showconfig\fR)
730
to list the path of the configuration file the data is coming
731
from\&. Good for debugging configuration processing\&.
733
Extended the build script with targets to regenerate the
734
embedded documentation, and diagrams, and to generate a
737
.SH "CHANGES FOR VERSION 3\&.0\&.5"
739
Fixed bug in the new code for #line pragmas triggered when
740
specifying C code without leading whitespace\&.
742
Extended the documentation to have manpages for the license,
743
source retrieval, installer, and developer's guides\&.
745
.SH "CHANGES FOR VERSION 3\&.0\&.6"
747
Fixed github issue 10\&. The critcl application now delivers a
748
proper exit code (1) on build failure, instead of always
749
indicating success (status 0)\&.
751
Fixed github issue 13\&. Handling of bufferoverflowU\&.lib for
752
release builds was inconsistent with handling for debug
753
builds\&. It is now identically handled (conditional) by
756
Documentation cleanup, mainly in the installation guide, and
757
the README\&.md shown by github
759
.SH "CHANGES FOR VERSION 3\&.0\&.7"
761
Fixed the code generated by \fBcritcl::c++command\fR\&.
762
The emitted code handed a non-static string table to
763
\fBTcl_GetIndexFromObj\fR, in violation of the contract, which
764
requires the table to have a fixed address\&. This was a memory
765
smash waiting to happen\&. Thanks to Brian Griffin for alrerting
766
us to the general problem\&.
768
.SH "CHANGES FOR VERSION 3\&.1"
770
Added a new higher-level package \fBcritcl::iassoc\fR\&.
772
This package simplifies the creation of code associating data
773
with an interpreter via Tcl's \fBTcl_(Get|Set)AssocData()\fR APIs\&. The
774
user can concentrate on his data while all the necessary boilerplate
775
C code to support this is generated by the package\&.
777
This package uses several of the new features which were added
778
to the core \fBcritcl\fR package, see below\&.
780
Added the higher-level package \fBcritcl::class\fR\&.
782
This package simplifies the creation of C level objects with
783
class and instance commands\&. The user can write a class definition
784
with class- and instance-variables and -methods similar to a TclOO
785
class, with all the necessary boilerplate C code to support this
786
generated by the package\&.
788
This package uses several of the new features which were added
789
to the core \fBcritcl\fR package, see below\&.
791
Extended the API for handling TEApot metadata\&. Added the
792
command \fBcritcl::meta?\fR to query the stored information\&. Main use
793
currently envisioned is retrieval of the current package's name by
794
utility commands, for use in constructed names\&. This particular
795
information is always available due to the static scan of the package
796
file on execution of the first critcl command\&.
798
The new packages \fBcritcl::iassoc\fR and
799
\fBcritcl::class\fR (see above) are users of this command\&.
801
Extended the API with a command, \fBcritcl::name2c\fR, exposing
802
the process of converting a Tcl name into base name, namespace, and C
803
namespace\&. This enables higher-level code generators to generate the same
804
type of C identifiers as \fBcritcl\fR itself\&.
806
The new package \fBcritcl::class\fR (see above) is a user
809
Extended the API with a command, \fBcritcl::source\fR,
810
executing critcl commands found in a separate file in the context of
811
the current file\&. This enables easier management of larger bodies of
812
code as it allows the user to split such up into easier to digest
813
smaller chunks without causing the generation of multiple packages\&.
815
Related to the previous item, extended the API with commands to
816
divert collection of generated C code into memory\&. This makes it
817
easier to use the commands for embedded C code in higher-level code
820
See the section \fBAdvanced: Diversions\fR for details of
821
the provided commands\&.
823
The new package \fBcritcl::class\fR (see above) is a user
824
of these facilities\&.
826
Extended the API with commands helping developers with the
827
generation of proper C \fI#line\fR directives\&. This allows
828
higher-level code generators to generate and insert their own
829
directives, ensuring that compile errors in their code are properly
832
See the section \fBAdvanced: Location management\fR for
833
details of the provided commands\&.
835
The new packages \fBcritcl::iassoc\fR and
836
\fBcritcl::class\fR (see above) are users of these facilities\&.
838
Extended the API with commands giving users the ability to
839
define custom argument and result types for \fB::critcl::cproc\fR\&.
841
See the section \fBAdvanced: Extending cproc\fR for
842
details of the provided commands\&.
844
.SH "CHANGES FOR VERSION 3\&.1\&.1"
846
Bugfixes all around\&. In detail:
848
Fixed the generation of wrong#args errors for
849
\fBcritcl::cproc\fR and derived code (\fBcritcl::class\fR
850
cproc-based methods)\&. Use NULL if there are no arguments, and
851
take the offset into account\&.
853
Fixed the handling of package names by
854
\fBcritcl::class\fR\&. Forgot that they may contain namespace
855
separators\&. Bumped to version 1\&.0\&.1\&.
857
Extended a \fBcritcl::class\fR generated error message in
858
instance creation for clarity\&. Bumped to version 1\&.0\&.2\&.
860
.SH "CHANGES FOR VERSION 3\&.1\&.2"
862
Enhancement\&. In detail:
864
Extended \fBcritcl::cproc\fR to be able to handle optional
865
arguments, in a limited way\&. This is automatically available to
866
\fBcritcl::class\fR cproc-based methods as well\&.
868
Bugfix in \fBlassign\fR emulation for Tcl 8\&.4\&. Properly set
869
unused variables to the empty string\&. Bumped version of
870
emulation package \fBlassign84\fR to 1\&.0\&.1\&.
872
.SH "CHANGES FOR VERSION 3\&.1\&.3"
874
Enhancement\&. In detail:
876
Added new argument type "pstring", for "Pascal String", a
877
counted string, i\&.e\&. a combination of string pointer and string
880
Added new methods \fBcritcl::argtypesupport\fR and
881
\fB::critcl::argsupport\fR to define and use additional
882
supporting code for an argument type, here used by "pstring"
883
above to define the necessary structure\&.
885
Semi-bugfixes in the packages \fBcritcl::class\fR and
886
\fBcritcl::iassoc\fR\&. Pragmas for the AS meta data scanner
887
to ensure that the template files are made part of the package\&.
888
Versions bumped to 1\&.0\&.4 and 1\&.0\&.1 respectively\&.
890
.SH "CHANGES FOR VERSION 3\&.1\&.4"
892
Bugfix in package \fBcritcl::class\fR\&. Generate a dummy
893
field in the class structure if the class has no class
894
variables\&. Without this change the structure would be empty,
895
and a number of compilers are not able to handle such a type\&.
897
Fixed a typo which broke the win64 configuration\&.
899
Fixed issue #16, a typo in the documentation of command
900
\fBcritcl::class\fR\&.
902
.SH "CHANGES FOR VERSION 3\&.1\&.5"
904
Fixed issue #19\&. Made the regular expression extracting the
905
MSVC version number more general to make it work on german
906
language systems\&. This may have to be revisited in the future,
907
for other Windows locales\&.
909
Fixed issue #20\&. Made option -tea work on windows, at least in
910
a unix emulation environment like msys/mingw\&.
912
.SH "CHANGES FOR VERSION 3\&.1\&.6"
914
Fixed issue #21\&. While the multi-definition of the stub-table
915
pointer variables was ok with for all the C linkers seen so far
916
C++ linkers did not like this at all\&. Reworked the code to
917
ensure that this set of variables is generated only once, in
918
the wrapper around all the pieces to assemble\&.
920
Fixed issue #22, the handling of the command identifier
921
arguments of \fBcritcl::ccommand\fR, \fBcritcl::cproc\fR, and
922
\fBcritcl::cdata\fR\&. We now properly allow any Tcl identifier
923
and generate proper internal C identifiers from them\&.
925
As part of this the signature of command \fBcritcl::name2c\fR
926
changed\&. The command now delivers a list of four values instead
927
of three\&. The new value was added at the end\&.
929
Further adapted the implementation of package
930
\fBcritcl::class\fR, a user of \fBcritcl::name2c\fR\&.
931
This package is now at version 1\&.0\&.6 and requires critcl 3\&.1\&.6
933
Lastly fixed the mis-handling of option \fB-cname\fR in
934
\fBcritcl::ccommand\fR, and \fBcritcl::cproc\fR\&.
938
.SH "CHANGES FOR VERSION 3\&.1\&.7"
940
Fixed issue #24\&. Extract and unconditionally display compiler
941
warnings found in the build log\&. Prevents users from missing
942
warnings which, while not causing the build to fail, may
943
still indicate problems\&.
945
New feature\&. Output hook\&. All non-messaging user output is now
946
routed through the command \fBcritcl::print\fR, and users are
947
allowed to override it when using the critcl application-as-package\&.
949
New feature, by Ashok P\&. Nadkarni\&. Platform configurations can
950
inherit values from configurations defined before them\&.
952
.SH "CHANGES FOR VERSION 3\&.1\&.8"
954
Fixed issue with package indices generated for Tcl 8\&.4\&.
955
Join the list of commands with semi-colon, not newline\&.
957
Fixed issue #26 which brought up use-cases I had forgotten to
958
consider while fixing bug #21 (see critcl 3\&.1\&.6)\&.
960
.SH "CHANGES FOR VERSION 3\&.1\&.9"
962
Fixed issue #27\&. Added missing platform definitions for
963
various alternate linux and OS X targets\&.
965
Fixed issue #28\&. Added missing -mXX flags for linking at the
966
linux-{32,64}-* targets\&.
968
Fixed issue #29\&. Replaced the use of raw "cheaders"
969
information in the processing of "cdefines" with the proper
970
include directives derived from it\&.
972
Fixed the issue behind rejected pull request #30 by Andrew
973
Shadura\&. Dynamically extract the stubs variable declarations
974
from the Tcl header files and generate matching variable
975
definitions for use in the package code\&. The generated code
976
will now be always consistent with the headers, even when
977
critcl's own copy of them is replaced by system headers\&.
979
Fixed issue #31\&. Accepted patch by Andrew Shadura, with
980
changes (comments), for easier integration of critcl with
981
OS package systems, replacing critcl's copies of Tcl headers
984
Fixed issue #32\&. Merged pull request by Andrew Shadura\&.
985
Various typos in documentation and comments\&.
987
Fixed issue #33\&. Handle files starting with a dot better\&.
990
Jean Claude Wippler, Steve Landers, Andreas Kupries
991
.SH "BUGS, IDEAS, FEEDBACK"
992
This document, and the package it describes, will undoubtedly contain
993
bugs and other problems\&.
994
Please report them at \fIhttps://github\&.com/andreas-kupries/critcl/issues\fR\&.
995
Ideas for enhancements you may have for either package, application,
996
and/or the documentation are also very welcome and should be reported
997
at \fIhttps://github\&.com/andreas-kupries/critcl/issues\fR as well\&.
999
C code, Embedded C Code, code generator, compile & run, compiler, dynamic code generation, dynamic compilation, generate package, linker, on demand compilation, on-the-fly compilation
1001
Glueing/Embedded C code
1004
Copyright (c) Jean-Claude Wippler
1005
Copyright (c) Steve Landers
1006
Copyright (c) 2011-2013 Andreas Kupries
b'\\ No newline at end of file'
added
removed
embedded/man/files/critcl_introduction.n
