1. Overview

The WSJT family of programs for weak-signal amateur radio communication includes WSJT, WSPR, MAP65, WSJT-X, and WSPR-X. User interfaces for WSJT and WSPR are written in Python. User interfaces for MAP65, WSJT-X, and WSPR-X are written in C++ and use the Qt5 framework. The build process, when the JTSDK(s), is similar for all 5 applications. Most number-crunching in all of the WSJT programs is done in Fortran.

2. Environment Setup

Before you can start developing WSJT applications, you must first set up your environment. The WSJT Developers Guide will use the respective SDK on Windows and /home/$USER/jtsdk plus build scripts on Linux.

The Containment Area Provides:
  • A fixed structure to work from

  • Provides system independent build tools

  • Produce repeatable results

  • Create an experimental area to test builds

  • Allows full testing without system installation

  • Provide build methods for non-developer testing

Windows Environment

The SDK provides the containment, plus it includes required tools to build a particular application and in some cased, several sub-elements within the particular application. Details of each kit can be found in their section.

Linux Environment

The containment area is /home/$USER/jtsdk which will house the src (source files), build and installation folders. The Linux SDK is under revision at the time of this writing. The end goal is to provide a distribution package that installs all the needed development and runtime packages, plus provide a series of scripts to build the various aspects of each application.

2.1. General Comments

  • When using any of the SDKs, you should not have to install any system level software packages.

  • All 5 main stream applications ( WSJT, WSJT-X, WSPR, WSPR-X and MAP65 ) can be built using the appropriate SDK.

  • If you have one or more required packages already installed on the host system, the SDK will not interfere with your System Paths or use System Applications to perform builds. This is to ensure no cross talk between tools chains or libraries creep into the builds.

  • This also helps the developers troubleshoot issues if they arise, as it provides for a consistent base from which to work.

2.2. JTSDK-DOC

  • JTSDK-DOC contains: Subversion, GNU Tools and scripts to build all WSJT Documentation.

  • Data-URI ( single file ) builds are only possible on Linux/Mac, as the the builds require a full Python27 implementation for base64 encoding. If you need a single file version of a document to accompany a package, post on a web-site, etc, the Linux builds system can build all documentation the same as Windows.

  • For build details, see JTSDK-DOC.

images/jtsdk-doc-main.png
Figure 1. JTSDK-DOC Main Menu

2.3. JTSDK-PY

  • JTSDK-PY contains Python3 + Modules, Subversion, Mingw32, GNU Tools and scripts required to build WSJT and WSPR.

  • For build details, see JTSDK-PY.

images/jtsdk-py-main.png
Figure 2. JTSDK-PY Main Menu

2.4. JTSDK-QT

  • JTSDK-QT contains QT5, CMake, Subversion, FFTW3, Mingw48_32, GNU Tools, hamlib-1.2, Hamlib-3 and scripts to build WSJT-X, WSPR-X and MAP65.

  • For build details, see JTSDK-QT.

images/jtsdk-qt-main.png
Figure 3. JTSDK-QT Main Menu

2.5. Path Configuration

The following paths are used throughout The WSJT Developers Guide.

WINDOWS
  • Scripts and final builds will under:

    • C:\JTSDK-DOC

    • C:\JTSDK-PY

    • C:\JTSDK-QT

  • Final builds end in the base %BASE_PATH%\%APP_NAME%

  • Example: C:\JTSDK-QT\wsjtx

LINUX
  • Souorce, Build and Install folders are in:

    • /home/$USER/jtsdk/$APPNAME

  • Support packages, ( Hamlib3, Pmw, etc ) will reside in the top level of JTSDK. This is to prevent issues with system level package installations, for example:

    • /home/$USER/jtsdk/hamlib3

    • /home/$USER/jtsdk/pmw

  • Additional packages, if needed, will be added in the same manner.

Tip /home/$USER/jtsdk is recommended, and used in this guide. This keeps all WSJT Build related activity together. For system where a package installer is available, the actual scripts will reside at the system level, and updated through the Distro Package Manager.

3. Windows SDK

Setup and installation is straight forward. Each SDK is a self extracting 7z compressed file.

Warning The current update method for each SDK is through JTSDK-DOC, as such, is a mandatory install.

3.1. Download

JTSDK-DOC

Download

JTSDK-PY

Download

JTSDK-QT

Download

Omni-Rig

Download ( For WSJT-X CMake Builds Only )

Hamlib3

See Hamlib3 Special Instructions

3.2. Install

Warning If you choose to install an SDK in a different location from the recommendation, you will need to reconfigure it, basically, rebuild the SDK from scratch.
  • Double Click or Right Click and Open the download

  • Change path to: C:\

  • Click the Extract Button

images/7z-extract.png
Figure 4. Self Extracting 7z File
  • Open a Windows CMD Terminal, then type,:

  • You can also browse to the env file, and double click

*For JTSDK-DOC*
C:\JTSDK-DOC\jtsdk-docenv.bat

*For JTSDK-PY*
C:\JTSDK-PY\jtsdk-pyenv.bat

*For JTSDK-QT*
C:\JTSDK\jtsdk-qtenv.bat

3.3. Update

To update JTSDK-PY, JTSDK-QT, or JTSDK-DOC you must install JTSDK-DOC and perform a check-out. Developer check-out is not required, however, if you intend to work on Documentation, use your Developer account v.s. Anonymous so you can ( check-in ) any edits you have made.

Checkout & Update
  • If you need to check-out first:

  • Open Windows CMD Terminal, and Type:

C:\JTSDK-DOC\jtsdk-docenv.bat

svn co svn://svn.code.sf.net/p/wsjt/wsjt/branches/doc

then type,

update
  • If you already have a checkout:

  • Open Windows CMD Terminal, and Type:

C:\JTSDK-DOC\jtsdk-docenv.bat

svn update

then type,

update
  • At this point, all three SDKs should be up to date, if installed.

  • A successful update should look similar to:

images/jtsdk-update.png
Figure 5. Master Script Update

3.4. Hamlib3 Build

Hamlib3 Special Build Instructions

As of _WSJT-X v1.4.0, as custom version of Hamlib3 is required. At some point, after official release from the Hamlib developers, we will shift all apps using Hamlib 1.2.15 to Hamlib3. A current version of Hamlib3 is now provided by JTSDK-QT and updated on occasion by JTSDK-DOC. Unless asked by one of the developers, you should not have to build Hamlib3 from source, but, a means to do so is outlined below.

Building packages with MinGW on Windows is not trivial. However, following the steps outlined below should produce a valid Hamlib3 build.

Important It is important to note that, due to the thread model differences between MSYS/MinGW_32 and Qt5 MinGW_48_32, you must use the Qt5 Tool Chain to build Hamlib3. The following instructions should build the binaries without much trouble.

MSYS is not included as part of Windows JTSDK v1.0 series. The following packages and associated build-script have been tested, and currently employed to build Hamlib3 present in JTSDK-QT.

These instructions are still being tested, but have provided stable builds when using the MSYS form the link below, and the build script.

Be forewarned, the script will install the newly build Hamlib3 to your JTSDK-QT\hamlib3 directory. If for whatever reason, you want to revert to the version provided by the (SDK), simply delete the folder, and update from JTSDK-DOC

Custom Hamlib3 Build With MSYS
SF Site

MSYS Download

Download File

msys+7za+wget+svn+git+mercurial+cvs-rev13.7z 2013-05-15

  • Extract to: C:\msys32

  • Browse to C:\msys32\msys and run the msys.bat shortcut.

  • You may want to close, then re-open the msys.bat after your first run, as the batch file creates all the required user profiles.

  • Re-Open C:\msys32\msys\msys.bat

  • At the log in prompt, type the following command (all on one line):

svn export --force https://svn.code.sf.net/p/wsjt/wsjt/branches/doc/dev-guide/scripts/build-hamlib.sh
Important This next step, depending on your Single Core CPU speed, can take a long time to perform, upwards for 5 to 7 minutes.
  • At the prompt, type: ./build-hamlib.sh

  • After successful completion of the build, you should have a new marker in C:\JTSDK-QT\hamlib3 that says something like: build-date-<date>, where date is the date from your Windows Date and Time.

  • From this point, build WSJT-X as you normally would.

3.5. OmniRig Install

OmniRig Special Instructions
Important OmniRig is special requirement to build WSJT-X using CMake. A binary installer is included with each SDK under C:\JTSDK-*\tools. Alternatively, you can download and install the latest from Afreet Software, Inc.
To Install
  • OmniRig Download

  • Extract .zip file and run the .exe file.

  • No other actions should be required.

To Uninstall
  • OmniRig provides an Uninstaller

  • Start >> Programs >> Omni-Rig >> Uninstall Omni-Rig

3.6. Uninstall

  • Delete (C:\JTSDK-DOC) , (C:\JTSDK-PY) or (C:\JTSDK-QT)

  • Nothing is installed to the system or registry

4. Linux SDK

At the time of this writing, the Linux SDK is still being writting. As development continues, updated will be added the the The WSJT Developers Guide.

4.1. Source Install

A source package will be provided to build the SDK components on systems that do not have a package installer. The installation method will employ a simple ( ./configure, make && make install ).

Package dependency lists will be provided, but it will be up to the user to ensure all build dependencies are met. General use tools such as Grep, Awk, Autotools, etc will be tested by the configure script to ensure the installation can occur.

4.2. Debian Install

A Debian package installer ( .deb ) will be provided by way of a Personal Package Archive (PPA), with the hopes it will eventually be included in Debian proper. This will allow for normal package installation by the system package manager ( apt-get, aptitude, Gdebi, etc).

5. Source Code

All source code for the WSJT programs is available through an open-source repository known as SourceForge, under control of the version-control program Subversion. Subversion is included in all three Software Development Kits (SDK). There is no need to install Subversion if you intend to build applications or documentation using the (SDKs).

You can browse the organization of files in the repository here. Code for program WSJT lies in the trunk directory, while code for the other programs is found in …/branches/map65, …/branches/wsjtx, and …/branches/wsprx. Various experimental branches may also exist, and snapshots of code for certain released program versions may be obtained from the …/tags directory.

Warning Please note: the HEAD of the SVN repository for any of these programs is likely to be an active development branch. There is no guarantee that a build from every revision will be successful, nor that it will provide a stable executable program.

5.1. Checkout Methods

There are two primary methods for checking out source code, Anonymous and Developer. Additional checkouts are provided by way of Release Candidates and Tagged Releases.

5.2. Anonymous

Anonymous checkouts allow you to build all documentation and applications using the same methods as the developers, however, you cannot check-in your local updates to the repository.

Each (SDK) has short-cuts built-in for Anonymous check-outs. For example, to check-out WSJT, from the JTSDK-PY environment, type:

checkout wsjt

You can also manually check-out WSJT, using

svn co https://svn.code.sf.net/p/wsjt/wsjt/trunk

5.3. Developer

In order to use the developer check-out or check-in process

  • Create a SourceForge User Account

  • Email K1JT to be added to the Developer List.

Then, using WSJT as the example:

svn co https://user@svn.code.sf.net/p/wsjt/wsjt/trunk

Substitute your SourceForge username for user.

Tip Due to the variations in user names, developer check-out short-cuts are not possible, and must be manually entered.

5.4. Release Candidates

Often, release candidates (RC) are provided for Alpha or Beta testing. Where feasible, the (SDK) provides a method of build for each candidate.

The posted (RC) is tested against the (SDK) and should perform the build correctly. Back-porting, due to the many variables involved, is not possible at this time. If you need an older version of a particular application, the best advice would be to use a previously posted binary installer or the Tagged Branch.

Release Candidate Locations (URLs):

The following uses WSJT-X as an example. Note the URL differences. At the time of this writing, the current release candidate is WSJT-X v1.4 RC2. Pulling the release candidate branch will get you the Next (RC) in the branch, in this case (RC3), not (RC2). To pull Tag: WSJT-X v1.4 RC2, use the Tagged RC2 Branch.

Base URL: https://svn.code.sf.net/p/wsjt/wsjt/branches/

../wsjtx-1.4 ..: would pull WSJT-X v1.4 (RCx) next release version
../wsjtx ......: would pull WSJT-X v1.5 (RC1) devel version

5.5. Tagged Releases

A tagged version of a particular application is frozen, both in terms of the tool set used to build it, and the feature set it provides. Additional bug fixes or feature enhancements are sent upstream to the development trunk or branch. As such, the respective (SDK) may or may not be able to re-build historical tagged branches correctly. Future releases of the respective (SDK) may allow for this type of regression / back-porting activity.

Important In general, unless you have a specific need for an earlier version, you should always use the latest tagged release version for a given application.
Base URL: https://svn.code.sf.net/p/wsjt/wsjt/tags

../wsjtx-1.4.0-rc2 ..: would pull WSJT-X v1.4 (RC2)

6. Build Matrix

While there may be more than one build option per application, the primary method is used to distribute release versions, as such, should be up to date with the latest code changes. The WSJT Developers Guide uses the primary build method in all JTSDKs and build-scripts, as such, should provide fairly stable builds.

6.1. Windows

The following matrix outlines the Windows primary build method for each application.

Table 1. Windows Build Matrix: x = Primary, o = Optional
Method Docs WSJT WSJT-X WSPR WSPR-X MAP65

CMake



x


x

x

Qmake



o


o

o

Makefile


x


x



Script

x

x

x

x

x

x

Comments
JTSDK-DOC

( WSJT Documentation )

  • Build scripts

JTSDK-PY

( WSJT WSPR )

  • Makefile + build scripts

JTSDK-QT

( WSJT-X WSPR-X MAP65 )

  • CMake + build scripts

  • QtCreator + Qmake + Makefile.MinGW (optional)

6.2. Linux

The following matrix outlines the Linux primary build method for each application.

The Linux build methods are being updated by the developers as time allows. Expect frequent updates and build anomalies as these updates progress.

Table 2. Linux Build Matrix: x = Primary, o = Optional
Method Docs WSJT WSJT-X WSPR WSPR-X MAP65

CMake



x


x

x

Qmake



o


o

o

Makefile


x


x



Script

x

x

x

x

x

x

Comments

Long term, the goal is to improve the CMake build methods for WSPR-X and MAP65 and add CMake build methods for WSJT and WSPR, eventually having CMake as the primary build method. Qmake + Makefile.linux will still be maintained to all for QtCreator builds.

WSJT and WSPR require significant Python updates from Python 2.7 to Python 3.x plus new modules in order to build properly. Care should be taken when adding Python3 + modules to an existing Python 2.7 Linux distribution. Using Python VENV is a safe approach one may consider.

Build Status
WSJT

Methods being updated. Requires Python3 + New Modules

WSJT-X

Build fine with CMake, requires Hamlib3

WSPR

Methods being updated. Requires Python3 + New Modules

WSPR-X

Builds fine with CMake, requires CMakefiles.txt modification

MAP65

Builds with CMake.

7. Package Matrix

Generally, the package requirements are the same for Windows, Linux and OS X. The major differences between them is the Windows compiler requirement, Mingw32 or Mingw48_32 v.s. the standard GNU tools available in most all Linux or OS X.

For Windows, it is possible, through the use of MSYS or Cygwin to compile the required dependencies. However, it is highly recommended to use the Windows JTSDKs or pre-built binary installers from the respective developers.

For Linux and OS X, with very few exceptions, all of the packages are available through their respective package managers, as such, is the recommended method of installation. Other than those distributions that use compiling as their primary install method (Arch, Gentoo, Slackware, and Friends), compiling dependencies is unnecessary in most cases. If you need to compile a dependency from source, consult the respective website or details from within the package. Most are fairly straight forward.

7.1. Windows

The following matrix outlines the Windows development package requirements for each application, including documentation.

Table 3. Windows Package Matrix: x = Required, o = Optional
Package Docs WSJT WSJT-X WSPR WSPR-X MAP65

CMake



x


x

x

FFTW3F


x

x

x

x

x

Hamlib



o

x

x


Hamlib3



x

o

o


Mingw32


x


x



Mingw48_32



x


x

x

Omni-Rig



x




Portaudio


x


x

x

x

Python3


x


x



Qt5



x


x

x

Subversion

x

x

x

x

x

x

Comments
Hamlib

Current distro release 1.2.15.x

Hamlib3

Custom build from Bill Somerville, (G3WJS)

  • Hamlib3 is still under development

  • Potential release dates have yet to be announced

  • Use with WSPR and WSPR-X is experimental only

Mingw32

GNU 4.8.1 Tool Chain, provided by mingw.org

Mingw48_32

GNU 4.8.0 Tool Chain, provided by QT5

Omni-Rig

Required to build WSJT-X using CMake

Python3 Modules

WSJT and WSPR also require several Python Modules

  • Numpy (Numeric Python) v1.8.0+

  • Pillow (Python Imaging) v2.3.0+

  • Pmw (Python Megawidgets) v.2.0.0+ required for Python3

  • PyWin32 (Windows Extensions) 218.5+, Python version specific

  • cx_Freeze (Builds Windows exe files), v4.3.2+, Python3 version specific

7.2. Linux

The following matrix outlines the Linux development package requirements for each application, including documentation.

Package names very between Linux distributions. Distro package names, when known, are listed in the build section of each application. If you have a firm list of packages for your Linux distribution, send it to wsjt-devel for inclusion in The WSJT Developers Guide.

Table 4. Linux Package Matrix: x = Required, o = Optional
Package Docs WSJT WSJT-X WSPR WSPR-X MAP65

CMake



x


x

x

FFTW3F


x

x

x

x

x

GNU Tools


x

x

x

x

x

Hamlib



o

x

x


Hamlib3



x

o

o


Portaudio


x


x

x

x

Pulseaudio



x




Python3


x


x



Qt5



x


x

x

Subversion

x

x

x

x

x

x

Warning KVASD requires 32-Bit libc6. Some Linux distros call these multi-libs, others ia32-libs, some are individual libraries. If your using a 64-Bit OS the following 32-Bit libraries must be installed in addition too the package matrix requirements:
KVASD Requirements
libc.so.6

GCC C Library

libm.so.6

GCC C Library

libgcc_s.so.1libm.so.6

GCC C Library

libquadmath.so.0

Quad-Precision Math Library

Comments
GNU Tools

For 64bit OS C/C++, Gfortran, Make, v4.8.0+

Hamlib

Current distro release 1.2.15.x

Hamlib3

Custom build from Bill Somerville, (G3WJS)

  • Hamlib3 is still under development

  • Potential release dates have yet to be announced

  • Use with WSPR and WSPR-X is experimental only

Omni-Rig

Required to build WSJT-X using CMake

Pulseaudio

QT5 Runtime plug-in requirement

Python3 Modules

WSJT and WSPR also require several Python Modules

  • Numpy (Numeric Python) v1.8.0+

  • Pillow (Python Imaging) v2.3.0+

  • Pmw (Python Megawidgets) v.2.0.0+ required for Python3

8. Documentation

8.1. Windows Builds

The preferred method of building WSJT Documentation on Windows is using JTSDK-DOC. To install JTSDK-DOC, see Windows Install then perform the Update. This is all that is required.

BUILDING DOCUMENTATION
  • Open Windows CMD terminal, at the prompt, type,:

C:\JTSDK-DOC\jtsdk-docenv.bat
  • You should be presented with Figure-1

  • If you have not checked out Docs previously, you will be prompted to do so:

images/jtsdk-doc-co.png
Figure 6. Doc Directory Not Found
Tip If you intend to work on ( check-in ) documentation edits, you should use the Developer check-out. If you do not have Developer access and would like to work on documentation, see the Developer Section.
  • Follow the prompts, Anonymous or Developer, type,:

*For Anonymous Checkout*

svn co https://svn.code.sf.net/p/wsjt/wsjt/branches/doc

*For Developers*

svn co https://user%@svn.code.sf.net/p/wsjt/wsjt/branches/doc

DEV NOTE, Change ( USER ) to your SourceForge User Name
Tip Be sure to update JTSDK-DOC after checkout. Simply browse to and run: C:\JTSDK-DOC\doc\dev-guide\scripts\install-scripts.bat. Running the script will update all the SDKs you have installed.
  • Once you have checked-out / updated the documentation branch, you can build any of the documents with one command ( example uses wsjt ) type,:

build wsjt

*Document Location, per example*
C:\JTSDK-DOC\doc\wsjt\wsjt-main.html
  • Then view the document, type,:

wsjt
DOCUMENT HELP
  • The main screen is the help screen, if you need to re-list it type,:

doc-help

9. MAP-65

9.1. Windows CMake

The preferred method of compiling MAP65 on Windows is using JTSDK-QT. If you have not Installed and Updated JTSDK-QT, you should do so before continuing, see Windows Install and Update

Warning As of this writing, the CMake build method is being updated to bring it more in-line with MAP65 builds. Expect build anomalies until this method has been stabilized.
COMPILING OPTIONS

Using JTSDK-QT for compiling MAP65, you can build two versions:

The CMake process for MAP65 is not as sophisticated as that of WSJT-X. The process still uses Debug and Release, but the build times and final configuration are similar with the exception of adding Qt Debug capabilities. The default build is Debug. To build the Release version, use the ( -r ) flag.

COMPILE MAP65
  • Open Windows CMD terminal, at the prompt, type,:

C:\JTSDK-QT\jtsdk-qtenv.bat
  • You should be presented with Figure-3

  • At the Prompt, type,:

*For Debug*

build map65

*For Release*

build map65 -r

Note the ( -r for Release )
  • If you have not checked out MAP65 previously, you will be prompted to do so: