INSTALL

   1
   2 2 Installation
   3 **************
   4
   5 Clon currently works on Unix platforms (MacOS X included) with SBCL,
   6 CMUCL, CCL, ECL, CLISP and ABCL. Clon is provided as an ASDF 2 system,
   7 but has no mandatory dependency. CFFI may optionally be used with
   8 CLISP. *Note Supported Platforms::, for more information.
   9
  10    In addition to the library itself, the Clon distribution offers
  11 documentation in the form of 3 different manuals, some data files that
  12 are needed for it to work properly, and a couple of demonstration
  13 programs. Because of that, some bits of manual installation are needed.
  14
  15    After unpacking somewhere in the ASDF 2 source registry, please
  16 perform the following steps, in order.
  17
  18   1. Edit `Makefile.cnf' to your specific needs.
  19
  20   2. Type `make' to compile the documentation and the demo programs
  21      (end-user manual, user manual and possibly reference manual). By
  22      default, the documentation is built in info, PDF and HTML formats.
  23      If you want other formats (DVI and PostScript are available), type
  24      `make all-formats'. You can also type individually `make dvi'
  25      and/or `make ps' in order to get the corresponding format.
  26
  27   3. As documented in `Makefile.cnf', the reference manual is only
  28      generated if you have SBCL and the Declt library at hand (see
  29      `http://www.lrde.epita.fr/~didier/software/lisp/misc.php#declt').
  30
  31   4. Type `make install' to install both the documentation and the data
  32      files. If you have compiled the documentation in DVI and PostScript
  33      format, those will be installed as well. The same goes for the
  34      reference manual. The demo programs are not installed anywhere.
  35
  36    Type `make uninstall' to uninstall the library.
  37
  38
  39 A.1 Configuration
  40 =================
  41
  42 Some aspects of Clon's behavior can be configured _before_ the ASDF
  43 system is actually loaded. Clon looks for configuration options in a
  44 variable called `com.dvlsoft.clon.configuration' in the `cl-user'
  45 package. If set, this variable should contain a property list of
  46 configuration options and their corresponding values. Currently, the
  47 following options are provided.
  48
  49 :swank-eval-in-emacs
  50      This option is only useful if you use Slime, and mostly if you
  51      plan on hacking Clon itself. The library provides indentation
  52      information for some of its functions directly embedded in the
  53      code. This information can be automatically transmitted to
  54      (X)Emacs when the ASDF system is loaded if you set this option to
  55      `t'. However, note that for this to work, the Slime variable
  56      `slime-enable-evaluate-in-emacs' must also be set to `t' in your
  57      (X)Emacs session. If you're interested to know how this process
  58      works, I have described it in the following blog entry:
  59      `http://www.didierverna.com/sciblog/index.php?post/2011/07/20/One-more-indentation-hack'.
  60
  61 :dump
  62      This option is only used by the ABCL port. *note Dumping
  63      Executables::, provides more information on its use.
  64
  65
  66 A.2 Non-ANSI Features
  67 =====================
  68
  69 One feature of Clon that is beyond the ANSI standard is terminal
  70 autodetection (it requires an `ioctl' call and hence a foreign function
  71 interface). Terminal autodetection is used in several situations, for
  72 turning on highlighting automatically and for detecting a terminal line
  73 width.
  74
  75    If, for some reason, terminal autodetection is not available, Clon
  76 will work in so-called _restricted mode_. This means that
  77 `--clon-highlight=auto' won't work (highlighting will _not_ be turned
  78 on automatically on a tty). For the same reason, unless otherwise
  79 specified via either the `COLUMNS' environment variable or the
  80 `--clon-line-width' option, terminal output will be formatted for 80
  81 columns regardless of the actual terminal width (*note Global Control:
  82 (clon-enduser)Global Control.  ).
  83
  84
  85 A.3 Supported Platforms
  86 =======================
  87
  88 Clon currently works on Unix systems (including MacOS X) and has been
  89 ported to 6 Common Lisp implementations. I have no idea about Windows
  90 right now. The following table lists the supported platforms.
  91
  92 Compiler   Minimum Version   Dependencies
  93 -------------------------------------------------
  94 SBCL
  95 CMU-CL     20b
  96 CCL
  97 ECL        11.1.2(1)
  98 CLISP                        `cffi' (optional)
  99 ABCL       0.24.0(2)
 100
 101 ABCL specificities
 102 ------------------
 103
 104 Clon's ABCL port currently has two limitations:
 105    * It only works in restricted mode (*note Non-ANSI Features::).
 106
 107    * Since Java doesn't have a `putenv' or `setenv' function (!!), the
 108      `modify-environment' restart, normally proposed when an
 109      environment variable is set to a bogus value, is unavailable
 110      (*note Error Management: (clon-enduser)Error Management.  ).
 111
 112 CLISP specificities
 113 -------------------
 114
 115 As mentioned in the above table, CLISP's dependency on `cffi' is
 116 optional. CLISP needs `cffi' in order to implement terminal
 117 autodetection only (note that many other implementations come with their
 118 own foreign function interface). If `cffi' cannot be found when the
 119 ASDF system is loaded, you get a big red blinking light and a warning
 120 but that's all. Clon will still work, although in restricted mode.
 121
 122    ---------- Footnotes ----------
 123
 124    (1) more precisely, git revision
 125 3e2e5f9dc3c5176ef6ef8d7794bfa43f1af8f8db
 126
 127    (2) more precisely, svn trunk revision 13156
 128