INSTALL

   1
   2 2 Installation
   3 **************
   4
   5 Clon currently works on Unix (including MacOS X) and Windows (Cygwin or
   6 MinGW) with SBCL, CMUCL, CCL, ECL, CLISP and ABCL. Clon is provided as
   7 an ASDF 2 system, but has no mandatory dependency. CFFI may optionally
   8 be used with 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 :restricted
  62      Some non-ANSI features of Clon require external functionality that
  63      may not be available in all contexts. Normally, Clon should
  64      autodetect this and switch to so-called _restricted mode_ at
  65      build-time (*note Non-ANSI Features::). If Clon has failed to
  66      autodetect the problem (in which case I would like to know), or if
  67      for some reason, you explicitly want to disable those features,
  68      you may set the `:restricted' configuration option to `t'.
  69
  70 :dump
  71      This option is only used by the ABCL port. *note Dumping
  72      Executables::, provides more information on its use.
  73
  74
  75 A.2 Non-ANSI Features
  76 =====================
  77
  78 One feature of Clon that is beyond the ANSI standard is terminal
  79 autodetection (it requires an `ioctl' call and hence a foreign function
  80 interface). Terminal autodetection is used in several situations, for
  81 turning on highlighting automatically and for detecting a terminal line
  82 width.
  83
  84    If, for some reason, terminal autodetection is not available, Clon
  85 will work in so-called _restricted mode_. This means that
  86 `--clon-highlight=auto' won't work (highlighting will _not_ be turned
  87 on automatically on a tty). For the same reason, unless otherwise
  88 specified via either the `COLUMNS' environment variable or the
  89 `--clon-line-width' option, terminal output will be formatted for 80
  90 columns regardless of the actual terminal width (*note Global Control:
  91 (clon-enduser)Global Control.  ).
  92
  93
  94 A.3 Supported Platforms
  95 =======================
  96
  97 Clon currently works on Unix (including MacOS X) and Windows (Cygwin or
  98 MinGW) and has been ported to 6 Common Lisp implementations. The
  99 following table lists the supported platforms.
 100
 101 Compiler   Minimum Version   Dependencies
 102 -------------------------------------------------
 103 SBCL
 104 CMU-CL     20b
 105 CCL
 106 ECL        11.1.2(1)
 107 CLISP                        `cffi' (optional)
 108 ABCL       0.24.0(2)
 109
 110 ABCL specificities
 111 ------------------
 112
 113 Clon's ABCL port currently has two limitations:
 114    * It only works in restricted mode (*note Non-ANSI Features::).
 115
 116    * Since Java doesn't have a `putenv' or `setenv' function (!!), the
 117      `modify-environment' restart, normally proposed when an
 118      environment variable is set to a bogus value, is unavailable
 119      (*note Error Management: (clon-enduser)Error Management.  ).
 120
 121 CLISP specificities
 122 -------------------
 123
 124 As mentioned in the above table, CLISP's dependency on `cffi' is
 125 optional. CLISP needs `cffi' in order to implement terminal
 126 autodetection only (note that many other implementations come with their
 127 own foreign function interface). If `cffi' cannot be found when the
 128 ASDF system is loaded (or if CLISP itself has been compiled without
 129 `ffi' support), you get a big red blinking light and a warning but
 130 that's all. Clon will still work, although in restricted mode.
 131
 132    ---------- Footnotes ----------
 133
 134    (1) more precisely, git revision
 135 3e2e5f9dc3c5176ef6ef8d7794bfa43f1af8f8db
 136
 137    (2) more precisely, svn trunk revision 13156
 138