### Build dylib Example

Source: https://github.com/martin-olivier/dylib/blob/main/example/README.md

Commands to build the dylib example project. Ensure you are in the 'example' directory before running.

```sh
cmake . -B build
cmake --build build
```

--------------------------------

### Run dylib Example

Source: https://github.com/martin-olivier/dylib/blob/main/example/README.md

Commands to run the compiled dylib example executable. The exact command depends on your operating system.

```sh
# on unix, run the following command inside "build" folder
./dylib_example

# on windows, run the following command inside "build/Debug" folder
./dylib_example.exe
```

--------------------------------

### Install dylib using conan

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Use this command to install the dylib library via the conan package manager.

```sh
conan install --requires=dylib/3.0.1
```

--------------------------------

### Install dylib using vcpkg

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Use this command to install the dylib library via the vcpkg package manager.

```sh
vcpkg install dylib
```

--------------------------------

### Accessing C++ Symbols

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Illustrates how to get C++ functions and variables, including those within namespaces.

```APIDOC
## Accessing C++ Symbols

### Description
Retrieve C++ functions and variables, including those within namespaces, from a loaded dynamic library.

### Usage

```c++
// Load library
dylib::library lib("./foo", dylib::decorations::os_default());

// Get a C++ function with specific signature
auto int_to_string = lib.get_function<std::string(int)>("tools::to_string(int)");
auto double_to_string = lib.get_function<std::string(double)>("tools::to_string(double)");

// Get a C++ variable from a namespace
double pi = lib.get_variable<double>("global::math::pi_value");

// Use the retrieved functions and variable
std::string meaning_of_life_str = int_to_string(42);
std::string pi_str = double_to_string(pi);
```
```

--------------------------------

### Get C Function and Variable

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Retrieves a C function or a global variable from a loaded dynamic library. Ensure the library is loaded and the symbol names are correct.

```c++
// Load "foo" dynamic library

dylib::library lib("./foo", dylib::decorations::os_default());

// Get the C function "adder" (get_function<T> will return T*)

auto adder = lib.get_function<double(double, double)>("adder");

// Get the variable "pi_value" (get_variable<T> will return T&)

double pi = lib.get_variable<double>("pi_value");

// Use the function "adder" with "pi_value"

double result = adder(pi, pi);
```

--------------------------------

### Get Native Handle and Symbol

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Retrieves the native handle of the loaded dynamic library and a specific symbol using the library's handle. Useful for interoperability with C-style dynamic loading functions like dlsym.

```c++
dylib::library lib("./foo", dylib::decorations::os_default());

dylib::native_handle_type handle = lib.native_handle();
dylib::native_symbol_type symbol = lib.get_symbol("pi_value");

assert(handle != nullptr && symbol != nullptr);
assert(symbol == dlsym(handle, "pi_value"));
```

--------------------------------

### Get C++ Function and Variable

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Retrieves C++ functions and variables from a dynamic library, supporting namespaces and overloaded functions. The symbol name format must precisely match the mangled name or a qualified name.

```c++
// Load "foo" dynamic library

dylib::library lib("./foo", dylib::decorations::os_default());

// Get the C++ functions "to_string" located in the namespace "tools"
// The format for the function arguments is the following:
// type [const] [volatile] [*|&|&&]

auto int_to_string = lib.get_function<std::string(int)>("tools::to_string(int)");
auto double_to_string = lib.get_function<std::string(double)>("tools::to_string(double)");

// Get the variable "pi_value" located in the namespace "global::math"

double pi = lib.get_variable<double>("global::math::pi_value");

std::string meaning_of_life_str = int_to_string(42);
std::string pi_str = double_to_string(pi);
```

--------------------------------

### Loading Dynamic Libraries

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Demonstrates how to load dynamic libraries using relative or full paths, with and without OS-specific decorations.

```APIDOC
## Loading Dynamic Libraries

### Description
Load a dynamic library from a relative or a full path. The `dylib::library` class can also add filename decorations to the library name using `dylib::decorations::os_default()` or custom decorations.

### Usage

```c++
// Load from relative path
dylib::library lib1("./plugins/libfoo.so");

// Load from full path
dylib::library lib2("/lib/libfoo.so");

// Load with default OS decorations
dylib::library lib3("./foo", dylib::decorations::os_default());

// Load with custom decorations
auto custom_decorations = dylib::decorations(
    DYLIB_WIN_OTHER("", ".lib"), DYLIB_WIN_OTHER(".dll", ".so")
);
dylib::library lib4("./foo", custom_decorations);
```
```

--------------------------------

### Load Library with Default OS Decorations

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Loads a library using default OS decorations, which automatically append the correct extension (e.g., .dll, .dylib, .so) and prefix (e.g., lib) based on the operating system.

```c++
// Default OS decorations added
// Windows -> "foo.dll"
// MacOS   -> "libfoo.dylib"
// Linux   -> "libfoo.so"

dylib::library lib("./foo", dylib::decorations::os_default());
```

--------------------------------

### Build Unit Tests with CMake

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Use these CMake commands to configure and build the unit tests for the dylib library. Ensure you are in the project's root directory.

```sh
cmake . -B build -DDYLIB_BUILD_TESTS=ON
cmake --build build
```

--------------------------------

### Run Unit Tests with CTest

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Navigate to the build directory and execute this command to run the unit tests using CTest.

```sh
ctest
```

--------------------------------

### Build Shared Library and Executable

Source: https://github.com/martin-olivier/dylib/blob/main/example/CMakeLists.txt

Builds a shared library named 'dynamic_lib' from 'lib.cpp' and an executable named 'dylib_example' from 'main.cpp'. The executable is linked against the 'dylib' library.

```cmake
# build lib.cpp into a shared library

add_library(dynamic_lib SHARED lib.cpp)

# build main.cpp into an executable

add_executable(dylib_example main.cpp)
target_link_libraries(dylib_example PRIVATE dylib)
```

--------------------------------

### Integrate dylib using CMake Fetch

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Fetch and make the dylib library available in your CMake project. Ensure you have the correct Git repository URL and tag.

```cmake
include(FetchContent)

FetchContent_Declare(
    dylib
    GIT_REPOSITORY "https://github.com/martin-olivier/dylib"
    GIT_TAG        "v3.0.1"
)

FetchContent_MakeAvailable(dylib)
```

--------------------------------

### Fetch dylib Library using FetchContent

Source: https://github.com/martin-olivier/dylib/blob/main/example/CMakeLists.txt

Declares and makes available the 'dylib' library from a specified GitHub repository and tag using CMake's FetchContent module.

```cmake
include(FetchContent)

FetchContent_Declare(
    dylib
    GIT_REPOSITORY  "https://github.com/martin-olivier/dylib"
    GIT_TAG         "v3.0.1"
)

FetchContent_MakeAvailable(dylib)
```

--------------------------------

### Load Library with Custom OS Decorations

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Loads a library using custom filename decorations. This allows precise control over the library name format across different operating systems.

```c++
// Custom OS decorations added
// Windows -> "foo.dll"
// MacOS   -> "libfoo.so"
// Linux   -> "libfoo.so"

auto custom_decorations = dylib::decorations(
    DYLIB_WIN_OTHER("", "lib"), DYLIB_WIN_OTHER(".dll", ".so")
);
dylib::library lib("./foo", custom_decorations);
```

--------------------------------

### Load Dynamic Library from Relative Path

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Loads a dynamic library from a relative path. Ensure the library file is accessible from the current working directory.

```c++
// Load "foo" library from relative path "./plugins"

dylib::library lib("./plugins/libfoo.so");
```

--------------------------------

### CMake Project Configuration

Source: https://github.com/martin-olivier/dylib/blob/main/example/CMakeLists.txt

Sets the minimum CMake version, project name, and C++ standard. Configures output directories for runtime and library files.

```cmake
cmake_minimum_required(VERSION 3.11...3.31)

project(dylib_example)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
```

--------------------------------

### Load Dynamic Library from Full Path

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Loads a dynamic library using its absolute path. This is useful when the library's location is known precisely.

```c++
// Load "foo" library from full path "/lib"

dylib::library lib("/lib/libfoo.so");
```

--------------------------------

### Exception Handling for Library Loading and Symbol Resolution

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Demonstrates how to catch `dylib::load_error` and `dylib::symbol_error` exceptions, which are raised when a library fails to load or a symbol cannot be resolved. These exceptions inherit from `dylib::exception`.

```c++
try {
    dylib::library lib("./foo", dylib::decorations::os_default());
    double pi_value = lib.get_variable<double>("pi_value");
    std::cout << pi_value << std::endl;
} catch (const dylib::load_error &) {
    std::cerr << "failed to load 'foo' library" << std::endl;
} catch (const dylib::symbol_error &) {
    std::cerr << "failed to get 'pi_value' symbol" << std::endl;
}
```

--------------------------------

### Load Library with No Decorations

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Loads a library without adding any OS-specific filename decorations. The provided name is used exactly as is.

```c++
// No decorations added
// Windows -> "foo.lib"
// MacOS   -> "foo.lib"
// Linux   -> "foo.lib"

dylib::library lib("./foo.lib");
```

--------------------------------

### Exception Handling

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Details the exceptions thrown by the dylib library for loading and symbol resolution errors.

```APIDOC
## Exception Handling

### Description
Handles exceptions related to library loading (`load_error`) and symbol resolution (`symbol_error`), both of which inherit from `dylib::exception`.

### Usage

```c++
try {
    dylib::library lib("./foo", dylib::decorations::os_default());
    double pi_value = lib.get_variable<double>("pi_value");
    std::cout << pi_value << std::endl;
} catch (const dylib::load_error &) {
    std::cerr << "failed to load 'foo' library" << std::endl;
} catch (const dylib::symbol_error &) {
    std::cerr << "failed to get 'pi_value' symbol" << std::endl;
}
```
```

--------------------------------

### Accessing C Symbols

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Shows how to retrieve C functions and global variables from a loaded dynamic library.

```APIDOC
## Accessing C Symbols

### Description
Retrieve C functions and global variables from a loaded dynamic library using `get_function` and `get_variable`.

### Usage

```c++
// Load library
dylib::library lib("./foo", dylib::decorations::os_default());

// Get a C function (returns a function pointer)
auto adder = lib.get_function<double(double, double)>("adder");

// Get a C variable (returns a reference)
double pi = lib.get_variable<double>("pi_value");

// Use the retrieved function and variable
double result = adder(pi, pi);
```
```

--------------------------------

### Miscellaneous Tools

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Provides access to the native library handle and a generic symbol retrieval function.

```APIDOC
## Miscellaneous Tools

### Description
Access the native handle of the loaded dynamic library and retrieve symbols using `native_handle` and `get_symbol`.

### Usage

```c++
dylib::library lib("./foo", dylib::decorations::os_default());

// Get native handle
dylib::native_handle_type handle = lib.native_handle();

// Get a symbol
dylib::native_symbol_type symbol = lib.get_symbol("pi_value");

// Verify symbol retrieval
assert(handle != nullptr && symbol != nullptr);
assert(symbol == dlsym(handle, "pi_value"));
```
```

--------------------------------

### Gathering Library Symbols

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Explains how to collect all symbols from a dynamic library using the `symbols` method.

```APIDOC
## Gathering Library Symbols

### Description
Collect all symbols of a dynamic library using the `symbols` method and iterate through them.

### Usage

```c++
// Load library
dylib::library lib("./foo", dylib::decorations::os_default());

// Iterate through symbols
for (auto &symbol : lib.symbols()) {
    if (symbol.loadable)
        std::cout << symbol.demangled_name << std::endl;
}
```
```

--------------------------------

### Iterate Through Library Symbols

Source: https://github.com/martin-olivier/dylib/blob/main/README.md

Collects and iterates through all symbols within a loaded dynamic library. This can be used to inspect available functions and variables, checking their loadable status.

```c++
// Load "foo" dynamic library

dylib::library lib("./foo", dylib::decorations::os_default());

// Iterate through symbols

for (auto &symbol : lib.symbols()) {
    if (symbol.loadable)
        std::cout << symbol.demangled_name << std::endl;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.