Merge branch 'borglab:develop' into develop

Author: JokerJohn

.github/scripts/unix.sh

@@ -45,13 +45,15 @@ function configure()
       -DGTSAM_BUILD_TESTS=${GTSAM_BUILD_TESTS:-OFF} \
       -DGTSAM_BUILD_UNSTABLE=${GTSAM_BUILD_UNSTABLE:-ON} \
       -DGTSAM_WITH_TBB=${GTSAM_WITH_TBB:-OFF} \
-      -DGTSAM_BUILD_EXAMPLES_ALWAYS=${GTSAM_BUILD_EXAMPLES_ALWAYS:-ON} \
+      -DGTSAM_BUILD_EXAMPLES_ALWAYS=${GTSAM_BUILD_EXAMPLES_ALWAYS:-OFF} \
       -DGTSAM_ALLOW_DEPRECATED_SINCE_V43=${GTSAM_ALLOW_DEPRECATED_SINCE_V43:-OFF} \
       -DGTSAM_USE_QUATERNIONS=${GTSAM_USE_QUATERNIONS:-OFF} \
       -DGTSAM_ROT3_EXPMAP=${GTSAM_ROT3_EXPMAP:-ON} \
       -DGTSAM_POSE3_EXPMAP=${GTSAM_POSE3_EXPMAP:-ON} \
       -DGTSAM_USE_SYSTEM_EIGEN=${GTSAM_USE_SYSTEM_EIGEN:-OFF} \
       -DGTSAM_USE_SYSTEM_METIS=${GTSAM_USE_SYSTEM_METIS:-OFF} \
+      -DGTSAM_USE_BOOST_FEATURES=${GTSAM_USE_BOOST_FEATURES:-ON} \
+      -DGTSAM_ENABLE_BOOST_SERIALIZATION=${GTSAM_ENABLE_BOOST_SERIALIZATION:-ON} \
       -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF \
       -DGTSAM_SINGLE_TEST_EXE=OFF
 }
@@ -69,7 +71,6 @@ function finish ()
 # compile the code with the intent of populating the cache
 function build ()
 {
-  export GTSAM_BUILD_EXAMPLES_ALWAYS=ON
   export GTSAM_BUILD_TESTS=OFF
 
   configure
@@ -90,7 +91,6 @@ function build ()
 # run the tests
 function test ()
 {
-  export GTSAM_BUILD_EXAMPLES_ALWAYS=OFF
   export GTSAM_BUILD_TESTS=ON
 
   configure

.github/workflows/build-linux.yml

@@ -2,8 +2,8 @@ name: Linux CI
 
 on: [pull_request]
 
-# Every time you make a push to your PR, it cancel immediately the previous checks, 
-# and start a new one. The other runner will be available more quickly to your PR. 
+# Every time you make a push to your PR, it cancel immediately the previous checks,
+# and start a new one. The other runner will be available more quickly to your PR.
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -25,11 +25,12 @@ jobs:
         # Github Actions requires a single row to be added to the build matrix.
         # See https://help.github.com/en/articles/workflow-syntax-for-github-actions.
         name: [
-          ubuntu-20.04-gcc-9,
-          ubuntu-20.04-clang-9,
-          ubuntu-22.04-gcc-12,
-          ubuntu-22.04-clang-14,
-        ]
+            # "Bracket" the versions from GCC [9-14] and Clang [9-16]
+            ubuntu-20.04-gcc-9,
+            ubuntu-20.04-clang-9,
+            ubuntu-24.04-gcc-14,
+            ubuntu-24.04-clang-16,
+          ]
 
         build_type: [Debug, Release]
         build_unstable: [ON]
@@ -44,15 +45,15 @@ jobs:
             compiler: clang
             version: "9"
 
-          - name: ubuntu-22.04-gcc-12
-            os: ubuntu-22.04
+          - name: ubuntu-24.04-gcc-14
+            os: ubuntu-24.04
             compiler: gcc
-            version: "11"
+            version: "14"
 
-          - name: ubuntu-22.04-clang-14
-            os: ubuntu-22.04
+          - name: ubuntu-24.04-clang-16
+            os: ubuntu-24.04
             compiler: clang
-            version: "14"
+            version: "16"
 
     steps:
       - name: Checkout

.github/workflows/build-special.yml

@@ -2,8 +2,8 @@ name: Special Cases CI
 
 on: [pull_request]
 
-# Every time you make a push to your PR, it cancel immediately the previous checks, 
-# and start a new one. The other runner will be available more quickly to your PR. 
+# Every time you make a push to your PR, it cancel immediately the previous checks,
+# and start a new one. The other runner will be available more quickly to your PR.
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -34,6 +34,7 @@ jobs:
             ubuntu-clang-system-libs,
             ubuntu-no-boost,
             ubuntu-no-unstable,
+            ubuntu-build-examples,
           ]
 
         build_type: [Debug, Release]
@@ -81,6 +82,12 @@ jobs:
             version: "14"
             flag: no_unstable
 
+          - name: ubuntu-build-examples
+            os: ubuntu-22.04
+            compiler: clang
+            version: "14"
+            flag: build_examples
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -115,19 +122,24 @@ jobs:
             echo "CXX=clang++-${{ matrix.version }}" >> $GITHUB_ENV
           fi
 
-      - name: Install Boost
-        if: runner.os == 'Linux'
-        run: |
-          sudo apt-get -y install libboost-all-dev
-
       - name: Install (macOS)
         if: runner.os == 'macOS'
         run: |
-          brew install cmake ninja boost
+          brew install cmake ninja
           sudo xcode-select -switch /Applications/Xcode_${{ matrix.version }}.app
           echo "CC=clang" >> $GITHUB_ENV
           echo "CXX=clang++" >> $GITHUB_ENV
 
+      - name: Install Boost
+        run: |
+          if [ ${{matrix.flag}} != 'no_boost' ]; then
+            if [ ${{runner.os}} == 'Linux' ]; then
+              sudo apt-get -y install libboost-all-dev
+            elif [ ${{runner.os}} == 'macOS' ]; then
+              brew install boost
+            fi
+          fi
+
       - name: Set Allow Deprecated Flag
         if: matrix.flag == 'deprecated'
         run: |
@@ -153,6 +165,11 @@ jobs:
           echo "GTSAM_ROT3_EXPMAP=OFF" >> $GITHUB_ENV
           echo "GTSAM Uses Cayley map for Rot3"
 
+      - name: Build Examples
+        if: matrix.flag == 'build_examples'
+        run: |
+          echo "GTSAM_BUILD_EXAMPLES_ALWAYS=ON" >> $GITHUB_ENV
+
       - name: Use system versions of 3rd party libraries
         if: matrix.flag == 'system'
         run: |
@@ -181,7 +198,6 @@ jobs:
         with:
           swap-size-gb: 12
 
-
       - name: Build & Test
         run: |
           bash .github/scripts/unix.sh -t

Using-GTSAM-EXPORT.md

@@ -3,9 +3,9 @@
 To create a DLL in windows, the `GTSAM_EXPORT` keyword has been created and needs to be applied to different methods and classes in the code to expose this code outside of the DLL.  However, there are several intricacies that make this more difficult than it sounds.  In general, if you follow the following three rules, GTSAM_EXPORT should work properly.  The rest of the document also describes (1) the common error message encountered when you are not following these rules and (2) the reasoning behind these usage rules.
 
 ## Usage Rules
-1.  Put `GTSAM_EXPORT` in front of any function that you want exported in the DLL _if and only if_ that function is declared in a .cpp file, not just a .h file.
+1.  Put `GTSAM_EXPORT` in front of any function that you want exported in the DLL _if and only if_ that function is defined in a .cpp file, not just a .h file.
 2.  Use `GTSAM_EXPORT` in a class definition (i.e. `class GSTAM_EXPORT MyClass {...}`) only if:
-    * At least one of the functions inside that class is declared in a .cpp file and not just the .h file.
+    * At least one of the functions inside that class is defined in a .cpp file and not just the .h file.
     * You can `GTSAM_EXPORT` any class it inherits from as well.  (Note that this implictly requires the class does not derive from a "header-only" class.  Note that Eigen is a "header-only" library, so if your class derives from Eigen, _do not_ use `GTSAM_EXPORT` in the class definition!) 
 3.  If you have defined a class using `GTSAM_EXPORT`, do not use `GTSAM_EXPORT` in any of its individual function declarations.  (Note that you _can_ put `GTSAM_EXPORT` in the definition of individual functions within a class as long as you don't put `GTSAM_EXPORT` in the class definition.)
 4. For template specializations, you need to add `GTSAM_EXPORT` to each individual specialization.
@@ -28,7 +28,7 @@ But first, we need to understand exactly what `GTSAM_EXPORT` is.  `GTSAM_EXPORT`
 
 Rule #1 doesn't seem very bad, until you combine it with rule #2
 
-***Compiler Rule #2*** Anything declared in a header file is not included in a DLL.
+***Compiler Rule #2*** Anything defined in a header file is not included in a DLL.
 
 When these two rules are combined, you get some very confusing results.  For example, a class which is completely defined in a header (e.g. Foo) cannot use `GTSAM_EXPORT` in its definition.  If Foo is defined with `GTSAM_EXPORT`, then the compiler _must_ find Foo in a DLL.  Because Foo is a header-only class, however, it can't find it, leading to a very confusing "I can't find this symbol" type of error.  Note that the linker says it can't find the symbol even though the compiler found the header file that completely defines the class.