Overview

ecCodes uses CMake for compilation and installation. This is a first step towards an homogenisation of the installation procedures for all ECMWF packages.

Like autotools, CMake will run some tests on the user's system to find out if required third-party software libraries are available and note their locations (paths). Based on this information it will produce the Makefiles needed to compile and install ecCodes.

CMake is a cross-platform free software program for managing the build process of software using a compiler-independent method.

Please be reminded that ecCodes is also available as a "conda" package. See How to install ecCodes with Python bindings in conda - ecCodes FAQ for more information.

Generating the Makefiles with CMake

One nice and highly recommended feature of CMake is the ability to do out of source builds. In this way you can make all your ".o" files, various temporary files, and even the binary executables without cluttering up your source tree. To use out of source builds, first create a build directory, then change into your build directory and run cmake pointing it to the source directory and using your own options.

The command gives feedback on what requirements are fulfilled and what software is still required. The following table gives an overview of the different options.  The default (without any options) will compile a shared library only and install it in /usr/local/.
Note: When an option is ON by default, it is enabled even if not explicitly requested. Features with default OFF need to be explicitly enabled by the user with -DENABLE_<FEATURE>=ON


CMAKE_INSTALL_PREFIXwhere you want to install your ecCodes/usr/local
CMAKE_BUILD_TYPE

to select the type of compilation:

  • Debug
  • RelWithDebInfo
  • Release
RelWithDebInfo
BUILD_SHARED_LIBSSelect the type of library built:
  • ON (Build shared libraries only)
  • OFF (Build static libraries only)
  • BOTH (Build both shared and static libraries)
ON
CMAKE_CXX_COMPILERC++ Compiler
CMAKE_CXX_FLAGSFlags for the C++ Compiler
CMAKE_Fortran_COMPILERFortran Compiler
CMAKE_Fortran_FLAGSFlags for the Fortran Compiler
ENABLE_NETCDFFor the grib_to_netcdf conversion toolON
ENABLE_JPG

Enable JPEG2000 support. This option should look for JasPer or OpenJPEG.
If this option is enabled it is also possible to pick which one of OpenJPEG or JasPer to use:

  -DENABLE_JPG_LIBOPENJPEG=ON
  -DENABLE_JPG_LIBJASPER=ON

ON

ENABLE_PNGEnable PNG support for decoding/encodingOFF
ENABLE_AECEnable Adaptive Entropy Coding (AEC) for GRIB decoding/encoding (CCSDS)ON
ENABLE_PYTHON2

Note: This option is deprecated and was removed in Q1 2023.

The Python2 interface to the package.
For Python 3 use "pip3 install" (See below)

N/A
ENABLE_FORTRANOffers the Fortran 90 interface to the packageON
ENABLE_ECCODES_THREADSEnable thread-safety using POSIX threadsOFF
ENABLE_ECCODES_OMP_THREADSEnable thread-safety using OpenMP threadsOFF
ENABLE_MEMFSSee Memory based access to definition/sample files
Note: When this is enabled, the sample files and definitions are not installed.
To install them, add:
  -DENABLE_INSTALL_ECCODES_DEFINITIONS=ON
  -DENABLE_INSTALL_ECCODES_SAMPLES=ON
OFF
ENABLE_EXTRA_TESTSEnable extended regression testing (which requires data downloads)OFF
cmake options
doc
default


Note: The compilers can also be overridden by setting the environment variables CXX and FC.

Note: To see the full output from the compilation, you can use:

   make VERBOSE=1

Quick installation guide

Here is an example of a list of commands you could use to install ecCodes.  It is assumed “>” is the shell prompt.
First of all get the tarball "eccodes-x.y.z-Source.tar.gz" from our Releases page. Then:

> tar -xzf  eccodes-x.y.z-Source.tar.gz
> mkdir build ; cd build 

> cmake -DCMAKE_INSTALL_PREFIX=/path/to/where/you/install/eccodes ../eccodes-x.y.z-Source 
...

> make
> ctest
> make install


It is recommended that you always build in a clean directory and also install into a clean directory.

By default the ctest step above (running the tests) does NOT require any data to be downloaded and only runs basic sanity tests. However if you wish to exercise more of the functionality of ecCodes, you are advised to configure the build with:

> cmake ...  -DENABLE_EXTRA_TESTS=ON

In this mode the tests will take longer and you need to be connected to the internet (and set the relevant "http_proxy" environment variable if you must use a proxy) so data files can be downloaded for the tests. You can however download all the data files in one go (See the data tarball link at the top of the Releases page)

Also note that if you have several CPUs, you can invoke the "make" and "ctest" commands above in parallel (e.g. "make -j4", "ctest -j4").  This will speed up the whole build/test process significantly.

Python 3 bindings

The Python 3 bindings are built with CFFI and are packaged separately. However, from version 2.37.0 of the Python bindings, a pre-built version of the ecCodes binary library is supplied with the bindings, meaning that it is not necessary to build the ecCodes library unless you really need something very specific.
If you do wish to use your own build of the ecCodes binary library with its Python bindings, first install ecCodes as above with a shared library (either BUILD_SHARED_LIBS=ON or BOTH) and then install from PyPI with the --no-binary eccodes option as shown here:
> pip3 install eccodes --no-binary eccodes

If you are installing your own-built ecCodes binary library into a non-standard installation location, then set the environment variable ECCODES_DIR to tell the bindings where to find the root installation directory of the ecCodes engine.

> export ECCODES_DIR=/path/to/where/you/install/eccodes

For more information on installing the Python bindings and using a separate ecCodes binary library, please see https://github.com/ecmwf/eccodes-python/blob/master/README.rst.


See: https://pypi.org/project/eccodes/

Microsoft Windows

Please note: Windows is not a platform that is used for technical work at ECMWF. Therefore we cannot support this platform. For operational use, we strongly advise you to use Linux.

If you find problems, we invite the Windows user community to use our new set-up on GitHub to fork/contribute and issue pull request changes. Old Reliable Tech has set up automatic tests and builds for Windows on GitHub, which should ensure continued releases for this platform.