Document and script building the native bridge for older Linux#1
Merged
Conversation
The native bridge libraries bundled in the JAR are compiled on Ubuntu 24.04,
so they require GLIBC_2.32 and a libstdc++ exporting GLIBCXX_3.4.32 (a GCC 13+
runtime). On older hosts (e.g. Ubuntu 20.04: glibc 2.31 / GLIBCXX 3.4.28, and
also Ubuntu 22.04, whose libstdc++ only reaches GLIBCXX_3.4.30) the first BRKGA
call fails to load the bridge with "Cannot open library:
/tmp/brkga-native-*/libbrkga_bridge_1.so". Nothing in the docs covered this.
Add a way to build a compatible bridge locally and pick it up transparently:
- scripts/build_brkga_native.sh: standalone helper that clones the published
tag and builds the bridge inside an older base image (default ubuntu:20.04)
with g++-13 from the ubuntu-toolchain-r PPA. It statically links
libstdc++/libgcc by folding the flags into CXX ("-static-libstdc++
-static-libgcc"), so the result links against an old-enough glibc and carries
its own C++ runtime, needing no host GLIBCXX. The base image (IMAGE),
objective counts (TUPLE_NS), generic bridge (GENERIC), mating mode, extra-blob
capacity and output directory (OUT_DIR) are all parametrizable; inputs are
validated up front and the temporary clone is cleaned up on exit.
- docs/JAVA_GUIDE.md: new "Running on an older Linux" section explaining the
symptom, exactly which glibc/GLIBCXX thresholds are affected (with a table
showing that release date is not the criterion), and two build routes (Docker
and a local toolchain). Pointers added from "Installing", "Requirements and
platform", the root README and the examples README.
- .gitignore: ignore the locally built native/ output directories.
Verified end-to-end on Ubuntu 20.04: the built libbrkga_bridge_1.so needs at
most GLIBC_2.29 and no libstdc++.so.6, and the MainMinimal example runs against
it via examples/native/ with no extra flags.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The native bridge libraries bundled in the JAR are compiled on Ubuntu 24.04, so they require GLIBC_2.32 and a libstdc++ exporting GLIBCXX_3.4.32 (a GCC 13+ runtime). On older hosts (e.g. Ubuntu 20.04: glibc 2.31 / GLIBCXX 3.4.28, and also Ubuntu 22.04, whose libstdc++ only reaches GLIBCXX_3.4.30) the first BRKGA call fails to load the bridge with "Cannot open library: /tmp/brkga-native-*/libbrkga_bridge_1.so". Nothing in the docs covered this.
Add a way to build a compatible bridge locally and pick it up transparently:
scripts/build_brkga_native.sh: standalone helper that clones the published tag and builds the bridge inside an older base image (default ubuntu:20.04) with g++-13 from the ubuntu-toolchain-r PPA. It statically links libstdc++/libgcc by folding the flags into CXX ("-static-libstdc++ -static-libgcc"), so the result links against an old-enough glibc and carries its own C++ runtime, needing no host GLIBCXX. The base image (IMAGE), objective counts (TUPLE_NS), generic bridge (GENERIC), mating mode, extra-blob capacity and output directory (OUT_DIR) are all parametrizable; inputs are validated up front and the temporary clone is cleaned up on exit.
docs/JAVA_GUIDE.md: new "Running on an older Linux" section explaining the symptom, exactly which glibc/GLIBCXX thresholds are affected (with a table showing that release date is not the criterion), and two build routes (Docker and a local toolchain). Pointers added from "Installing", "Requirements and platform", the root README and the examples README.
.gitignore: ignore the locally built native/ output directories.
Verified end-to-end on Ubuntu 20.04: the built libbrkga_bridge_1.so needs at most GLIBC_2.29 and no libstdc++.so.6, and the MainMinimal example runs against it via examples/native/ with no extra flags.