Installation

Introduction

These are instructions for installing the mxlib c/c++ library. This is my personal library which I have built up over many years. Along the way I have tried to keep it organized and documented. I have installed it on several different linux systems (running Rocky, Fedora, or Ubuntu). Installation on Mac O/S is also possible using Conda.

mxlib now uses a CMake build system, the original make build system has been removed.

Quick Start

Assuming you have all the dependencies met, the recipe for installing mxlib with cmake is:

git clone https://github.com/jaredmales/mxlib.git
cd mxlib
mkdir _build
cd _build
cmake ..
make
sudo -E make install

Installing Dependencies

The libraries that mxlib depends on are easy to install from either source or using your O/S package manager.

Alternatively, see the below section for quickstart instructions using the conda package manager (part of miniconda or Anaconda) on Linux or macOS.

Scripts

Under mxlib/scripts there are scripts which will setup your system to build and use mxlib. For instance mxlib/scripts/mxlib_provision_ubuntu2404.sh will install dependencies and build and install mxlib for Ubuntu 24.04.

There is also a script to setup a multipass virtual machine, with a cloned mxlib repo. You can then run the provisioning script in the VM instance, after which you will have a working mxlib library installation.

Dependencies

This is the list of the other libraries that mxlib depends on. I usually install these from scratch to ensure maximum optimization (though I have little to no quantitative evidence that it matters), but you can probably manage most of these from the O/S package manager. You will need to make sure to install the dev packages.

1. You need a basic build system:
   1. You need a c compiler supporting C99.
   2. You need a c++17 compatible c++ compiler. c++20 is preferred and is the default.
   3. You need cmake and pkg-config
2. You need the boost c++ system library (this is probably obtainable from the linux distro package manager, fine to install with apt or yum).
   • On Ubuntu 26 you can just install sudo apt install libboost-dev.
   • On earlier Ubuntus you can install libboost-system-dev.
3. You need the Eigen matrix library (http://eigen.tuxfamily.org/index.php).
   • It is best to use cmake to configure Eigen and install it. This will ensure that the package config is updated.
4. You need the GNU Scientific Library (GSL) (this is probably obtainable from the linux distro package manager, but I recommend building yourself)
5. You need the cfitsio FITS library.
6. You need a BLAS and Lapack.
   • openblas: widely supported and should be available via package manager. Also easy to build yourself.
   • MKL: the intel Math Kernel Library (MKL) is probably the highest performance option for Intel CPUs. It is free (as-in-beer) and straightforward to install. See my notes on installing MKL.
   • ATLAS: Another option is ATLAS, see my notes on installing ATLAS.
7. You need the FFTW library, with at least version 3.3.5.
8. Optional: CUDA toolkit
9. Optional: ImageStreamIO from the milk library.

The relevant header files for each library need to be accessible to the compiler, either in a standard location or in one you specify when compiling your programs.

Installing Dependencies From Conda

The conda package manager contains packages for all of mxlib's external dependencies (not including vendored libraries, shipped under source/vendor/). This means setting up a correct build environment on macOS or Linux – even in a cluster environment, where you may not have root access – is straightforward. (To do: CUDA support with conda.)

Once you have installed conda (either miniconda or Anaconda is fine), you will create and activate an environment to use mxlib with.

$ conda create -y -n mxlib_env

The install process is tested with conda-forge packages, which you may not be using by default. (Installing them in the mxlib_env environment won't cause conflicts with any other environments you may have.)

$ conda activate mxlib_env
$ bash ./setup/conda_env_setup_Linux.bash
# or, on macOS:
$ bash ./setup/conda_env_setup_macOS.bash

You may see the message: "To make your changes take effect please reactivate your environment." That would be "conda deactivate" followed by "conda activate mxlib_env".

If all went well, you should now be able to build mxlib with cmake like so:

mkdir _build
cd _build
cmake -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ..
make
sudo make install

Configuring mxlib with cmake

The cmake build system will (in most cases) automatically configure mxlib for you and install a pkg-config file to assist with linking to mxlib. pkg-config is the supported downstream discovery interface; mxlib does not currently install a CMake package configuration file. The above Quick Start section gives the basic recipe for building mxlib.

If you want or need to modify things, cmake has many options and mxlib adds its own. You can use them like

cmake -DMXLIB_OPTION_NAME=val ..

Useful cmake options

cmake options for mxlib

option	type	default	description
CMAKE_INSTALL_PREFIX	string	/usr/local	destination for lib/mxlib.so and include/mx

cmake Options for mxlib

You may wish to change some of the settings or compile without some of the dependencies. To table below lists the mxlib specific options that can be passed to cmake .

cmake options for mxlib

option	type	default	description
MXLIB_CVERSION	string	–std=c99	mxlib c version
MXLIB_CXXVERSION	string	–std=c++20	mxlib c++ version (minimum is c++17)
MXLIB_CFLAGS	string	-march=native -mfma -DNDEBUG	mxlib c compiler flags
MXLIB_CXXFLAGS	string	-march=native -mfma -DNDEBUG	mxlib c++ compiler flags
MXLIB_OPTIMIZE	string	-O3 –fast-math	mxlib optimization settings
MXLIB_DEFINES	string	-D_XOPEN_SOURCE=700	mxlib compiler command line defines
MXLIB_INVALID_NUMBER_VALUE	string	empty (quiet NaN)	finite invalid-pixel override exported to consumers
MXLIB_USE_OPENMP	bool	ON	Whether or not to use OpenMP in mxlib and other libraries
MXLIB_USE_CUDA	bool	ON	Whether or not to use CUDA library for mxlib
MXLIB_USE_ISIO	bool	ON	Whether or not to use the ImageStreamIO library for mxlib
MXLIB_USE_FFT_FROM	string	fftw	Which library to use for the FFT interface in mxlib
MXLIB_USE_BLAS_FROM	string	openblas	Which library to use for BLAS and Lapack in mxlib. Supported choicess: mkl, openblas.

By default, mx::improc::invalidNumber<T>() returns a quiet NaN. This preserves invalid pixels in a form understood by FITS and common image-display tools. Its classification uses mxlib's fast-math-safe floating-point utilities. A build that requires a finite sentinel can select one explicitly:

cmake -S . -B _build -DMXLIB_INVALID_NUMBER_VALUE=-3e38

Because the setting affects a header-defined public API, the generated mxlib.pc exports the corresponding compile definition to pkg-config consumers. Applications that do not use the installed metadata must compile all mxlib-using translation units with the same MXLIB_INVALID_NUMBER_VALUE definition.

Configuring BLAS

Configuring MKL

Even though cmake includes a package-finder for MKL, it doesn't work the way we need it to for mxlib. So the following options allow for manual configuration of mxlib for MKL.

cmake options for mkl in mxlib

option	type	default	description
MXLIB_MKL_INCLUDE_DIRECTORY	string	$ENV{MKLROOT}/include	MKL include directory
MXLIB_MKL_DEFINITIONS	string	-DMXLIB_MKL	MKL compiler defines
MXLIB_MKL_CFLAGS	string	-m64	MKL compiler c-flags (used for cxx too)
MXLIB_MKL_LIBDIRS	list	$ENV{MKLROOT}/lib/intel64	MKL link directories
MXLIB_MKL_LDFLAGS	string	-Wl,–no-as-needed	MKL link flags
MXLIB_MKL_LIBS	list	mkl_intel_lp64;mkl_sequential;mkl_core;pthread;m;dl	MKL libraries

Using mxlib

Git Version Tracking

Mxlib includes a system to track its git version, using the SHA1 hash. This, in principle, allows any results to be tagged with the version of the library used to generate them. The goal is to always be able to restore the code to a given point so that previous results can be reproduced. The library will issue a warning at compile time if there are any modifications to it that aren't yet committed, meaning that they aren't trackable.

Linking to mxlib

For CMake applications, import the installed pkg-config metadata and link the resulting target:

find_package(PkgConfig REQUIRED)
pkg_check_modules(MXLIB REQUIRED IMPORTED_TARGET mxlib)
target_link_libraries(myProgram PRIVATE PkgConfig::MXLIB)

For a direct compiler invocation, use pkg-config --cflags --libs mxlib so the same required definitions, include paths, and dependency libraries are applied.

Once mxlib is built and installed, set the $MXMAKEFILE variable in your shell (and/or shell profile files):

export MXMAKEFILE=/path/to/mxlib/mk/MxApp-cmake.mk

You can then build a single .cpp program, let's say "myProgram.cpp", with the following line

make -B -f $MXMAKEFILE t=myProgram

Note that tab-complete usually works, so you type make -B -f $MX<tab> and the shell should work for you.

Now to install the program, you need to give make a hint about what is to be installed. The command is

make -f $MXMAKEFILE TARGET=myProgram install

This installs the myProgram binary to $PREFIX/bin.

For more complicated applications, you can create a local Makefile which specifies the TARGET and additional objects with OTHER_OBJS, and finally includes MxApp.mk. See MxApp.mk for additional options.