← Back to branch summary

~ubuntu-branches/ubuntu/utopic/critcl/utopic

« back to all changes in this revision

Viewing changes to doc/critcl_installer.man

  • Committer: Package Import Robot
  • Author(s): Andrew Shadura
  • Date: 2013-05-11 00:08:06 UTC
  • Revision ID: package-import@ubuntu.com-20130511000806-7hq1zc3fnn0gat79
Tags: upstream-3.1.9
Import upstream version 3.1.9

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/critcl_installer.man
 
1
[comment {-*- tcl -*- doctools manpage}]
 
2
[include version.inc]
 
3
[manpage_begin critcl_install_guide n [vset VERSION]]
 
4
[include include/module.inc]
 
5
[titledesc {Critcl - The Installer's Guide}]
 
6
[description]
 
7
[include include/welcome.inc]
 
8
 
 
9
[para] The audience of this document is anyone wishing to build the
 
10
packages, for either themselves, or others.
 
11
 
 
12
[para] For a developer intending to extend or modify the packages we
 
13
additionally provide
 
14
 
 
15
[list_begin enum]
 
16
[enum] [term {Critcl - License}].
 
17
[enum] [term {Critcl - The Developer's Guide}].
 
18
[list_end]
 
19
 
 
20
[para]
 
21
 
 
22
Please read [term {Critcl - How To Get The Sources}] first, if that was
 
23
not done already. Here we assume that the sources are already
 
24
available in a directory of your choice.
 
25
 
 
26
[para]
 
27
 
 
28
[section Requisites]
 
29
 
 
30
Before Critcl can be build and used a number of requisites must be installed. These are:
 
31
 
 
32
[list_begin enumerated]
 
33
[enum] The scripting language Tcl.
 
34
       For details see [sectref Tcl].
 
35
[enum] Various packages from the Tcllib bundle for [syscmd Tcl].
 
36
       For details see [sectref Tcllib].
 
37
[list_end]
 
38
 
 
39
This list assumes that the machine where Critcl is to be installed is
 
40
essentially clean. Of course, if parts of the dependencies listed
 
41
below are already installed the associated steps can be skipped. It is
 
42
still recommended to read their sections though, to validate that the
 
43
dependencies they talk about are indeed installed.
 
44
 
 
45
[include include/rq_tcl.inc]
 
46
[include include/rq_tcllib.inc]
 
47
 
 
48
[section {Build & Installation}]
 
49
 
 
50
To install Critcl simply run
 
51
 
 
52
[example {
 
53
    /path/to/tclsh /path/to/critcl/build.tcl install
 
54
}]
 
55
 
 
56
where [file /path/to/tclsh] is the tclsh of your Tcl installation, and
 
57
[file /path/to/critcl] the location of the Critcl sources on your system.
 
58
 
 
59
[para]
 
60
 
 
61
This builds all packages and then places them in a directory where the
 
62
[cmd tclsh] will find them. 
 
63
 
 
64
[para]
 
65
 
 
66
It further creates a [file critcl] application script and places it
 
67
into the directory [cmd tclsh] resides in, making it a sibling of that
 
68
executable. The critcl application is written to use that executable
 
69
as well, and not search for it in the [var PATH].
 
70
 
 
71
[para]
 
72
 
 
73
On Windows you can invoke the file [file build.tcl] with a
 
74
double-click.  This will pop up a small graphical interface for
 
75
entering the destination and performing the installation. This
 
76
handling of a double-click is restricted to Windows only however.
 
77
 
 
78
[para]
 
79
 
 
80
On unix the same GUI is acessible by invoking [file build.tcl] without
 
81
any arguments.
 
82
 
 
83
[para]
 
84
 
 
85
To get help about the methods of [file build.tcl], and their complete
 
86
syntax, invoke  [file build.tcl] with argument [method help], i.e., like
 
87
 
 
88
[example {
 
89
    /path/to/tclsh /path/to/critcl/build.tcl help
 
90
}]
 
91
 
 
92
[section {First Use, Testing the Installation}]
 
93
 
 
94
With critcl installed it is now the time to try at least one of the
 
95
examples distributed with it. This will also test if the installation
 
96
was successful.
 
97
 
 
98
[para] Below I show the steps to generate and then use the low- and
 
99
high-level stack example packages. I am intentionally bypassing the
 
100
[file build.tcl] file the example is coming with, to show the use of
 
101
[cmd critcl] itself.
 
102
 
 
103
[para][example {
 
104
 
 
105
    > cd examples/stack
 
106
    > /path/to/critcl -keep -cache B -pkg cstack.tcl
 
107
    > /path/to/critcl -keep -cache B -pkg stackc.tcl
 
108
    > tclsh
 
109
    % lappend auto_path [pwd]/lib
 
110
    % package require stackc
 
111
    % join [info loaded] \n
 
112
    % stackc S
 
113
    % S push FOO
 
114
    % S size
 
115
    % S destroy
 
116
    % exit
 
117
    >
 
118
}]
 
119
 
 
120
[para] Some explanations:
 
121
[list_begin itemized]
 
122
[item]  The example shows only the commands entered on the shell (and
 
123
        tclsh) command line. Their responses are left out.
 
124
[item]  Use of option [option -keep] causes critcl to leave the
 
125
        generated .c files behind, for edification. Normally this
 
126
        happens only in case of trouble.
 
127
[item]  Use of option [option -cache] redirects the location of the
 
128
        directory to hold generated and build files to a local
 
129
        directory with a known name, for an easy look after.
 
130
[item]  Both [package cstack] and [package stackc] have to use the
 
131
        [emph same] [option -cache] so that [package stackc] will
 
132
        find the stub table headers exported by [package cstack].
 
133
[list_end]
 
134
 
 
135
[include include/feedback.inc]
 
136
[manpage_end]