Merge branch 'develop' into ci_updates_nov2023

.github/workflows/Intel.yml

@@ -40,17 +40,17 @@ jobs:
         echo "source /opt/intel/oneapi/setvars.sh" >> ~/.bash_profile
 
     - name: checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         path: bufr
         submodules: true
 
     - name: cache-data
       id: cache-data
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/data
-        key: data-10
+        key: data-15
 
     - name: build
       run: |
@@ -70,4 +70,4 @@ jobs:
       if: steps.cache-data.outputs.cache-hit != 'true'
       run: |
         mkdir ~/data
-        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-11.6.0.tgz ~/data
+        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-12.1.0.tgz ~/data

.github/workflows/Linux.yml

@@ -30,17 +30,17 @@ jobs:
        sudo python3 -m pip install -U pdoc
 
     - name: checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         path: bufr
         submodules: true
 
     - name: cache-data
       id: cache-data
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/data
-        key: data-10
+        key: data-15
 
     - name: build
       run: |
@@ -69,4 +69,4 @@ jobs:
       if: steps.cache-data.outputs.cache-hit != 'true'
       run: |
         mkdir ~/data
-        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-11.6.0.tgz ~/data
+        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-12.1.0.tgz ~/data

.github/workflows/MacOS.yml

@@ -17,6 +17,7 @@ jobs:
     runs-on: macos-latest
     env:
       FC: gfortran-11
+      F90: gfortran-11
 
     steps:
 
@@ -34,16 +35,16 @@ jobs:
         sudo ln -sf /usr/local/bin/gfortran-11 /usr/local/bin/gfortran
 
     - name: checkout-bufr
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with: 
         path: bufr
 
     - name: cache-data
       id: cache-data
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/data
-        key: data-10
+        key: data-15
 
     - name: build-bufr
       run: |
@@ -65,4 +66,4 @@ jobs:
       if: steps.cache-data.outputs.cache-hit != 'true'
       run: |
         mkdir ~/data
-        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-11.6.0.tgz ~/data
+        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-12.1.0.tgz ~/data

.github/workflows/Spack.yml

@@ -0,0 +1,92 @@
+# This is a CI workflow for the NCEPLIBS-bufr project.
+#
+# This workflow builds NCEPLIBS-bufr with Spack, including installing with the
+# "--test root" option to run the CTest suite. It also has a one-off job that
+# validates the recipe by ensuring that every CMake option that should be set
+# in the Spack recipe is so set.
+#
+# Alex Richert, Jan 2024
+name: Spack
+on:
+  push:
+    branches:
+    - develop
+  pull_request:
+    branches:
+    - develop
+
+jobs:
+  # This job builds with Spack using every combination of variants and runs the CTest suite each time
+  Spack:
+
+    strategy:
+      matrix:
+        os: ["ubuntu-latest"]
+        variants: ["+python ~shared ~utils", "~python +shared +utils"]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+
+    - name: checkout-bufr
+      uses: actions/checkout@v4
+      with: 
+        path: bufr
+
+    - name: install-python
+      if: ${{ contains(matrix.variants, '+python') }}
+      run: |
+        sudo apt install python3 python3-numpy
+
+    - name: cache-data
+      id: cache-data
+      uses: actions/cache@v4
+      with:
+        path: ~/data
+        key: data-15
+
+    - name: spack-build-and-test
+      run: |
+        git clone -c feature.manyFiles=true https://github.com/spack/spack -b releases/v0.21
+        . spack/share/spack/setup-env.sh
+        spack env create bufr-env $GITHUB_WORKSPACE/bufr/spack/spack.yaml
+        spack env activate bufr-env
+        cp $GITHUB_WORKSPACE/bufr/spack/package.py $SPACK_ROOT/var/spack/repos/builtin/packages/bufr/package.py
+        spack develop --no-clone --path $GITHUB_WORKSPACE/bufr bufr@develop test_files=/home/runner/data
+        spack add bufr@develop%gcc@11 ${{ matrix.variants }}
+        spack external find cmake gmake python py-numpy
+        spack concretize
+        # Run installation and run CTest suite
+        spack install --verbose --fail-fast --test root
+        # Print test results
+        #cat $(spack location -i bufr)/.spack/install-time-test-log.txt
+        # Run 'spack load' and check that key build options were respected
+        spack load bufr
+        if [[ "${{ matrix.variants }}" =~ "+shared" ]]; then suffix="so" ; else suffix="a"; fi
+        libvar=BUFR_LIB4
+        ls ${BUFR_LIB4} | grep -cE "/libbufr_4\."$suffix'$'
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: ${{ failure() }}
+      with:
+        name: spackci-ctest-output-${{ matrix.os }}-${{ matrix.variants }}
+        path: ${{ github.workspace }}/*/spack-build-*/Testing/Temporary/LastTest.log
+
+  # This job validates the Spack recipe by making sure each cmake build option is represented
+  recipe-check:
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: checkout-bufr
+      uses: actions/checkout@v4
+      with: 
+        path: bufr
+
+    - name: recipe-check
+      run: |
+        echo "If this jobs fails, look at the most recently output CMake option below and make sure that option appears in spack/package.py"
+        for opt in $(grep -ioP '^option\(\K(?!(ENABLE_DOCS))[^ ]+' $GITHUB_WORKSPACE/bufr/CMakeLists.txt) ; do
+          echo "Checking for presence of '$opt' CMake option in package.py"
+          grep -cP "define.+\b${opt}\b" $GITHUB_WORKSPACE/bufr/spack/package.py
+        done

.github/workflows/developer.yml

@@ -28,17 +28,17 @@ jobs:
           sudo python3 -m pip install -U gcovr pdoc
 
     - name: checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         path: bufr
         submodules: true
 
     - name: cache-data
       id: cache-data
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/data
-        key: data-10
+        key: data-15
 
     - name: build-docs
       run: |
@@ -66,16 +66,16 @@ jobs:
       if: steps.cache-data.outputs.cache-hit != 'true'
       run: |
         mkdir ~/data
-        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-11.6.0.tgz ~/data
+        cp $GITHUB_WORKSPACE/bufr/build/test/bufr-12.1.0.tgz ~/data
         
-    - uses: actions/upload-artifact@v3
+    - uses: actions/upload-artifact@v4
       with:
         name: test-coverage
         path: |
           bufr/build/*.html
           bufr/build/*.css
 
-    - uses: actions/upload-artifact@v3
+    - uses: actions/upload-artifact@v4
       with:
         name: docs
         path: |

CMakeLists.txt

@@ -14,6 +14,8 @@ project(
 option(ENABLE_DOCS "Enable generation of doxygen-based documentation." OFF)
 option(ENABLE_PYTHON "Enable building python module 'ncepbufr'" OFF)
 option(BUILD_SHARED_LIBS "Enable building shared libraries" OFF)
+option(BUILD_UTILS "Enable building utilities" ON)
+option(BUILD_TESTING "Enable automated testing" ON)
 
 # Developers can use this option to specify a local directory which
 # holds the test files. They will be copied instead of fetching the
@@ -105,7 +107,10 @@ elseif(CMAKE_Fortran_COMPILER_ID MATCHES "^(GNU)$")
 endif()
 
 add_subdirectory(src)
-add_subdirectory(utils)
+
+if(BUILD_UTILS)
+  add_subdirectory(utils)
+endif()
 
 if(ENABLE_PYTHON)
   add_subdirectory(python)
@@ -114,8 +119,8 @@ endif()
 add_subdirectory(tables)
 
 # Turn on unit testing.
-include(CTest)
 if(BUILD_TESTING)
+  include(CTest)
   add_subdirectory(test)
 endif()
 

README.md

@@ -62,6 +62,15 @@ If Python interoperability is desired, `-DENABLE_PYTHON=ON` can also
 be added to the above cmake command.  However, version 3 of Python
 must be installed and available on the system.
 
+## References
+
+Hartnett, E., Ator, J, Lei, H., Richert, A., Woollen, J., King, A.,
+Hartnett, A., [NCEPLIBS GRIB and BUFR Libraries: Maintaining and
+Modernizing NOAA's Libraries for WMO Data
+Formats](https://www.researchgate.net/publication/376390180_NCEPLIBS_GRIB_and_BUFR_Libraries_Maintaining_and_Modernizing_NOAA's_Libraries_for_WMO_Data_Formats),
+American Geophysical Union (AGU) 2023. (See also
+[poster](https://www.researchgate.net/publication/376582005_Poster_-_IN51B-0416_NCEPLIBS_GRIB_and_BUFR_Libraries_Maintaining_and_Modernizing_NOAA's_Libraries_for_WMO_Data_Formats)).
+
 ## Disclaimer
 
 The United States Department of Commerce (DOC) GitHub project code is

VERSION

@@ -1 +1 @@
-12.0.1
+12.1.0

docs/dx_tables.md

@@ -14,8 +14,6 @@ information must be supplied, such as the example shown below. Such
 files must be syntactically correct and also complete, in the sense
 that all necessary mnemonics must exist and be fully-defined.
 
-<br>
-
 ## Mnemonics
 
 A <i>mnemonic</i> is a
@@ -26,8 +24,6 @@ descriptive, alphanumeric name for a data value.
 sequences composed of one or more Table B (or other Table D) mnemonics and which are themselves
 normally direct constituents of a particular Table A mnemonic.
 
-<br>
-
 At the highest level, we have a Table A mnemonic which completely
 describes a type of data subset (e.g. rawinsonde, wind profiler,
 etc.). This Table A mnemonic is defined as a sequence of one or more
@@ -38,13 +34,6 @@ described as a sequence of one or more Table B mnemonics which
 correspond to basic data values (e.g. pressure, temperature, humidity,
 etc.).
 
-<br>
-
-The entire sequence of data values that constitute a particular type
-of data subset is fully and unambiguously defined.
-
-<br>
-
 Mnemonics never themselves appear within actual BUFR messages.  Their
 only purpose is to make it easier for users to interact with the
 software by providing descriptive names to represent individual data
@@ -70,8 +59,6 @@ more Table B (or other Table D) mnemonics.
 mnemonics are defined in terms of their scale factor, reference value,
 bit width, and units.
 
-<br>
-
 <div id="section1">
 ### Section 1
 

docs/master_tables.md

@@ -13,8 +13,6 @@ different value of IO is specified, then only a
 [DX BUFR tables](@ref dfbftab) file is normally required, and master
 BUFR tables are not needed.
 
-<br>
-
 Whenever master BUFR tables are used, they are read in by the BUFRLIB
 software as a corresponding set of four system files, from a directory
 on the local filesystem as specified within a separate preceding call
@@ -66,8 +64,6 @@ stored within Section 1 of each new message to be decoded. For more
 details about the above values, see the discussion on Section 1 within
 the official [WMO Manual 306, Volume I.2](@ref manual).
 
-<br>
-
 Now that we've discussed the content and naming conventions for master
 BUFR table files, let's turn our attention to the actual format of
 these files:

docs/user_guide.md

@@ -70,10 +70,10 @@ library subroutines and functions to accomplish different tasks.
 @anchor hierarchy
 It's important to understand the following hierarchy:
 
-1. Any BUFR file can consist of one or more BUFR messages.
-2. Any BUFR message can consist of one or more BUFR data subsets, which are akin to reports from individual
+1. Any BUFR file can contain one or more BUFR messages.
+2. Any BUFR message can contain one or more BUFR data subsets, which are akin to reports from individual
 observational stations at a particular time and location.
-3. Any BUFR data subset can consist of one or more BUFR data descriptors and corresponding data values.
+3. Any BUFR data subset can contain one or more BUFR data descriptors and corresponding data values.
 
 This allows many of the most commonly used library subroutines and
 functions to be grouped based on which level of the hierarchy they