imapsync/README_Windows.txt

# $Id: README_Windows.txt,v 1.24 2021/06/15 10:29:45 gilles Exp gilles $
# 
# This is the README_Windows.txt file for imapsync 
# imapsync: IMAP syncing and migration tool.

=====================
 Imapsync on Windows
=====================

 There are two ways to install and use imapsync on Windows systems: A) or B).

 Standard users should take the A) way, the simplest way.

 Developers, or power users that want to build their own imapsync.exe
 or modify it, have to consider the B) way, the complex and powerful way.


---------------
A) Simplest way
---------------

A.0) Preamble for visual users looking for a visual tool.

 First, the visual thing I am talking about here is not the online visual
 interface I call /X that you might have seen and used at the URL
 https://imapsync.lamiral.info/X/
 This /X visual interface is not yet available on Windows as a service
 that you can install and use in your system.
 I plan to make a visual tool available on Windows but, for now,
 I encountered technical issues.

 So what visual thing am I talking about?
 
 Imapsync itself is not a visual tool. The visual tool is Notepad or
 any text editor. Many pure visual users have succeeded in using
 imapsync to transfer their email accounts. As you can guess, only
 the ones that tried have succeeded, so don't give up before
 trying at least once. Another assumption is that visual users can read.
 Let's go for some reading!

A.1) Get imapsync.

 Get imapsync at https://imapsync.lamiral.info/
 You'll then have access to a zip archive file named imapsync_1.977.zip
 where 1.977 is the imapsync release number.

A.2) Extract the zip file in a folder where you will work with imapsync.

 You can work on the Desktop since the zip file extraction creates
 a unique folder named imapsync_1.977/
 
 Do not unzip the archive in what is called a "system" directory since
 you may encounter permission issues.

Two-point to have in mind:
* You don't need to be an Administrator to unzip the zip archive.
* You don't need to be an Administrator to run imapsync.


A.3) Check the folder

 In the folder extracted imapsync_1.977 you see 7 files and 2 directories,
 which may be presented in a different order than the following, the order
 is not important anyway. The really important files to get your mailbox
 transfer job started in a few minutes are the first two files of the 
 following list:

 * README_Windows.txt     is the current file you are reading.
 * imapsync_example.bat   is a simple batch file example that you will copy and edit.

 * README.txt             is the imapsync general document.
 * FAQ.d/*                FAQs are a good read when something goes wrong.
 * sync_loop_windows.bat  is a batch file example for syncing many accounts.
 * file.txt               is an input file example for syncing many accounts.
 * imapsync.exe           is the imapsync 64bit binary. You don't have to run it directly.
 * imapsync_32bit.exe     is the imapsync 32bit binary. You don't have to run it directly.
 * Cook/                  is the directory to build imapsync.exe from its source, 
                          for the B) way and expert users.

 You can copy or rename the file imapsync_example.bat as you wish,
 as long as its extension remains ".bat", for example, mysync.bat

 On Windows systems, a file name ending with a .bat extension means "I am a batch script". 
 A batch script is a file containing commands, it's a program.
 Don't be afraid, a program can be very simple to modify and I hope 
 imapsync_example.bat is one of them.

 The batch scripts have to stay in the same directory as 
 imapsync.exe because of the way they call imapsync.exe.
 They use the string ".\imapsync.exe", so let them be in the same directory.

 You can change the path .\ to whatever you want if you understand what
 you are doing (you have to use a pathname from the script point of view).

 For the rest of this documentation, I assume you copied
 imapsync_example.bat to a file named mysync.bat

 If you don't know how to copy and rename a file then use imapsync_example.bat 
 itself, it's ok. The original file is still in the zip file in case
 you want to restart from scratch.

A.4) Edit the batch file

 This section describes how to edit the file mysync.bat to change 
 the example values with yours.
 
 To edit mysync.bat, you have to right-click on it and select "modify"
 in the list presented in the small window menu.

 Notepad or Notepadd++ are very good editor candidates to modify it.
 Notepad is already installed on any Windows system, Notepadd++
 is not usually installed but if you have it then use it.

 Office Word or any powerful text processor is NOT good for that job.
 Text processors transform files in a special format that is wrong to
 make them stay a good batch file, so don't use them!

 Files FAQ.txt and FAQ.d/* contain many tips and special options sometimes
 needed by specific imap software servers like Exchange, Office365, or Gmail.
 Those files are also available online at
 https://imapsync.lamiral.info/FAQ.d/
 You don't have to look into them unless you encounter problems.

A.5) Run the batch file

 To run imapsync with your values just double-click on the batch file mysync.bat

 There is no need to have administrator privileges to run imapsync.

 The run happens in a DOS window; usually, this window is black.


If imapsync.exe returns immediately with the ERRORLEVEL -1, it may be
because you have an Group Policy in place to prevent execution of 
programs in %TEMP%. Temporarily remove this restriction and imapsync 
will work as expected. Thanks to Walter H. for this input!
Technically imapsync.exe is an embedded Perl script with also Perl 
and many Perl modules glued together in an archive auto-extracted. 

A.6) Look at the sync running. 

 You can abort the sync at any time with a quick double ctrl-c, 
 ie hit ctrl-c twice within one second.
 
 A single ctrl-c will reconnect to both imap servers.
 You can also simply abort the sync by closing the DOS window,
 using the cross situated at the up-right corner.

 What you see in this DOS terminal is also put in a logfile located
 in the subdirectory LOG_imapsync/

A.7) Control what happened.

 When the sync is finished you can find the whole log file 
 of the output in the folder named "LOG_imapsync/".
 The logfile name is based on the launching date,
 hour, minute, second, milliseconds, plus the user1 and user2 parameters.
 For example, a file name can be
 LOG_imapsync\2019_11_29_14_49_36_514_tata_titi.txt

 There is one log file created for each run.
 The log file name is printed at the end of the imapsync run.

 IMPORTANT: When there is a problem, the problem is very often described
 at the end of the log file. It means you don't have to read all this
 bloody ununderstandable verbose logfile, just read the end first.


A.8) Loop on A.4 through A.7

 * A.4) edit the batch file
 * A.5) run the batch file
 * A.6) look at the run and the log file
 * A.7) control what happened.

 Loop on the process of editing, running, and controlling imapsync
 until you solve all issues and the sync is over.

A good sign that the sync went very well is when the nearly last lines are like:

" The sync looks good, all 123456 identified messages in host1 are on host2.
" There is no unidentified message
" Detected 0 errors

Congratulations!


------------
B) Hard way
------------

It is the hard way because it installs all software dependencies.
This is the way for modifying imapsync.exe if needed.

B.1) Install Perl if it isn't already installed.
  Strawberry Perl is a very good candidate
  http://strawberryperl.com/
  I use 5.30.1.1 (released 2019-11-22) but previous and later releases 
  should work as well (Perl 5.18 to 5.26 do).

B.2) Go into the Cook/ directory
B.3) Double-click build_exe.bat 

It should create a binary imapsync.exe in the current Cook/ directory.

B.4) Move imapsync.exe in the upper directory and follow instructions
     from A.3) to A.8)