Neko: the Haxe virtual machine that stopped growing in 2021

Deprecated in 2021, still shipping in 2026

The first thing the README says, under a heading that gives a date, is that Neko is deprecated as of 2021-09-09, and that Neko is not actively maintained anymore.

What follows is the more useful part of the notice, because a deprecation without a scope is not much of a statement. The project keeps it compatible with the existing Haxe standard library and with Haxe language features. It does not expect any new features in Neko itself, and it does not expect the implementation of any new Haxe standard library API.

So the maintenance that continues is compatibility maintenance. The runtime keeps working with what already exists, and the gap widens by one API every time the Haxe standard library grows.

That is a materially different thing from an abandoned project, and the release history shows it. Version 2.4.0 was published on 2024-07-18, with 2.4.0-rc.1 before it on 2024-06-30, and 2.4.1 on 2025-04-15. The last push to the repository was on 2026-10-13, and the repository is not archived.

For an evaluation, the dates are the answer. A project that says it will not add features but does ship releases and still takes commits is a project whose value is stability, not possibility.

What the virtual machine is made of

Neko is the Neko Virtual Machine, the runtime for the Haxe language, and the project topics are interpreter, neko and virtual-machine.

The repository layout shows the pieces of a language runtime. There is a vm/ directory, which is the virtual machine itself, a src/ directory for the C sources, a boot/ directory, a libs/ directory for the standard library pieces that ship with it, an extra/ directory, a cmake/ directory with the build logic alongside the top level CMakeLists.txt, a tests/ directory, and a deploy.sh script. The README points at the project site nekovm.org for the wider description.

The naming convention that matters for anyone extending it is the ndll. The CMake options call them NDLLs, and each one is a native dynamic library that the VM loads to add a capability, which is why the options are phrased as switches such as build SSL support or build MySQL support. The switch set maps closely onto the third party libraries in the dependency list, so the extension surface and the dependency surface are the same thing.

The VM itself is a bytecode implementation with a just in time compiler, and the build has switches for turning the JIT off or turning on JIT debugging. The interpreter framing in the topics is accurate for the part of the runtime that does not compile.

Building it on Mac and Linux with CMake

Neko is built with CMake, with version 3.x recommended, and a C compiler. On Windows the supported compilers are Visual Studio 2010, 2013, 2015 and 2017, on Mac it is XCode with its command line tools, and on Linux it is gcc, obtainable by installing the build-essential package on Debian and Ubuntu.

The Mac and Linux build is the familiar CMake sequence:

# make a build directory, and change to it
mkdir build
cd build

# run cmake
cmake ..

# let's build, the outputs can be located in the "bin" directory
make

# install it if you want
# default installation prefix is /usr/local
make install

The Windows build runs in a Visual Studio command prompt, and the generator is chosen explicitly:

cmake -G "Visual Studio 12 2013" ..

# let's build, the outputs can be located in the "bin" directory
msbuild ALL_BUILD.vcxproj /p:Configuration=Release

# install it if you want
# default installation location is C:\HaxeToolkit\neko
msbuild INSTALL.vcxproj /p:Configuration=Release

The comments in the build file are worth reading rather than skipping, because they tell you where the outputs land. The binaries end up in the bin directory inside the build tree, and the install step puts them under /usr/local on Mac and Linux or under C:\HaxeToolkit\neko on Windows.

On Windows, CMake downloads and builds the third party libraries into the build folder during the build. On Mac and Linux you either install the libraries to your system first, or you use the STATIC_DEPS option described below.

Nine third party libraries decide what the VM can do

The dependency table is the most informative part of the build documentation, because it shows what Neko links against and therefore what its standard library can reach.

The Boehm GC provides the garbage collector, and OpenSSL provides the TLS and crypto. pcre2 and zlib give the regular expression and compression support, and they sit together with the others because both are exposed to the Haxe side as ndlls. Apache 2.2 or 2.4 with apr and apr-util is there for the Apache modules, MariaDB or MySQL through Connector/C for the database, and SQLite for the embedded one. mbed TLS is the second TLS implementation, which gives a choice of crypto backends, and GTK+3 on Linux provides the UI support.

The Debian and Ubuntu package names are given for each, so the list maps directly onto an apt command: libgc-dev, libssl-dev, libpcre2-dev, zlib1g-dev, apache2-dev, libmariadb-client-lgpl-dev-compat or libmysqlclient-dev, libsqlite3-dev, libmbedtls-dev, and libgtk-3-dev.

There is one platform asymmetry worth knowing. On Windows, CMake will download and build the libraries during the build, but you need to install Perl manually because OpenSSL needs it for configuration. On Mac and Linux the libraries are installed by you, or the static dependency option builds them into the build folder instead.

The CMake options that shape the binary

The build has a set of options that a user is expected to know about, and they are grouped by what they change.

The NDLL switches exclude libraries and their dependencies from the build, and they are all on by default: WITH_REGEXP for Perl compatible regex support, WITH_UI for the GTK-3 user interface, WITH_SSL for SSL support, WITH_MYSQL for MySQL support, WITH_SQLITE for SQLite support, and WITH_APACHE for the Apache modules. Turning one off removes both the library and the ndll that wraps it, which is how you get a smaller VM.

STATIC_DEPS defines which dependencies are linked statically. It can be all, none, or a list of library names, and the default is all on Windows and none everywhere else. The list form is explicit, with an example that names BoehmGC, Zlib, OpenSSL, MariaDBConnector, pcre2, SQLite3, APR, APRutil, Apache and MbedTLS. A library that is not in the list has to be installed manually and is linked dynamically.

Two libraries cannot be linked statically. GTK+3 is excluded because of the difficulty of building it and its own dependencies, and the Boehm GC cannot be statically linked on Windows.

The remaining options are about how the result behaves. RELOCATABLE, available on Mac and Linux and on by default, sets the RPATH to $ORIGIN on Linux and @executable_path on Mac, so the executable finds libneko and the ndll files next to itself rather than in /usr/lib or /usr/local/lib, which is what makes a portable copy possible. NEKO_JIT_DISABLE turns the JIT off on every platform, and NEKO_JIT_DEBUG turns on JIT debugging. RUN_LDCONFIG, available on Linux and on by default, runs ldconfig after make install so that the shared library cache can find libneko.

Options are passed on the command line in the usual CMake form, with the -Doption=value pattern, or set in the CMake GUI.

Snapshot binaries and a one command install on Mac

Not everybody should be compiling this. The README points at the artifacts section in the summary of each GitHub Actions build, where compiled binaries are published, and the continuous integration badge shows a main workflow on the master branch.

For Mac there is an even shorter route, through Homebrew:

brew install neko --HEAD

That installs the required dependencies, builds Neko and installs it to the system, and the binaries can be found with brew --prefix neko. Upgrading later is brew reinstall neko --HEAD.

The HEAD flag is worth understanding, because it says what the install is. It installs the latest master branch rather than a released version, which is the right choice for a project whose releases trail the branch, and the wrong choice if you need a fixed, reproducible binary.

For a project in production, the practical split is this. Use the prebuilt artifact or the Homebrew snapshot for a development machine, and use a source build with the options you need for the machines that ship, pinning the source revision so that the binary is reproducible.

That is the same decision, in other words, that a source build gives you control over. A source build lets you switch off the components you do not need, statically link the rest so the binary carries its dependencies, and make the result relocatable so it can be copied between machines.

Where Neko is the wrong choice now

Three limits are structural, and one of them is a date in a heading.

The first is the deprecation itself. A new Haxe standard library API will not be implemented in Neko, so a feature you want to use from the Haxe side may simply not exist in this runtime, and there is no timetable for it arriving. For a team whose application is finished and stable, that is an inconvenience. For a team whose application is still being written, it is disqualifying.

The second is the dependency surface for a self hosted or offline runtime. Nine third party libraries, a garbage collector, two TLS stacks, three database drivers and a GTK user interface is a lot to carry, and the static linking options exist precisely because that surface is heavy.

The third is that a VM with no new features still has to be maintained, and the maintenance here is compatibility only. The releases continue, the branch still takes commits, and none of that changes what the notice says.

The honest alternative for a new project is to compile the same VM yourself with only the pieces you need, using the NDLL switches and STATIC_DEPS, and to treat the source build rather than the release as your artefact. That is a different approach from installing a published binary, and it is the only one the project still supports in a meaningful sense.

For an existing deployment, the decision is a patch and a rebuild rather than a migration, and the CMake options are what you would use to keep the footprint the same while moving to a newer revision.

Editorial conclusion

Adopt Neko only where it already runs, in a product that depends on the existing Haxe standard library and the ndll extensions compiled for it, where the value is in a compatible build rather than new capability. Do not adopt it for anything new, because the deprecation notice commits to no new Neko features and no implementation of new Haxe standard library API, and that is a permanent constraint rather than a temporary gap. Verify first which Neko version your Haxe compiler targets, whether the ndlls you need exist for that version, and whether your platform has a prebuilt binary or needs the full CMake build with its third party dependencies.

Frequently asked questions

Official sources

1. HaxeFoundation/neko on GitHub
2. Issues
3. Project website
4. README
5. Releases