Skip to content

Building from source

This page describes how to build the JURASSIC command-line tools from source using the provided Makefile. It is intended for developers and advanced users who want to compile JURASSIC themselves, change compiler flags, or enable optional build modes.

If you are only looking for a "first run", see the Quickstart. For general setup and prerequisites, see Installation.

What the Makefile builds

The top-level build produces a set of small executables (command-line tools) that are linked against the JURASSIC libraries in ../libs/build/. The Makefile defines the executable list in the EXC variable.

Typical tools include drivers for:

  • forward modelling (e.g. formod)
  • kernels / Jacobians (e.g. kernel)
  • retrieval (e.g. retrieval)
  • format conversion utilities (*_fmt tools)
  • table utilities (tblgen, tblfmt, ...)

The exact list can be inspected in the Makefile via the EXC = ... line.

Default build

From the directory that contains the Makefile, run:

make

This builds the default target all (i.e., all executables).

For a faster build on multi-core systems:

make -j

Build outputs

By default, the resulting executables are placed in the current build directory (the same directory as the Makefile).

A version string is compiled into the code via:

  • VERSION ?= $(shell git describe --abbrev=6 --dirty --always --tags)

This means builds from a Git checkout will embed a descriptive version (e.g. tag + commit hash), and "dirty" working trees are marked.

Running the test suite

The Makefile defines a test list in TESTS and provides a check target that runs them:

make check

Each test is executed by running the corresponding ../tests/<name>/run.sh script (the Makefile prints a pass/fail banner for each test).

Installing and uninstalling

The Makefile supports a simple "copy install" into a binary directory:

make install

The default install destination is:

  • DESTDIR ?= ../bin

To install into a custom location:

make install DESTDIR=/path/to/bin

To uninstall from the same destination:

make uninstall DESTDIR=/path/to/bin

Important build variables

You can override Makefile variables on the command line. The most relevant ones are:

Compiler and flags

  • CC - C compiler (default: gcc)
  • CFLAGS - compile flags
  • LDFLAGS - link flags

Examples:

make CC=clang
make OPT="-O2 -march=native"

Optimization and diagnostics flags

  • OPT (default: -O3) - optimization flags passed into CFLAGS
  • INFO (default: 0) - if set to 1, adds -fopt-info for optimization reports
  • PROF (default: 0) - if set to 1, adds -pg for profiling builds
  • COV (default: 0) - if set to 1, enables coverage flags (--coverage)

Examples:

make OPT=-O0
make INFO=1
make PROF=1
make COV=1

Static linking

  • STATIC (default: 0) - if set to 1, attempts to add -static
make STATIC=1

Note: the Makefile explicitly prevents static builds when UNIFIED=1.

Library paths

The build expects headers and libraries under:

  • includes: ../libs/build/include (added via INCDIR)
  • libs: ../libs/build/lib (added via LIBDIR)

If these directories are missing, ensure the dependency libraries have been built/installed as described in Installation.

Optional: build with the JURASSIC-UNIFIED library

The Makefile contains an option to link against a "JURASSIC-UNIFIED" library (including CUDA runtime linkage). This is controlled by:

  • UNIFIED ?= 0 (default off)
  • UNIDIR = ../../jurassic-unified (path to the unified repository)

To enable:

make UNIFIED=1

When UNIFIED=1, the Makefile:

  • adds include paths from $(UNIDIR)/include
  • adds library paths from $(UNIDIR)/unified_library and $(CUDA_PATH)/lib64
  • links against -lcudart -ljurassic_unified (and -lstdc++)

You may need to define CUDA_PATH in your environment, for example:

export CUDA_PATH=/usr/local/cuda
make UNIFIED=1

Developer utility targets

The Makefile provides several targets that are helpful for development:

  • make clean - remove build products (executables, objects, coverage files)
  • make doxygen - build Doxygen documentation
  • make mkdocs - build MkDocs documentation (runs mkdocs build in ../docs)
  • make cppcheck - run static analysis (requires cppcheck)
  • make indent - apply code formatting rules (requires indent)
  • make lizard - run cyclomatic complexity analysis (requires lizard)
  • make coverage - generate coverage output (requires lcov, genhtml, gcov)
  • make strip - strip symbols from executables
  • make dist - create a source distribution artifact (if used in your workflow)

Not all developer tools are required for normal builds. If a target fails because a tool is missing, either install the tool or skip that target.

Troubleshooting

"Cannot find headers/libraries under ../libs/build/..."

This typically means dependency libraries have not been built or the build directory layout differs from what the Makefile expects. Ensure your dependency build step populates:

  • ../libs/build/include
  • ../libs/build/lib

MPI / OpenMP issues

The Makefile enables OpenMP via -fopenmp in CFLAGS by default (for GCC). If you use a different compiler, you may need compiler-specific OpenMP flags.

CUDA / unified build issues

If UNIFIED=1 fails:

  • confirm UNIDIR points to the correct checkout of jurassic-unified
  • ensure CUDA_PATH is set and points to a valid CUDA installation
  • confirm the unified library has been built before building this repository

Next steps

After a successful build:

  • run make check to validate basic functionality
  • proceed to the Quickstart examples
  • consult Code structure if you plan to modify or extend the code