Skip to content

BUILDING.md

Latest commit

 

History

History
267 lines (182 loc) · 10.1 KB

BUILDING.md

File metadata and controls

267 lines (182 loc) · 10.1 KB

Building DynAdjust from source code

The following build instructions are only needed if you would like to build DynAdjust yourself or make changes to the source code and contribute to the DynAdjust repository, rather than use pre-built binaries.

Table of contents

Overview of prerequisites

To build DynAdjust, the following prerequisites will be needed:

The way in which these prerequisites are installed will depend upon your operating system and will be discussed in the following sections.

Linux (Ubuntu)

For the case of Linux, we will give instructions on how to compile for Ubuntu. The appropriate package manager commands will vary depending on the Linux distribution that you use. We highly recommend trying the pre-built static binaries that we now generate that will work on any Linux distribution without any dependencies (assuming a x64 platform).

Installing prerequisites

Update package lists.

sudo apt update

Install runtime and development prerequisites.

sudo apt install -y libxerces-c-dev xsdcxx libboost-system-dev libboost-filesystem-dev libboost-timer-dev libboost-thread-dev libboost-program-options-dev

You now have two options, either OpenBLAS or Intel oneAPI Math Kernel Library.

OpenBLAS

For OpenBLAS, just run:

sudo apt install -y libopenblas-dev liblapacke-dev

Intel oneAPI Math Kernel Library

Either download and install yourself manually, or run:

wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/ac050ae7-da93-4108-823d-4334de3f4ee8/intel-oneapi-base-toolkit-2025.1.2.9_offline.sh -O oneapi.sh
sudo sh oneapi.sh -a --action install --components intel.oneapi.lin.mkl.devel --eula accept -s

Compile the source code

Download an official release (e.g., 1.2.9) with:

curl -O https://github.com/GeoscienceAustralia/DynAdjust/archive/refs/tags/v1.2.9.tar.gz
tar xvf v1.2.9.tar.gz
cd ~/DynAdjust-1.2.9

If you are using Intel MKL, then load it.

source /opt/intel/oneapi/setvars.sh

Now, compile the code with CMake.

mkdir build
cmake -S dynadjust -B build
cmake --build build --parallel

MacOS

Building DynAdjust on MacOS is just as easy as Linux.

Install prerequisites

Install Homebrew first if absent: visit https://brew.sh and run the one-line install script.

Run the following commands to install the prerequisites.

brew update
brew install boost xerces-c xsd

Compile the source code

Download an official release (e.g., 1.2.9) with:

curl -O https://github.com/GeoscienceAustralia/DynAdjust/archive/refs/tags/v1.2.9.tar.gz
tar xvf v1.2.9.tar.gz
cd ~/DynAdjust-1.2.9

If you are using Intel MKL, then load it.

source /opt/intel/oneapi/setvars.sh

Now compile the code with cmake.

mkdir build
cmake -S dynadjust -B build
cmake --build build --parallel

Windows using Visual Studo, CMake, and vcpkg

Prerequisites

Install Microsoft Visual Studio 2022

Microsoft's Visual Studio 2022 Community Edition is available from https://visualstudio.microsoft.com/vs/community/

C++ is required for compiling all DynAdjust binaries. During installation of Visual Studio, ensure C++ Desktop development and CMake tools for Windows components are installed. Dot NET is not used for any DynAdjust projects, however MFC is required for building GeoidInt.exe (Geoid Interpolation software), which has a (dialog-based) graphical user interface.

Full instructions for installing and using packages with CMake in Visual studio can be found here. Below is a brief summary of the steps.

Install git

On Windows, you will first need to install git.

Install vcpkg

If you do not have vcpkg installed, you can install it using the following steps.

git clone https://github.com/microsoft/vcpkg C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat

As per Microsoft's guidelines for setting up CMake projects to use vcpkg, DynAdjust has been configured to use the vcpkg toolchain file via the CMakePresets.json file. There is no need to manually change or configure the use of vcpkg.

Install dependency packages using vcpkg

Now we can install the dependencies.

vcpkg install boost-geometry boost-process boost-iostreams boost-spirit boost-system boost-filesystem boost-timer boost-thread boost-program-options boost-interprocess xerces-c

Install Code Synthesis XSD library

DynAdjust requires Code Synthesis XSD to parse XML files. Since version 1.2.9, the CMake project file will automatically download XSD. Hence, there is no need to manually download and install it.

Install Intel oneAPI MKL library

If you do not have it, download and install the Intel oneAPI Math Kernel Library {oneMKL). No extra configuration required because the installer registers MKL on the system PATH. Also, if Visual Studio 2022 is already installed, the Intel oneMKL installer will automatically enable integration into the Visual Studio 2022 IDE. This means that the oneAPI MKL libraries and headers will be automatically referenced upon compiling DynAdjust without modification.

Download the DynAdjust source code

Download and unzip an official release (e.g. 1.2.9) to C:\Data\Dev\ via the following command:

cd C:\Data\Dev
curl https://github.com/GeoscienceAustralia/DynAdjust/archive/refs/tags/v1.2.9.zip -o DynaDjust-1.2.9.zip
tar -xf DynAdjust-1.2.9.zip

Alternativey, you can use git to get the latest version:

cd C:\Data\Dev
git clone https://github.com/GeoscienceAustralia/DynAdjust.git C:\Data\Dev

Option 1: Compile the source code via command prompt

cd path\to\DynAdjust
mkdir build
cmake -G "Visual Studio 17 2022" -A x64 -D USE_MKL=ON -D CMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake" -S dynadjust -B build
cmake --build build --config Release --parallel

Option 2: Compile the source code via the Visual Studio IDE

Upon executing Visual Studio, select Open a local folder and navigate to the root folder where DynAdjust was extracted (above), where the top-most CMakeLists.txt file exists.

Get Started

Upon opening this folder, Visual Studio will

  • Add CMake items to the Project menu, with commands for viewing and editing CMake scripts.

  • Display the folder structure and files in the Solution Explorer .

  • Run CMake and generate the CMake cache file (CMakeCache.txt) for the default configuration. The CMake command line is displayed in the Output Window, along with other output from CMake.

  • Start, in the background, to index the source files to enable IntelliSense, browsing information, refactoring, and so on. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources.

Once CMake cache generation has succeeded, you can also view your projects organized logically by targets. Choose the Select View button on the Solution Explorer toolbar. From the list in Solution Explorer - Views, select CMake Targets View and press Enter to open the targets view.

Targets

This will display all the DynAdjust executables and dependent dynamic link library (DLL) projects defined in the CMakeLists.txt file.

Targets

The project for each executable is named using the convention dna<program-name>wrapper, except for the main program dynadjust. Upon compilation, these projects will create executables named <program-name>.exe. Each executable named <program-name>.exe is dependent on a DLL named dna<program-name>.dll. The CMakeLists.txt file will ensure each dependency DLL is compiled first before compiling the executables.

The CMakePresets.json file manages four configurations:

  1. Debug version with MKL (build-dbg-mkl)
  2. Release version with MKL (build-rel-mkl)
  3. Debug version with OpenBLAS (build-dbg-openblas)
  4. Release version with OpenBLAS (build-rel-openblas)

To build DynAdjust:

  1. Select the Build Configuration you would like to build (e.g. build-rel-mkl)
  2. From the Project Menu, select Delete Cache and Reconfigure
  3. Select Build All, or select the executable or DLL and then *Build