#!/bin/cat
# $Id: INSTALL.Darwin.txt,v 1.43 2024/11/14 13:25:25 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 with MacPorts
E) Installing imapsync script on Darwin / Mac OS X the way I do
F) Building imapsync binary on Darwin / Mac OS X


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

There is two standalone imapsync binaries for Mac OS X 
called "imapsync_bin_Darwin_i386" and "imapsync_bin_Darwin_x86_64" 
(without the quotes), avavailable in the compressed tarball called 
imapsync-2.290.tgz where 2.290 is the imapsync version number. 
Those binaries are not multi-architectures so they may not work 
on your system. They are the Mach-O i386 executable and the 
Mach-O 64-bit x86_64 executable.

The compressed tarball can be found at
https://imapsync.lamiral.info/dist/

Here are two direct links to those binaries:
https://imapsync.lamiral.info/dist/imapsync_bin_Darwin_i386
https://imapsync.lamiral.info/dist/imapsync_bin_Darwin_x86_64

There is no binary for the M1 processor. It's because I don't have 
a M1 host so I can't compile an imapsync M1 binary. If your system
is an M1 one, you have to install imapsync with brew or macports. 
See C) and D) below to achieve this.

Now, I'm going to explain the Mac installation, if you're lucky 
with the architecture. Anyway, what I'm going to explain here 
will help you if you install imapsync by another way.

Download the tarball imapsync-2.290.tgz
A direct link is 
https://imapsync.lamiral.info/dist2/imapsync-2.290.tgz

I suppose this tarball imapsync-2.290.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 your login name.

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

Untar the tarball:

  cd  # it should bring you to your $HOME directory
  pwd # it should show you that you are in your $HOME directory
  tar xzvf imapsync-2.290.tgz # it will extract imapsync archive in the current directory

In case the last command fails, it means the tarball file called imapsync-2.290.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.290/ 
Go into the directory imapsync-2.290 with the command:

  cd imapsync-2.290


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

  ./imapsync_bin_Darwin_x86_64


If it doesn't work, try the other binary imapsync_bin_Darwin_i386

  ./imapsync_bin_Darwin_i386

If it doesn't work, bad luck, you'll have to see C) and D) below.

To go further, perform a complete test with two real IMAP server
accounts of mine:  

  ./imapsync_bin_Darwin_x86_64 --testslive

If this sync works fine then imapsync_bin_Darwin_x86_64 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_x86_64"
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_x86_64 \
    --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_x86_64 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_x86_64
After this first launch, the security asks to authorize the unknown 
developer program. Setup the root of the imapsync_bin_Darwin_x86_64 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
=======================================================================

To install brew on your system, see https://brew.sh/ 

Once brew is installed on your system, install imapsync 
with the command:

  brew install imapsync

See more details at 
https://formulae.brew.sh/formula/imapsync

Once imapsync installed, do a real test with my 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 with MacPorts
=======================================================================

To install MacPorts on your system, see 
https://www.macports.org/install.php

Once MacPorts is installed on your system, install imapsync 
with the command (sudo is not needed if you're root):

  sudo port install imapsync

or

  port install imapsync # if you are already user root.

See more details at 
https://ports.macports.org/port/imapsync/

Once imapsync installed, do a real test with my IMAP 
server test.lamiral.info:

  imapsync --testslive


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

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

First, you need to install or activate XCode:

  sudo xcodebuild -license


The "make" command is also 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

For some modules like JSON::WebToken you might need to use 
the --force option when the build fails because of some 
failed tests. It's ok to use the --force Luke.

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"

=======================================================================
F) 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


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