Installation ============ This documentation provides installation instructions for CODA. This release has been verified to work on Linux, Windows (7 or higher), and macOS (10.13 or higher), but you may encounter problems when trying to build or run this software on other systems. If you do encounter problems, please read the FAQ document which is also contained in this package to see if your problem is already described there. Otherwise, look at the Feedback section of this document to see what you can do to report your problem back to us. Supported platforms ------------------- CODA is designed to run on most Unix-based operating systems (including Linux and macOS) and Windows. The platforms that are supported include at least Linux, Windows, and macOS. What you will need ------------------ - The CODA package: You can choose between a source installation (coda-x.y.z.tar.gz) or a binary installation (CODA-x.y.z-win64.exe (Windows only)). Note that x.y.z stands for the version number of the package. The source package contains the source code for all CODA components (C Library, IDL interface, MATLAB interface, Fortran interface, Python interface, and the tools codacheck, codacmp, codadd, codadump, and codafind) together with all documentation. You will need this package if you want to use CODA on a Unix-based system. For Windows you will only need this package if you want to have access to the CODA source (if, for instance, you want to extend/improve CODA). The binary package, which is only available for Windows, contains pre-built versions of everything from the source distribution (without the sources) and all documentation and examples. For the IDL and MATLAB interfaces, pre-built versions are included for IDL 8.3 and higher for Windows, and MATLAB R2019b (v9.7) and higher for Windows. For the Python interface, a pre-built version for Python 3.11 is included. For the Java interface, a pre-built version for JDK 11 is included. All CODA interfaces have been compiled with HDF4 and HDF5 support built in. If you do not have the CODA package you need, you can download it from the CODA GitHub website: https://github.com/stcorp/coda/releases - If you plan on using the Fortran interface you should have a Fortran 77 or Fortran 90 compiler. - If you plan on using the IDL interface you need a recent version of IDL: The IDL interface has been verified to work with IDL version 6.3 and higher, but earlier versions may also work. - If you plan on using the MATLAB interface you need a recent version of MATLAB: The MATLAB interface will only work with MATLAB version 6.5 (R13) and higher. - If you plan on using the Python interface you need Python version 2.7 or higher and the Python 'numpy' and 'cffi' packages. - If you plan on using the Java interface you need JDK/JRE version 8 or higher. - If you use Windows you will need to have the Microsoft Visual C++ Redistributable Packages for Visual Studio 2015 installed. The installer can be found at the following link: https://www.microsoft.com/en-us/download/details.aspx?id=48145 The following items are only needed if you use the CODA source distribution: - A C compiler: Most Unix platforms come with their own C compiler so this should not be a problem. For macOS you should make sure you have installed the Developer Tools. For Windows you need Microsoft Visual C++ 2009 (v9) or higher. - If you want to use the HDF4 features of CODA then you will need to have a recent version of HDF4 installed. You will also need the additional required libraries libjpeg and zlib. - If you want to use the HDF5 features of CODA then you will need to have a recent version of HDF5 installed. You will also need the additional required library zlib (and optionally szip). Using GitHub ------------ CODA is also available from GitHub, but this is only recommended to be used by users who want to co-develop CODA and it will only work on Unix-based systems. You will need to have additional software installed and need to peform additional steps if you want to build CODA from the GitHub git respository. Additional software that you will need: - autoconf - automake - libtool - flex (>=2.5.20) - bison - doxygen - swig (for java interfaces) After you clone and checkout the CODA git repository first run the bootstrap script in the root of the source directory:: $ ./bootstrap After that you can follow the steps as usual for building the source package. Note that the CMake build scripts that come with CODA can also be used to build CODA, but they do not allow regeneration of automatically generated files (such as the documentation), so they are not recommended for performing co-development of CODA. Using Conda ----------- CODA is also available as a conda package for Windows, Linux, and macOS (only 64bit and Python3). You can install CODA using conda with:: $ conda install -c conda-forge coda Note that this version of CODA does not include the Fortran, Java, MATLAB, and IDL interfaces. It only includes the Python interfaces, C library, and command line tools. Also be aware that if you use conda within an Anaconda installation to first create a separate environment using e.g. `conda create -n coda` and `conda activate coda`, otherwise the conda installation will likely fail. The recommended installation of conda is Miniforge or Mambaforge as this will ensure that all packages are taken from the conda-forge channel by default. Building the source package (Unix) ---------------------------------- To build the source package, make sure to download the official CODA source package, which is named coda-x.y.z.tar.gz. Don't use the packages called 'Source code' from GitHub as these are contents of the git respository (see 'Using GitHub' above). The CODA source package comes with both an autotools and a CMake build system. For Unix-based systems the recommended approach is to use the autotools based system (using the configure script), which is what is described below. Building with CMake is also supported, but not documented here. The following steps will guide you through the process of building the CODA libraries and executables (including the IDL, MATLAB, Python, and Java interfaces) on a Unix-based platform: 1) Go to the directory that contains the downloaded coda-x.y.z.tar.gz file and unpack this package:: $ gzip -d coda-x.y.z.tar.gz $ tar xf coda-x.y.z.tar Make sure you replace ``x.y.z`` with the appropriate version number. 2) You should now have a ``coda-x.y.z`` directory. Go to this directory:: $ cd coda-x.y.z 3) Next you will have to execute the ``configure`` script that checks what system you are on and sets up the build environment. There are several options you can pass to this script. The most important ones are: ``--prefix `` : By default, if you perform an installation of the CODA package (see further below on how to do this) all files are installed in subdirectories under ``/usr/local``. Executables will appear under ``/usr/local/bin``, libraries under ``/usr/local/lib`` and all data files (documentation and examples) under ``/usr/local/share/coda``. However, installing the files into the default places requires you to have administrator privileges, which you may not have. In order to install CODA in a different location where you do have permission to copy files to, you can use this option to provide a different installation directory. For instance, you can use ``--prefix=$HOME/coda`` to install the software in the subdirectory ``coda`` of your home directory. ``--enable-idl`` : By default CODA is built without the IDL interface. Use this option to enable building of the interface to IDL. ``IDL=`` : If you want to build the IDL interface you should also use this option to tell the configuration script where you have installed IDL. The is the root directory of your IDL installation. It should contain for instance the ``bin`` directory with the idl executable and an ``external`` directory containing the file ``export.h``. Also make sure that you provide an absolute path for the IDL root directory (i.e. starting with a ``/``). ``--enable-matlab`` : By default CODA is built without the MATLAB interface. Use this option to enable building of the interface to MATLAB. ``MATLAB=`` : If you want to build the MATLAB interface you should also use this option to tell the configuration script where you have installed MATLAB. The is the root directory of your MATLAB installation. It should contain for instance the ``bin`` directory with the matlab and mex executables (or symbolic links to them) and an ``extern/include`` subdirectory containing the file ``mex.h``. Also make sure that you provide an absolute path for the MATLAB root directory (i.e. starting with a ``/``). ``--enable-python`` : By default CODA is built without the Python interface. Use this option to enable building of the interface to Python. Make sure that you choose the install prefix option (``--prefix``) such that the target location of the python package (e.g. ``/lib/python3.7/site-packages``) ends up in your python path. Also, if you enable the Python interface then make sure you have installed the numpy package for Python. ``PYTHON=`` : If you want to build the Python interface you should also use this option to tell the configuration script where your Python executable is located (e.g. ``PYTHON=/usr/bin/python``). Make sure that you provide an absolute path for the Python executable (i.e. the path should start with a ``/``). ``--enable-java`` : By default CODA is built without the Java interface. Use this option to enable building of the interface to Java. ``--with-hdf4`` : CODA is able to read HDF4 files and provide some export functionality using this format. By default this capability is not included when you built CODA. To include HDF4 support you will need to have a recent version of HDF4 installed and include the ``--with-hdf4`` option when calling ``./configure``. ``HDF4_LIB=`` : If you have installed HDF4 then CODA will try to locate the HDF4 libraries in the default locations for libraries (``/usr/local/lib`` is usually not considered a default location!). If ``./configure`` complains that it can't find the ``df``, ``hdf``, or ``mfhdf`` library files, pass this option to ``./configure`` with the location of these library files. ``HDF4_INCLUDE=`` : If you have installed HDF4 then CODA will try to locate the HDF4 include files in the default locations for include files (``/usr/local/include`` is usually not considered a default location!). If ``./configure`` complains that it can't find the ``hdf.h`` or ``mfhdf.h`` include files, pass this option to ``./configure`` with the location of these include files. ``--disable-hdf4-vdata-attributes`` : Pass this option if you are using HDF4 version 4.2r1 or earlier. This option disables the support for vdata and vgroup attributes because of a problem in the HDF4 library for HDF 4.2r1 and earlier. The problem was solved in HDF 4.2r2, so for that version and later versions don't provide this option. ``--with-hdf5`` : CODA is able to read HDF5 files and provide some export functionality using this format. By default this capability is not included when you built CODA. To include HDF5 support you will need to have a recent version of HDF5 installed and include the ``--with-hdf5`` option when calling ``./configure``. ``HDF5_LIB=`` : If you have installed HDF5 then CODA will try to locate the HDF5 library in the default locations for libraries (``/usr/local/lib`` is usually not considered a default location!). If ``./configure`` complains that it can't find the ``hdf5`` library files, pass this option to ``./configure`` with the location of this library file. ``HDF5_INCLUDE=`` : If you have installed HDF5 then CODA will try to locate the HDF5 include files in the default locations for include files (``/usr/local/include`` is usually not considered a default location!). If ``./configure`` complains that it can't find the ``hdf5.h`` include file, pass this option to ``./configure`` with the location of this include file. ``F77=`` : This allows you to select which fortran compiler you will be using when you intend to use to CODA Fortran interface. CODA will then generate the Makefile template that reflects the settings for the specified fortran compiler. Note that the compiler may also be a f90 or f95 compiler. Note that you don't have to provide any options to the configure script to create the Fortran interface for CODA. The wrapper code is always created. You should now call the configure script with the options that are appropriate for you. For instance, if you want to install CODA in the default location (``/usr/local``) and if you want to build the IDL interface (but not the MATLAB interface) with IDL installed in ``/usr/local/itt/idl`` and if you don't need to have the HDF4 and HDF5 capability of CODA then your invocation of configure would be:: $ ./configure --enable-idl IDL=/usr/local/itt/idl 4) If this completes successfully, you are now able to build the library by executing the ``make`` command:: $ make 5) In order to make use of the CODA library and interfaces, you should install the CODA software. Please make sure you have provided the appropriate installation directory option (``--prefix=``) to the configure script, as explained in the previous section, if you do not want to install CODA in its default location ``/usr/local``. After running the configure script, issue the following command:: $ make install 6) Next, you may want to install one or more product format definition files (.codadef files). There are no .codadef files included with CODA, but they are available from several other sources. If you put them in the default definition directory (``$prefix/share/coda/definitions``) then the CODA command line tools and the IDL and MATLAB interfaces will automatically find them. You can also install the .codadef files in a different location and set the CODA_DEFINITION environment to point to a ``:`` separated list of paths. Each path can either be a full path to a .codadef file or a directory (containg only .codadef files). When you use the CODA_DEFINITION environment variable then also the C, Fortran and Python interfaces of CODA will be able to find the .codadef files. 7) If you enabled the IDL interface then you will have to add ``/lib/coda/idl`` to your ``DLM_PATH``. You do this by setting an ``IDL_DLM_PATH`` environment variable and add this setting to your system shell startup script (if you don't now how to set environment variables or add these to your shell startup script, please ask your system administrator). The variable should be set to ```` appended with the CODA DLM directory. If, for instance, you have installed CODA in ``/usr/local`` then you should set the ``IDL_DLM_PATH`` environment variable to ``:/usr/local/lib/coda/idl``. Note that you should ideally not use the IDL ``pref_set`` function to set the ``IDL_DLM_PATH``. The CODA DLM file will still load, but CODA will not be able to find its coda format definition files this way. You can work around this by setting an explicit path to your coda definition files directory instead of having CODA automatically determine this location based on the ``IDL_DLM_PATH``. This is done by setting the ``CODA_DEFINITION`` environment variable. This can be done outside IDL by setting the environment variable globally, but you can also do this inside IDL before you call any CODA functions using:: IDL> SETENV, 'CODA_DEFINITION=/path/to/codadefs/' 8) If you enabled the MATLAB interface then you should create a ``startup.m`` file in a ``matlab`` directory in your home directory (``~/matlab/startup.m``) that contains the line:: addpath /lib/coda/matlab 9) If you enabled Python then you won't have to do anything if you installed CODA in the same directory as you installed Python (e.g. if both are installed under ``/usr/local`` for instance). You can verify whether this is the case by checking that the file ``/lib/python3.7/os.py`` exists. (the pythonx.y directory name will depend on the Python version that you are using). If you installed CODA in another location then you should create a ``coda.pth`` file in the directory ``/lib/python3.7/site-packages`` containing one text line with the location of the Python package:: /lib/python3.7/site-packages Python will then automatically load the coda.pth file at startup and add the path to the Python package to the Python searchpath. You can also manually modify the searchpath from within Python by calling the following Python commands: >>> import sys >>> sys.path.append('/lib/python3.7/site-packages') But this manual modification will be lost as soon as you quit Python. 10) For Java you can find the CODA jni/jar files, an example script and an Ant build script in ``/share/coda/java``. Of course you should replace ```` in the above steps with the installation directory you have chosen with the ``--prefix`` option for the configure script or otherwise ``/usr/local`` (the default install location for CODA). Information on how to set environment variables on macOS can be found `here `_. Installing the binary package (Windows) --------------------------------------- To install the binary package of CODA for Windows just run the executable which will guide you through the installation process. After a successful installation you will have to perform some last steps if you want to use the IDL, MATLAB and/or Python interfaces. For Python you will have to copy the ``C:\Program Files\CODA\python\coda`` directory to the site-packages folder of your Python installation. However, if you want to use the Python interfaces on Windows, it is recommended to just install the Anaconda package of CODA. For IDL you will have to add ``\lib\coda\idl`` to your ``DLM_PATH``. You do this by setting an ``IDL_DLM_PATH`` environment variable. On Windows open the 'System' control panel of your Windows operating system and goto the 'Advanced' tab. Then click on 'Environment Variables' and create a new system variable with the name ``IDL_DLM_PATH`` and value ``;C:\Program Files\CODA\lib\coda\idl``. If you have installed CODA in a location different from ``C:\Program Files\CODA`` then replace this part in the value by the installation directory you chose when installing CODA. Note that you should ideally not use the IDL ``pref_set`` function to set the ``IDL_DLM_PATH``. The CODA DLM file will still load, but CODA will not be able to find its coda format definition files this way. You can work around this by setting an explicit path to your coda definition files directory instead of having CODA automatically determine this location based on the ``IDL_DLM_PATH``. This is done by setting the ``CODA_DEFINITION`` environment variable. This can be done outside IDL by setting the environment variable globally, but you can also do this inside IDL before you call any CODA functions using:: IDL> SETENV, 'CODA_DEFINITION=/path/to/codadefs/' For MATLAB you will have to start MATLAB and goto the 'Set Path...' menu item in the 'File' menu. Here you should add the directory ``C:\Program Files\CODA\lib\coda\matlab``. If you have installed CODA in a location different from ``C:\Program Files\CODA`` then replace this part of the directory by the installation directory you had chosen when you installed CODA. For Java you can find the CODA jni/jar files, an example script and an Ant build script in ``C:\Program Files\CODA\share\coda\java``. Note: The binary installer for Windows comes with full HDF4 and HDF5 support included in all CODA modules. Next, you may want to install one or more product format definition files (.codadef files). There are no .codadef files included with CODA, but they are available from several other sources. If you put them in the default definition directory (``\share\coda\definitions``) then the CODA command line tools and the IDL, MATLAB, and Python interfaces will automatically find them. You can also install the .codadef files in a different location and set the ``CODA_DEFINITION`` environment to point to a ``;`` separated list of paths. Each path can either be a full path to a .codadef file or a directory (containing only .codadef files). When you use the ``CODA_DEFINITION`` environment variable then also the C, Fortran and Python interfaces of CODA will be able to find the .codadef files. Building the source package (Windows) ------------------------------------- To build the source package, make sure to download the official CODA source package, which is named ``coda-x.y.z.tar.gz``. The official and only supported build system on Windows is CMake. You will need to have builds of HDF4 and HDF5 (and their dependencies) available as well in order to build CODA with HDF4 and HDF5 support. The locations of include files and libraries for the third-party dependencies can be set using ``_INCLUDE_DIR`` and ``_LIBRARY_DIR`` CMake options. The generation of the Windows binary installer is done using CPack and WIX. So, in order to recreate the Windows binary installer, you will also have to make sure that you have CMake (3.0 or later) and WIX installed. Documentation location ---------------------- Both the source and binary CODA packages come with documentation in HTML. For the source package you can access the documentation from within the unpacked CODA source package directory by going to the ``doc/html`` subdirectory and opening the file ``index.html`` in your Internet browser. If you perform an install of the source package all documentation will also be installed. You can find the documentation under the subdirectory ``share/coda/doc/html`` of your installation directory (``/usr/local`` by default). For the Windows binary package all documentation can be found in the subdirectory ``doc\html`` of your installation directory (``C:\Program Files\CODA`` by default). Known issues ------------ When compiling with HDF4 enabled, and where HDF4 is build with only static libraries (which is the default), you may get the following error during compilation:: Undefined symbols: "_GRreftoindex", referenced from: _init_hdf4Vgroups in libcoda.a(libcoda_la-coda-hdf4-definition.o) "_VFnfields", referenced from: _init_hdf4Vdatas in libcoda.a(libcoda_la-coda-hdf4-definition.o) "_SDend", referenced from: _coda_hdf4_close in libcoda.a(libcoda_la-coda-hdf4-definition.o) "_GRstart", referenced from: _coda_hdf4_open in libcoda.a(libcoda_la-coda-hdf4-definition.o) This is due to an issue with GNU libtool, a tool to deal with shared/static libraries and which is used by various open source packages (including CODA). There are (at least) three ways of working around this problem: - Remove the libdf.la and libmfhdf.la files after installation of HDF4 (these files are only used by libtool, so this should not introduce any other problems on your system) - Build HDF4 with shared libraries enabled (add '--enable-shared' as option to the call to ./configure when configuring your HDF4 source package) - Explicitly add 'LIBS="-L -lmfhdf -ldf"' as an option to the configure script of CODA, where should be replaced with the directory location of the HDF4 libraries. Feedback -------- If you encounter any problems while trying to build, install or run one or more components of the CODA package then create a topic on the Atmospheric Toolbox Forum for support: https://forum.atmospherictoolbox.org/ If you are using the source package on a Unix based system, please provide a copy of the config.log file that is created when you run ``./configure`` and a copy of the output of ``make`` with your e-mail. Apart from problems, we would also appreciate to hear from you if you have any ideas, suggestions, or comments that may help us to improve the quality or functionality of CODA.