Compiling#

For most users, we recommend using the precompiled libraries. It’s going to be simpler. We recognize that this won’t work for Linux users, or for those who may need more customization. We provide the handle source for this reason. This document breaks down that you need to compile Handel. We’ll note where the two operating systems diverge in the procedure.

Prerequisites#

The following prerequisites apply to all build hosts.

CMake 3.25+
An ANSI C99 compatible compiler (gcc, msvc)
Broadcom PCI/PCIe SDK for xMap or MPX-32D (STJ) products with the PLX_SDK_DIR environment variable set.
Windows only - Visual Studio

Linux#

libusb-dev or equivalent to ensure that you have the USB headers for compilation.

Build Environment#

Handel uses CMake as its build system generator. CMake provides a consistent experience across both Windows and Linux. The tool evaluates your environment and checks for prerequisites. Once done, CMake generates a build script that’s compatible with the compilation environment (make, nmake, Visual Studio, etc.)

We recommend that you use an x64 Developer PowerShell for Visual Studio on Windows. You’ll need the defines, paths, etc. to build. Getting all this sorted without the Visual Studio environment can be painful.

Note

The following sections assume that you are working in a terminal environment of some sort. The commands should be the same in both PowerShell or Bash.

Cloning the project#

We highly recommend using git to clone the repository. That way you have all of the necessary information and version control. You can get everything you need using the following command in your terminal:

git clone --depth 1 --tags https://github.com/xiallc/Handel-Releases.git handel

This command clones the most recent source release along with its tag into a folder called handel. The git tag provides CMake with the information it needs to generate the version header.

Building#

Now that you have the source code navigate into the source folder and create the build directory.

cd handel; mkdir build; cd build

Next, you’ll generate the build scripts and choose what options you want. We provide a complete list of options in the following sections. For now, we’ll build the default configuration (64-bit, microDXP, USB2) with tests and examples.

cmake ../ -DEXAMPLES=ON -DTESTS=ON

As the command runs you’ll see a summary of the supported interfaces and devices output in the terminal. For example, in Windows:

-- Enabled Options:
--     Devices: UDXP
--     Protocols: USB2
--     Libraries: XUP
--     Misc: X64

Linux will look the same as above, just without the XUP library enabled. If you didn’t clone the repository or don’t have git installed, you may see a warning that CMake couldn’t determine the version. You can continue with the following steps without error. But, we do recommend cloning the project to maximize support if things go wrong.

Warning

At least one device and protocol must be defined when building.

Compiling#

It’s time to compile the library and programs.

cmake --build ./ --config Release

This should result in success and you’ll have all the programs and library ready for use. You can double check this by locating the Handel library in

Linux: ./src/libhandel.so
Windows: ./src/Release/handel.dll and ./src/Release/handel.lib

Aggregation#

The compilation process leaves the artifacts scattered through the various folders. They’re usable. But, it’s easier to aggregate them in one place. To do that we’ll use CMake’s install command:

cmake --install ./ --prefix=./handel-dist

This will gather up all the necessary files you need for a distribution and drop them into a folder called handel-dist. The folder structure is nearly identical to our official distribution archives.

CMake Options#

The following options get passed to CMake during the build step. They use the -D flag and the desired status of the option. For example, -DUDXP=OFF or -DXMAP=ON.

Devices#

Flag	Description	Default	Windows	Linux
`MERCURY`	Mercury/Mercury-4	OFF	X	X
`SATURN`	Saturn	OFF	X	X
`STJ`	MPX-32D for STJs	OFF	X
`UDXP`	microDXP	ON	X	X
`UDXPS`	microDXP setup	OFF	X
`ULTRALO`	UltraLo-1800	OFF	X
`XMAP`	xMAP	OFF	X

Warning

The UltraLo-1800 support is an exclusive flag. All functionality not directly needed by that system will be disabled.

Protocols#

Flag	Description	Default	Windows	Linux
`EPP`	Enhanced Parallel Port connections	OFF	X (32-bit Only)
`PLX`	Broadcom PCI/PCIe	OFF	X
`SERIAL`	Support direct RS-232 connections	OFF	X (32-bit Only)
`USB`	USB 1.X	OFF	X (32-bit Only)
`USB2`	USB 2.X	ON	X	X

Libraries#

Flag	Description	Default	Windows	Linux
`XUP`	XW library	ON	X

Misc#

Flag	Description	Default	Windows	Linux
`ANALYSIS`	Additional static code analysis during compilation	OFF	X	X
`EXAMPLES`	Example programs	OFF	X	X
`TESTS`	Test programs for QA	OFF	X	X
`VLD`	Visual Leak Detector	OFF	X
`X64`	x64 architectures	ON	X	X

Compiler Flags#

Under the hood, the code uses preprocessor defines to include or exclude specific configurations. Should you implement your own build system then you will need to use these as compilation flags for your compiler. All defines operate by exclusion. They’re prefixed with EXCLUDE_ followed by the specific item you want to exclude.

Products: XMAP, STJ, SATURN, MERCURY, UDXP, UDXPS
Interfaces: PLX, SERIAL, EPP, USB, USB2

For example, EXCLUDE_XMAP or EXCLUDE_USB. Linux builds must always include the following items: EXCLUDE_XMAP, EXCLUDE_STJ, EXDLUDE_PLX, EXCLUDE_UDXPS, EXCLUDE_XUP.

Warning

We do not recommend creating your own build system for the software. Our system handles dependencies and additional flags that may impact the performance of your system. Please be aware that not all define parings are valid. For example, xMap doesn’t support USB.