Clone and Build a Bundle

This page lays out the generic steps to clone, build, and test a JEDI bundle. For specific instructions on modules, environment variables, etc. on NOAA HPC platforms see:

• Hera
• Orion

Clone Bundle

Currently there are three supported bundles for EMC developers:

• ufo-bundle
• fv3-bundle
• ioda-bundle

For more information on what a bundle is, and the differences between these three see Bundles in ecbuild.

Once you have determined which bundle you wish to clone and build, first you need to clone it.

cd /path/to/JEDI/work
git clone https://github.com/jcsda-internal/fv3-bundle.git

Replace /path/to/JEDI/work with where you wish to clone the bundle to and fv3-bundle with the name of the bundle you wish to clone.

NOTE: This only clones the bundle, and does not clone all the repositories/components that make up the bundle. The additional cloning step will happen during the ecbuild step.

Make build directory

Some people like to create the build directory inside the bundle, others like it to be next to it in the cloning directory, but it does not matter where the build directory is located relative to the bundle.

Create a build directory. In this example, we will put the build directory inside the bundle.

cd fv3-bundle
mkdir build
cd build

Check your branches (if applicable)

If wanting to compile/run/test any branch/tag of a component besides develop, you will need to modify the bundle's CMakeLists.txt file.

vi /path/to/JEDI/work/fv3-bundle/CMakeLists.txt

This file tells ecbuild (the build wrapper for cmake used by JEDI) which components, and just as importantly, which tags/branches of each component, to clone, checkout and build.

The different JEDI components are briefly discussed in another page on this wiki. When doing development or testing, this file will need to be modified to ensure that the correct tags/branches are being built. Just because you are working in a branch on a subdirectory (e.g. ufo’s feature/myfeature branch), the build will not include your code changes unless you ensure that the ecbuild_bundle line for ufo also is checking out feature/myfeature.

Instead of TAG, which is for GitHub tags, use BRANCH when wanting to checkout a specific branch. Additionally, at the end of these lines, one can add a UPDATE, which will perform a git pull on each branch that includes UPDATE during build time.

github.com/jcsda is the public repository that everyone has access to, but some of you may have access to jcsda-internal. Others may fork a repository to do their own work on it. Be sure that the ecbuild_bundle line points to the correct URL to whichever repository you wish to clone/work with.

Run ecbuild

Once you have verified each component will check out the branch that you want, it is time to run ecbuild. Depending on the machine you are on, and the options you wish to build with, your ecbuild command may change. For a very basic case:

ecbuild /path/to/bundle

This command will do the following

• Clone all repositories in the bundle
• Checkout branches/tags as specified
• Find locations of compilers, libraries, etc. for building
• Prepare cmake files for building the libraries and executables

If this command runs successfully, next it is time to actually build/compile the code. An example of the standard out that implies it was successful:

-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/my/JEDI/build

Run make

On HPC platforms, you can run make with multiple threads to speed up the process:

make -jN

where N is the number of threads.

This is a reasonable choice for NOAA HPC platforms:

make -j8

Just running make will work fine on any machine, but will be ~8x slower than the above command.

Run ctest

Assuming everything built correctly without issues, now we can verify that the code runs as expected. The JEDI components each have a number of unit tests, tests that run quickly and test a very small subset of code or that use a small set of input data.

These unit tests are built in the ctest framework. To list all of the tests available to run, in your build directory: ctest -N

Notice how there are several tests for each component. To run a subset of tests, you can use -R somestr where somestr is a regular expression to match. For example: ctest -R fv3jedi

will run all of the tests that have ‘fv3jedi’ in their names. You can combine -R and -N to just list the tests that match some regular expression, i.e.: ctest -N -R fv3jedi

To run every test, just type: ctest

After doing this, if all goes correctly, you should see something like this:

100% tests passed, 0 tests failed out of 853

Label Time Summary:
atlas         =  69.60 sec*proc (134 tests)
crtm          =  41.83 sec*proc (80 tests)
executable    = 263.19 sec*proc (262 tests)
fckit         =  26.36 sec*proc (14 tests)
femps         =   8.82 sec*proc (1 test)
fortran       =   8.08 sec*proc (35 tests)
fv3-jedi      = 375.26 sec*proc (61 tests)
fv3jedi       = 377.55 sec*proc (62 tests)
ioda          =  15.67 sec*proc (15 tests)
mpi           = 527.23 sec*proc (144 tests)
oops          = 100.21 sec*proc (204 tests)
openmp        = 307.92 sec*proc (123 tests)
saber         = 326.33 sec*proc (149 tests)
script        = 1109.46 sec*proc (589 tests)
ufo           = 428.92 sec*proc (194 tests)

Total Test time (real) = 1398.17 sec

This means that all the tests passed and your bundle is ready to go.

You’ll notice that the tests run without any output, you can add -V (for verbose) and -VV (very verbose) to see output (even more output) when each test runs.