#!/bin/cat
# $Id: INSTALL.Darwin.txt,v 1.39 2022/05/17 14:31:44 gilles Exp gilles $

This documentation is also located online at 
https://imapsync.lamiral.info/INSTALL.d/
https://imapsync.lamiral.info/INSTALL.d/INSTALL.Darwin.txt


Usual users should follow the A) section only, with the exeption 
of reading B) before if you use a Catalina system.

A) Installing imapsync binary on Darwin / Mac OS X
B) Installing imapsync on Catalina
C) Installing imapsync script on Darwin / Mac OS X with brew
D) Installing imapsync script on Darwin / Mac OS X the way I do
E) Building imapsync binary on Darwin / Mac OS X


=======================================================================
A) Installing imapsync binary on Darwin / Mac OS X
=======================================================================

There is a standalone imapsync binary for Mac OS X 
called "imapsync_bin_Darwin" (without the quotes),
available in the compressed tarball called imapsync-2.200.tgz
where 2.200 is the imapsync version number. 

In case you haven't buy it yet or forgot where the download link is,
check https://imapsync.lamiral.info/dist/

Download the tarball imapsync-2.200.tgz, not the binary imapsync_bin_Darwin
because the binary is also in the tarball and there are other useful files
in the tarball. The binary present in /dist/ is just there for a fast upgrade
when you need one.

I suppose this tarball imapsync-2.200.tgz is downloaded under your $HOME directory, 
let say /Users/gilles/, but you can put it anywhere. In real, your $HOME directory 
is not /Users/gilles/, it maybe /Users/john/ or /Users/zoey/ where John or Zoey
is you login name.

Open a terminal: /Applications/Utilities/Terminal double-click on Terminal.

Untar the tarball:

  cd
  pwd
  tar xzvf imapsync-2.200.tgz

In case the previous command fails, it means the tarball file called imapsync-2.200.tgz
is not in your $HOME directory, you may have downloaded it elsewhere on the file system.
A way to find it is the command:

  find / | grep imapsync 


Now that the tarball is extracted, it created a directory called imapsync-2.200/ 
Go into the directory imapsync-2.200 with the command:

  cd imapsync-2.200


First let's have a simple run to see if imapsync_bin_Darwin works. 
You should see some help about options and an example at the end 
of this run:

  ./imapsync_bin_Darwin

To go further, perform a complete test with two
real IMAP server accounts:  
  
  ./imapsync_bin_Darwin --testslive

If this sync works fine then imapsync_bin_Darwin is ready for any 
imap account synchronization. 

When reading the documentation with imapsync command lines examples, 
you have to replace the command "imapsync" by "imapsync_bin_Darwin"
For example, instead of the command:

  ./imapsync \
    --host1 test1.lamiral.info --user1 test1 --password1 secret1 \
    --host2 test2.lamiral.info --user2 test2 --password2 secret2

you have to use:

  ./imapsync_bin_Darwin \
    --host1 test1.lamiral.info --user1 test1 --password1 secret1 \
    --host2 test2.lamiral.info --user2 test2 --password2 secret2


The script examples/imapsync_example_darwin.sh is ready to use,
it is a copy of examples/imapsync_example.sh adapted to Mac users.


Be careful the way you edit the script files, use a text editor. 
Do not use a word processor because word processors add 
or use special formating characters that will break the shell
scripts. If you use TextEdit, use the text mode.

In the terminal, try:

  sh examples/imapsync_example_darwin.sh

or copy it and run your copy instead:

  cp examples/imapsync_example_darwin.sh mysync.sh
  sh mysync.sh

Now read on the tutorial
https://imapsync.lamiral.info/doc/TUTORIAL_Unix.html
in order to complete your formation on imapsync.

If you need to sync or migrate many accounts, 
the script examples/sync_loop_darwin.sh is also ready to use.


=======================================================================
B) Installing imapsync on Catalina
=======================================================================

Caveat Catalina: The binary imapsync_bin_Darwin is detected as a malware
or similar on the latest Mac OS X named Catalina. 
It's Catalina new security policy. Imapsync is not a malware or similar.
All other Mac OS X releases are ok.

In order to pass away this detection, follow these steps:

Run imapsync_bin_Darwin
After this first launch, the security asks to authorize the unknown 
developer program. Setup the root of the imapsync_bin_Darwin file 
and then run it again or any of the .sh files, it should run ok 
without any notice any more.

Sources of this tip:
https://www.quora.com/What-does-Can-t-be-opened-because-it-s-integrity-cannot-be-verified-mean-on-OSX-Catalina
https://github.com/fastlane/fastlane/issues/15186#issuecomment-532047545
https://github.com/neovim/neovim/issues/11011#issuecomment-531369505

Other way, on the binary: Control + Right Click -> Open

See also the last section of https://support.apple.com/en-us/HT202491
"How to open an app that hasn't been notarized or is from an unidentified developer"

I don't own a Catalina computer so I can't experiment on this nor make
imapsync directly ok with Catalina. You're richer than me :-)


=======================================================================
C) Installing imapsync script on Darwin / Mac OS X with brew
=======================================================================

In case you have brew installed on your system ( see https://brew.sh/ ),
install imapsync with the command:

  brew install imapsync
  
Do a real test with imap server test.lamiral.info:

  imapsync --testslive

If you encouter an error like "String.c: loadable library and perl binaries
are mismatched (got handshake key 0xc500080, needed 0xc400080)",
then install imapsync from source with the command:

  brew install -s imapsync

Thanks to Alessandro for this tip!

=======================================================================
D) Installing imapsync script on Darwin / Mac OS X the way I do
=======================================================================

This part is only for advanced Unix users, or brave users.

The "make" command is a prerequisite to build some Perl modules.
Install the "make" command in case it is not already installed.

First let us install cpanminus locally in ~/perl5

  curl -L https://cpanmin.us | perl - -l ~/perl5 App::cpanminus local::lib

Then take this install into account in the current environment

  perl -I ~/perl5/lib/perl5 -Mlocal::lib        # just to see the variables
  eval `perl -I ~/perl5/lib/perl5 -Mlocal::lib` # doing the variables assigments

If you want to have always this setting in your environment then run the commands
  
  echo 'eval `perl -I ~/perl5/lib/perl5 -Mlocal::lib`' >> ~/.profile
  echo 'export MANPATH=$HOME/perl5/man:$MANPATH' >> ~/.profile
  cat ~/.profile 
  . ~/.profile

Now let's update the standard CPAN Perl module

  cpanm CPAN

The specific install part for imapsync begins, the script "prerequisites_imapsync"
helps to verify what is needed to install on your system

  curl -L http://imapsync.lamiral.info/INSTALL.d/prerequisites_imapsync > prerequisites_imapsync 
  sh prerequisites_imapsync

  cpanm Authen::NTLM
  cpanm IO::Tee 
  cpanm Mail::IMAPClient # File::Copy::Recursive?
  
  cpanm Unicode::String
  cpanm Sys::MemInfo
  cpanm File::Tail
  cpanm Proc::ProcessTable

  cpanm Test::MockObject

  cpanm Readonly
  cpanm Data::Uniqid
  cpanm JSON::WebToken

We're ready to install and test the latest imapsync

  curl -L http://imapsync.lamiral.info/imapsync > imapsync
  chmod +x imapsync
  ./imapsync
  ./imapsync --testslive 
  ./imapsync --tests

You can rerun "sh prerequisites_imapsync" 
to verify everything is ok:

  sh prerequisites_imapsync 

When everything is ok the script execution ends with this sentence
"All needed modules are already installed"

=======================================================================
E) Building imapsync binary on Darwin / Mac OS X
=======================================================================

cpanm Module::ScanDeps
cpanm PAR::Packer

pp -x -u -o imapsync.bin imapsync 

./imapsync.bin 
./imapsync.bin  --testslive
./imapsync.bin  --tests
./imapsync.bin  --module


=======================================================================
=======================================================================