INSTALL

 __       __   ______      _____  ________      __    __ 
|  \  _  |  \ /      \    |     \|        \    |  \  |  \
| $$ / \ | $$|  $$$$$$\    \$$$$$ \$$$$$$$$    | $$  | $$
| $$/  $\| $$| $$___\$$      | $$   | $$ ______ \$$\/  $$
| $$  $$$\ $$ \$$    \  __   | $$   | $$|      \ >$$  $$ 
| $$ $$\$$\$$ _\$$$$$$\|  \  | $$   | $$ \$$$$$$/  $$$$\ 
| $$$$  \$$$$|  \__| $$| $$__| $$   | $$       |  $$ \$$\
| $$$    \$$$ \$$    $$ \$$    $$   | $$       | $$  | $$
 \$$      \$$  \$$$$$$   \$$$$$$     \$$        \$$   \$$
                                                         
                                                         
                                                         
Installing WSJT-X
=================

Binary packages of WSJT-X are available from the project web site:

       http://www.physics.princeton.edu/pulsar/K1JT/wsjtx.html


Building from Source
====================

On Linux systems  some of the prerequisite libraries  are available in
the mainstream distribution repositories. They are Qt v5, FFTW v3, and
the Boost  C++ libraries.   For MS Windows  see the  section "Building
from  Source on  MS  Windows" below.  For Apple  Mac  see the  section
"Building from Source on Apple Mac".

Qt v5, preferably v5.9 or later is required to build WSJT-X.

Qt v5  multimedia support, serial  port, and Linguist is  necessary as
well  as  the  core  Qt  v5 components,  normally  installing  the  Qt
multimedia development, Qt serialport development packages, and the Qt
Linguist  packages are  sufficient  to  pull in  all  the required  Qt
components and  dependants as a  single transaction.  On  some systems
the Qt  multimedia plugin  component is  separate in  the distribution
repository an it may also need installing.

The single precision FFTW v3  library libfftw3f is required along with
the  libfftw library  development  package.   Normally installing  the
library  development  package  pulls  in all  the  FFTW  v3  libraries
including the single precision variant.

The  Hamlib  library requires  the  readline  development package  and
optionally  requires  the  libusb-1.0-1 library,  if  the  development
version  (libusb-1.0-0-dev) is  available  Hamlib  will configure  its
custom USB device  back end drivers. Most rigs do  not require this so
normally you can choose not to  install libusb-1.0-dev but if you have
a SoftRock USB or similar SDR that uses a custom USB interface then it
is required.

The Hamlib  library is  required. Currently WSJT-X  needs to  be built
using a  forked version of the  Hamlib git master. This  fork contains
patches  not yet  accepted by  the Hamlib  development team  which are
essential for  correct operation of  WSJT-X. To build the  Hamlib fork
from sources something like the following recipe should suffice:

$ mkdir ~/hamlib-prefix
$ cd ~/hamlib-prefix
$ git clone git://git.code.sf.net/u/bsomervi/hamlib src
$ cd src
$ git checkout integration
$ ./bootstrap
$ mkdir ../build
$ cd ../build
$ ../src/configure --prefix=$HOME/hamlib-prefix \
   --disable-shared --enable-static \
   --without-cxx-binding --disable-winradio \
   CFLAGS="-g -O2 -fdata-sections -ffunction-sections" \
   LDFLAGS="-Wl,--gc-sections"
$ make
$ make install-strip

This will build a binary  hamlib package located at ~/hamlib-prefix so
you will need  to add that to your CMAKE_PREFIX_PATH  variable in your
WSJT-X build.  On Linux  that is  probably the only  path you  have on
CMAKE_PREFIX_PATH  unless  you  are   using  a  locally  installed  Qt
installation.

To get the  sources either download and extract a  source tarball from
the project web site or preferably fetch the sources directly from the
project's  subversion repository.

$ mkdir -p ~/wsjtx-prefix/build
$ cd ~/wsjtx-prefix
$ git clone git://git.code.sf.net/p/wsjt/wsjtx src

To build WSJT-X you will need CMake and asciidoc installed.

$ cd ~/wsjtx-prefix/build
$ cmake -D CMAKE_PREFIX_PATH=~/hamlib-prefix -DWSJT_SKIP_MANPAGES=ON \
  	-DWSJT_GENERATE_DOCS=OFF ../src
$ cmake --build .
$ cmake --build . --target install

The recipe  above will install  into /usr by  default, if you  wish to
install  in  you own  directory  you  can  add  a prefix-path  to  the
configure step like:

$ cd ~/wsjtx-prefix/build
$ cmake -D CMAKE_PREFIX_PATH=~/hamlib-prefix \
    -DWSJT_SKIP_MANPAGES=ON -DWSJT_GENERATE_DOCS=OFF \
    -D CMAKE_INSTALL_PREFIX=~/wsjtx-prefix ../src
$ cmake --build .
$ cmake --build . --target install

this will install WSJT-X at ~/wsjtx-prefix.


Building from Source on MS Windows
==================================

Because  building on  MS  Windows  is quite  complicated  there is  an
Software Development Kit available  that provides all the prerequisite
libraries and tools for building  WSJT-X. This SDK is called JT-SDK-QT
which is documented here:

http://physics.princeton.edu/pulsar/K1JT/wsjtx-doc/dev-guide-main.html

If you need to build Hamlib rather than use the Hamlib kit included in
the  JT-SDK the  following recipe  should help.  Reasons for  building
Hamlib from source might include picking up the very latest patches or
building a different branch that you wish to contribute to.

Hamlib optionally depends upon  libusb-1.0, see "Building from Source"
above  for more  details.   If you  wish to  include  support for  the
optional  custom  USB  Hamlib  rig   drivers  then  you  must  install
libusb-1.0 before  building Hamlib. The  package may be  obtained from
http://libusb.info/,  install   it  in  a  convenient   location  like
C:\Tools.

On Windows there is a complication in that the compilers used to build
Qt  and WSJT-X  are the  MinGW ones  bundled with  the Qt  package but
Hamlib needs to be build from an MSYS shell with the tools required to
build  an autotools  project. This  means that  you need  to tell  the
Hamlib configuration  to use  the Qt bundled  MinGW compilers  (if you
don't  then  the  thread  support   library  use  by  Hamlib  will  be
incompatible  with that  used by  Qt and  WSJT-X). So  on Windows  the
Hamlib build recipe is something like:

In an MSYS shell:-

$ mkdir ~/hamib-prefix
$ cd ~/hamlib-prefix
$ git clone git://git.code.sf.net/u/bsomervi/hamlib src
$ cd src
$ git checkout integration
$ ./bootstrap
$ mkdir ../build
$ cd ../build
   ../src/configure --prefix=$HOME/hamlib-prefix \
   --disable-shared --enable-static \
   --without-cxx-binding --disable-winradio \
   CC=<path-to-Qt-MinGW-tools>/gcc \
   CXX=<path-to-Qt-MinGW-tools>/g++ \
   CFLAGS="-g -O2 -fdata-sections -ffunction-sections -I<path-to-libusb-1.0>/include" \
   LDFLAGS="-Wl,--gc-sections" \
   LIBUSB_LIBS="-L<path-to-libusb-1.0>/MinGW32/dll -lusb-1.0"
$ make
$ make install

NOTE: <path-to-Qt-MinGQ-tools>  should be substituted with  the actual
path   to  your   Qt   bundled  tools   e.g  on   my   system  it   is
C:\Tools\Qt\Tools\mingw530_32\bin

NOTE: <path-to-libusb-1.0> should be  substituted with the actual path
to  your libusb-1.0  installation directory  e.g. on  my system  it is
C:\Tools\libusb-1.0.20

This   will    leave   a   Hamlib   binary    package   installed   at
c:/Users/<user-name>/hamlib-prefix which  is what needs to  be on your
CMAKE_PREFIX_PATH. On  Windows you  almost certainly  will be  using a
CMake tool chain  file and this is  where you will need  to specify the
Hamlib binary location as one of the paths in CMAKE_PREFIX_PATH.


Building from Source on Apple Mac
=================================

These instructions are adapted from my Evernote page at:

    https://www.evernote.com/pub/bsomervi/wsjt-xmacbuilds

There are several  ways to get the required GNU  and other open source
tools and libraries installed, my preference is MacPorts because it is
easy to use and does everything we need.

You  will need  Xcode, MacPorts,  CMake  and, Qt.   The Xcode  install
instructions are included in the MacPorts documentation.

MacPorts
--------
Install MacPorts from instructions here:

    http://www.macports.org/install.php

More detailed instructions are available in the documentation:

    https://guide.macports.org

The ports that need to be installed are:

autoconf
automake
libtool
pkgconfig
texinfo
gcc5
fftw-3-single +gcc5
asciidoc
libusb-devel

These are installed by typing:

$ sudo port install autoconf automake \
   libtool pkgconfig texinfo gcc5 asciidoc \
   fftw-3-single +gcc5 libusb-devel

Once complete you should have all the tools required to build WSJT-X.

Uninstalling MacPorts
---------------------
If at some point  you wish to remove the ports  from your machine. The
instructions are here:

    https://guide.macports.org/#installing.macports.uninstalling .

Hamlib
------
First fetch hamlib from the repository, in this case my fork of Hamlib
3 until the official repository has all the fixes we need:

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

The integration  branch is my system  testing branch which has  all my
latest published changes.

To build:

$ cd ~/hamlib-prefix/build
$ ../src/configure \
   --enable-static \
   --disable-shared \
   --disable-winradio \
   --prefix=$HOME/hamlib-prefix \
   CFLAGS="-g -O2 -mmacosx-version-min=10.7 -I/opt/local/include" \
   LIBUSB_LIBS="-L/opt/local/lib -lusb-1.0"
$ make
$ make install-strip

The   above  commands   will  build   hamlib  and   install  it   into
~/hamlib-prefix. If `make install-strip` fails, try `make install`.


CMake
-----
Although CMake  is available via MacPorts  I prefer to use  the binary
installer  from cake.org  as  the MacPorts  port  doesn't include  the
graphical CMake tool cmake-gui which I find quite useful.

Fetch    the    latest    CMake     universal    64-bit    DMG    from
http://www.cmake.org/download/  open the  DMG then  drag and  drop the
application bundle onto the supplied /Applications link.

To  complete  the  install  process  you need  to  run  the  CMake-gui
application as root from a terminal shell as follows:

$ sudo "/Applications/CMake.app/Contents/MacOS/cmake" --install

that installs  the CMake command  line tools  which you can  verify by
typing into a terminal window:

$ cmake --version

If the install command above fails  with a "No such file or directory"
error, that probably means that /usr/local/bin does not exist. You can
create it correctly with the following commands:

$ sudo mkdir -p /usr/local/bin
$ sudo chmod 755 /usr/local/bin
$ sudo chgrp wheel /usr/local/bin

and then retry the install command.


Qt
--

Download the latest on-line installer package from the Qt web site and
isntall the latest Qt stable version development package.


WSJT-X
------
First fetch the source from the repository:

$ mkdir -p ~/wsjtx-prefix/build
$ cd ~/wsjtx-prefix
$ git clone git://git.code.sf.net/p/wsjt/wsjtx src

this links to the Subversion repository in a read-only fashion, if you
intend to  contribute to the project  then you probably want  to get a
developer login  and use a read-write  checkout. Even if you  don't it
can be upgraded at a later date.

The checkout  is of  the latest  code on the  project trunk,  i.e. the
development  branch. You  can easily  switch the  checkout to  another
branch  or  even  a  tag  if  you want  to  build  a  prior  published
generation. For now  we will build the latest  development sources. To
configure:

$ cd ~/wsjtx-prefix/build
$ FC=gfortran-mp-5 \
   cmake \
   -D CMAKE_PREFIX_PATH="~/Qt/5.9/clang_64;~/hamlib-prefix;/opt/local" \
   -D CMAKE_INSTALL_PREFIX=~/wsjtx-prefix \
   -D CMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk \
   ~/wsjtx-prefix/src

Substitute the  Mac OS X SDK  version you have installed  in the above
command if you have a different version from 10.11.

The CMAKE_PREFIX_PATH variable specifies where CMake should look first
for other packages, the two  elements may be different depending where
you have installed Qt and what version you have (~/local/qt-macx-clang
if  you have  built  Qt from  sources  as described  above  in the  Qt
section) and where you installed  Hamlib (i.e.  the --prefix configure
option above in the Hamlib section).

If you already have the fftw3-dev  package installed on your system it
may well get selected in preference to  the one you built above in the
MacPorts installation.  It is  unlikely that  a prior  installation of
libfftw3f is  correctly configured  for use in  a WSJT-X  package, the
CMAKE_PREFIX_PATH above  is augmented  with the  MacPorts installation
location  (/opt/local)  to  ensure  the  correct  libfftw3f.dylib  and
headers are located.

To build:

$ cmake --build .
$ cmake --build . --target install

which installs the WSJT-X application bundle into ~/wsjtx-prefix


Updating and Rebuilding Hamlib
==============================

From  time  to time  new  fixes  will be  pushed  to  the Hamlib  fork
repository integration branch. To pick them up type:

$ cd ~/hamlib-prefix/src
$ git pull

To rebuild hamlib with the changed sources:

$ cd ~/hamlib-prefix/build
$ make
$ make install-strip


Updating and Rebuilding WSJT-X
==============================

To update to the latest sources type:

$ cd ~/wsjtx-prefix/src
$ git pull
$ cd ~/wsjtx-prefix/build
$ cmake --build .
$ cmake --build . --target install


73
Bill
G4WJS.