# Bare runtime API

<mark style="{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }">
  stable
</mark>

The core JavaScript API of [Bare](/bare/explanation/bare-runtime) is exposed through the global `Bare` namespace. This page documents that surface as of Bare 1.37.1. For the command-line runner, see the [`bare` CLI](/bare/reference/bare/cli). Bare provides no standard library beyond this namespace; the collection of external `bare-*` modules built for it is in [Bare modules](/bare/reference/bare/modules).

Upstream documents the namespace as TSDoc comments in [`src/bare.d.ts`](https://github.com/holepunchto/bare/blob/main/src/bare.d.ts). Before Bare 1.35.0 this documentation was in the README. The npm [`bare`](https://www.npmjs.com/package/bare) package exports the `Bare` namespace, with `Addon` and `Thread` as named exports for ESM, and ships that file as `index.d.ts`. `bare@1.35.0` was published without it, although its `package.json` points to it, so TypeScript finds no typings for that version. `bare@1.35.1` ships it. The declarations import `Duplex` from [`bare-stream`](/bare/reference/bare/modules/bare-stream) for the type of [`Bare.IPC`](#bareipc), and `bare` lists `bare-stream` as an optional peer dependency from 1.35.0.

## Process properties [#process-properties]

#### `Bare.platform` [#bareplatform]

The operating system Bare was compiled for. One of `android`, `darwin`, `freertos` (since 1.37.0), `ios`, `linux`, `watchos` (since 1.37.1), `win32`.

#### `Bare.arch` [#barearch]

The processor architecture Bare was compiled for. One of `arm`, `arm64`, `arm64-32` (since 1.37.1), `armv8m` (since 1.37.0), `ia32`, `mips`, `mipsel`, `riscv32` (since 1.37.0), `riscv64`, `x64`.

None of the platforms and architectures added in 1.37 is in the [platform support](#supported-platforms) table. `arm64-32` is the architecture of Apple Watch, and contains a hyphen, so a host such as `watchos-arm64-32` cannot be split on hyphens into its parts. From Bare 1.37.1, addon resolution parses the host with [`bare-host-parser`](https://github.com/holepunchto/bare-host-parser) instead.

#### `Bare.argv` [#bareargv]

The command-line arguments passed to the process when launched.

#### `Bare.pid` [#barepid]

The ID of the current process.

#### `Bare.exitCode` [#bareexitcode]

The code returned once the process exits. If the process exits via `Bare.exit()` without a code, `Bare.exitCode` is used. Assigned values are truncated to eight bits, so `256` becomes `0`.

#### `Bare.version` [#bareversion]

The Bare version string, with a leading `v`, such as `v1.37.1`.

#### `Bare.versions` [#bareversions]

An object of version strings for Bare and its dependencies, keyed by library name and without the leading `v`. It holds `bare`, `uv` for libuv, and an entry for the JavaScript engine, which is `v8` with the default engine:

```js
Bare.versions
// { bare: '1.37.1', uv: '1.53.0', v8: '15.7.112.12' }
```

From Bare 1.37.0, V8 is version 15.7, up from 14.8, and includes DrumBrake, the WebAssembly interpreter of V8. On iOS, where V8 runs without a JIT, WebAssembly now runs in that interpreter, where earlier versions had no `WebAssembly` global. It is slower there than on platforms that compile it. The V8 build for the x64 iOS simulator leaves WebAssembly out, so that target still has no `WebAssembly` global. Android builds don't include DrumBrake.

## Lifecycle methods [#lifecycle-methods]

#### `Bare.exit([code])` [#bareexitcode-1]

Immediately terminate the process or current thread with exit status `code`, defaulting to `Bare.exitCode`. Like `Bare.exitCode`, `code` is truncated to eight bits.

#### `Bare.suspend([linger])` [#baresuspendlinger]

Suspend the process and all threads, emitting a `suspend` event that signals all work should stop immediately. When all work has stopped and the process would otherwise exit, an `idle` event is emitted. If no listener resumes the process from that event, the loop blocks until the process is resumed, which keeps the process from exiting. `linger` is passed to `suspend` listeners and defaults to `0`. (since 1.36.0) A `linger` above `2147483647` throws a `RangeError`. Earlier versions wrapped such a value to a 32-bit signed integer, so a large or `Infinity` linger could become negative or `0`.

#### `Bare.wakeup([deadline])` [#barewakeupdeadline]

Wake the process and all threads during suspension, emitting a `wakeup` event that signals work may be performed until `deadline`, a number of milliseconds that defaults to `0`. Once the process is idle, or `deadline` has passed, it suspends again and an `idle` event is emitted. (since 1.36.0) A `deadline` above `2147483647` throws a `RangeError`. Earlier versions wrapped such a value to a 32-bit signed integer, and a deadline that became negative left the wakeup timer never firing.

#### `Bare.idle()` [#bareidle]

Immediately suspend the event loop and trigger the `idle` event.

#### `Bare.resume()` [#bareresume]

Resume the process and all threads after suspension, emitting a `resume` event. May be called from a `suspend`, `wakeup`, or `idle` listener to cancel suspension, which is possible from the moment the `suspend` event is emitted until all `idle` listeners have run.

## Events [#events]

Listeners attach with `Bare.on(event, listener)`.

#### `uncaughtException`— `(err)` [#uncaughtexception-err]

A JavaScript exception was thrown within an execution context, the process or a thread, without being caught there. By default uncaught exceptions are printed to `stderr` and the process is aborted, whichever thread threw; adding a listener on that thread overrides that default, and a listener on another thread does not see the exception. If the listener itself throws, that error is reported in place of the original and the process is aborted.

#### `unhandledRejection`— `(reason, promise)` [#unhandledrejection-reason-promise]

A promise was rejected within an execution context without the rejection being handled there. The default behavior, printing to `stderr` and aborting the process, is overridden by adding a listener. An error thrown from the listener is treated as an uncaught exception, so it goes to the `uncaughtException` listeners, or aborts the process if there are none.

#### `beforeExit`— `(code)` [#beforeexit-code]

Emitted when the loop runs out of work, before the process or thread exits. Scheduling more work here keeps the process alive and re-arms the event. Not emitted on explicit `Bare.exit()` or an uncaught exception.

#### `exit`— `(code)` [#exit-code]

Emitted when the process or thread exits.

> [!WARNING]
> Additional work **must not** be scheduled from an `exit` listener. If the process is forcefully terminated from within an `exit` listener, the remaining listeners do not run.

#### `suspend`— `(linger)`, `wakeup`— `(deadline)`, `idle`— `()`, `resume`— `()` [#suspend-linger-wakeup-deadline-idle--resume-]

The lifecycle events described under [Lifecycle methods](#lifecycle-methods). Each is emitted for the process or for the current thread.

* `suspend` — the process or thread was suspended. Defer, cancel, or pause any in-progress or outstanding work, such as network activity or file system access, and schedule no additional work.
* `wakeup` — the process or thread woke up during suspension. Once it becomes idle, or if it is not idle by the time `deadline` has passed, it suspends itself again and an `idle` event is emitted.
* `idle` — the process or thread became idle after suspension. Once all listeners have run, the event loop blocks and no further work is performed until the process is resumed.
* `resume` — the process or thread resumed after suspension. Continue deferred and paused work; new work may be scheduled again.

A `suspend`, `wakeup`, or `idle` listener may call `Bare.resume()` to cancel the suspension before it completes.

## Lifecycle [#lifecycle]

Bare exposes process suspension so it can behave on platforms with strict application-lifecycle rules—mobile in particular. A suspended loop stays alive but idle rather than exiting, and can be woken for bounded bursts of work. The same transitions are available from C (`bare_suspend()`, `bare_wakeup()`, `bare_resume()`) and from JavaScript.

Suspending emits a `suspend` event. Once the loop has no work left and would otherwise exit, it emits `idle` and blocks, which keeps the process from exiting. Resuming emits `resume` and unblocks the loop, which can then exit once no work is left. While the process is suspended, the loop can be woken for limited periods to perform work, which emits `wakeup`. Each wakeup has a deadline, after which the loop is stopped and the process suspends again, emitting another `idle` event.

```mermaid
stateDiagram-v2
  direction LR
  [*] --> Active
  Active --> Suspending: Bare.suspend()
  Active --> Terminated: Bare.exit()
  Active --> Exiting
  Suspending --> Active: Bare.resume()
  Suspending --> Awake: Bare.wakeup()
  Suspending --> Suspended: Bare.idle()
  Suspending --> Terminated: Bare.exit()
  Suspending --> Idle
  Awake --> Active: Bare.resume()
  Awake --> Suspended: Bare.idle()
  Awake --> Terminated: Bare.exit()
  Awake --> Idle
  Idle --> Suspended
  Idle --> Active: Bare.resume()
  Idle --> Terminated: Bare.exit()
  Suspended --> Active
  Suspended --> Awake: Bare.wakeup()
  Terminated --> Exiting
  Exiting --> [*]
```

For the rationale, see [Inside Bare](/bare/explanation/bare-runtime#the-lifecycle); for driving it from a native host, see [One core, many platforms](/bare/explanation/bare-on-native).

## `Bare.Addon` [#bareaddon]

Loads native addons—typically C/C++ shared libraries.

> [!NOTE]
> This is an advanced API most users never touch directly; native addons are normally loaded for you by the modules that need them.

* `new Addon(url)`— added in Bare 1.31.0. Load a static or dynamic addon from a `url` whose protocol is `builtin:`, `linked:`, or `file:`. If `url` is not a static addon, Bare looks for a matching dynamic object library instead. Returns an `addon` whose `addon.url` is the WHATWG `URL` identifier of the addon and whose `addon.exports` are its exports. Throws an `AddonError` whose `code` is `UNKNOWN_PROTOCOL` for any other protocol, or `CANNOT_LOAD` if loading fails, which includes loading a dynamic addon that the process has not already loaded once it is sealed.
* `Addon.host`— the target triplet identifying the current addon host.
* `Addon.seal()`— added in Bare 1.32.0. Freeze addon loading. Once sealed, no further dynamic addon can be loaded by the current thread or any other thread of the process, now or in the future; loading one throws. An addon that the process has already loaded can still be loaded after the seal, and `Addon.loaded()` reports whether it has. Statically linked addons are compiled in and remain available. This is one-way for the lifetime of the process, and applies to this process alone—intended for embedders that load a fixed set of trusted addons up front and then want to block any further native code, for example when building a sandbox. Embedders running several Bare processes within the same operating system process can seal each of them independently, and sealing one has no effect on the addons the others can load. Addons are owned by the process that loaded them and are unloaded when it is torn down. From Bare 1.33.0, sealing also freezes the [embedder context](/bare/reference/bare/embedder-context) registry, after which no further handles can be published. See the [threat model](https://github.com/holepunchto/bare/blob/main/docs/threat-model.md) for what sealing does and doesn't guarantee.
* `Addon.sealed`— added in Bare 1.32.0. Whether `Addon.seal()` has been called.
* `Addon.loaded(url)` (since 1.35.0) — whether the current process has already loaded the dynamic addon identified by `url`, a `URL` with the `file:` or `linked:` protocol. It loads nothing. Any other protocol, including `builtin:`, gives `false`. The answer covers every thread of the process, and it stays `true` after `Addon.seal()`. On a sealed process, `new Addon(url)` for a dynamic addon succeeds only if `Addon.loaded(url)` is `true`.
* `Addon.cache`, `Addon.load(url)`, `Addon.resolve(specifier, parentURL[, options])`— deprecated in Bare 1.31.0, superseded by `new Addon(url)`. Still work, but new code should use the constructor.

`Bare.Addon` loads native code only. From Bare 1.36.0, which ships [`bare-module`](/bare/reference/bare/modules/bare-module#webassembly-addons) 7.5.0, the module system can also load the WebAssembly build of an addon, `prebuilds/wasi-wasm32/<name>.wasm`. It runs that build through [`bare-wasm-abi`](/bare/reference/bare/modules/bare-wasm-abi) rather than `Bare.Addon`, sandboxed through WASI, when an import asks for it with `with: { host: 'wasi-wasm32' }` or when the package has no native build for `Addon.host`. Sealing does not stop WebAssembly addons. On a sealed process, the module system skips native builds that `Addon.loaded()` reports as not loaded when it resolves an addon, so for an addon resolved after the seal, a package that also ships a `.wasm` build loads that build instead. Inside a bundle, which keeps the resolutions recorded at pack time, it doesn't fall back, and the native addon throws `CANNOT_LOAD`. If the package ships no `.wasm` build, the import throws `ADDON_NOT_FOUND`, where Bare 1.35 threw `CANNOT_LOAD`. WASI limits only the system calls of a WebAssembly addon: it still reaches the JavaScript global object, including `Bare.Addon`: before the seal it can load native addons, and after it, it can get back any native addon the process already loaded. Before Bare 1.37.0, WebAssembly addons could not run on iOS, which had no `WebAssembly` global. From 1.37.0 they run there in the DrumBrake interpreter, more slowly than a native build, except on the x64 simulator, which still has no WebAssembly.

## `Bare.Thread` [#barethread]

Lightweight threads with synchronous joins—similar to Node.js workers but with a minimal surface.

> [!NOTE]
> This is an advanced API most users never touch directly.

* `Thread.isMainThread`— `true` on the main thread.
* `Thread.self`— the current thread as a `ThreadProxy`, or `null` on the main thread. `Thread.self.data` is the data passed on creation, or `null` if none was passed.
* `new Thread(filename, source[, options])`— added in Bare 1.32.0. Start a thread that runs `source`, a string or Buffer. `filename` names the source and does not say where to read it from. From 1.36.0, it is the only form that is not deprecated.
* (Deprecated in 1.36.0) `new Thread([filename][, options][, callback])`, `new Thread(callback)`, `new Thread(filename, callback)` — start a thread that runs the source in `options.source` or, if `callback` is given, the body of `callback`, which is invoked on the new thread with `Thread.self.data` as its argument. `filename` defaults to `<thread>`. The plain-callback form has no `filename` and was added in 1.32.0. Still work, but new code should pass the source, or use [`bare-thread`](https://github.com/holepunchto/bare-thread), which also bundles the modules a thread imports.
* `Thread.create(...)`— deprecated in Bare 1.31.0. Equivalent to `new Thread(...)`. Still works, but new code should use the constructor.
* `thread.joined`— whether the thread has been joined with the current thread.
* `thread.join()`— block and wait for the thread to exit.
* `thread.suspend([linger])`, `thread.wakeup([deadline])`, `thread.resume()`— suspend, wake, or resume the thread. Each is equivalent to calling `Bare.suspend()`, `Bare.wakeup()`, or `Bare.resume()` from within the thread. (since 1.36.0) The same `RangeError` applies to `linger` and `deadline`.
* `thread.terminate()`— terminate the thread. Equivalent to calling `Bare.exit()` from within the thread.

The options object takes:

| Option                       | Default                    | Description                                                                                                                                                                                                                                                                                                                        |
| ---------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`                       | `null`                     | Data to pass to the thread, available there as `Thread.self.data`.                                                                                                                                                                                                                                                                 |
| `transfer`                   | `[]`                       | The transfer list for `data`.                                                                                                                                                                                                                                                                                                      |
| `encoding`                   | `'utf8'`                   | The encoding of the source if it is a string.                                                                                                                                                                                                                                                                                      |
| `stackSize`                  | `0`                        | The stack size of the thread in bytes. `0` takes the default.                                                                                                                                                                                                                                                                      |
| `mount` (since 1.35.0) | `filename` followed by `/` | The URL to mount the thread's bundle at, as a `URL` or a string that parses as one. The bundle serves only the modules under it, so `file:///` lets it serve any file. `null` and `undefined` take the default, and any other value throws a `TypeError`. See [Starting a thread from a bundle](#starting-a-thread-from-a-bundle). |
| `source`                     |                            | Deprecated in Bare 1.32.0. The source to run. Pass it after `filename` instead.                                                                                                                                                                                                                                                    |

A thread is loaded through a protocol that reaches nothing, so it runs only the source it was given. `filename` names that source rather than locating it, and a thread does not inherit the module protocol of the thread that spawned it. Anything else the thread needs, including the modules it imports, must travel with it as `source` or `data`. Reading a module graph off disk and handing it over is the spawner's job, so that a thread never reaches further than the code that started it. A thread given a `filename` but no source or callback has nothing to run, because it cannot read the file. It throws `MODULE_NOT_FOUND` on startup, which nothing catches, so the process aborts. From Bare 1.35.0, the one thing that protocol answers is that the native addons a bundle declares exist, as described below.

Higher-level worker threads are available in [`bare-worker`](/bare/reference/bare/modules).

### Starting a thread from a bundle [#starting-a-thread-from-a-bundle]

To run a module graph on a thread, bundle it with [`bare-bundle`](/bare/reference/bare/modules/bare-bundle) and pass the bundle as `source`, which is what [`bare-thread`](https://github.com/holepunchto/bare-thread) does. Give the thread a `filename` that ends in `.bundle`, such as `bare:/thread.bundle`. The extension makes Bare read `source` as a bundle, and `filename` is where the bundle is mounted by default.

The bundle serves only the modules under its mount. `options.mount` sets the mount, and without it the mount is `filename` followed by `/`, so a thread named `bare:/thread.bundle` mounts its bundle at `bare:/thread.bundle/`. A `filename` that is a path rather than a URL is read as a `file:` URL, so `/app/thread.bundle` mounts its bundle at `file:///app/thread.bundle/`. A `/` is added to the end of a mount that has none. A key that is a path in the bundle, such as `/entry.js`, is placed under the mount. A key that is an absolute URL, such as `file:///app/entry.js`, stays where it is, so the mount has to be a prefix of it. The bundles that `bare-thread` prepares from files on disk name their modules this way. A module outside the mount is not served from the bundle, and because the thread's protocol reaches nothing else, loading it throws `MODULE_NOT_FOUND`. Nothing in the thread catches that error, so the process aborts. Pass `file:///` as the mount to let the bundle serve any file.

```js
const Bundle = require('bare-bundle')

const bundle = new Bundle()

bundle.write('file:///app/dep.js', 'module.exports = "hello"')

bundle.write('file:///app/entry.js', 'console.log(require("./dep.js"))', {
  main: true,
  imports: { './dep.js': 'file:///app/dep.js' }
})

const thread = new Bare.Thread('bare:/thread.bundle', bundle.toBuffer(), {
  mount: 'file:///app/'
})

thread.join()
```

Without `mount`, this thread fails on Bare 1.35.0, because `file:///app/entry.js` is outside `bare:/thread.bundle/`.

A bundle can also declare native addons without carrying their binaries. `bare-bundle` keeps them as the bundle's `addons`. (since 1.35.0) The protocol of a thread answers that the addons a bundle declares exist, so they resolve to the paths the bundle gives and load from disk through `Bare.Addon`. `Addon.seal()` still governs that load: on a sealed process, the thread loads such an addon only if the process has already loaded it. On earlier releases the thread fails with `MODULE_NOT_FOUND` for a declared addon that the bundle does not embed.

*Added in 1.35.0.*

> [!WARNING]
> **Upgrading to Bare 1.35.** Bare 1.35.0 changed how a thread loads a bundle. If your code, or a library you use, starts a thread from a bundle, check these.
>
> * Pass `mount` when the bundle holds modules outside `filename` followed by `/`, which is the case for a bundle keyed by absolute `file:` URLs. Earlier releases ignored `mount` and served a bundle's modules wherever their URLs were, so a bundle that loaded before can fail with `MODULE_NOT_FOUND` on 1.35.0. On an earlier release the option does nothing, so passing it is safe on both. The change comes from [`bare-module`](/bare/reference/bare/modules/bare-module#loading-bundles), which serves a bundle only from under its mount since 7.2.2. Bare 1.34.1 embeds `bare-module` 7.2.0 and Bare 1.35.0 embeds 7.4.0.
> * The same rule applies to a bundle that your own code loads inside a thread with `Module.load()` or `Module.loadSync()`, as `bare-worker` does for the entry of a worker. Pass the `mount` option, which `bare-module` has since 7.3.0. If the bundle declares addons that it does not embed, also pass a `protocol` whose `exists()` returns `true` for their URLs. The protocol that Bare gives a thread answers only for the bundle that the thread was started with.
> * `bare-thread` passes `mount` from 1.3.0 for a thread it starts from a path, and `bare-worker` passes it from 4.5.1. On Bare 1.35.0, a worker started with `bare-worker` 4.5.0 fails at startup with `Uncaught ModuleTraverseError: MODULE_NOT_FOUND` for `bare-worker/lib/worker-thread.js`. `bare-thread` 1.4.0 leaves addons out of the bundles it prepares, so a thread that loads an addon through it needs Bare 1.35.0 or later. `bare-worker` answers for the addons of a worker's own bundles from 4.5.3, so use `bare-worker` 4.5.3 or later. The other direction can fail too: on Bare 1.34.1, `bare-worker` 4.5.3 fails with `MODULE_NOT_FOUND` for the addons that its bundles declare when it resolves `bare-thread` 1.4.0, which its `^1.3.0` range allows, so move Bare and `bare-worker` together.

## `Bare.IPC` [#bareipc]

Optional streaming communication between an embedder and JavaScript. Defaults to `null`, meaning no streaming channel is set. When an embedder provides one, `Bare.IPC` is expected to be an instance of a [`bare-stream`](/bare/reference/bare/modules/bare-stream) `Duplex`. The higher-level [`bare-kit`](/bare/reference/bare/bare-kit) IPC abstraction is built on this.

Unlike `Bare.Addon` and `Bare.Thread`, which cannot be replaced or deleted, `Bare.IPC` can be assigned, so that an embedder can set it. Nothing can be added to `Bare`, and the `Bare` global itself cannot be replaced.

> [!NOTE]
> This is an advanced API most users never touch directly.

## Embedding [#embedding]

Bare can be embedded with the C API in [`include/bare.h`](https://github.com/holepunchto/bare/blob/main/include/bare.h):

```c
#include <bare.h>
#include <uv.h>

bare_t *bare;
bare_setup(uv_default_loop(), platform, &env /* Optional */, argc, argv, options, &bare);
bare_load(bare, filename, source, &module /* Optional */);
bare_run(bare, UV_RUN_DEFAULT);

int exit_code;
bare_teardown(bare, UV_RUN_DEFAULT, &exit_code);
```

If `source` is `NULL`, the contents of `filename` are read at runtime. For platform shells that wrap this API, see [`bare-ios`](https://github.com/holepunchto/bare-ios) and [`bare-android`](https://github.com/holepunchto/bare-android), or use [`bare-kit`](/bare/reference/bare/bare-kit), which packages embedding behind a worklet API.

From Bare 1.34.0, an embedder whose thread belongs to a host loop, such as the run loop of a user interface, drives Bare with `bare_poll()` instead of `bare_run()`. It runs the loop without blocking and reports how long the host may sleep before calling again:

```c
int timeout;
bare_poll(bare, &timeout);
```

`timeout` is in milliseconds, and may be `NULL` if the host has no use for it. A timeout of `-1` means the host may sleep until the loop's backend descriptor, as given by `uv_backend_fd()`, becomes readable. With a timeout of `0`, poll again without sleeping. `bare_poll()` returns zero once the process has exited, and sets `timeout` to `0` when it does, so check the return value rather than the timeout. Tear the process down at that point rather than polling it again.

> [!WARNING]
> Do not sleep on the timeout alone. Work can arrive from another thread while the host sleeps, and a host that waits only for the timeout to elapse does not notice it until then. Wait on the descriptor from `uv_backend_fd()` as well, and wake on whichever comes first.

To hand addons a native handle that only the embedder can produce, such as the Android `JavaVM *`, publish it with `bare_context_set()` before the first `bare_load()`. Values are set per process and cannot be changed once set, and every addon in the process can read what is published, so publish only what all of them may use. Addons should cope with a value that is not set. See the [embedder context API](/bare/reference/bare/embedder-context).

> [!WARNING]
> Bare is designed to be embedded alongside code the embedder may not fully trust. [`Bare.Addon.seal()`](#bareaddon) is the mechanism for freezing the set of native code a process can load. The Bare [threat model](https://github.com/holepunchto/bare/blob/main/docs/threat-model.md) sets out what sealing does and does not promise, and embedders should read it before running untrusted JavaScript. In short:
>
> * Sealing promises only that no new native code gets in. New JavaScript can still load, and so can WebAssembly addons, which the engine runs and which reach no further than JavaScript.
> * The intrinsics are shared by every module graph in a realm, and Bare does not freeze them. Untrusted code that can write to them can watch and steer other graphs, so the protocol you give it does not reliably limit it. Run untrusted code in a realm of its own, or freeze the intrinsics first.
> * An embedder has five duties: check what the addons you load add up to, hand on only what you mean to, keep untrusted code away from the shared intrinsics, use an OS sandbox, and seal early and every process. Handing on covers the module protocol and anything published with `bare_context_set()`.

To build `libbare` for linking into an embedder, see [Building Bare](#building-bare).

### `bare_poll()` [#bare_poll]

```c
int
bare_poll(bare_t *bare, int *timeout);
```

Runs the event loop without blocking, in place of `bare_run()`, for an embedder whose thread belongs to a host loop, such as the run loop of a user interface. Requires Bare >=1.34.0.

| Parameter | Type       | Description                                                                 |
| --------- | ---------- | --------------------------------------------------------------------------- |
| `bare`    | `bare_t *` | The process to poll.                                                        |
| `timeout` | `int *`    | Receives how long the host may sleep before polling again, in milliseconds. |

Returns zero once the process has exited, at which point it should be torn down rather than polled again.

```c
int timeout;
bare_poll(bare, &timeout);
```

A `timeout` of `-1` means that the host may sleep until the backend descriptor of the loop, as given by `uv_backend_fd()`, becomes readable. A host that sleeps on the timeout alone rather than on the descriptor misses work that arrives from another thread.

### `bare_attach()` and `bare_detach()` [#bare_attach-and-bare_detach]

```c
int
bare_attach(bare_t *bare, bare_t **previous);

int
bare_detach(bare_t *bare, bare_t *previous);
```

`bare_attach()` attaches the process to the calling thread and stores the process that was attached before in `previous`. The attached process is the one that `bare_context_get()` resolves against and that an addon loaded while attached belongs to. `bare_detach()` detaches the process and attaches `previous` in its place; a `NULL` `previous` leaves the thread attached to no process. Both return `0` on success. Requires Bare >=1.34.0.

`bare_run()` attaches the process while it runs, and so does loading an addon, so native code reached through either is already attached. A call the embedder makes itself is not, so attach the process around it:

```c
bare_t *previous;
bare_attach(bare, &previous);

js_call_function(env, receiver, fn, argc, argv, &result);

bare_detach(bare, previous);

bare_run(bare, UV_RUN_NOWAIT);
```

Attachments nest, so detach on the same thread and in the reverse order of attaching. `bare_detach()` returns `-1` if the process is not the one the thread is attached to, which is what detaching out of order looks like, and restores nothing. `bare_attach()` returns `-1` if the process has terminated or exited.

Attaching does not run the loop. The call may leave work behind that only the loop can run, which is why the example runs it once detached.

### C API reference [#c-api-reference]

Everything below is declared in [`include/bare.h`](https://github.com/holepunchto/bare/blob/main/include/bare.h), except where a different header is named. Unless a function says otherwise, it returns `0` on success and a negative value on failure.

#### Setup and teardown [#setup-and-teardown]

```c
int
bare_version(int *major, int *minor, int *patch);
```

Stores the version of the Bare that is linked in. Any of the pointers may be `NULL`. Use it when Bare is linked dynamically, where the version of the header can differ from the version of the library. For the version of the header, see [`BARE_VERSION`](#headers-and-macros).

```c
int
bare_setup(uv_loop_t *loop, js_platform_t *platform, js_env_t **env, int argc, const char *argv[], const bare_options_t *options, bare_t **result);
```

Sets up a Bare process on `loop` and stores it in `result`. `platform` is the JavaScript platform to create the environment with. If `env` is given, it receives the JavaScript environment of the process, for use with the `js_*` functions. `argc` and `argv` become `Bare.argv`, and are copied. `options` may be `NULL` for the defaults; see [`bare_options_t`](#bare_options_t). Returns a negative value on failure, in which case nothing is allocated and `result` is untouched.

```c
int
bare_load(bare_t *bare, const char *filename, const uv_buf_t *source, js_value_t **result);
```

Loads the module identified by `filename`, which may be any of the formats the module system supports; see [`bare-module`](/bare/reference/bare/modules/bare-module). If `source` is `NULL` the contents of `filename` are read from disk. Otherwise `source` must remain alive until `bare_teardown()` has returned. If `result` is given, it receives the exports of the module. The process is attached to the calling thread while the module loads.

```c
int
bare_run(bare_t *bare, uv_run_mode mode);
```

Runs the I/O event loop in `mode`, emitting `beforeExit` and `exit` as the loop runs out of work. It returns zero once the process has exited. With `UV_RUN_ONCE` or `UV_RUN_NOWAIT` it can return a non-zero value, meaning work remains and it should be called again. If the process is suspended, it does not return until another thread resumes it. To drive the loop from a host loop that owns the thread, use [`bare_poll()`](#bare_poll) instead.

`bare_poll()`, `bare_attach()` and `bare_detach()`, which require Bare `>=1.34.0`, are documented above under [`bare_poll()`](#bare_poll) and [`bare_attach()` and `bare_detach()`](#bare_attach-and-bare_detach).

```c
int
bare_teardown(bare_t *bare, uv_run_mode mode, int *exit_code);
```

Tears the process down and frees it, storing the exit code in `exit_code` if given. Do not use the JavaScript environment, or `bare`, once it has returned zero. It runs the loop in `mode` first. If handles are still open afterwards it returns a positive value and leaves `bare` valid, in which case call it again.

```c
int
bare_exit(bare_t *bare, int exit_code);
```

Immediately terminates the process with an exit status of `exit_code`. It works by calling `Bare.exit()` in the JavaScript environment, so call it from the thread that owns the environment. To terminate from any other thread, use `bare_terminate()`.

```c
int
bare_terminate(bare_t *bare);
```

Terminates the process as soon as possible. Safe to call from any thread.

#### Suspension [#suspension]

These are the C counterparts of [`Bare.suspend()`](#baresuspendlinger), [`Bare.wakeup()`](#barewakeupdeadline) and [`Bare.resume()`](#bareresume), and are safe to call from any thread. Each returns the result of waking the loop, so it returns a negative value only if that fails.

```c
int
bare_suspend(bare_t *bare, int linger);
```

Suspends the process as soon as possible. Once it has suspended, `bare_run()` does not return until another thread resumes the process.

```c
int
bare_wakeup(bare_t *bare, int deadline);
```

Wakes the process up if it is suspended, and gives it time until `deadline` to do background work.

```c
int
bare_resume(bare_t *bare);
```

Resumes the process as soon as possible. If the process is not yet idle after being suspended, the suspension is cancelled.

From Bare 1.37.0, a transition that another thread requests just as the loop runs out of work is still carried out, where earlier versions could drop it. Once the loop has run out of work with no transition pending, and the process has begun to exit, these functions and `bare_terminate()` do nothing and return `0`. The same goes for the lifecycle methods of a [`Bare.Thread`](#barethread) that is exiting.

#### Sealing, context and attaching [#sealing-context-and-attaching]

```c
int
bare_seal(bare_t *bare);
```

Seals addon loading for the process, equivalent to [`Bare.Addon.seal()`](#bareaddon). Once sealed, the process cannot load a further dynamic addon on any of its threads, now or in the future, and statically linked addons stay available. The seal applies to the process alone and is lifted when it is torn down. It also freezes the context registry, so nothing can be published to it afterwards. Requires Bare `>=1.32.0`.

`bare_context_set()` and `bare_context_get()`, which require Bare `>=1.33.0`, and `bare_attach()` and `bare_detach()`, which require Bare `>=1.34.0`, are documented in the [embedder context API](/bare/reference/bare/embedder-context).

#### `bare_options_t` [#bare_options_t]

```c
struct bare_options_s {
  int version;
  size_t memory_limit;
};
```

Options for `bare_setup()`. Set `version` to `0`, the only version there is, and any field you leave unset takes its default. A `NULL` `options` takes every default.

| Field          | Since | Description                                                                                                                                                                                                                                                                 |
| -------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`      | 0     | The version of the struct. Fields newer than this version are ignored.                                                                                                                                                                                                      |
| `memory_limit` | 0     | The memory limit of each JavaScript heap in bytes. The limit applies to each thread individually, including the main thread. By default it is inferred from the amount of physical memory of the device. The default can be changed at build time with `BARE_MEMORY_LIMIT`. |

#### Listeners [#listeners]

Each of these attaches a native listener that is the C counterpart of a JavaScript event on `Bare`. `data` is passed back to the listener as its last argument. A listener is a single slot, so a second call replaces the first, and `NULL` clears it. The event listeners run after the JavaScript listeners for the same event, and only for the main thread, not for the other threads of the process.

| Function                              | Listener type                                  | Equivalent to               |
| ------------------------------------- | ---------------------------------------------- | --------------------------- |
| `bare_on_before_exit(bare, cb, data)` | `void (*)(bare_t *, void *data)`               | `Bare.on('beforeExit', cb)` |
| `bare_on_exit(bare, cb, data)`        | `void (*)(bare_t *, void *data)`               | `Bare.on('exit', cb)`       |
| `bare_on_suspend(bare, cb, data)`     | `void (*)(bare_t *, int linger, void *data)`   | `Bare.on('suspend', cb)`    |
| `bare_on_wakeup(bare, cb, data)`      | `void (*)(bare_t *, int deadline, void *data)` | `Bare.on('wakeup', cb)`     |
| `bare_on_idle(bare, cb, data)`        | `void (*)(bare_t *, void *data)`               | `Bare.on('idle', cb)`       |
| `bare_on_resume(bare, cb, data)`      | `void (*)(bare_t *, void *data)`               | `Bare.on('resume', cb)`     |
| `bare_on_thread(bare, cb, data)`      | `void (*)(bare_t *, js_env_t *, void *data)`   | none                        |

The listener types are `bare_before_exit_cb`, `bare_exit_cb`, `bare_suspend_cb`, `bare_wakeup_cb`, `bare_idle_cb`, `bare_resume_cb` and `bare_thread_cb`. Unlike the others, a `bare_on_thread()` listener is called with the JavaScript environment of each thread created with the [`Thread`](#barethread) constructor, before that thread runs any JavaScript, so it is the place to modify the environment of the thread. The `beforeExit` and `exit` listeners are not passed the exit code.

#### Headers and macros [#headers-and-macros]

`include/bare.h` includes three more headers, available to embedders and native addons alike.

| Header           | Provides                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bare/version.h` | `BARE_VERSION_MAJOR`, `BARE_VERSION_MINOR`, `BARE_VERSION_PATCH`, and `BARE_VERSION`, the version of the header as a string such as `"1.37.1"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `bare/target.h`  | `BARE_PLATFORM` (`"ios"`, `"darwin"`, `"android"`, `"linux"`, `"win32"`, from 1.35.0 `"wasi"`, from 1.37.0 `"freertos"`, or from 1.37.1 `"watchos"`), `BARE_ARCH` (`"arm64"`, `"arm"`, `"x64"`, `"ia32"`, `"riscv64"`, `"mips"`, `"mipsel"`, from 1.35.0 `"wasm32"`, from 1.37.0 `"riscv32"` or `"armv8m"`, or from 1.37.1 `"arm64-32"`), `BARE_LIBC` (`"gnu"`, `"musl"` or `"bionic"`, on Linux and Android only), `BARE_SIMULATOR`, and the combined `BARE_TARGET`, equal to `BARE_HOST`. Each platform and architecture also has a matching flag, such as `BARE_PLATFORM_LINUX` or `BARE_ARCH_X64`. |
| `bare/module.h`  | The native addon API below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

From Bare 1.35.0, `bare/target.h` also recognizes a compiler that targets WebAssembly under WASI, which it detects with `__wasi__` and `__wasm32__`. It sets `BARE_PLATFORM` to `"wasi"` and `BARE_ARCH` to `"wasm32"`, and defines the flags `BARE_PLATFORM_WASI` and `BARE_ARCH_WASM32`. The [platform support](#supported-platforms) table has no WebAssembly target, and the `Bare.platform` and `Bare.arch` types in `bare.d.ts` do not list these values.

From Bare 1.37.0, it recognizes FreeRTOS by `__FREERTOS__`, 32-bit RISC-V by `__riscv` with `__riscv_xlen` of 32, and Armv8-M Mainline with a hardware floating-point calling convention, which sets `BARE_ARCH_ARMV8M`. Any other M-profile Arm target is an error. From Bare 1.37.1, it recognizes watchOS by `TARGET_OS_WATCH`, which sets `BARE_PLATFORM_WATCHOS`, and the `arm64_32` architecture of Apple Watch by `__ARM64_ARCH_8_32__`, which sets `BARE_ARCH_ARM64_32`. These targets are not in the platform support table either.

`bare/module.h` is how a native addon registers itself, which is the C side of [`Bare.Addon`](#bareaddon):

```c
BARE_MODULE(id, fn)
```

Registers the addon, where `fn` is `js_value_t *fn(js_env_t *env, js_value_t *exports)` and returns the exports. `id` is an identifier that is unique within the library, used to name the generated registration code. Define `BARE_MODULE_NAME` before including the header to name the addon, which a statically linked addon requires. A library registers one module. By default the addon registers through exported symbols that Bare looks up once the library is loaded, which suits a dynamic addon. Define `BARE_MODULE_REGISTER_CONSTRUCTOR` to register from a library constructor instead, which suits both dynamic and statically linked addons.

```c
void *
bare_module_find(const char *query);
```

Finds a loaded addon by name, optionally suffixed with `.bare`. Addons are named `<name>@<version>`, and the version may be cut off at a component boundary, so `foo@1` matches `foo@1.2.3` but not `foo@10.0.0`. A query with no version matches only an addon registered without one, and if several addons match, the most recently loaded is returned. Only the addons loaded by the process running on the calling thread are matched, along with the statically linked addons. Returns `NULL` if nothing matches or no process is running on the thread. The library belongs to Bare and must not be closed. It stays loaded for as long as the process that loaded the addon, so a caller that keeps it past the call must take a reference of its own. Before Bare 1.35.0 the function returned `uv_lib_t *`. In C, a `void *` converts to `uv_lib_t *` without a cast, so existing C code compiles unchanged. C++ code needs a cast.

```c
void
bare_module_register(bare_module_t *module);
```

Registers a module with Bare. `BARE_MODULE()` calls it for you, so you do not normally call it directly. A module registered while the thread is loading a dynamic addon becomes that addon, owned by the process doing the load. A module registered at any other time is a statically linked addon, owned by no process, available to every process including a sealed one, and registered for the life of the operating system process. `module->version` must be `BARE_MODULE_VERSION`. The module is copied, so it need not outlive the call.

### Building Bare [#building-bare]

Bare is compiled with [`bare-make`](/bare/reference/bare/modules/bare-make). From a checkout of [`holepunchto/bare`](https://github.com/holepunchto/bare), install the tool globally, install the build and runtime dependencies, generate the build system, and build:

```console
npm i -g bare-make
npm i
bare-make generate
bare-make build
```

`bare-make generate` only has to be run once per repository checkout. After updating `bare-make` or your compiler toolchain, regenerate the build system with `bare-make generate --no-cache`, which disregards the existing build system cache.

When the build completes, the `bare(.exe)` binary is in the `build/bin` directory. The `libbare.(a|lib)` and `(lib)bare.(dylib|dll|lib)` libraries are in the root of the `build` directory.

#### Linking [#linking]

When linking against the static `libbare.(a|lib)` library, use whole archive linking. Bare relies on constructor functions to register native addons, and without whole archive linking the linker removes them because nothing references them.

#### Compile options [#compile-options]

Compile options customize aspects of the runtime. Set one by passing `--define option=value` to `bare-make generate`.

> [!WARNING]
> The compile options are not covered by semantic versioning and are subject to change without warning.

| Option               | Default                    | Description                                                                                                                                                                                |
| -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BARE_ENGINE`        | `github:holepunchto/libjs` | The JavaScript engine to use.                                                                                                                                                              |
| `BARE_ENGINE_SHARED` | `OFF`                      | Link the JavaScript engine as a shared library rather than embedding it. Added in Bare 1.35.0. When `ON`, the prebuilds that `BARE_PREBUILDS` enables for the default engine are not used. |
| `BARE_PREBUILDS`     | `ON`                       | Enable prebuilds for supported third-party dependencies.                                                                                                                                   |
| `BARE_MEMORY_LIMIT`  | `0`                        | The default memory limit of each JavaScript heap. See `memory_limit` in [`bare_options_t`](#bare_options_t).                                                                               |

#### Sanitizers [#sanitizers]

Compile Bare with a sanitizer by passing `--sanitize` to `bare-make generate`:

```console
bare-make generate --sanitize address
```

This instruments Bare but not the JavaScript engine. To instrument the engine too, build a sanitized V8 prebuild with [`chromium-prebuilds`](https://github.com/holepunchto/chromium-prebuilds) and add `--define BARE_PREBUILDS=OFF --define GN_DIR=<src> --define GN_OUT_DIR=<out>`.

## Supported platforms [#supported-platforms]

Bare sorts the platforms it targets into two tiers. **Tier 1** targets have prebuilds, as defined by the project's [`prebuild.yml`](https://github.com/holepunchto/bare/blob/main/.github/workflows/prebuild.yml) workflow, and a compilation or test failure on one fails the project's CI. **Tier 2** targets are known to work, but are not compiled or tested automatically, so a regression can slip into a release and counts as a bug. A target can move between tiers in a minor release, and that is not a breaking change.

| Platform      | Architectures                 | Minimum                        | Tier | Notes                                  |
| ------------- | ----------------------------- | ------------------------------ | ---- | -------------------------------------- |
| Linux (glibc) | `arm64`, `x64`                | Linux 5.15, GNU C Library 2.35 | 1    | Ubuntu 22.04, Debian 12, OpenWrt 23.05 |
| Linux (glibc) | `riscv64`                     | Linux 6.8, GNU C Library 2.39  | 2    | Ubuntu 24.04, Debian 13                |
| Linux (musl)  | `arm`, `arm64`, `ia32`, `x64` | Linux 5.10, musl 1.2           | 2    | Alpine 3.13, OpenWrt 22.03             |
| Linux (musl)  | `mips`, `mipsel`              | Linux 5.10, musl 1.2           | 2    | OpenWrt 22.03                          |
| Linux (musl)  | `riscv64`                     | Linux 6.6, musl 1.2            | 2    | Alpine 3.20                            |
| Android       | `arm`, `arm64`, `ia32`, `x64` | Android 10                     | 1    |                                        |
| macOS         | `arm64`, `x64`                | macOS 13.0                     | 1    |                                        |
| iOS           | `arm64`, `x64`                | iOS 15.0                       | 1    | `x64` is simulator only                |
| Windows       | `x64`                         | Windows 10                     | 1    |                                        |
| Windows       | `arm64`                       | Windows 11                     | 1    |                                        |

Bare is developed primarily on Apple hardware, with Linux and Windows systems running as virtual machines.

From Bare 1.37.0, an iOS app that embeds Bare must be signed with the [`com.apple.developer.kernel.extended-virtual-addressing`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.kernel.extended-virtual-addressing) entitlement. V8 reserves a large region of virtual memory when it starts, for pointer compression and for the heap of its C++ garbage collector, and on iOS that is more than the default address space of an app. Without the entitlement, the app aborts on a device with `Failed to reserve virtual memory for process-wide V8 pointer compression cage`. See [Bare Kit](/bare/reference/bare/bare-kit#ios-entitlement) for how to add it.

From Bare 1.37.0, V8 is built with pointer compression on every 64-bit platform. JavaScript heaps take less memory, but all of them in one operating system process share a single reservation of about 4 GiB: every [`Bare.Thread`](#barethread), Bare Kit worklet, and Bare process that an embedder runs there. Once their heaps together outgrow it, the whole process aborts with `Fatal JavaScript out of memory`, even if each heap is within its own limit.

The macOS and iOS minimums rose in Bare 1.34.1, from 12.0 and 14.0. A project that ships to macOS 12 or iOS 14 stays on Bare 1.34.0 or earlier. The table follows [Bare's README](https://github.com/holepunchto/bare#platform-support), which is the authority if the two ever differ.

## See also [#see-also]

* [Inside Bare](/bare/explanation/bare-runtime)—what the runtime adds and why.
* [Embedder context API](/bare/reference/bare/embedder-context)—pass native handles from the embedder to addons.
* [`bare` CLI](/bare/reference/bare/cli)—run scripts and start a REPL.
* [`bare-kit` reference](/bare/reference/bare/bare-kit)—embed a Bare worklet in a native app.
* [Bare modules](/bare/reference/bare/modules)—the `bare-*` standard library.