Skip to content

Add Symbol Versioning Support#3096

Open
skmcgrail wants to merge 4 commits intoaws:mainfrom
skmcgrail:washbear-symbol-ver
Open

Add Symbol Versioning Support#3096
skmcgrail wants to merge 4 commits intoaws:mainfrom
skmcgrail:washbear-symbol-ver

Conversation

@skmcgrail
Copy link
Member

@skmcgrail skmcgrail commented Mar 12, 2026

⚠️ This is very much experimental. When we are ready to stabilize on our SONAME and Symbol Versioning direction we will bump to version 1. For now 0 reported in our soname and version scripts indicates that it is unstable and open for breakage. ⚠️

Summary

  • ELF symbol versioning for libcrypto-awslc and libssl-awslc shared libraries, automatically enabled when building in distribution packaging mode (-DENABLE_DIST_PKG=1). All public API symbols are assigned to the AWS_LC_1_0 version namespace (~3,800 libcrypto symbols, ~600 libssl symbols).
  • Symbol registry files (crypto/libcrypto.txt, ssl/libssl.txt) and GNU ld version scripts (crypto/libcrypto.map, ssl/libssl.map) that serve as the source of truth for exported symbols and their versions.
  • Go-based tooling (util/read_public_symbols, util/generate_version_script) to extract public symbols from headers and generate version scripts, along with shell scripts (util/generate_initial_version_scripts.sh, util/update_symbol_version.sh) for initial population and version bumps.
  • CI jobs in the abidiff.yml workflow for incremental (commit-to-commit) and baseline (headers-to-registry) symbol checks, detecting unregistered new APIs and blocking public symbol removals (ABI breaks).
  • CI jobs in linux-multi-arch-omnibus.yml to validate symbol versioning works end-to-end by building and running tests across Ubuntu 24.04, Amazon Linux 2, and Amazon Linux 2023 on both x86_64 and aarch64.
  • CMake integration via cmake/GenerateVersionScript.cmake with linker compatibility probing (detects --undefined-version support for lld compatibility).
  • Documentation in docs/SymbolVersioning.md, BUILDING.md, and README.md covering build configuration, version evolution, developer workflow, and troubleshooting.

Testing

  • run_symbol_version_test.sh validates: version scripts are applied, all exported symbols have version tags, no unversioned symbols leak, version definitions are present, and libraries link correctly
  • run_dist_pkg_run_tests.sh builds with -DENABLE_DIST_PKG=ON and runs the full test suite
  • CI symbol check jobs (incremental + baseline) pass for both libcrypto and libssl
  • Multi-arch CI matrix (gcc/clang × x86_64/aarch64 × AL2/AL2023/Ubuntu) passes
  • go test passes for util/read_public_symbols and util/generate_version_script

I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

@codecov-commenter
Copy link

codecov-commenter commented Mar 12, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.14%. Comparing base (1df4976) to head (1fa44ab).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3096      +/-   ##
==========================================
- Coverage   78.16%   78.14%   -0.02%     
==========================================
  Files         689      689              
  Lines      121643   121676      +33     
  Branches    16987    16996       +9     
==========================================
+ Hits        95077    95089      +12     
- Misses      25682    25704      +22     
+ Partials      884      883       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@skmcgrail skmcgrail marked this pull request as ready for review March 16, 2026 18:38
@skmcgrail skmcgrail requested a review from a team as a code owner March 16, 2026 18:38
@@ -0,0 +1,326 @@
#!/usr/bin/env bash
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • This tests indicates success when run, but returns an error exit status:
...
-- Build files have been written to: /home/justsmth/repos/aws-lc/build_symbol_test
ninja: Entering directory `/home/justsmth/repos/aws-lc/build_symbol_test'
[416/416] Creating library symlink ssl/libssl-awslc.so.0 ssl/libssl-awslc.so
✓ PASS: Build successful
  • This test should be added to the CI.

Comment on lines +93 to +94
LIBCRYPTO_SO="${BUILD_DIR}/crypto/libcrypto-awslc.so.0.0.0"
LIBSSL_SO="${BUILD_DIR}/ssl/libssl-awslc.so.0.0.0"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • libcrypto-awslc.so.0.0.0 is hard-coded, but the build produces libcrypto-awslc.so.1.70.0 (the SOFTWARE_VERSION from CMakeLists.txt)?

Comment on lines +38 to +41
print_pass() {
echo -e "${GREEN}✓ PASS${NC}: $1"
((pass_count++))
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The silent failure is due to set -e and ((pass_count++)), which on first run evaluates to ((0++)) returning exit code 1 and terminating the script.

This should work:

pass_count=$((pass_count + 1))

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants