C++ Utilities Usage Guide¶

This guide explains how to build, install, and use the command-line utilities provided by the C++ implementation within the opat-core project.

Dependencies¶

To build the C++ utilities, you will need the following build system tools:

Meson: The primary build system used for the project.
CMake: Required by Meson for certain tasks, particularly dependency detection.

Additionally, the build process requires the following libraries:

gtest (Google Test): Used for running unit tests.
xxHash: Used for hashing functionalities.

Internet Connection Requirement: If gtest and xxHash are not already installed on your system in a way that Meson/CMake can find them, the Meson build process is configured to automatically download them using its WrapDB feature. Therefore, an internet connection may be required during the meson setup step if these dependencies need to be fetched.

Building from Source¶

Follow these steps to compile the C++ utilities:

Clone the Repository: If you haven’t already, clone the opat-core repository:
```
git clone https://github.com/4D-STAR/opat-core.git
cd opat-core
```
Configure the Build with Meson: Use Meson to set up the build directory. Running this from the repository root creates a build subdirectory. The –buildtype=release flag optimizes the build.
```
meson setup build --buildtype=release
```
Compile the Code: Use Meson to compile the source code within the configured build directory.
```
meson compile -C build
```

Upon successful compilation, the executables (opatHeader, opatVerify, opatInspect) will be located within the build directory.

Installation¶

To install the compiled utilities to a system-wide location (e.g., /usr/local/bin, depending on your system configuration and permissions), run the following command from the repository root:

meson install -C build

You might need administrator privileges (e.g., using sudo) depending on the installation prefix configured by Meson.

Headers¶

In order to use opatIO from within another C++ program you will need to link against the opatIO library and include the opatIO.h header file.

#include "opatIO.h"

int main() {
  OpatIO opat("gs98hz.opat");
  double kappa = opat.get([0.01, 0.001])["data"]["table"][0][0];
}

The complication here with all of the indexing is that we access the first tag in the data card at 0.01, 0.001 (this first tag is called data). Then we get the table from that (as opposed to the row and column values, such as logR and logT), then we get the 0,0 element from the table.

Command-Line Utilities¶

The build process generates three command-line utilities for interacting with OPAT files:

opatHeader¶

Purpose: Prints the main header information from a specified OPAT file.
Usage:
```
opatHeader -f <path_to_opat_file>
```
- Replace <path_to_opat_file> with the actual path to your .opat file.

opatVerify¶

Purpose: Validates the structure and integrity of an OPAT file to ensure it conforms to the format specification. It checks headers, offsets, and potentially checksums.
Usage:
```
opatVerify -f <path_to_opat_file>
```
- Replace <path_to_opat_file> with the actual path to your .opat file.

opatInspect¶

Purpose: Prints both the main header information and the card catalog entries from a specified OPAT file. This gives a more detailed overview than opatHeader.
Usage:
```
opatInspect -f <path_to_opat_file>
```
- Replace <path_to_opat_file> with the actual path to your .opat file.

Example¶

To view the header of a file named my_data.opat located in the current directory, you would run:

opatHeader -f my_data.opat