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 or Ubuntu). Installation on Mac O/S is also possible using Conda.

The below instructions were updated in July 2025 after implementing the CMake build system. The original make build system still works (July, 2025) but will not be maintained going forward.

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.

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 make
4. To use the cmake build system you need cmake and pkg-config
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 you can just install libboost-system-dev.
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.
You need the GNU Scientific Library (GSL) (this is probably obtainable from the linux distro package manager, but I recommend building yourself)
You need the cfitsio FITS library.
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.
You need the FFTW library, with at least version 3.3.5.
Optional: CUDA toolkit
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 it along with a pkg-config and a cmake configuration file to asssist with linking to mxlib. 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_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.

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

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.

Old Makefile Build System

Configuring the old makefile build system requires editing files in the mxlib/local directory. To avoid getting the modification warning due to makefile modifications, the only files you should edit during installation are the local/Common.mk, local/MxLib.mk, and local/mxApp.mk. Do not edit these in the mk folder.

Configuring and Building mxlib

Once you have met all the dependencies:

clone mxlib from https://github.com/jaredmales/mxlib
If you need to customize the build (e.g. switch the BLAS or FFT library used or modify paths), run make setup. This will create three Makefiles in local/ for you to customize.
To further configure mxlib edit the files in the local/ directory only. Some options are:
- Any variable set with ?= in the files in mk/ can be overridden in the corresponding local/ one. The files in local/ are not tracked in git and editing them will not cause compile warnings.
- If you want to change the install path from $HOME to something else, set PREFIX= in local/Common.mk.
- USE_BLAS_FROM can be set to mkl, ATLAS, or Accelerate (macOS only). You may also need to override BLAS_INCLUDES, BLAS_LDFLAGS, and/or BLAS_LDLIBS to set paths and flags. (See mk/MxApp.mk for examples.)
You can also pass config options to make, as in make PREFIX=/path/to/libs.
Build mxlib by running make at the top level.
Install mxlib with make install. sudo may be required depending on the PREFIX. Possibly sudo -E.

Makefile build with Conda

If you have used conda to install the dependencies you should set PREFIX=$CONDA_PREFIX and NEED_CUDA=no. It is recommended that you do this in local/Common.mk but it can be done on the command line as:

make install PREFIX=$CONDA_PREFIX NEED_CUDA=no

Now mxlib headers and libraries are in $CONDA_PREFIX/include and $CONDA_PREFIX/lib and should be found by default as long as "conda activate mxlib_env" is always run after you open a new terminal and before you compile things that use mxlib.