2
'\" Generated from file '/home/aku/Projects/Packages/Critcl/dev-master/embedded/man/files/critcl_installer\&.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_install_guide" n 3\&.1\&.8 doc "C Runtime In Tcl (CriTcl)"
246
critcl_install_guide \- Critcl - The Installer's Guide
248
Welcome to the \fIC Runtime In Tcl\fR, \fICriTcl\fR for short, a
249
system to build C extension packages for Tcl on the fly, from C code
250
embedded within Tcl scripts, for all who wish to make their code go
253
The audience of this document is anyone wishing to build the
254
packages, for either themselves, or others\&.
256
For a developer intending to extend or modify the packages we
259
\fICritcl - License\fR\&.
261
\fICritcl - The Developer's Guide\fR\&.
264
Please read \fICritcl - How To Get The Sources\fR first, if that was
265
not done already\&. Here we assume that the sources are already
266
available in a directory of your choice\&.
269
Before Critcl can be build and used a number of requisites must be installed\&. These are:
271
The scripting language Tcl\&.
272
For details see \fBTcl\fR\&.
274
Various packages from the Tcllib bundle for \fBTcl\fR\&.
275
For details see \fBTcllib\fR\&.
277
This list assumes that the machine where Critcl is to be installed is
278
essentially clean\&. Of course, if parts of the dependencies listed
279
below are already installed the associated steps can be skipped\&. It is
280
still recommended to read their sections though, to validate that the
281
dependencies they talk about are indeed installed\&.
283
As we are building a Tcl package that should be pretty much obvious
284
that a working Tcl installation is needed, and I will not belabor the
287
Out of the many use whatever you are comfortable with, as long
288
as it provides Tcl 8\&.5, or higher, and Tk 8\&.5 or higher\&.
290
This may a Tcl installation provided by your operating system
291
distribution, from a distribution-independent vendor, or built by
294
Myself, I used \fIActiveState's\fR [http://www\&.activestate\&.com]
295
ActiveTcl 8\&.5 distribution during development of the binding, as I am
296
most familiar with it\&.
298
\fI(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining ActiveTcl and TclDevKit for them)\&.\fR
300
This distribution can be found at
301
\fIhttp://www\&.activestate\&.com/activetcl\fR\&. Retrieve the archive of
302
ActiveTcl 8\&.5 for your platform and install it as directed by
305
Assuming that ActiveTcl got installed I usually run the command
312
to install all packages ActiveState provides, and the kitchensink, as
313
the distribution itself usually contains only the ost important set of
314
packages\&. This ensures that the dependencies for Critcl are all
317
If that is not to your liking you have to read the sections for
318
Critcl to determine the exact set of packages required, and install
323
teacup install $packagename
327
Both \fBteacup\fR commands above assume that ActiveState's
328
TEApot repository at \fIhttp://teapot\&.activestate\&.com\fR is in the
329
list of repositories accessible to \fBteacup\fR\&. This is automatically
330
ensured for the ActiveTcl distribution\&. Others may have to run
334
teacup archive add http://teapot\&.activestate\&.com
337
to make this happen\&.
339
For those wishing to build Tcl/Tk on their own, their sources
343
\fIhttp://core\&.tcl\&.tk/tcl/\fR
346
\fIhttp://core\&.tcl\&.tk/tk/\fR
349
To use Critcl a few packages found in the Tcllib bundle are
350
required\&. These packages are:
356
And to accelerate this package, it is recommend to get and
367
The system will work without them, but can become quite slow,
368
especially when handling large code blocks\&.
373
Assuming that ActiveTcl is installed, or some other Tcl
374
installation with \fBteacup\fR available, most (not md5c) of these
375
packages can be installed via
379
teacup install $packagename
383
The \fBteacup\fR command above assumes that ActiveState's
384
TEApot repository at \fIhttp://teapot\&.activestate\&.com\fR is in the
385
list of repositories accessible to \fBteacup\fR\&. This is automatically
386
ensured for the ActiveTcl distribution\&. Others may have to run
390
teacup archive add http://teapot\&.activestate\&.com
393
to make this happen\&.
395
Now, for those wishing to install the packages from source,
396
the CVS repository for the two bundles can be found at
397
\fIhttps://sourceforge\&.net/projects/tcllib\fR\&.
399
Releases of Tcllib can be found in the associated Files
400
section, or CVS can be used to check out the sub-project tcllib\&.
402
Tcllib comes with its own installation instructions\&. These will
403
not be repeated here\&. If there are problems with its directions please
404
file a bug against the Tcllib project at the above url, and not
406
.SH "BUILD & INSTALLATION"
407
To install Critcl simply run
411
/path/to/tclsh /path/to/critcl/build\&.tcl install
414
where "\fI/path/to/tclsh\fR" is the tclsh of your Tcl installation, and
415
"\fI/path/to/critcl\fR" the location of the Critcl sources on your system\&.
417
This builds all packages and then places them in a directory where the
418
\fBtclsh\fR will find them\&.
420
It further creates a "\fIcritcl\fR" application script and places it
421
into the directory \fBtclsh\fR resides in, making it a sibling of that
422
executable\&. The critcl application is written to use that executable
423
as well, and not search for it in the \fBPATH\fR\&.
425
On Windows you can invoke the file "\fIbuild\&.tcl\fR" with a
426
double-click\&. This will pop up a small graphical interface for
427
entering the destination and performing the installation\&. This
428
handling of a double-click is restricted to Windows only however\&.
430
On unix the same GUI is acessible by invoking "\fIbuild\&.tcl\fR" without
433
To get help about the methods of "\fIbuild\&.tcl\fR", and their complete
434
syntax, invoke "\fIbuild\&.tcl\fR" with argument \fBhelp\fR, i\&.e\&., like
438
/path/to/tclsh /path/to/critcl/build\&.tcl help
441
.SH "FIRST USE, TESTING THE INSTALLATION"
442
With critcl installed it is now the time to try at least one of the
443
examples distributed with it\&. This will also test if the installation
446
Below I show the steps to generate and then use the low- and
447
high-level stack example packages\&. I am intentionally bypassing the
448
"\fIbuild\&.tcl\fR" file the example is coming with, to show the use of
449
\fBcritcl\fR itself\&.
456
> /path/to/critcl -keep -cache B -pkg cstack\&.tcl
457
> /path/to/critcl -keep -cache B -pkg stackc\&.tcl
459
% lappend auto_path [pwd]/lib
460
% package require stackc
461
% join [info loaded] \\n
473
The example shows only the commands entered on the shell (and
474
tclsh) command line\&. Their responses are left out\&.
476
Use of option \fB-keep\fR causes critcl to leave the
477
generated \&.c files behind, for edification\&. Normally this
478
happens only in case of trouble\&.
480
Use of option \fB-cache\fR redirects the location of the
481
directory to hold generated and build files to a local
482
directory with a known name, for an easy look after\&.
484
Both \fBcstack\fR and \fBstackc\fR have to use the
485
\fIsame\fR \fB-cache\fR so that \fBstackc\fR will
486
find the stub table headers exported by \fBcstack\fR\&.
489
Jean Claude Wippler, Steve Landers, Andreas Kupries
490
.SH "BUGS, IDEAS, FEEDBACK"
491
This document, and the package it describes, will undoubtedly contain
492
bugs and other problems\&.
493
Please report them at \fIhttps://github\&.com/andreas-kupries/critcl/issues\fR\&.
494
Ideas for enhancements you may have for either package, application,
495
and/or the documentation are also very welcome and should be reported
496
at \fIhttps://github\&.com/andreas-kupries/critcl/issues\fR as well\&.
498
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
500
Glueing/Embedded C code
503
Copyright (c) Jean-Claude Wippler
504
Copyright (c) Steve Landers
505
Copyright (c) 2011-2013 Andreas Kupries
b'\\ No newline at end of file'
added
removed
embedded/man/files/critcl_installer.n
