Bring your own iceoryx2

[patdhlk]

Brief feature description

Add support for using an externally-provided iceoryx2 native library instead of requiring the bundled git submodule. Users should be able to specify a custom path to their existing iceoryx2 installation (e.g., system-installed, custom-built, or from a package manager) through MSBuild properties or environment variables, allowing the C# bindings to locate and use the pre-built libiceoryx2_ffi_c library.

Detailed information

Current Situation

• iceoryx2 is included as a git submodule pointing to https://github.com/eclipse-iceoryx/iceoryx2.git
• The Iceoryx2.csproj hardcodes native library paths to ../../iceoryx2/target/release/
• Users must clone the submodule and build the Rust FFI library from source

Proposed Solution

Introduce configurable MSBuild properties that allow users to override the native library source path:

Property	Description
Iceoryx2NativeLibraryPath	Custom path to the directory containing the native library
Iceoryx2UseSystemLibrary	When true, skip copying and rely on system library search paths (LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PATH)

Pros

• Reduced build time: Skip cloning and building the Rust submodule when iceoryx2 is already available
• Disk space savings: Avoid duplicate copies of iceoryx2 source and build artifacts
• Version flexibility: Use a specific iceoryx2 version that may differ from the submodule's pinned commit
• Package manager integration: Enable use of iceoryx2 installed via package managers such as vcpkg, Conan, apt, or brew (the iceoryx2 team is considering vcpkg support, making this feature increasingly relevant)
• CI/CD optimization: Pre-build native libraries once and reuse across multiple .NET builds
• Embedded/constrained environments: Support scenarios where the full Rust toolchain isn't available

Cons

• Version compatibility risk: User-provided library may not be ABI-compatible with the C# bindings
• Additional configuration complexity: Users need to understand the new properties
• Support burden: More potential failure modes when custom paths are misconfigured

Implementation Considerations

• Add version compatibility checks if feasible (e.g., check for expected FFI symbols)
• Provide clear documentation on required iceoryx2 version and build flags
• Consider supporting the standard .NET runtime native library resolution (e.g., runtimes/{rid}/native/)

Use case

1. Enterprise environments: Organizations may have a centralized, pre-approved iceoryx2 build that must be used across all projects for compliance or security reasons.

2. Embedded systems development: When targeting resource-constrained devices where the Rust toolchain cannot run, developers cross-compile iceoryx2 separately and need to point the C# bindings to the pre-built library.

3. Continuous Integration: CI pipelines that cache the native library separately from the source code to speed up builds. The iceoryx2 native library can be built once and reused across multiple .NET project builds.

4. Package manager installations: As the iceoryx2 team is considering vcpkg support (and potentially other package managers like Conan in the future), users should be able to seamlessly use iceoryx2 libraries installed through these package managers without needing to also build from the git submodule. This will become increasingly important as iceoryx2 adoption grows across the C++ and system-level development ecosystem.

5. System package managers: On Linux distributions that package iceoryx2 (or may in the future), users should be able to use the system-provided library via standard library paths.

6. Multi-language projects: Projects using iceoryx2 from multiple language bindings (Rust, C++, C#) that already have the native library built for another binding.

Additional context

Example Usage (Proposed)

<!-- Use custom iceoryx2 installation -->
<PropertyGroup>
  <Iceoryx2NativeLibraryPath>/opt/iceoryx2/lib</Iceoryx2NativeLibraryPath>
</PropertyGroup>

<!-- Use vcpkg-installed iceoryx2 -->
<PropertyGroup>
  <Iceoryx2NativeLibraryPath>$(VcpkgInstalledDir)/lib</Iceoryx2NativeLibraryPath>
</PropertyGroup>

# Via command line
dotnet build -p:Iceoryx2NativeLibraryPath=/usr/local/lib

# Or use system library paths (works with package manager installations)
dotnet build -p:Iceoryx2UseSystemLibrary=true

Related Patterns

• Similar to how libgit2sharp allows specifying native library paths
• Comparable to Python's LD_LIBRARY_PATH approach for native extensions
• Follows .NET's standard runtimes/{rid}/native/ convention for runtime-specific assets

Files Requiring Changes

• src/Iceoryx2/Iceoryx2.csproj - Add conditional logic for library path resolution
• src/Iceoryx2/Native/NativeLibraryLoader.cs - Update library loading logic to check custom paths
• README.md - Document the new configuration options
• Consider adding a Directory.Build.props example for project-wide configuration