INSTALL

    _____  ________  _______    __    __ 
   |     \|        \|       \  |  \  |  \
    \$$$$$ \$$$$$$$$| $$$$$$$\ | $$  | $$
      | $$   | $$   | $$  | $$  \$$\/  $$
 __   | $$   | $$   | $$  | $$   >$$  $$ 
|  \  | $$   | $$   | $$  | $$  /  $$$$\ 
| $$__| $$   | $$   | $$__/ $$ |  $$ \$$\
 \$$    $$   | $$   | $$    $$ | $$  | $$
  \$$$$$$     \$$    \$$$$$$$   \$$   \$$
                                                         
                                                         
                                                         
Installing JTDX
=================

Binary packages of JTDX are available from the project web site:

       https://jtdx.tech


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.9 or later is required to build JTDX

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 optionally requires  the libusb-1.0 library, if the
development   version  (libusb-1.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 JTX  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  JTDX. 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/p/jtdx/hamlib src
$ cd src
$ ./bootstrap
$ mkdir ../build
$ cd ../build
$ ../src/configure --prefix=$HOME/hamlib-prefix \
   --disable-static --enable-shared --without-readline \
   --without-indi --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
JTDX 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 git repository.

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


To build JTDX you will need CMake and asciidoc installed.

$ cd ~/jtdx-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 ~/jtdx-prefix/build
$ cmake -D CMAKE_PREFIX_PATH=~/hamlib-prefix \
   -D CMAKE_INSTALL_PREFIX=~/jtdx-prefix ../src
$ cmake --build .
$ cmake --build . --target install

this will install JTDX at ~/jtdx-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  JTDX. 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 JTDX  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  JTDX). 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/p/jtdx/hamlib src
$ cd src
$ git checkout integration
$ ./bootstrap
$ mkdir ../build
$ cd ../build
   ../src/configure --prefix=$HOME/hamlib-prefix \
   --disable-static --enable-shared \
   --without-indi --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
=================================

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
gcc9
fftw-3-single +gcc9
asciidoc
asciidoctor
libusb-devel

These are installed by typing:

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

Once complete you should have all the tools required to build JTDX.

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/p/jtdx/hamlib src
$ cd src
$ ./bootstrap

To build:

$ cd ~/hamlib-prefix/build
$ ../src/configure \
   --enable-shared \
   --disable-static \
   --disable-winradio \
   --prefix=$HOME/hamlib-prefix \
   --without-readline \
   --without-indi \
   --without-cxx-binding \
   CFLAGS="-g -O2 -mmacosx-version-min=10.13 -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`.


Qt
--
Preferable is install qt from macports.
sudo port install qt5


NOTE: As of Qt  v5.4 building Qt from source on Mac OS  X is no longer
necessary since the  Qt team have switched to using  the modern libc++
Standard    C++   Library    for    all    distributable   run    time
components. Instead you may simply  download a binary installer for OS
X 64-bit. The binary installer is here:

    http://www.qt.io/download

The    binary   Qt    distributions    prior   to    Qt   v5.4    from
http://www.qt.io/download unfortunately are built to use the libstdc++
C++ support  library, JTDX uses  a less geriatric C++  dialect 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        tarball        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-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.


JTDX
------
First fetch the source from the repository:

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

this links to the Git 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 master,  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 ~/jtdx-prefix/build
$ FC=gfortran-mp-9 \
   cmake \
   -D CMAKE_PREFIX_PATH="/opt/local/libexec/qt5;~/hamlib-prefix;/opt/local" \
   -D CMAKE_INSTALL_PREFIX=~/jtdx-prefix \
   -D CMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk \
   ~/jtdx-prefix/src

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

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 JTDX  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 JTDX application bundle into ~/jtdx-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 JTDX
==============================

To update to the latest sources type:

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


73