imapsync/INSTALL

# $Id: INSTALL,v 1.28 2013/05/14 08:19:08 gilles Exp gilles $
# 
# INSTALL file for imapsync 
# imapsync : IMAP sync or copy 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.


UNIX
----

 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.

WINDOWS
-------

a) Simplest way:

- Buy imapsync.exe at http://imapsync.lamiral.info/

- Run imapsync.exe in a command prompt (execute cmd.exe).

- Or simpler, look at the batch file at
  http://imapsync.lamiral.info/examples/imapsync_example.bat
  and replace the parameters with your values
  then run the batch file with a double-click.
  It is simpler to edit a batch file with notepad than 
  the command line in dos mode.

b) Hard way:

- Get imapsync-x.xx.tgz
- Install Perl if it isn't already installed.
  Strawberry Perl is a very good candidate
  http://strawberryperl.com/

- Use the command CPAN to install modules listed in the PREREQUISITES section.
  There is also a batch file that does this install for you
  It is called install_modules.bat available at
  http://imapsync.lamiral.info/examples/install_modules.bat

c) How to build imapsync.exe?

- Do the hard stuff in b)
- Run W/build_exe.bat (found in the tarball)

PREREQUISITES 
-------------

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

You need : 
- Perl 
  try : perl -v

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

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

  perl -c imapsync

  The good answer is "imapsync syntax OK".

Here is some individual module help:

- Perl Mail::IMAPClient module 
  try : 

  perl -mMail::IMAPClient -e ''
  
  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 may bug).
  Don't hesitate to use latest Mail-IMAPClient-3.xx 
  (3.xx >= 3.32 at the time of this writing)

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


- Perl Digest::MD5 module. 
  try:

  perl -mDigest::MD5 -e ""

  http://search.cpan.org/
  http://search.cpan.org/~gaas/Digest-MD5-2.52/
  To know the version you have on your system try :
  perl -mDigest::MD5 -e 'print $Digest::MD5::VERSION, "\n"'
  I use 2.39 (Ubuntu package)

- Term::ReadKey
  perl -mTerm::ReadKey -e ""

- IO::Socket::SSL
  perl -mIO::Socket::SSL -e ""

- File::Spec
  perl -mFile::Spec -e ""

- File::Path
  perl -mFile::Path -e ""

- Perl Digest::HMAC_MD5 module
  Good for non plain text password over network.
  perl -mDigest::HMAC_MD5 -e ""

- Perl Authen::NTLM
  perl -mAuthen::NTLM -e ""

- Perl Time::HiRes
  perl -mTime::HiRes  -e ""

- Perl Data::Uniqid
  perl -mData::Uniqid  -e ""

- Perl URI::Escape
  perl -mURI::Escape  -e ""


Test everything in one command:

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

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 Digest::MD5"
  perl -MCPAN -e "install Term::ReadKey"
  perl -MCPAN -e "install IO::Socket::SSL"
  perl -MCPAN -e "install File::Spec"
  perl -MCPAN -e "install Digest::HMAC_MD5"
  perl -MCPAN -e "install Authen::NTLM"
  perl -MCPAN -e "install Time::HiRes"
  perl -MCPAN -e "install Data::Uniqid"
  perl -MCPAN -e "install URI::Escape"


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

Modules Authen::NTLM, Data::Uniqid may be not available 
this way since I haven't find them on Ubuntu.

Example on Debian/Ubuntu:

  aptitude install  libmail-imapclient-perl # Mail::IMAPClient
  aptitude install  libdigest-md5-file-perl # Digest::MD5
  aptitude install  libterm-readkey-perl    # Term::ReadKey
  aptitude install  libio-socket-ssl-perl   # IO::Socket::SSL
  aptitude install  libfile-spec-perl       # File::Spec
  aptitude install  libdigest-hmac-perl     # Digest::HMAC_MD5 Digest::HMAC_SHA1


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

To see what will be done, just run:

  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.

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.