# $Id: INSTALL,v 1.38 2014/05/29 23:42:11 gilles Exp gilles $
# 
# INSTALL file for imapsync 
# imapsync : IMAP sync and migrate tool.

INTRODUCTION
============

 imapsync works fine under any operating system with Perl and Perl modules (listed below).
 imapsync.exe works fine standalone under Windows XP, Vista, Seven, 20XX, either 32 or 64bit.

WINDOWS
=======

Read the file README_Windows.txt

UNIX
====

This section doesn't concern Windows imapsync.exe users.

 Purchase imapsync at
 http://imapsync.lamiral.info/
 You'll have access to a compressed tarball called imapsync-x.xx.tgz
 where x.xx is the version number. Untar the tarball where
 you want (on Unix):

 tar xzvf  imapsync-x.xx.tgz

 Go into the directory imapsync-x.xx and read the INSTALL file.
 You're already reading the INSTALL file.


You need : 
- Perl 
  try : perl -v

  Get Perl here:
  http://www.perl.org/

- Some perl modules. To verify in one command that you have
  all needed modules, just run:

  perl -c imapsync

  The good answer is "imapsync syntax OK".
  Any other output will list the missing modules in the
  Perl paths (it then talks about @INC variable).

Here is some individual module help:

- To check if your system has Perl Mail::IMAPClient module 
  try : 

  perl -mMail::IMAPClient -e ''

  It should print nothing, nothing printed means Mail::IMAPClient
  is already installed on your system.

  If the module Mail::IMAPClient is not on the system,
  you can use a copy included in the imapsync tarball
  or get the latest Mail::IMAPClient module here:
  http://search.cpan.org/dist/Mail-IMAPClient/

  I use always the latest Mail-IMAPClient-3.xx
  To know the version you have on your system try :

  perl -mMail::IMAPClient -e 'print $Mail::IMAPClient::VERSION, "\n"'

  New Mail-IMAPClient-3.xx works very well with imapsync,
  Use at least Mail-IMAPClient-3.25 (previous releases may bug).
  Do not hesitate to use latest Mail-IMAPClient-3.xx 
  (3.xx >= 3.35 at the time of this writing)

  Look at the shell script named "i3" in the tarball, it can be used to
  run imapsync with included Mail-IMAPClient-3.35/ wherever you 
  unpacked the imapsync tarball.

Test all Perl modules dependency in one command:

  perl -mMail::IMAPClient -mDigest::MD5 -mTerm::ReadKey -mIO::Socket::SSL \
       -mDigest::HMAC_MD5 -mAuthen::NTLM -e -mTime::HiRes \
       -mData::Uniqid -mURI::Escape -mFile::Copy::Recursive -mIO::Tee ""

You can install easily those Perl modules in latest release via the
following commands (with root permissions)

  perl -MCPAN -e "install Mail::IMAPClient"
  perl -MCPAN -e "install Term::ReadKey"
  perl -MCPAN -e "install IO::Socket::SSL"
  perl -MCPAN -e "install Digest::HMAC_MD5"
  perl -MCPAN -e "install URI::Escape"
  perl -MCPAN -e "install File::Copy::Recursive"
  perl -MCPAN -e "install IO::Tee"

  perl -MCPAN -e "install Data::Uniqid"
  perl -MCPAN -e "install Authen::NTLM"


You can also install them easily by using the standard install
command on your system if the packages have been made on it.
Doing so you may not have the latest release but most of the time 
it doesn't care. 

Modules 
 Authen::NTLM
 Data::Uniqid
may be not available in the distribution way since I haven't find them
on Ubuntu nor on Mandriva but Centos supports them.

On Debian/Ubuntu:

  aptitude install libmail-imapclient-perl     # Mail::IMAPClient
  aptitude install libterm-readkey-perl        # Term::ReadKey
  aptitude install libio-socket-ssl-perl       # IO::Socket::SSL
  aptitude install libdigest-hmac-perl         # Digest::HMAC_MD5 Digest::HMAC_SHA1
  aptitude install liburi-perl                 # URI::Escape
  aptitude install libfile-copy-recursive-perl # File::Copy::Recursive
  aptitude install libio-tee-perl              # IO::Tee

On Mandriva:

  urpmi perl-Mail-IMAPClient     # Mail::IMAPClient
  urpmi perl-Term-ReadKey        # Term::ReadKey
  urpmi perl-IO-Socket-SSL       # IO::Socket::SSL
  urpmi perl-Digest-HMAC         # Digest::HMAC_MD5 Digest::HMAC_SHA1
  urpmi perl-URI                 # URI::Escape
  urpmi perl-File-Copy-Recursive # File::Copy::Recursive
  urpmi perl-IO-Tee              # IO::Tee
  

On  CentOS (thanks to Ralf Hauber)

  Install RPM Repository: Fedora Epel

  See http://pkgs.org/centos-6-rhel-6/epel-i386/perl-Data-Uniqid-0.12-2.el6.noarch.rpm.html
  wget http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
  rpm -Uvh epel-release*rpm

  yum install perl-Mail-IMAPClient       # Mail::IMAPClient
  yum install "perl(Term::ReadKey)"      # Term::ReadKey
  yum install "perl(Authen::NTLM)"       # Authen::NTLM
  yum install perl-Data-Uniqid           # Data::Uniqid
  yum install perl-File-Copy-Recursive   # File::Copy::Recursive
  yum install perl-IO-Tee                # IO::Tee


INSTALLING on Unix
------------------

To see what will be done, just run (you need the make command):

  make -n install

To install imapsync in /usr/bin/ and man page in /usr/share/man/man1/, just run (as root):

  make install

or copy the file imapsync where you want it to be.
For example:

  cp imapsync /usr/bin/

TESTING on Unix
---------------

Tests will break as they are home specific.
You need a running imap server on localhost with several accounts
toto with a password located in the file $HOME/var/pass/secret.toto
titi with a password located in the file $HOME/var/pass/secret.titi
tata with a password located in the file $HOME/var/pass/secret.tata

Of course, you can change the file tests.sh and run tests with:

  sh -x tests.sh

Specific tests can be run by using them as argument to tests.sh:

  sh -x tests.sh ll_ssl_justconnect ll_bad_host ...

The tests.sh script break on first failure ("set -e" directive).

Since I added more tests you also need a remote imap server see the
file tests.sh and help yourself. No time to make a universal test
file.