bare-addon

Template repository for creating Bare native addons. For information on how to use the template, see Creating a repository from a template.

Building

https://github.com/holepunchto/bare-make is used for compiling the native bindings in binding.c. Start by installing the tool globally:

npm i -g bare-make

Next, generate the build system for compiling the bindings, optionally setting the --debug flag to enable debug symbols and assertions:

bare-make generate [--debug]

This only has to be run once per repository checkout. When updating bare-make or your compiler toolchain it might also be necessary to regenerate the build system. To do so, run the command again with the --no-cache flag set to disregard the existing build system cache:

bare-make generate [--debug] --no-cache

With a build system generated, the bindings can be compiled:

bare-make build

This will compile the bindings and output the resulting shared library module to the build/ directory. To install it into the prebuilds/ directory where the Bare addon resolution algorithm expects to find it, do:

bare-make install

To make iteration faster during development, the shared library module can also be linked into the prebuilds/ directory rather than copied. To do so, set the --link flag:

bare-make install --link

Prior to publishing the module, make sure that no links exist within the prebuilds/ directory as these will not be included in the resulting package archive.

Publishing

To publish an addon, make sure to first compile bindings for the targets you wish to support. The prebuild workflow defined in .github/workflows/prebuild.yml automates this process for all tier 1 targets supported by Bare. The whole process can be handily orchestrated by the GitHub CLI. As the package version is part of the compiled bindings, make sure to first commit and push a version update:

npm version <increment>
git push
git push --tags

To start the prebuild workflow for the newly pushed version, do:

gh workflow run prebuild --ref <version>

To watch the status of the workflow run until it finishes, do:

gh run watch

When finished, the resulting prebuilds can be downloaded to the prebuilds/ directory by doing:

gh run download --name prebuilds --dir prebuilds

Important

You still need to manually run npm pub to publish the package to npm.

Dependencies

Addons are rarely self-contained and most often need to pull in external native libraries. For this, https://github.com/holepunchto/cmake-fetch should be used. Start by installing the package as a development dependency:

npm i -D cmake-fetch

Next, import the package in the CMakeLists.txt build definition:

find_package(cmake-fetch REQUIRED PATHS node_modules/cmake-fetch)

This will make the fetch_package() function available. To fetch an external native library, such as https://github.com/holepunchto/liburl, add the following line after the project() declaration in the build definition:

fetch_package("github:holepunchto/liburl")

Finally, link the imported native library to the addon:

target_link_libraries(
  ${bare_addon}
  PUBLIC
    url
)

Troubleshooting

Local changes not being reflected after installation

The bare CLI statically links built-in native addons using link_bare_module() in bare/bin/CMakeLists.txt. If you are working on one of those, bare may be loading a cached version of it.

To check the current cache state, do:

bare --print 'Bare.Addon.cache'

To bypass this issue during development, manually bump the version field in the package.json to invalidate the cache.

License

Apache-2.0