-
Notifications
You must be signed in to change notification settings - Fork 11
/
INSTALL
173 lines (141 loc) · 7.83 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
2 Installation
**************
First of all, see Clon's homepage for tarballs, Git repository and
online documentation. Clon is an ASDF 3 library. If you download a
Clon tarball, or clone the repository, you need to unpack somewhere in
the ASDF source registry. Otherwise, Clon is also available via
Quicklisp. *Note Supported Platforms::, for more information on
portability and dependencies.
Clon's main system is called ‘net.didierverna.clon’. Depending on
your installation, you may thus either ‘asdf:load-system’, or
‘ql:quickload’ it in your Lisp image. If you encounter grovel or ffi
related problems, you may need to set the ‘CC’ environment variable to a
working compiler before loading.
Alternatively, if you just want to use the core library without all
the platform-dependent bells and whistles (*note Non-ANSI Features::),
you may also just load the ‘net.didierverna.clon.core’ system.
In addition to the library itself, the Clon distribution offers
documentation in the form of 3 different manuals, some data files like
sample themes (*note (clon-enduser)Theme Creation::), and a couple of
demonstration programs. If you want to benefit from all these wonders,
some bits of manual installation are needed. After unpacking, please
perform the following steps, in order.
1. Edit ‘make/config.make’ to your specific needs.
2. Type ‘make’ to compile the documentation (end-user manual, user
manual and reference manual). By default, the documentation is
built in Info, PDF, and HTML formats. If you want other formats
(DVI and PostScript are available), type ‘make all-formats’. You
can also type individually ‘make dvi’ and/or ‘make ps’ in order to
get the corresponding format.
3. Type ‘make install’ to install both the documentation and the data
files. If you have compiled the documentation in DVI and
PostScript format, those will be installed as well.
The reference manual's Texinfo source is included in the distribution
(and in the repository), although it is generated automatically by
Declt. Before compiling, it is possible to regenerate a local version
of it with hyperlinks to your installation by typing ‘make localref’.
For this to work, you need SBCL and Declt though. If you ever need to
regenerate the regular version, you can also type ‘make generate’.
Type ‘make uninstall’ to uninstall the library.
Finally, if you want to play with the demo programs, ‘cd’ to the
‘demo/’ directory, and type either ‘make asdf-dump’ or ‘make clon-dump’.
These are two different methods for producing standalone executables,
via ASDF or via Clon itself. *Note Dumping Executables:: for more
information. ‘make install’ does not do anything with the demo
programs.
8.1 Configuration
=================
Some aspects of Clon's behavior can be configured _before_ the library
is actually loaded. Clon stores its user-level configuration (along
with some other setup parameters) in another ASDF system called
‘net.didierverna.clon.setup’ (and the eponym package). In order to
configure the library (I repeat, prior to loading it), you will
typically do something like this:
(require "asdf")
(asdf:load-system :net.didierverna.clon.setup)
(net.didierverna.clon.setup:configure <option> <value>)
-- Function: configure KEY VALUE
Set KEY to VALUE in the current Clon configuration.
Out of curiosity, you can also inquire the current configuration for
specific options with the following function.
-- Function: configuration KEY
Return KEY's value in the current Clon configuration.
Currently, the following options are provided.
:swank-eval-in-emacs
This option is only useful if you use Slime, and mostly if you plan
on hacking Clon itself. The library provides indentation
information for some of its functions directly embedded in the
code. This information can be automatically transmitted to Emacs
when the ASDF system is loaded if you set this option to ‘t’.
However, note that for this to work, the Slime variable
‘slime-enable-evaluate-in-emacs’ must also be set to ‘t’ in your
Emacs session. If you're interested to know how this process
works, I have described it in this blog entry
(http://www.didierverna.net/blog/index.php?post/2011/07/20/One-more-indentation-hack).
:restricted
Some non-ANSI features of Clon require external functionality that
may not be available in all contexts. Normally, Clon should
autodetect this and switch to so-called _restricted mode_ at
build-time (*note Non-ANSI Features::). If Clon has failed to
autodetect the problem (in which case I would like to know), or if
for some reason, you explicitly want to disable those features, you
may set the ‘:restricted’ configuration option to ‘t’. Another way
to do it, without even bothering with configuration is to just use
the ‘net.didierverna.clon.core’ system instead of the regular one.
:dump
This option is only used by the ABCL port. *note Dumping
Executables::, provides more information on its use.
8.2 Non-ANSI Features
=====================
One feature of Clon that is beyond the ANSI standard is terminal
autodetection (it requires an ‘ioctl’ call and hence a foreign function
interface). Terminal autodetection is used in several situations, for
turning on highlighting automatically and for detecting a terminal line
width.
If, for some reason, terminal autodetection is not available, Clon
will work in so-called _restricted mode_. This means that
‘--clon-highlight=auto’ won't work (highlighting will _not_ be turned on
automatically on a tty). For the same reason, unless otherwise
specified via either the ‘COLUMNS’ environment variable or the
‘--clon-line-width’ option, terminal output will be formatted for 80
columns regardless of the actual terminal width (*note
(clon-enduser)Global Control::).
Appendix A Supported Platforms
******************************
Clon is an ASDF 3 library. It currently works on Unix (including MacOS
X) and Windows (Cygwin or MinGW) and has been ported to 8 Common Lisp
implementations. It requires ‘editor-hints.named-readtables’. The
following table lists the supported platforms and some additional,
platform-dependent dependencies.
Compiler Minimum Version Dependencies
-------------------------------------------------
SBCL 1.0.56
CMU-CL 20b
CCL
ECL 11.1.2(1)
CLISP ‘cffi’ (optional)
ABCL 1.1.0(2)
Allegro(3) ‘cffi’ (optional)
LispWorks ‘cffi’ (optional)
A.1 CLISP, Allegro and LispWorks specificities
==============================================
As mentioned in the above table, CLISP, Allegro and LispWorks dependency
on ‘cffi’ is optional. They need ‘cffi’ in order to implement terminal
autodetection only (note that many other implementations come with their
own foreign function interface). If ‘cffi’ cannot be found when the
ASDF system is loaded (or in the case of CLISP, if it has been compiled
without ‘ffi’ support), you get a big red blinking light and a warning
but that's all. Clon will still work, although in restricted mode.
A.2 ABCL specificities
======================
Clon's ABCL port currently has two limitations:
• It only works in restricted mode (*note Non-ANSI Features::).
• Since Java doesn't have a ‘putenv’ or ‘setenv’ function (!!), the
‘modify-environment’ restart, normally proposed when an environment
variable is set to a bogus value, is unavailable (*note
(clon-enduser)Error Management::).
---------- Footnotes ----------
(1) more precisely, git revision
3e2e5f9dc3c5176ef6ef8d7794bfa43f1af8f8db
(2) more precisely, svn trunk revision 140640
(3) both standard and modern images are supported