INSTALL

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