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