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 /pkg/lib/<arch>/, /pkgs/, /mnt/)
• 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:

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

Accessing system libraries

System libraries on the public ABI list initially load 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

1. Your app's library requests pthread_create.
2. The dynamic linker finds libpthread.so.0 on the public ABI list.
3. The linker makes the symbol available to your app through standard symbol resolution.
4. 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:

1. /lib/:/usr/lib/:/vendor/usr/lib/ (system-preferred search paths)
2. DT_RPATH (if no DT_RUNPATH exists)
3. LD_LIBRARY_PATH
4. DT_RUNPATH
5. 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:

1. /pkg/lib/<arch>/:/pkgs/:/mnt/ (app-preferred search paths)
2. DT_RPATH (if no DT_RUNPATH exists)
3. LD_LIBRARY_PATH
4. DT_RUNPATH
5. 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:

1. Remove system libraries from your package that appear on the Vega OS public ABI list.
2. Update your build configuration (CMakeLists.txt, Makefiles) to link system libraries dynamically.
3. Verify you bundled all non-system dependencies in your package.
4. Rebuild your VPKG and revalidate.
5. 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:

Related topics

• Fix Linker Namespacing Issues
• Validate Your Package with Strict ABI Check
• Use VPT for Vega App Packages

Last updated: Jun 18, 2026