doc/install.texi

   1 @node Installation, The REPL, Introduction, Top
   2 @chapter Installation
   3
   4 @menu
   5 * Must needs::
   6 * The easy and quick way::
   7 * From the source's mouth::
   8 * Friends::
   9 @end menu
  10
  11 @node Must needs, The easy and quick way, Installation, Installation
  12 @section Must needs
  13
  14 @cindex supported versions
  15 @cindex versions supported
  16 If Geiser came with any guarantees, you'd break all of them by not using
  17 GNU Emacs @value{EMACS_VERSION} (or better: i regularly use it with a
  18 recent Emacs snapshot) and at least one of the supported Schemes,
  19 namely:
  20
  21 @itemize @bullet
  22 @item
  23 @uref{http://www.racket-lang.org, Racket} @value{RACKET_VERSION} or better
  24 @item
  25 @uref{http://www.gnu.org/software/guile, Guile} @value{GUILE_VERSION} or
  26 better
  27 @end itemize
  28
  29 Since Geiser supports multiple REPLs, having both of them will just add
  30 to the fun.
  31
  32 You'll also need Geiser itself.  The quickest installation is via its
  33 ELPA package, as described in the next section.  If you prefer to use
  34 the source code directly, it's not that difficult either: just keep on
  35 reading.
  36
  37 @node The easy and quick way, From the source's mouth, Must needs, Installation
  38 @section The easy and quick way
  39
  40 @cindex quick install
  41 @cindex ELPA
  42 Did i mention that the easiest way of installing Geiser is using its
  43 @uref{http://emacswiki.org/emacs/ELPA, ELPA} package?  If you're using
  44 Emacs 24, @uref{http://emacswiki.org/emacs/ELPA, ELPA} is already there;
  45 for earlier versions, the page i just linked to twice will tell you
  46 where to find the goodies.
  47
  48 ELPA packages live in repositories accessible via HTTP.  You can find
  49 Geiser's package either in @uref{http://marmalade-repo.org, Marmalade}
  50 (for releases) or in @uref{http://melpa.milkbox.net, MELPA} (for the
  51 unstable version directly from the git repo).  To tell Emacs that a repo
  52 exists, you add it to @code{package-archives}:
  53
  54 @example
  55 (require 'package)
  56 (add-to-list 'package-archives
  57   '("marmalade" . "http://marmalade-repo.org/packages/"))
  58 ;; You don't need this one if you prefer marmalade and released versions:
  59 ;; (add-to-list 'package-archives
  60 ;;  '("melpa" . "http://melpa.milkbox.net/packages/"))
  61 (package-initialize)
  62 @end example
  63
  64 And then installing Geiser is as easy as:
  65
  66 @example
  67 M-x package-install RET geiser RET
  68 @end example
  69
  70 Alternatively, you can manually download the @uref{@value{PACKAGE},
  71 package file}, and install from your local disk with @kbd{M-x
  72 package-install-file}
  73
  74 With that, you are pretty much all set up.  See @ref{The REPL} to start
  75 using Geiser.
  76
  77 @ifnotinfo
  78 And, by the way, if you prefer to keep reading this manual within Emacs,
  79 @kbd{C-h i m Geiser RET} will bring you to the info version of it that
  80 you just installed!
  81 @end ifnotinfo
  82
  83 @node From the source's mouth, Friends, The easy and quick way, Installation
  84 @section Installing from source
  85
  86 @subsubheading Downloading Geiser
  87
  88 @cindex use the source, Luke
  89 The latest release tarball can be found @downfile{, here}.  Just
  90 download @downfile{@value{TARBALL}, @value{TARBALL}} and untar it in a
  91 directory of your choice.
  92
  93 If you feel like living on the bleeding edge, just grab Geiser from its
  94 Git repository @uref{http://git.savannah.nongnu.org/cgit/geiser.git/, over
  95 at Savannah}, either with the following incantation:
  96
  97 @example
  98 git clone git://git.sv.gnu.org/geiser.git
  99 @end example
 100
 101 @noindent or, if you happen to live behind a firewall, with the alternative:
 102
 103 @example
 104 git clone http://git.sv.gnu.org/r/geiser.git
 105 @end example
 106
 107 @noindent
 108 You can also follow Geiser's development in
 109 @uref{https://github.com/jaor/geiser, one}
 110 @uref{http://repo.or.cz/w/geiser.git, or}
 111 @uref{http://gitorious.org/geiser, three} mirrors that are kept
 112 synchronized with the one at Savannah.
 113
 114 Either way, you'll now be in possession of a copy of Geiser's libre
 115 code.  I'll follow you into its directory and the next section.
 116
 117 @subsubheading Setting it up
 118
 119 Geiser is ready to be used out of the box without much more ado.  For the
 120 sake of concreteness, let's assume you put its source in the directory
 121 @file{~/lisp/geiser}.  All you need to do is to add the following
 122 line to your Emacs initialisation file (be it @file{~/.emacs} or any of
 123 its moral equivalents):
 124
 125 @example
 126 (load-file "~/lisp/geiser/elisp/geiser.el")
 127 @end example
 128
 129 @noindent
 130 or simply evaluate that form inside Emacs (you wouldn't kill a friend
 131 just to start using Geiser, would you?).  That's it: you're ready to
 132 @ifhtml
 133 @ref{quick-start,,go}.
 134 @end ifhtml
 135 @ifnothtml
 136 go (@pxref{The REPL}).
 137 @end ifnothtml
 138
 139 @ifnotinfo
 140 If you obtained the Geiser source tree from a release tarball, you can
 141 even continue to read this fine manual inside Emacs by opening
 142 @file{doc/geiser.info} using @kbd{C-u C-h i}.  The manual is also
 143 available in PDF format @downfile{geiser-manual-@value{VERSION}.pdf,
 144 here}.
 145 @end ifnotinfo
 146
 147 @cindex byte-compilation
 148 What?  You still here?  I promise the above is all that's needed to start
 149 using Geiser.  But, in case you are missing your @t{configure/make all
 150 install} routine, by all means, you can go through those motions to byte
 151 compile and install Geiser too.  That is, you enter the source directory
 152 and (since we grabbed the development tree) run the customary
 153 @i{autogen} script:
 154
 155 @example
 156 $ cd ~/lisp/geiser
 157 $ ./autogen.sh
 158 @end example
 159
 160 @noindent
 161 I recommend that you compile Geiser in a separate directory:
 162
 163 @example
 164 $ mkdir build && cd build
 165 $ ../configure
 166 <some drivel here>
 167 $ make all
 168 <more of the above>
 169 @end example
 170
 171 Now you have two options: loading the byte-compiled Geiser from the
 172 @file{elisp} subdirectory, or installing it system-wide.  To load the
 173 byte-code from here, add this line to your initialisation file:
 174
 175 @example
 176 (load "~/lisp/geiser/build/elisp/geiser-load")
 177 @end example
 178
 179 @noindent
 180 and eval that form and you're done (you could also restart Emacs, but
 181 killing your friends is widely considered bad form).  Yes, that's
 182 @code{load} and @file{geiser-load} instead of @code{load-file} and
 183 @file{geiser.el}.
 184
 185 If you prefer a system-wide installation, just type:
 186
 187 @example
 188 $ sudo make install
 189 @end example
 190
 191 With the above spell, Geiser will be compiled and installed in a safe
 192 place inside Emacs load path.  To load it into Emacs you'll need,
 193 @i{instead} of the @code{load-file} form above, the following line in
 194 your initialisation file:
 195
 196 @example
 197 (require 'geiser-install)
 198 @end example
 199
 200 @noindent
 201 Please note that we're requiring @code{geiser-install}, and @i{not}
 202 @code{geiser}, and that there's no @code{load-file} to be seen this
 203 time.  There are some ways of fine-tuning this process, mainly by
 204 providing additional arguments in the call to @t{configure}: you'll find
 205 those gory details in the file called @file{INSTALL}, right at the root
 206 of the source tree.  The installation will also take care of placing this
 207 manual, in Info format, where Emacs can find it, so you can continue to
 208 learn about Geiser inside its natural habitat.  See you there and into
 209 the next chapter!
 210
 211 @node Friends,  , From the source's mouth, Installation
 212 @section Friends
 213
 214 Although Geiser does not need them, it plays well with (and is enhanced
 215 by) the following Emacs packages:
 216
 217 @cindex paredit
 218 @cindex company
 219 @cindex quack
 220 @itemize @bullet
 221 @item @uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}.
 222 @anchor{paredit}
 223 Regardless of whether you use Geiser or not, you shouldn't be coding
 224 in any Lisp dialect without the aid of Taylor Campbell's structured
 225 editing mode.
 226 @item @uref{http://company-mode.github.io/, Company}.
 227 Nikolaj Schumacher's and Dmitry Gutov's @code{company-mode} provides a
 228 generic front-end for completion engines (such as Geiser's), with pretty
 229 and automatic completion lists.
 230 @item @uref{http://www.neilvandyke.org/quack/, Quack}.
 231 You can still use the many goodies provided by Neil van Dyke's
 232 @code{quack-mode}, since most of them are not (yet) available in Geiser.
 233 The only caveat might be a conflict between Quack's and Geiser's default
 234 key bindings, which i'm sure you'll manage to tackle just fine.  It's
 235 also probably a good idea to require @code{quack} @i{after} loading
 236 @file{geiser.el} (or requiring a compiled version).
 237 @end itemize
 238
 239 @noindent
 240 You just need to install and setup them as usual, for every package's
 241 definition of usual.  Geiser will notice their presence and react
 242 accordingly.
 243
 244 @c Local Variables:
 245 @c mode: texinfo
 246 @c TeX-master: "geiser"
 247 @c End: