Documentation updates

[geiser.git] / doc / install.texi

@node Installation, The REPL, Introduction, Top
@chapter Installation

@menu
* Must needs::
* The easy and quick way::
* From the source's mouth::
* Friends::
@end menu

@node Must needs, The easy and quick way, Installation, Installation
@section Must needs

@cindex supported versions
@cindex versions supported
If Geiser came with any guarantees, you'd break all of them by not using
GNU Emacs @value{EMACS_VERSION} (or better: i regularly use it with a
recent Emacs snapshot) and at least one of the supported Schemes,
namely:

@itemize @bullet
@item
@uref{http://www.racket-lang.org, Racket} @value{RACKET_VERSION} or better
@item
@uref{http://www.gnu.org/software/guile, Guile} @value{GUILE_VERSION} or
better
@end itemize

Since Geiser supports multiple REPLs, having both of them will just add
to the fun.

You'll also need Geiser itself.  The quickest installation is via its
ELPA package, as described in the next section.  If you prefer to use
the source code directly, it's not that difficult either: just keep on
reading.

@node The easy and quick way, From the source's mouth, Must needs, Installation
@section The easy and quick way

@cindex quick install
@cindex ELPA
Did i mention that the easiest way of installing Geiser is using its
@uref{http://emacswiki.org/emacs/ELPA, ELPA} package?  If you're using
Emacs 24, @uref{http://emacswiki.org/emacs/ELPA, ELPA} is already there;
for earlier versions, the page i just linked to twice will tell you
where to find the goodies.

ELPA packages live in repositories accessible via HTTP.  You can find
Geiser's package either in @uref{http://marmalade-repo.org, Marmalade}
or in Geiser's repository, located at
@code{http://download.savannah.gnu.org/releases/geiser/packages}.  To
tell Emacs that a repo exists, you add it to @code{package-archives}:

@example
(require 'package)
(add-to-list 'package-archives
  '("marmalade" . "http://marmalade-repo.org/packages/"))
;; You don't need this one if you have marmalade:
;; (add-to-list 'package-archives
;;  '("geiser" . "http://download.savannah.gnu.org/releases/geiser/packages"))
(package-initialize)
@end example

And then installing Geiser is as easy as:

@example
M-x install-package RET geiser RET
@end example

Alternatively, you can manually download the @uref{@value{PACKAGE},
package file}, and install from your local disk with @kbd{M-x
package-install-file}

With that, you are pretty much all set up.  See @ref{The REPL} to start
using Geiser.

@ifnotinfo
And, by the way, if you prefer to keep reading this manual within Emacs,
@kbd{C-h i m Geiser RET} will bring you to the info version of it that
you just installed!
@end ifnotinfo

@node From the source's mouth, Friends, The easy and quick way, Installation
@section Installing from source

@subsubheading Downloading Geiser

@cindex use the source, Luke
The latest release tarball can be found @downfile{, here}, while older
versions are @uref{@value{OLD_DOWN_BASE}/, here}.  Just download
@downfile{@value{TARBALL}, @value{TARBALL}} and untar it in a directory
of your choice.

If you feel like living on the bleeding edge, just grab Geiser from its
Git repository @uref{http://git.savannah.nongnu.org/cgit/geiser.git/, over
at Savannah}, either with the following incantation:

@example
git clone git://git.sv.gnu.org/geiser.git
@end example

@noindent or, if you happen to live behind a firewall, with the alternative:

@example
git clone http://git.sv.gnu.org/r/geiser.git
@end example

@noindent
You can also follow Geiser's development in
@uref{https://github.com/jaor/geiser, one}
@uref{http://repo.or.cz/w/geiser.git, or}
@uref{http://gitorious.org/geiser, three} mirrors that are kept
synchronized with the one at Savannah.

Either way, you'll now be in possession of a copy of Geiser's libre
code.  I'll follow you into its directory and the next section.

@subsubheading Setting it up

Geiser is ready to be used out of the box without much more ado.  For the
sake of concreteness, let's assume you put its source in the directory
@file{~/lisp/geiser}.  All you need to do is to add the following
line to your Emacs initialisation file (be it @file{~/.emacs} or any of
its moral equivalents):

@example
(load-file "~/lisp/geiser/elisp/geiser.el")
@end example

@noindent
or simply evaluate that form inside Emacs (you wouldn't kill a friend
just to start using Geiser, would you?).  That's it: you're ready to
@ifhtml
@ref{quick-start,,go}.
@end ifhtml
@ifnothtml
go (@pxref{The REPL}).
@end ifnothtml

@ifnotinfo
If you obtained the Geiser source tree from a release tarball, you can
even continue to read this fine manual inside Emacs by opening
@file{doc/geiser.info} using @kbd{C-u C-h i}.  The manual is also
available in PDF format @downfile{geiser-manual-@value{VERSION}.pdf,
here}.
@end ifnotinfo

@cindex byte-compilation
What?  You still here?  I promise the above is all that's needed to start
using Geiser.  But, in case you are missing your @t{configure/make all
install} routine, by all means, you can go through those motions to byte
compile and install Geiser too.  That is, you enter the source directory
and (since we grabbed the development tree) run the customary
@i{autogen} script:

@example
$ cd ~/lisp/geiser
$ ./autogen.sh
@end example

@noindent
I recommend that you compile Geiser in a separate directory:

@example
$ mkdir build && cd build
$ ../configure
<some drivel here>
$ make all
<more of the above>
@end example

Now you have two options: loading the byte-compiled Geiser from the
@file{elisp} subdirectory, or installing it system-wide.  To load the
byte-code from here, add this line to your initialisation file:

@example
(load "~/lisp/geiser/build/elisp/geiser-load")
@end example

@noindent
and eval that form and you're done (you could also restart Emacs, but
killing your friends is widely considered bad form).  Yes, that's
@code{load} and @file{geiser-load} instead of @code{load-file} and
@file{geiser.el}.

If you prefer a system-wide installation, just type:

@example
$ sudo make install
@end example

With the above spell, Geiser will be compiled and installed in a safe
place inside Emacs load path.  To load it into Emacs you'll need,
@i{instead} of the @code{load-file} form above, the following line in
your initialisation file:

@example
(require 'geiser-install)
@end example

@noindent
Please note that we're requiring @code{geiser-install}, and @i{not}
@code{geiser}, and that there's no @code{load-file} to be seen this
time.  There are some ways of fine-tuning this process, mainly by
providing additional arguments in the call to @t{configure}: you'll find
those gory details in the file called @file{INSTALL}, right at the root
of the source tree.  The installation will also take care of placing this
manual, in Info format, where Emacs can find it, so you can continue to
learn about Geiser inside its natural habitat.  See you there and into
the next chapter!

@node Friends,  , From the source's mouth, Installation
@section Friends

Although Geiser does not need them, it plays well with (and is enhanced
by) the following Emacs packages:

@cindex paredit
@cindex company
@cindex quack
@itemize @bullet
@item @uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}.
@anchor{paredit}
Regardless of whether you use Geiser or not, you shouldn't be coding
in any Lisp dialect without the aid of Taylor Campbell's structured
editing mode.
@item @uref{http://nschum.de/src/emacs/company-mode/, Company}.
Nikolaj Schumacher's @code{company-mode} provides a generic front-end
for completion engines (such as Geiser's).  Very nice if you like that
kind of thing: judge by yourself with the help of
@uref{http://www.screentoaster.com/watch/stU0lSRERIR1pYRFVdXVlRVFFV/company_mode_for_gnu_emacs,
this screencast}.
@item @uref{http://www.neilvandyke.org/quack/, Quack}.
You can still use the many goodies provided by Neil van Dyke's
@code{quack-mode}, since most of them are not (yet) available in Geiser.
The only caveat might be a conflict between Quack's and Geiser's default
key bindings, which i'm sure you'll manage to tackle just fine.  It's
also probably a good idea to require @code{quack} @i{after} loading
@file{geiser.el} (or requiring a compiled version).
@end itemize

@noindent
You just need to install and setup them as usual, for every package's
definition of usual.  Geiser will notice their presence and react
accordingly.

@c Local Variables:
@c mode: texinfo
@c TeX-master: "geiser"
@c End: