crossbind
GitHub

Data files

Many C++ libraries need data files: PROJ its coordinate database, GDAL its format tables, OpenSSL a CA bundle. Declare them once in targetSpecs, and they are copied to the right place on every platform, with matching environment variables.

The shape

In a targetSpecs entry (how entries match), specs.data copies files and specs.env sets environment variables in the running module:

crossbind.config.js
export default {
paths: { config: import.meta.url },
targetSpecs: [
{
platform: 'wasm',
runtimeEnv: 'browser',
specs: {
data: { 'share/proj': '/usr/share/proj' },
env: { PROJ_LIB: '/usr/share/proj' },
},
},
{
platform: 'wasm',
runtimeEnv: 'node',
specs: {
data: { 'share/proj': 'proj' },
env: { PROJ_LIB: '_CROSSBIND_DATA_PATH_/proj' },
},
},
{
platform: 'android',
specs: {
data: { 'share/proj': 'proj' },
env: { PROJ_LIB: '_CROSSBIND_DATA_PATH_/proj' },
},
},
{
platform: 'ios',
specs: {
data: { 'share/proj': 'proj' },
env: { PROJ_LIB: '_CROSSBIND_DATA_PATH_/proj' },
},
},
],
};

How data paths resolve

In data, the key is where the files are in the build (share/proj), and the value is where they land on the target platform.

  • A value starting with / is an absolute path in the module's virtual filesystem, as /usr/share/proj in the browser entry.
  • A value without a leading slash is relative to the platform's data folder, which _CROSSBIND_DATA_PATH_ expands to.

So the browser entry differs: in the browser everything lives in the virtual filesystem, while Node.js and mobile apps have a real data folder on disk.

Environment variables

specs.env values reach the running module, with _CROSSBIND_DATA_PATH_ replaced by the data folder. A value can also be a function of (state, target) that returns a string, for a path known only at build time.

initNative() takes env as well, for values not known at build time (Runtime API).

Assets that come with a package

A prebuilt package declares its own data, so installing @crossbind/port-proj brings the coordinate database and its PROJ_LIB setting along. Write targetSpecs only for data of your own, or to change where a dependency's data goes.

WASI
A WASI command of your own gets a data/ folder beside it: pass --dir and --env to wasmtime run yourself (Executables). The prebuilt command-line tools set both up for you.

What else targetSpecs carries

The same entries hold the build settings of each target:

KeyEffect
cmake.compileOptionsextra compiler flags for the sources crossbind compiles itself
binary.emccFlagsextra flags for the emscripten link (wasm only)
binary.wasiFlagsextra flags for the wasi command link
envenvironment variables for the build and the running module
datadata files to ship, as described above
ignoreLibNamedrop a specific .a from the link line

More in Configuration.

Type to search every guide page and section.
↑↓ navigate↵ openesc close