
Installation

   Unison is designed to be easy to install. The following sequence of
   steps should get you a fully working installation in a few minutes.
   (If you run into trouble, you may find the suggestions in the section
   ``Advice'' helpful.)
   
   Unison can be used with either of two user interfaces:
    1. a simple textual interface, suitable for dumb terminals (and
       running from scripts), and
    2. a more sophisticated grapical interface, based on Gtk.
       
   You will need to install a copy of Unison on every machine that you
   want to synchronize. However, you only need the version with a
   graphical user interface (if you want a GUI at all) on the machine
   where you're actually going to display the interface (the CLIENT
   machine). Other machines that you synchronize with can get along just
   fine with the text version.
   
  Downloading Unison
  
   If a pre-built binary of Unison is available for the client machine's
   architecture, just download it and put it somewhere in your search
   path (if you're going to invoke it from the command line) or on your
   desktop (if you'll be click-starting it).
   
   The executable file for the graphical version (with a name including
   gtkui) actually provides both interfaces: the graphical one appears by
   default, while the text interface can be selected by including -ui
   text on the command line. The textui executable provides just the
   textual interface.
   
   If you don't see a pre-built executable for your architecture, you'll
   need to build it yourself. See the section ``Building Unison'' .
   (There are also a small number of ``contributed ports'' to other
   architectures that are not maintained by us. See the section
   ``Contributed Ports'' to check what's available.)
   
   Check to make sure that what you've downloaded is really executable.
   Either click-start it, or type "unison -version" at the command line.
   
  Installing Ssh
  
   Unison can be used in several different modes: with different
   directories on a single machine, with a remote machine over a direct
   socket connection, with a remote machine using rsh (on Unix systems),
   or with a remote Unix system (from either a Unix or a Windows client)
   using ssh for authentication and secure transfer. If you intend to use
   the last option, you may need to install ssh.
   
   Your local host will need just an ssh client; the remote host needs an
   ssh server (or daemon), which is only available on Unix systems.
   Unison is known to work with ssh version 1.2.27 (Unix) and version
   1.2.14 (Windows); other versions may or may not work.
   
    Unix
    
    1. Install ssh.
         1. Become root. (If you do not have administrator permissions,
            ask your system manager to install an ssh client and an ssh
            server for you and skip this section.)
         2. Download ssh-1.2.27.tar.gz from ftp://ftp.ssh.com/pub/ssh/.
         3. Install it:
               o Unpack the archive (gunzip ssh-1.2.27.tar.gz and then
                 tar xvf ssh-1.2.27.tar.gz).
               o following instructions in INSTALL, enter ./configure,
                 make, and make install.
               o to run the ssh daemon:
                    # find the server daemon sshd (e.g.,
                      /usr/local/sbin/sshd on RedHat-Linux systems).
                    # put its full pathname in the system initialization
                      script to have it run at startup (this script is
                      called /etc/rc.d/rc.sysinit on RedHat-Linux, for
                      example).
         4. Once a server is running on the remote host and a client is
            available on the local host, you should be able to connect
            with ssh in the same way as with rsh (e.g., ssh foobar, then
            enter your password).
    2. If you like, you can now set up ssh so that you only need to type
       your password once per X session, rather than every time you run
       Unison (this is not necessary for using ssh with Unison, but it
       saves typing).
         1. Build your keys :
               o enter ssh-keygen and type a passphrase as required.
               o your private key is now in ~/.ssh/identity (this file
                 must remain private) and your public key in
                 ~/.ssh/identity.pub.
         2. Allow user-mode secure connection.
               o append contents of the local file ~/.ssh/identity.pub to
                 the file ~/.ssh/authorized_keys on the remote system.
               o Test that you can connect by starting ssh and giving the
                 passphrase you just chose instead of your remote
                 password.
         3. Create an agent to manage authentication for you :
               o start ssh-agent with the parent program whose children
                 will be granted automatic connections (e.g., ssh-agent
                 bash or ssh-agent startx).
               o enter ssh-add to enter your passphrase and enable
                 automatic login for connections to come.
               o you should now be able to run Unison using SSH without
                 giving any passphrase or password.
               o to kill the agent, enter ssh-agent -k, or simply exit
                 the program you launched using ssh-agent.
       
    Windows
    
   Many Windows implementations of ssh only provide graphical interfaces,
   but Unison requires an ssh client that it can invoke with a
   command-line interface. A suitable version of ssh can be installed as
   follows.
   
    1. Download an ssh executable. Warning: there are many
       implementations and ports of ssh for Windows, and not all of them
       will work with Unison. We have gotten Unison to work with Cygwin's
       port of openssh, and we suggest you use that one. Here's how to
       install it:
         1. First, create a new folder on your desktop to hold temporary
            installation files. It can have any name you like, but in
            these instructions we'll assume that you call it Foo.
         2. Direct your web browser to www.cygwin.com, and click on the
            ``Install now!'' link. This will download a file, setup.exe;
            save it in the directory Foo. The file setup.exe is a small
            program that will download the actual install files from the
            Internet when you run it.
         3. Start setup.exe (by double-clicking). This brings up a series
            of dialogs that you will have to go through. Select ``Install
            from Internet.'' For ``Local Package Directory'' select the
            directory Foo. For ``Select install root directory'' we
            recommend that you use the default, C:\cygwin. The next
            dialog asks you to select the way that you want to connect to
            the network to download the installation files; we have used
            ``Use IE5 Settings'' successfully, but you may need to make a
            different selection depending on your networking setup. The
            next dialog gives a list of mirrors; select one close to you.
            Next you are asked to select which packages to install. The
            default settings in this dialog download a lot of packages
            that are not strictly necessary to run Unison with ssh. If
            you don't want to install a package, click on it until
            ``skip'' is shown. For a minimum installation, select only
            the packages ``cygwin'' and ``openssh,'' which come to about
            1900KB; the full installation is much larger. After the
            packages are downloaded and installed, the next dialog allows
            you to choose whether to ``Create Desktop Icon'' and ``Add to
            Start Menu.'' You make the call.
         4. You can now delete the directory Foo and its contents.
    2. You must set the environment variables HOME and PATH. Ssh will
       create a directory .ssh in the directory given by HOME, so that it
       has a place to keep data like your public and private keys. PATH
       must be set to include the Cygwin bin directory, so that Unison
       can find the ssh executable.
          + On Windows 95/98, add the lines

    set PATH=%PATH%;<SSHDIR>
    set HOME=<HOMEDIR>
            to the file C:\AUTOEXEC.BAT, where <HOMEDIR> is the directory
            where you want ssh to create its .ssh directory, and <SSHDIR>
            is the directory where the executable ssh.exe is stored; if
            you've installed Cygwin in the default location, this is
            C:\cygwin\bin. You will have to reboot your computer to take
            the changes into account.
          + On Windows NT/2k, open the environment variables dialog box:
               o Windows NT: My Computer/Properties/Environment
               o Windows 2k: My Computer/Properties/Advanced/Environment
                 variables
            then select Path and edit its value by appending ;<SSHDIR> to
            it, where <SSHDIR> is the full name of the directory that
            includes the ssh executable; if you've installed Cygwin in
            the default location, this is C:\cygwin\bin.
    3. Test ssh from a DOS shell by typing

      ssh <remote host> -l <login name>
       You should get a prompt for your password on <remote host>,
       followed by a working connection.
    4. Note that ssh-keygen may not work (fails with 'gethostname: no
       such file or directory') on some systems. This is OK: you can use
       ssh with your regular password for the remote system.
    5. You should now be able to use Unison with an ssh connection. If
       you are logged in with a different user name on the local and
       remote hosts, provide your remote user name when providing the
       remote root (i.e., //username@host/path...).
       
  Running Unison
  
   Once you've got Unison installed on at least one system, read the
   Tutorial section of the user manual (or type "unison -doc tutorial")
   for instructions on how to get started.
   
  Upgrading
  
   Upgrading to a new version of Unison should be as simple as throwing
   away the old binary and installing the new one.
   
   Before upgrading, it is a good idea to use the old version to make
   sure all your replicas are completely synchronized. A new version of
   Unison will sometimes introduce a different format for the archive
   files used to remember information about the previous state of the
   replicas. In this case, the old archive will be ignored (not deleted
   --- if you roll back to the previous version of Unison, you will find
   the old archives intact), which means that any differences between the
   replicas will show up as conflicts and need to be resolved manually.
   
  Contributed Ports
  
   A few people have offered to maintain pre-built executables, easy
   installation scripts, etc., for particular architectures. They are not
   maintained by us and are not guaranteed to work, be kept up to date
   with our latest releases, etc., but you may find them useful. Here's
   what's available at the moment:
   
     * Dan Pelleg (mailto:dpelleg+unison@cs.cmu.edu) has ported unison to
       FreeBSD. This means that any FreeBSD user with an up-to-date
       ``ports'' collection can install unison by doing: cd
       /usr/ports/net/unison; make && make install. (Make sure your
       ``ports'' collection is fully up to date before doing this, to
       ensure that you get the most recent Unison version that has been
       compiled for FreeBSD.)
       FreeBSD binaries can also be obtained directly from
       
     http://www.freebsd.org/cgi/ports.cgi?query=unison&stype=all.
     * Andrew Pitts has built binaries for some versions of Unison for
       the Linux-PPC platform. They can be found in
       ftp://ftp.cl.cam.ac.uk/papers/amp12/unison/.
     * Robert Paris (mailto:robot101@hadesian.demon.co.uk) maintains a
       Debian package for Unison.
     * Chris Cocosco (mailto:crisco+unison@bic.mni.mcgill.ca) provides
       binaries for Unison under SGI IRIX (6.5). They can be found in
       
     www.bic.mni.mcgill.ca/users/crisco/unison.irix/.
       
  Building Unison from Scratch
  
   If a pre-built image is not available, you will need to compile it
   from scratch; the sources are available from the same place as the
   binaries.
   
   In principle, Unison should work on any platform to which OCaml has
   been ported and on which the Unix module is fully implemented. In
   particular, it has been tested on many flavors of Windows (98, NT,
   2000) and Unix (Solaris, Linux, FreeBSD, MacOS X), and on both 32- and
   64-bit architectures.
   
   Unison does not work (and probably never will) on MacOS versions 8 or
   9.
   
    Unix
    
   You'll need the Objective Caml compiler (version 3.00 or later), which
   is available from http://caml.inria.fr. Building and installing OCaml
   on Unix systems is very straightforward; follow the instructions in
   the distribution. You'll probably want to build the native-code
   compiler in addition to the bytecode compiler, but this is not
   absolutely necessary.
   
   (Quick start: on many systems, the following sequence of commands will
   get you a working and installed compiler: first do make world opt,
   then su to root, then do make install.)
   
   You'll also need the GNU make utility, standard on many Unix systems.
   (Type "make --version" to check that you've got the GNU version.)
   
   Once you've got OCaml installed, grab a copy of the Unison sources,
   unzip and untar them, change to the new "unison" directory, and type

            make UISTYLE=text

   The result should be an executable file called "unison".
   
   Type "./unison" to make sure the program is executable. You should get
   back a usage message.
   
   If you want to build a graphical user interface, choose one of the
   following:
     * Gtk interface:
       You will need Gtk (version 1.2 or later, available from
       http://www.gtk.org and standard on many Unix installations). You
       also need the most recent version of LablGtk. Grab the developers'
       tarball from
       http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html, untar
       it, and follow the instructions to build and install it.
       (Quick start: make configure, then make, then make opt, then su
       and make install.)
       Now build unison. If your search paths are set up correctly,
       typing

       make UISTYLE=gtk
       should build a unison executable with a Gtk graphical interface.
       
   If this step does not work, don't worry: Unison works fine with the
   textual interface.
   
   Put the unison executable somewhere in your search path, either by
   adding the Unison directory to your PATH variable or by copying the
   executable to some standard directory where executables are stored.
   
    Windows
    
   Although the binary distribution should work on any version of
   Windows, some people may want to build Unison from scratch on those
   systems too.
   
   The detailed instructions can be found in the INSTALL.win32 file
   provided with the sources. Please refer to it if you encounter any
   problem with the quick procedure described below.
   
   You'll need the Windows version of the Objective Caml compiler
   (version 3.00 or later, available from http://caml.inria.fr). Note
   that Objective Caml can compile either to bytecode or to native code,
   and under Windows, if you want to compile to native code you will also
   need Visual C++ (version 6.0 or later) and masm, the Microsoft
   assembler.
   
   Once you've got OCaml installed, grab a copy of the Unison sources and
   type

            make UISTYLE=text

   to compile to native code, or
            make UISTYLE=text NATIVE=false

   to compile to bytecode (e.g., if you don't have Vc++).
   
   The result should be an executable file called "unison.exe".
   
   Building the GTK version under Windows is currently an ``experts
   only'' operation. The tricky part is installing lablgtk; grab the
   sources from
   
     http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html.
     
   and follow the instructions there.
   
   Once lablgtk is built and installed, typing
            make UISTYLE=gtk

   should build Unison.
   
    Installation Options
    
   The Makefile in the distribution includes several switches that can be
   used to control how Unison is built. Here are the most useful ones:
     * Building with NATIVE=true uses the native-code OCaml compiler,
       yielding an executable that will run quite a bit faster. We use
       this for building distribution versions.
     * Building with make THREADS=true enables an experimental
       multi-threaded transport subsystem, which uses network bandwidth
       more effectively by overlapping several transfers. Use at your own
       risk.
     * Building with make DEBUGGING=true generates debugging symbols.
     * Building with make STATIC=true generates a (mostly) statically
       linked executable. We use this for building distribution versions,
       for portability.
       

