README
The build_tools directory contains scripts used for building Mac and
Windows executables and packaging them in installers.

Do NOT use this directory for running these tools. If you do that, then
the output files might accidently get committed to the repo, and that is
not what we want.

--------------------------------------------------------------------------------
Instructions for Mac build:

  1) Install pyinstaller:

       % pip install pyinstaller

  2) Install dmgbuild:

       % pip install dmgbuild

  3) Set environment variable $GITHUB to point to the parent directory
     of your clone of the IV_Swinger GitHub repo, e.g.:

       % export GITHUB="$HOME/GitHub"

     Or to make it permanent (assuming you use bash):

       % echo 'export GITHUB="$HOME/GitHub"' >> ~/.bash_profile

  4) Update the version string in $GITHUB/IV_Swinger/python3/version.txt

  5) Complete all testing using straight Python (this assumes that
     you have installed all of the required Python packages):

       % cd $GITHUB/IV_Swinger/python3
       % python IV_Swinger2_gui.py

  6) Create a build folder/directory somewhere NOT under $GITHUB, e.g.:

       % mkdir $HOME/IV_Swinger2_build

  7) Run pyinstaller script in the build folder:

       % cd $HOME/IV_Swinger2_build
       % $GITHUB/IV_Swinger/build_tools/mac_run_pyi

       NOTE: this generates some warnings and errors. See the section
             "Acceptable Mac errors and warnings" below.

  8) Test the generated executable:

       % cd $HOME/IV_Swinger2_build/dist
       % open IV\ Swinger\ 2.app

  9) Apply generic code signature:
 
       % codesign --force --deep -s - IV\ Swinger\ 2.app

 10) Build the DMG with dmgbuild:

       % cd $HOME/IV_Swinger2_build
       % $GITHUB/IV_Swinger/build_tools/mac_build_dmg

 11) Test the DMG:

       % open *.dmg

       Follow instructions to install

 12) Test the installed app by launching from Applications folder

--------------------------------------------------------------------------------
Acceptable Mac errors and warnings

The mac_run_pyi script may generate the following, which are all OK:

 - Anything labeled "INFO:" is ok

 - WARNING: Hidden import "pkg_resources.py2_warn" not found!
 - WARNING: Hidden import "pkg_resources.markers" not found!
 - WARNING: Library Advapi32 required via ctypes not found
 - WARNING: Library setupapi required via ctypes not found
 - WARNING: Library Cfgmgr32 required via ctypes not found
 - WARNING: Library user32 required via ctypes not found
 - WARNING: Ignoring /System/Library/Frameworks/CoreFoundation.framework/CoreFoundation imported from (...) - only basenames are supported with ctypes imports!
 - WARNING: Ignoring /System/Library/Frameworks/IOKit.framework/IOKit imported from (...) - only basenames are supported with ctypes imports!
 - .../site-packages/setuptools/distutils_patch.py:25: UserWarning: Distutils was imported before Setuptools. This usage is discouraged and may exhibit undesirable behaviors or errors. Please use Setuptools' objects directly or at least import Setuptools first.

--------------------------------------------------------------------------------
Instructions for Windows build (Python 3):

NOTE: it is assumed that you already have python and pip installed as
      well as all of the python packages required to run IV_Swinger2_gui.py
      using straight Python (See README file in python3 directory).

  1) Install WiX, pyinstaller, BeautifulSoup4, and lxml:

       http://wixtoolset.org/releases/ (install latest)
         -> add %WIX%bin to your %path%
       pip install pyinstaller
       pip install beautifulsoup4
       pip install lxml

  2) Set environment variable %GITHUB% to point to the parent directory
     of your clone of the IV_Swinger GitHub repo, e.g.:

       set GITHUB=%HOME%\Documents\GitHub
       setx GITHUB %HOME%\Documents\GitHub

  3) Update the version string in %GITHUB%\IV_Swinger\python\version.txt

  4) Complete all testing using straight Python:

       cd %GITHUB%\IV_Swinger\python3
       python IV_Swinger2_gui.py

  5) Create a build folder/directory somewhere NOT under %GITHUB%, e.g.:

       mkdir %HOME%\IV_Swinger2_build

  6) Run the run_pyi.bat script in that folder:

       cd %HOME%\IV_Swinger2_build
       %GITHUB%\IV_Swinger\build_tools\run_pyi.bat

       NOTE: this generates some warnings and errors. See the section
             "Acceptable Windows errors and warnings" below.

  7) Test the generated executable:

       cd %HOME%\IV_Swinger2_build\dist\"IV Swinger 2"
       "IV Swinger 2.exe"

  8) Run the WiX "heat" utility like this:

       cd %HOME%\IV_Swinger2_build
       heat dir ".\dist\IV Swinger 2" -ag -sfrag -sreg -template product -out heat.wxs

       Now you have a file %HOME%\IV_Swinger2_build\heat.wxs

  9) Run the fix_heat_wxs.py script:

       python %GITHUB%\IV_Swinger\build_tools\fix_heat_wxs.py heat.wxs

 10) Run candle (WiX tool):

       candle IV_Swinger2_*.wxs

 11) Run light (WiX tool):

       light -b ".\dist\IV Swinger 2" -sice:ICE60 IV_Swinger2_*.wixobj

 12) Test the installer:

       msiexec /i IV_Swinger2_*.msi /l*v IV_Swinger2.log
     OR
       Find it with Windows Explorer and double-click it

 13) Test the installed app by launching from the Start Menu

--------------------------------------------------------------------------------
Acceptable Windows errors and warnings:

The run_pyi.bat script may generate the following, which are all OK:

 - Anything labeled "INFO:" is ok
 
 - ModuleNotFoundError: No module named 'win32com'
 - ModuleNotFoundError: No module named 'tornado'

 - WARNING: Hidden import "pkg_resources.py2_warn" not found!
 - WARNING: Hidden import "pkg_resources.markers" not found!

 - RuntimeError: The WebAgg backend requires Tornado.

--------------------------------------------------------------------------------