WSJT-X/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 and FFTW v3.
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.1 or later is required to build WSJT-X.

Qt v5 multimedia  support and serial port is necessary  as well as the
core  Qt   v5  components,  normally  installing   the  Qt  multimedia
development  package   and  Qt  serialport  development   package  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 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
     mkdir ../build
     cd ../build
     ../src/autogen.sh --prefix=$HOME/hamlib-prefix \
          --disable-shared --enable-static \
          --without-cxx-binding --disable-winradio \
          CFLAGS="-fdata-sections -ffunction-sections" \
          LDFLAGS="-Wl,--gc-sections"
     make
     make install

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.  The  project svn  repository has  a
non-standard layout  in that the WSJT-X  project is not on  the trunk,
instead the main code line is in a branch at ^/branches/wsjtx

     mkdir -p ~/wsjtx-prefix/build
     cd ~/wsjtx-prefix
     svn checkout svn://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx src

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

     cd ~/wsjtx-prefix/build
     cmake -D CMAKE_PREFIX_PATH=~/hamlib-prefix ../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 \
         -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.

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
    mkdir ../build
    cd ../build
    ../src/autogen.sh --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="-fdata-sections -ffunction-sections" \
        LDFLAGS="-Wl,--gc-sections"
    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\mingw48_32\bin

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
gcc49
fftw-3-single +gcc49
asciidoc

These are install by typing:

    sudo port install autoconf automake \
        libtool pkgconfig texinfo gcc49 asciidoc \
        fftw-3-single +gcc49

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

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

You need  to make one  small change  to the sources  to build on  OS X
using the MacPorts tools, here is a sed command to make the change:

     sed -i.orig '/libtoolize/s/lib/glib/' autogen.sh

To build:

    cd ~/hamlib-prefix/build
    ../src/autogen.sh \
       --enable-static \
       --disable-shared \
       --disable-winradio \
       --prefix=$HOME/hamlib-prefix
    make
    make install-strip

The above commands will build hamlib and install it into ~/hamlib-prefix


Qt
--
The   binary    Qt   distributions    from   http://www.qt.io/download
unfortunately  are built  to use  the libstdc++  C++ support  library,
WSJT-X uses  a less  geriatric C++  dialet which  uses the  libc++ C++
support  library.  This   means  that  you  need  to   build  Qt  from
sources. This is not difficult but does take some time.

Download       the      Qt       source       tar      ball       from
http://www.qt.io/download-open-source/,  the link  is  about half  way
down the page, you want the full  sources tar ball shown as a 'tar.gz'
link.

Unpack the sources and cd into the top level directory then type:

$ ./configure -prefix ~/local/qt-macx-clang -opensource \
    -confirm-license -platform macx-clang -silent -nomake tests \
    -nomake examples -sdk macosx10.10 -skip qtwebkit \
    -skip qtwebkit-examples -skip qtquick1 -skip qtconnectivity \
    -skip qtlocation -skip qtsensors -skip qtscript \
    -skip qtwebsockets -skip qtwebengine -skip qtwebchannel \
    -skip qtwayland -skip qtquickcontrols -skip qtdeclarative \
    -skip qtxmlpatterns -skip qtenginio
$ make -j4
$ make install

If you are building on 10.8 or  don't have the 10.10 Mac SDK (Xcode 6)
available, you can substitute '-sdk macosx10.9' above.

The build above will take a few hours to complete.


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 application
as root from a terminal shell:

    sudo /Applications/CMake.app/Contents/MacOS/CMake

in the CMake application choose  "Tools->Install For Command Line Use"
from the menu and then click the "Install Command Line Links".


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

    mkdir -p ~/wsjtx-prefix/build
    cd ~/wsjtx-prefix
    svn checkout svn://svn.code.sf.net/p/wsjt/wsjt/branches/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-4.9 \
    cmake \
        -D CMAKE_PREFIX_PATH="~/local/qt-macx-clang;~/hamlib-prefix;/opt/local" \
        -D CMAKE_INSTALL_PREFIX=~/wsjtx-prefix \
        ~/wsjtx-prefix/src

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 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
    svn update
    cd ~/wsjtx-prefix/build
    cmake --build .
    cmake --build . --target install


73
Bill
G4WJS.