conan

<!-- GENERATED from docs/api/conan.md by scripts/build-agent-skill.mjs. Do not edit. -->

Conan — C and C++ packages from ConanCenter

> Import a C or C++ library from [ConanCenter](https://conan.io/center) the way you import a > crate with `cargo:`: declare it, then name one of its headers. crossbind builds the package with > its own toolchain, links it like a port and binds the header like any other. Web builds (wasm32 > and wasm64, `st` and `mt`), React Native on Android (arm64-v8a and x86_64) and iOS (arm64 > devices and simulators), and Node.js addons for Linux (glibc and musl), macOS and Windows, x64 and > arm64.

Requirement

Nothing to install for web, Android, Linux addon and Windows addon builds with the default Docker runner: the toolchain images carry Conan 2.33 from image family 1.0.11 on. iOS and macOS packages build on your Mac with Xcode whatever the runner, so those builds need Conan 2.19 or later and CMake on the `PATH` (`brew install conan` or `brew upgrade conan`, or `pipx install conan`); a Conan release older than your Xcode still takes its clang. The first build of a package needs the network, to reach ConanCenter and the sources its recipe downloads. Under `RUNNER=LOCAL`, web builds need Conan 2.19 or later, Emscripten and CMake on the `PATH`, and Android, Linux and Windows packages are refused: they need the android image's NDK, the linux image's sysroots and the windows image's llvm-mingw.

Declare, then import

// crossbind.config.js — top level, next to `dependencies`
conanDependencies: {
  zlib: '1.3.2',
  libpng: '[>=1.6 <2]',
  sqlite3: { version: '3.53.4', options: { enable_fts5: true } },
},

import { initNative, zlibVersion, compressBound } from 'conan:zlib/zlib.h';
import { png_access_version_number } from 'conan:libpng/png.h';

await initNative();
zlibVersion(); // '1.3.2'

• A key is the Conan package name. Its value is a version, a Conan version range, or

`{ version, options }` with options the recipe defines.

• `conan:<package>/<header>` names a header under the package's include directory,

subdirectories included: `conan:libxml2/libxml/parser.h`.

• Importing a package that `conanDependencies` does not declare is a hard error. A package that

another one requires (zlib under libpng) is built and linked either way, and importable once it is declared.

• `shared` is not an option you can set: every package links statically into the module.

Through your own header

The include directories of every Conan package are on your native sources' include path, so a header of your own can use any of them, C++ libraries included. It is also the way to reach what a header cannot bind on its own, such as templates and header-only libraries:

// src/native/text.h
#include <string>
#include <fmt/format.h>

class Text {
public:
    static std::string price(double value) { return fmt::format("{:.2f}", value); }
};

import { initNative, Text } from './native/text.h';

C++ exceptions cross between your code and a Conan package: an `fmt::format_error` thrown inside libfmt reaches your `catch`.

Your sources and their bridges compile with the defines a recipe declares for the code that uses it (`cpp_info.defines`), on every target. libcurl's `CURL_STATICLIB`, for one, tells `curl.h` on Windows that the library is linked in, not loaded from a DLL.

React Native

The same imports work in a React Native app on Android and iOS, from JavaScript and from your own headers. The native build installs the packages before Metro bundles the bridges, and a Metro server started before that first build picks them up once they are staged. On Android, Metro reads headers for arm64-v8a, so its packages are built even when the app builds x86_64 only.

Android packages are built for API level 33, as the ports are. In an app whose `minSdkVersion` is lower, a package that calls a newer libc function fails to link, as such a port would.

iOS packages are built for the device and the simulator SDK, arm64 and iOS 15.1 like the ports, and each library becomes an xcframework that the `react-native-crossbind` pod vendors. CocoaPods links what it finds at `pod install`, so run `pod install` again after you change `conanDependencies`.

Node.js addons

A Node.js addon for Linux, macOS or Windows (`crossbind build -p linux -p linuxmusl -p darwin -p win32 -e node`) links the packages too, and your own headers reach them as [above](#through-your-own-header). Each addon links the packages built for its own target, with the system libraries and Apple frameworks their recipes ask for (`system_libs`, `frameworks`); glibc and musl builds share every Conan setting, so crossbind keeps them apart as packages of their own. A package's symbols stay inside the addon, as a port's do: Node.js exports its own zlib and OpenSSL, and the addon's copies do not trade calls with them.

`pnpm --filter @crossbind/e2e-backend-nodejs-native-conan e2e:prod` runs the fixture's glibc addon on Debian, its musl addon on Alpine and its macOS addon on the host (after `build:darwin`), and reads each Windows addon for the DLLs it loads and the symbols it exports; CI also runs the Windows addons on x64 and arm64 Windows.

What a build does

1. When a build starts (`buildStart` in Vite and Rollup, `beforeRun` and `watchRun` in Webpack and Rspack, `crossbind build`, the Gradle or Xcode build of a React Native app), crossbind runs `conan install` for every release target the build needs, with a profile crossbind writes from its own toolchain:

• wasm, in the web image: the image's `emcc`, `-fwasm-exceptions -msimd128`, `-pthread` on

`mt`, `-sMEMORY64=1` on wasm64;

• Android, in the android image: its NDK through the NDK's own CMake toolchain, API level 33 and

`c++_static`, as the ports' Android archives are built;

• iOS, on your Mac: the clang and archive tools of `/Applications/Xcode.app` for the device and

the simulator SDK, arm64, deploymen