imapsync/INSTALL

# $Id: INSTALL,v 1.21 2011/11/17 08:07:03 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).

b) Hard way:

- Get imapsync-x.xx.tgz
- Install Perl if it isn't already installed.
  Strawberry Perl is a good candidate
- Use PPM to install modules listed in the PREREQUISITES section.
  PPM is Perl Package Manager.


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 Mail::IMAPClient module here:
  http://search.cpan.org/
  http://search.cpan.org/~djkernen/
  http://search.cpan.org/~djkernen/Mail-IMAPClient-2.2.9/
  
  In fact I use Mail-IMAPClient-2.2.9 and latest Mail-IMAPClient-2.xx
  (xx >= 25)
  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 now with imapsync,
  at least with Mail-IMAPClient-3.25 (previous may bug)

- Perl Digest::MD5 module. 
  try:

  perl -mDigest::MD5

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

- Term::ReadKey
  perl -mTerm::ReadKey -e ''

- IO:Socket:SSL.pm
  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 Authen::NTLM
  perl -mAuthen::NTLM -e ''

Everything in one command:

  perl -mMail::IMAPClient -mDigest::MD5 -mTerm::ReadKey -mIO::Socket::SSL \
       -mFile::Spec -mDigest::HMAC_MD5 -mAuthen::NTLM -e ''

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

To see what will be done, just run:

  make -n install

To install imapsync, just run:

  make install

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

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

The test 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 the tests with :

sh -x tests.sh

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.