Manage native libraries with linker namespacing

Linker namespacing is a library isolation technique that organizes shared libraries into separate linking environments within a process. Vega’s dynamic linker (ld-linux-<arch>.so) implements this technique to prevent conflicts between your app’s libraries and system libraries. The dynamic linker enforces namespace boundaries at runtime on all devices. Linker namespacing applies to all native code running on Vega OS.

When you need this

You need to understand linker namespacing if you’re: Building apps with native code

Using C/C++ libraries in your Vega app
Integrating third-party native SDKs (video players, analytics, DRM)
Creating custom Turbo Modules with native implementations
Porting existing Android or Linux apps to Vega

Encountering build or runtime issues

Build fails with “library found in package” errors
App crashes with “cannot open shared object file” errors
Symbols resolve incorrectly at runtime
App works on one device but fails on another

Preparing for Appstore submission

Your app must pass ABI validation during certification
You need to ensure your app works across OS updates
You want to avoid rejection due to library conflicts

What linker namespacing provides

Stability: Your app only accesses well-versioned, Application Binary Interface (ABI)-stable system libraries
Isolation: Your bundled libraries never conflict with system libraries
Compatibility: Your app continues working across OS updates

What you can do with linker namespacing

Build apps with native code that use shared libraries correctly
Bundle third-party libraries without causing conflicts
Link against system libraries safely and efficiently
Troubleshoot build failures related to library dependencies or ABI violations

How it works

The dynamic linker separates libraries into two namespaces to enforce isolation and prevent conflicts. Your app’s namespace

Contains all libraries bundled in your app package (mounted, at runtime, to )
Can access approved system libraries from the Vega OS public ABI list
Isolated from internal OS libraries

System namespace

Contains OS-internal libraries
Only exposes libraries on the public ABI list to apps
Prevents access to unstable or version-incompatible system libraries

Runtime loading process

At runtime, your app’s native entry points load into the app namespace. Then, for each subsequently loaded library, the dynamic linker:

Determines which namespace the requested library belongs to.
Checks whether your app has permission to access that library.
Loads the library only if it belongs to your app’s namespace or is on the public ABI list.
Blocks access to system-internal libraries, preventing runtime failures from incompatible versions.

Accessing system libraries

System libraries on the public ABI list are initially loaded into the system namespace, but your app can still access them through symbol resolution. Here’s how: Example: Your app uses pthread_create from libpthread.so.0

Your app’s library requests pthread_create.
The dynamic linker finds libpthread.so.0 on the public ABI list.
The linker makes the symbol available to your app through standard symbol resolution.
Your app successfully calls pthread_create without directly accessing the system namespace.

This mechanism ensures your app only accesses stable, versioned APIs while maintaining namespace isolation. Transitive dependencies of these system libraries (libraries that libpthread.so.0 itself depends on) remain isolated to the system namespace unless they also appear on the public ABI list.

Library search order

The Vega dynamic linker uses different search paths depending on whether the requested library is part of the public OS ABI or bundled with your app.

System libraries (on public OS ABI list)

When the requested library appears on the public OS ABI list, the linker searches in this order:

/lib/:/usr/lib/:/vendor/usr/lib/ (system-preferred search paths)
DT_RPATH (if no DT_RUNPATH exists)
LD_LIBRARY_PATH
DT_RUNPATH
Remaining system default search paths

App-bundled libraries (not on public OS ABI list)

When the requested library isn’t on the public OS ABI list, the linker searches in this order:

(app-preferred search paths)
DT_RPATH (if no DT_RUNPATH exists)
LD_LIBRARY_PATH
DT_RUNPATH
Remaining system default search paths

Enforcement strategy

Vega enforces ABI compliance through a two-tier approach:

Build-time validations (best-effort)

Vega development tools include best-effort build-time ABI validation to catch issues early during development, which can also run in CI pipelines. This avoids issues later at runtime.

Purpose: Identify potential runtime failures before device deployment
Scope: Verifies package structure and dependency modeling against ABI requirements
Limitations: Can’t catch all possible runtime scenarios, such as dynamic dlopen paths and ambient symbols

Runtime enforcement

The dynamic linker strictly enforces namespace isolation when your app runs on physical or virtual devices within a Vega system image. Apps can’t access non-public system libraries and have access only to the ABI-listed libraries, which the system exposes through proxy mechanisms.

Validate your package

Starting with SDK version 0.22, ABI validation runs automatically during the build process. The Vega packaging tool (vpt) checks your package for:

Bundled system libraries that should be dynamically linked
Missing third-party dependencies
Incorrect library paths or loading patterns

Build fails with ABI violations

If your build fails ABI validation:

Remove system libraries from your package that appear on the Vega OS public ABI list.
Update your build configuration (CMakeLists.txt, Makefiles) to link system libraries dynamically.
Verify all non-system dependencies are bundled in your package.
Rebuild your VPKG and revalidate.
Test on actual devices to confirm runtime behavior.

Best practices

Use these best practices to ensure your app complies with Vega’s ABI requirements and avoids runtime conflicts.

Never bundle system libraries, dynamically link them

Always check the Vega OS public ABI list before bundling libraries. If a library appears on this list, link to it dynamically instead of bundling it. Use DT_NEEDED entries (preferred) in your build configuration or explicitly call dlopen() for system libraries:

# In your CMakeLists.txt, add system libraries to target_link_libraries
# This creates DT_NEEDED entries for dynamic linking
target_link_libraries(your_app PRIVATE pthread)

Bundle all third-party dependencies

Include any libraries not on the Vega OS public ABI list directly in your app package. For example, bundle libcurl into the app:

# In your CMakeLists.txt:
# 1. Find the library in your build environment
find_library(CURL_LIBRARY curl)

# 2. Link it to your target
target_link_libraries(your_app PRIVATE ${CURL_LIBRARY})

# 3. Install it to your package's lib directory
install(FILES ${CURL_LIBRARY} DESTINATION lib)

Use unqualified library names

When calling dlopen(), use library names without paths:

// Correct
dlopen("libutil.so.1", RTLD_NOW);

// Incorrect: avoid fully-qualified paths
dlopen("/some/path/libutil.so.1", RTLD_NOW);

Model dependencies explicitly

Don’t rely on ambient symbols. Always declare dependencies through DT_NEEDED entries or explicit dlopen() calls. When you follow these best practices, your app benefits from Vega’s namespace isolation model, which provides:

Safe bundling: Apps can bundle any third-party library that isn’t on the OS public ABI list without conflicts
Symbol isolation: Prevents symbol conflicts (including improper binding) between app libraries and system libraries
ABI consistency: Ensures each namespace maintains consistent and expected ABI semantics
Version independence: App and system can use different versions of the same library without interference

Vega OS public ABI list

The following libraries are available to all apps through the public ABI:

Libraries	Description
ld-linux-<arch>.so	Dynamic linker
libc.so.6	Glibc v2.35
libdl.so.2	Glibc v2.35
libm.so.6	Glibc v2.35
libpthread.so.0	Glibc v2.35
librt.so.1	Glibc v2.35
libutil.so.1	Glibc v2.35
libkeplerscript-2.so.2	Used for custom TurboModule support
libkeplerscript-3.so.3	Used for custom TurboModule support
libapmf.so	Used for native IDL support

​When you need this

​What linker namespacing provides

​What you can do with linker namespacing

​How it works

​Runtime loading process

​Accessing system libraries

​Library search order

​System libraries (on public OS ABI list)

​App-bundled libraries (not on public OS ABI list)

​Enforcement strategy

​Build-time validations (best-effort)

​Runtime enforcement

​Validate your package

​Build fails with ABI violations

​Best practices

​Never bundle system libraries, dynamically link them

​Bundle all third-party dependencies

​Use unqualified library names

​Model dependencies explicitly

​Vega OS public ABI list

​Related topics