WSJT-X/doc/building on MS Windows.txt

Building WSJT-X on MS Windows
=============================

Here I describe my set up, you  may have other preferences due to your
favoured file system layout for  tools, utilities, and libraries. Many
variations are possible,  use this guide as a template.  The aim is to
provide an environment suitable for general development.

Prerequisite Tools and Libraries
================================

Here is an overview list, details are filled out below:

     * Qt Open Source Framework
     * Cmake build system generator
     * FFTW v3 DFT library
     * libusb usb device library
     * MSYS2 *nix like command line environment
     * Hamlib rig control library
     * Pkg Config Lite
     * Boost C++ libraries (see separate document)
     * portaudio library (used by map65)

Qt Framework
------------

At the  time of writing I  recommend using Qt v5.15.2  64-bit, v5.15.1
has a defect  that affects us so  is best avoided. You  need the MinGW
version  as we  do not  support  the MSVC  version  due to  lack of  a
suitable FOSS  Fortran complier. To  install the Qt developer  SDK you
should download the official Qt  on-line installer, this allows you to
install one or  more variants of the  Qt SDK and also  to maintain and
update the installation  at a later date. There are  many versions and
components within  versions available, you  only need the  base 64-bit
MinGW framework  for Qt  v5.15.2 and the  matching MinGW  8.1.0 64-bit
developer tools, other components can  be unchecked within the on-line
installer.  The  default install location  is C:\Qt which is  fine, do
not attempt  to move the  location of  the installed libraries  if you
decide you want it elsewhere,  the installer patches the libraries for
the installed location  and it is easier to  un-install and re-install
if you wish to change the installed location.

CMake
-----

Download  and install  a recent  version from  the official  CMake web
site. A  default installation is  fine. I am currently  using v3.18.4,
versions as old as v3.9 should work.

Other tools and libraries without installers
--------------------------------------------

For small  libraries that  don't have a  Windows installer  and change
often  I locate  them under  a directory  C:\Tools.  This  location is
arbitrary and just used to aggregate such items in one place, but this
document assumes that location so you may need to adjust paths etc. if
you use a different location.

FFTW v3 DFT library
-------------------

The   MS   Windows   builds   of  FFTW3   can   be   downloaded   from
http://www.fftw.org/install/windows.html.  The ZIP  archives for  this
package have  no directory structure  so create a directory  under C:\
Tools\ called fftw-3.3.5-dll64 and unzip  the archive there.  You only
need the 64-bit package.

libusb library
--------------

This library is available  from https://libusb.info/, download the .7z
archive  as  the  .zip  archive  does not  contain  the  libraries  we
require. Unzip this package into C:\Tools.

MSYS2
-----

This  utility is  available  from  https://www.msys2.org/. Follow  the
download, installation, and initial upgrading instructions there. Once
installed and  updated you will  need to install some  packages, these
are needed to provide the necessary  *nix tools and utilities to build
Hamlib from sources.

    pacman -S autoconf automake libtool make tar

Hamlib
------

There is  a fork of  the official Hamlib project  which we keep  up to
date with  the official project  master branch, we  recommend building
from the  'integration' branch, or  a suitable  tag on that  fork. The
fork is a git repository which can be cloned with this command:

    mkdir -p ~/src/sf/bsomervi
    cd !$
    git clone git://git.code.sf.net/u/bsomervi/hamlib hamlib
    cd hamlib
    git checkout integration

Next you must build Hamlib using the MinGW compiler tools bundled with
Qt. As you  will build Hamlib again when there  are updates you should
set  up  you  MSYS2  command  line  environment  for  this.  I  use  a
$HOME/.bash_profile file containing these lines:

    dll_paths_64bit=/c/Tools/libusb-1.0.23/MinGW64/dll:$HOME/local/hamlib/mingw64/release/bin
    export PATH=/c/Qt/Tools/mingw810_64/bin:$dll_paths_64bit:$PATH

Test the amended ~/.bash_profile file by opening a new MSYS2 shell and
typing:

    which gcc
    which libusb-1.0.dll

The first time you checkout the  Hamlib sources you must bootstrap the
configuration script,  this is done with  a script at the  root of the
Hamlib sources:

    cd ~/src/sf/bsomervi/hamlib
    ./bootstrap

Now you need to configure and build Hamlib from an MSYS2 shell. Create
a build directory outside of the  Hamlib sources you have just cloned,
then change working directory to that build directory.

    mkdir -p ~/build/hamlib/release
    cd !$
    ~/src/sf/bsomervi/hamlib/configure --enable-shared --disable-static \
        --prefix=$HOME/local/hamlib/mingw64/release \
	CFLAGS="-DNDEBUG -g -O2 -fdata-sections -ffunction-sections -I/c/Tools/libusb-1.0.23/include" \
	CXXFLAGS="-DNDEBUG -g -O2 -fdata-sections -ffunction-sections" \
	LDFLAGS="-Wl,--gc-sections" \
	LIBUSB_LIBS="-L/c/Tools/libusb-1.0.23/MinGW64/dll -lusb-1.0"

Then build and install the Hamlib package into a local directory:

    make & make install-strip

If you wish  you can make a debug configuration  build of Hamlib which
can be useful if you intended  to contribute to the Hamlib project, or
for tracking down issues:

    mkdir -p ~/build/hamlib/debug
    cd !$
    ~/src/sf/bsomervi/hamlib/configure --enable-shared --disable-static \
        --prefix=$HOME/local/hamlib/mingw64/debug \
	CFLAGS="-g -O0 -I/c/Tools/libusb-1.0.23/include" \
	CXXFLAGS="-g -O0" \
	LIBUSB_LIBS="-L/c/Tools/libusb-1.0.23/MinGW64/dll -lusb-1.0"
    make && make install

To update the Hamlib sources to the latest commit and rebuild:

    cd ~/src/sf/bsomervi/hamlib
    git pull
    cd ~/build/hamlib/release
    make & make install-strip
    cd ~/build/hamlib/debug
    make && make install

Note that  the WSJT-X CMake  build script  will not detect  an updated
build of the  Hamlib DLL, so to avoid using  an out-of-date Hamlib DLL
you should  delete the Hamlib  DLL (libhamlib-4.dll) from  your WSJT-X
release configuration  install tree  before rebuilding  and installing
WSJT-X after a Hamlib update.

Pkg Config Lite
---------------

This package allows the WSJT-X CMake configuration to locate and learn
the options needed to consume the  Hamlib package. You can download it
from  https://sourceforge.net/projects/pkgconfiglite/files/0.28-1/ and
unzip it into a convenient location, as with other ancillary tools and
libraries I put these under C:\Tools\.

portaudio
---------

This library  is only available as  sources so must be  built. It uses
autotools  and building  using  MinGW  tools from  an  MSYS2 shell  is
recommended. Ensure  your MSYS2 shell environment  (PATH) is correctly
set up for the MinGW tool chain you wish to build with, i.e. the MinGW
tools bundled with the Qt installation for 32-, or 64-bit as required.

Download    this    specific    version's   sources    tarball    from
http://files.portaudio.com/download.html , at the time of writing that
was  the pa_stable_v190600_20161030.tgz  file.  Unzip  and unpack  the
tarball in a suitable location like ~/src :

    cd ~/src
    tar xf ~/Downloads/pa_stable_v190600_20161030.tgz


Note that on Windows portaudio  will only build static libraries using
the standard configuration, we  prefer dynamic libraries for portaudio
as  users may  wish to  substitute a  build of  the library  with ASIO
support for personal  use (we cannot redistribute  binaries built from
proprietary closed source sources like the Steinberg ASIO SDK).

In order  to build  DLLs on  Windows the  configure script  requires a
patch as follows:

    sed -i -e 's/-luuid//g' ~/src/portaudio/configure

This removes  linker dependencies on the  MS uuid library since  it is
only  available as  a static  archive  and using  that would  disallow
shared library creation.

Out-of-source-tree builds are recommended, create a build directory in
a suitable location like ~/build and change working directory to it:

    mkdir -p ~/build/portaudio/mingw64
    cd !$

Configure and build and install the library in a suitable place (I use
~/local as a root directory for installed packages.

    ~/src/portaudio/configure --prefix=$(HOME)/local/portaudio/mingw64 \
       --with-winapi=wmme,directx,wdmks --disable-static --enable-shared CFLAGS=-DNDEBUG
    make && make install

Repeat for the 32-bit architecture if required, using a suitable MSYS2
environment for  the required  tool chain, different  build directory,
and install location.

Update your CMake  tool chain files to include  the install directory,
or directories, above.  I have something like this in  the 64-bit tool
chain files:

    # ...
    set (PORTAUDIODIR C:/Users/bill/local/portaudio/mingw64)
    # ...
    set (CMAKE_PREFIX_PATH ... ${PORTAUDIODIR} ...)
    #...

and similarly with  the 32-bit tool chain file  specifying the mingw32
portaudio installation root directory.

To run Debug configuration WSJT-X builds you will also need to add the
location of the portaudio DLL to your PATH environment variable, like:

   SET "Path=%UserProfile%\local\portaudio\mingw64\bin;%Path%"

Verify the setup with:

   WHERE libportaudio-2.dll