Contributing#

Bugs and feature requests#

Use the official repository (named Rygel, because this is a monorepo containing multiple projects) for bugs, ideas and features requests.

Go here: https://github.com/Koromix/rygel/

Build from source#

We provide prebuilt binaries, packaged in the NPM archive, so in most cases it should be as simple as npm install koffi. If you want to hack Koffi or use a specific platform, follow the instructions below.

Start by cloning the repository with Git:

1git clone https://github.com/Koromix/rygel
2cd rygel/src/koffi

As said before, this is a monorepository containg multiple projects, hence the name.

Windows#

First, make sure the following dependencies are met:

Once this is done, run this command from the test or the benchmark directory (depending on what you want to build):

1cd koffi/test # or cd koffi/benchmark
2node ../../cnoke/cnoke.js

Other platforms#

Make sure the following dependencies are met:

Once this is done, run this command from the test or the benchmark directory (depending on what you want to build):

1cd koffi/test # or cd koffi/benchmark
2node ../../cnoke/cnoke.js

Running tests#

Koffi is tested on multiple architectures using emulated (accelerated when possible) QEMU machines. First, you need to install qemu packages, such as qemu-system (or even qemu-system-gui) on Ubuntu.

These machines are not included directly in this repository (for license and size reasons), but they are available here: https://koromix.dev/files/machines/

For example, if you want to run the tests on Debian ARM64, run the following commands:

1cd rygel/src/koffi/tools/
2wget -q -O- https://koromix.dev/files/machines/qemu_debian_arm64.tar.zst | zstd -d | tar xv
3sha256sum -c --ignore-missing registry/sha256sum.txt

Note that the machine disk content may change each time the machine runs, so the checksum test will fail once a machine has been used at least once.

And now you can run the tests with:

1node qemu.js test # Several options are available, use --help

And be patient, this can be pretty slow for emulated machines. The Linux machines have and use ccache to build Koffi, so subsequent build steps will get much more tolerable.

By default, machines are started and stopped for each test. But you can start the machines ahead of time and run the tests multiple times instead:

1node qemu.js start # Start the machines
2node qemu.js test # Test (without shutting down)
3node qemu.js test # Test again
4node qemu.js stop # Stop everything

You can also restrict the test to a subset of machines:

1# Full test cycle
2node qemu.js test debian_x64 debian_i386
3
4# Separate start, test, shutdown
5node qemu.js start debian_x64 debian_i386
6node qemu.js test debian_x64 debian_i386
7node qemu.js stop

Finally, you can join a running machine with SSH with the following shortcut, if you need to do some debugging or any other manual procedure:

1node qemu.js ssh debian_i386

Each machine is configured to run a VNC server available locally, which you can use to access the display, using KRDC or any other compatible viewer. Use the info command to get the VNC port.

1node qemu.js info debian_x64

Code style#

Koffi is programmed in a mix of C++ and assembly code (architecture-specific code). It uses node-addon-api (C++ N-API wrapper) to interact with Node.js.

My personal preference goes to a rather C-like C++ style, with careful use of templates (mainly for containers) and little object-oriented programming. I strongly prefer tagged unions and code locality over inheritance and virtual methods. Exceptions are disabled.