@c -*-texinfo-*-

@include trampver.texi

@c The installation chapter.
@node Installation
@chapter Installing @value{tramp} into @value{emacsname}.
@cindex installation

If you use the version that comes with your @value{emacsname}, the
following information is not necessary.  Installing @value{tramp} into your
@value{emacsname} is a relatively easy process, at least compared
to rebuilding your machine from scratch. ;)

Seriously though, the installation should be a fairly simple matter.
The easiest way to proceed is as follows:

@itemize @bullet
@item
Choose a directory, say @file{~/@value{emacsdir}/}.  Change into that
directory and unpack the tarball.  This will give you a directory
@file{~/@value{emacsdir}/tramp-@value{trampver}/} which contains
subdirectories @file{lisp} for the Lisp code and @file{texi} for the
documentation.  Make a symbolic link:

@example
ln -s tramp-@value{trampver} tramp
@end example

@item
@command{cd} to @file{~/@value{emacsdir}/tramp/} and type
@command{./configure --with-contrib} to configure Tramp for your
system.

Running `configure' takes awhile.  While running, it prints some
messages telling which features it is checking for.

@item
Type @command{make} to build the byte-compiled Lisp files as well as
the Info manual.

@item
Type @command{make install} to install the Tramp Lisp files and Info
manual.

@item
You can remove the byte-compiled Lisp files and the Info manual from
the source directory by typing @command{make clean}.  To also remove
the files that @command{configure} created, type @command{make
distclean}.

@item
NOTE: If you run into problems running the example @command{make}
command, don't despair.  You can still byte compile the @file{*.el}
files by opening @value{emacsname} in @command{dired} (@command{C-x
d}) mode, at @file{~/@value{emacsdir}/tramp/lisp}.  Mark the lisp files with
@kbd{m}, then press @kbd{B} to byte compile your selections.

Something similar can be done to create the info manual.  Just change
to directory @file{~/@value{emacsdir}/tramp/texi} and load the
@file{tramp.texi} file in @value{emacsname}.  Then press @kbd{M-x
texinfo-format-buffer @key{RET}} to generate
@file{~/@value{emacsdir}/tramp/info/tramp}.
@end itemize

@menu
* Installation parameters::     Parameters in order to control installation.
* Load paths::                  How to plug-in @value{tramp} into your environment.
* Japanese manual::             Japanese manual.
@end menu

@node Installation parameters
@section Parameters in order to control installation.
@cindex installation

There are some Lisp packages which are not contained in older
@value{emacsname}en by default yet.  In order to make a link for them
into Tramp's @file{contrib} directory, you must use the
@option{--with-contrib} option:

@example
./configure --with-contrib
@end example

By default, @command{make install} will install @value{tramp}'s files in
@file{@value{lispdir}} and @file{@value{infodir}}.  You can specify an
installation prefix other than @file{@value{instprefix}} by giving
@command{configure} the option @option{--prefix=PATH}.
@ifset emacs
On Linux systems, it has been reported useful to apply

@example
./configure --prefix=/usr/share
@end example
@end ifset

If your installed copy of @value{emacsname} is named something other than
@option{@value{emacsdir}}, you will need to tell `make' where to find it so
that it can correctly byte-compile the @value{tramp} sources.

For example, to force the use of @value{emacsothername} you might do
this:

@example
./configure --with-@value{emacsotherdir}
make
make install
@end example

The syntax of @value{tramp} file names is different for @value{emacsname}
and @value{emacsothername}.  The Info manual will be generated for
the Emacs flavor choosen in the @command{configure} phase. If you want
the Info manual for the other version, you need to set the variable
@option{EMACS_INFO} to @command{make}:

@example
./configure --with-@value{emacsdir}
make EMACS_INFO=@value{emacsotherdir}
@end example

Also, the @option{--prefix=PATH} option to @command{configure} may
not be general enough to set the paths you want.  If not, you can pass
variables to the @command{make} command to control the installation.
For a complete list of tweakable variables, look in the makefile.

For example, to put the Lisp files in @file{~/elisp} and the Info file
in @file{~/info}, you would type:

@example
./configure
make
make lispdir=~/elisp infodir=~/info install
@end example

Running @command{configure} might result in errors or warnings.  The
output explains in detail what's going wrong.

In case of errors, it is mandatory to fix them before continuation.
This can be missing or wrong versions of @command{@value{emacsdir}},
@value{emacsname} packages, @command{make}, or @command{makeinfo}.

Warnings let @command{configure} (and the whole installation process)
continue, but parts of Tramp aren't installed.  This can happen with
missing or wrong versions of @command{texi2dvi} or
@command{install-info}.  Here you can decide yourself whether you want
to renounce on the related feature (@file{tramp.dvi} file for printed
output, Tramp entry in Info's @file{dir} file), or whether you want to
adapt your $PATH environment variable, and rerun @command{configure}.
An alternative is calling the missed parts manually later on.

@node Load paths
@section How to plug-in @value{tramp} into your environment.
@cindex installation

If you don't install @value{tramp} into the intended directories, but prefer
to use from the source directory, you need to add the following lines
into your @file{.emacs}:

@lisp
(add-to-list 'load-path "~/@value{emacsdir}/tramp/lisp/")
(require 'tramp)
@end lisp

@ifset xemacs
NOTE: For @value{emacsname}, the package @file{fsf-compat} must be
installed.  For details on package installation, see @ref{Packages, ,
,xemacs}.
@ifhtml
(If the previous link doesn't work, try the @value{emacsname}
documentation at
@uref{http://www.xemacs.org/Documentation/packageGuide.html,the
@value{emacsname} site}.)
@end ifhtml
@end ifset

If the environment variable @env{INFOPATH} is set, add the directory
@file{~/@value{emacsdir}/tramp/info/} to it.  Else, add the directory to
@ifset emacs
@code{Info-default-directory-list}, as follows:

@lisp
(add-to-list 'Info-default-directory-list "~/@value{emacsdir}/tramp/info/")
@end lisp
@end ifset
@ifset xemacs
@code{Info-directory-list}, as follows:

@lisp
(add-to-list 'Info-directory-list "~/@value{emacsdir}/tramp/info/")
@end lisp
@end ifset

@node Japanese manual
@section Japanese manual.
@cindex installation

Thanks to Yoichi Nakayama @email{yoichi@@geiin.org}, there exists a
japanese translation of the @value{tramp} manual.  You can generate it
applying the @option{--with-japanese-manual} option:

@example
./configure --with-japanese-manual
@end example

This will result in an Info manual
@iftex
@file{tramp_ja}.
@end iftex
@ifnottex
@ifset jamanual
@inforef{Top,,tramp_ja}.
@end ifset
@ifclear jamanual
@file{tramp_ja}.
@end ifclear
@end ifnottex
