GENie: one Lua script, every build system

One Lua script, several build systems

GENie, pronounced as Jenny, is a project generator tool. It automagically generates a project from a Lua script, making applying the same settings for multiple projects easy.

The generators it supports are the list of things you would otherwise write by hand. GNU Makefile. JSON Compilation Database. Ninja, marked experimental. Visual Studio, and the README lists the versions it covers, 2010, 2012, 2013, 2015, 2017, 2019, 2022 and 2026. And XCode.

The value of a generator like this is not that any one of those outputs is better, it is that there is one description of the project and several renderings of it. A Visual Studio solution and a Makefile describing the same set of source files, the same include paths, the same preprocessor defines and the same optimisation settings drift apart within weeks. One Lua script cannot drift, because there is only one of it.

The scripting reference is a separate document in the docs/ directory, and there is a recorded talk, an introduction to GENie at CppCon 2016, linked from the README.

The primary language is C, and the repository layout is a normal C project: src/, tests/, docs/, scripts/, build/ and a lowercase makefile at the top level, alongside an .editorconfig, a .github directory and a LICENSE file.

It started as a Premake fork, and deliberately stopped being one

The History section is short and the important sentence is the second one.

The initial version of GENie is a fork of Premake 4.4 beta 5, and there is no intention to keep it compatible with it.

That is a design decision stated up front, and it saves a lot of confusion, because Premake is well known and the two tools look similar. Anything you have read about Premake is not documentation for GENie. The fork point is Premake 4.4 beta 5, and everything after that is GENie's own history.

The changelog since the fork is where the shape of the project becomes visible, and it is long. The early entries add Visual Studio 2013 support, hash UUID support where os.uuid should produce a consistent UUID, and a search for a default script with the default script name changed to genie.lua, though solution.lua and premake4.lua are also allowed, and it can be located in a scripts directory. The Lua runtime is updated from 5.1.4 to 5.3.0.

The rest of the list is a long tail of additions and removals across the years, and the removals are as informative as the additions. CodeBlocks and CodeLite support was removed. FASTBuild was added and later removed. Qbs support was added and later removed. The xcode3 and xcode4 actions were removed and replaced by xcode8 through xcode11 and then xcode14 and xcode15. Visual Studio 2002, 2003, 2005 and 2008 support was removed. The clean action was removed. And support was added for PS4 and Orbis projects, Nintendo Switch projects, Vala, MASM, Swift for the make and ninja generators, and WinRT, and a per-configuration files list, and a jcdb action for generating a JSON compilation database.

The pattern is a tool that keeps up with what the platforms need, and that treats every generator as something that can be replaced when the upstream one moves on.

The download, and building it yourself

There are two ways to get GENie, and the stable download is a single binary per platform.

The stable version is listed as version 1196, with a commit hash given alongside it, and the binaries are hosted in the bx repository under tools/bin. There is a Linux binary, an OSX one, and a Windows genie.exe, each fetched from a raw GitHub URL.

Building from source is three commands:

git clone https://github.com/bkaradzic/genie
cd genie
make

The makefile is at the top level and lowercase, which is the convention of the author's other projects.

For a project with a build configuration of its own, the build system has a debug mode, because the README explains that you can debug build scripts using ZeroBrane Studio and that you must compile GENie in debug mode with `make config=debug`.

That is worth pausing on, because a project generator is a program you write programs with. When a script does not do what you expected, the useful tool is a Lua debugger attached to the generator itself, and a release build of a C program with an embedded Lua interpreter is not where you want to be doing that. The debug configuration exists for that one job, and the ZeroBrane Studio link is the specific editor the author recommends for it.

There is also a related project mentioned in the README, zidar, a set of build system scripts and related tools built around GENie, from a different author.

The features that changed how a project is described

The changelog is a list of flags and actions, and a few of them show how the project model works.

There is a startproject action that sets the default project in Visual Studio. There is an options section, with a ForceCpp to enforce C++ compilation even when the file extension is for C. There is a solution folders group feature, and a targetsubdir, and a SingleOutputDir flag that restores the original behaviour of using a single output directory.

The excludes handling was split, and the distinction is a good one. With Visual Studio, excludes will exclude files from the build while the files are still added to the project file, whereas removefiles removes files completely from the project. The same Lua script therefore produces a project file that lists the file, which is what you want when the file is generated at build time, and a build that skips it.

The language specific build options are the other big one. There are separate buildoptions for C, C++, Objective-C, Objective-C++, assembly and Swift, so the same option that means one thing for a C compiler and another for Swift is expressed once per language rather than with conditionals.

And there are the flags that exist to work around toolchain behaviour: NoMultiProcessorCompilation to disable multiprocessor compilation in MSVC, UnsignedChar to force char to be unsigned, and NoBufferSecurityCheck to disable security checks in Visual Studio. Each of these is a thing a project on that toolchain needs and a project elsewhere does not, and a generator that can express them per project is more useful than one that cannot.

There is also a behaviour that matters for build systems: detect when generated project files are not changing, and skip writing over existing project files.

C++ standard flags and a generator list that keeps moving

Two details in the changelog are worth pulling out because they show the maintenance pattern.

The first is the C++ standard selection. There are flags for Cpp11, Cpp14, Cpp17, Cpp20 and CppLatest, added as a group. A generator that predates C++11 has to hard code a default standard, and a project that wants C++20 has to override it by hand in every generator. Five flags cover the range, and the project can then state the standard once in the Lua script and get the right compiler flag in the Makefile, the Visual Studio project and the Xcode project.

The second is the pattern of the version support. Visual Studio support arrives in steps over years, vs2013, then vs2015, then vs2017, then vs2019, then vs2022, then vs2026, with the older ones removed along the way. The Xcode side works the same way, with the action names xcode8 through xcode11 and then xcode14 and xcode15, the last of which brings visionOS support. The pattern is a generator that adds support for a new toolchain release and drops support for the ones nobody uses, which is a maintenance posture that keeps the tool relevant on a current machine.

There is also the addition of xcode15 with visionOS support, and the removal of the xcode3 and xcode4 actions, and the removal of the clean action, and the removal of the NoMinimalRebuild option in favour of reversed logic in EnableMinimalRebuild, which is the kind of change that breaks a script and gets documented so people can fix it.

The end state of the topic list on the repository matches the feature set: cmake, fastbuild, generator, makefile, ninja, premake, qbs, qtcreator, visual-studio and xcode. The tags list both what GENie does now and what it once did: premake is where it started, and fastbuild and qbs were later removed.

Editorial conclusion

Adopt GENie if your project has to be built on several toolchains and you are tired of maintaining a Makefile, a Visual Studio project and an Xcode project side by side, because the Lua script becomes the single description and the generators are interchangeable. Do not adopt it if your project builds with one tool, since a single Makefile is less machinery. Before you commit, read the fork history, because GENie started as a fork of Premake 4.4 beta 5 with no intention of remaining compatible, so Premake documentation does not apply, and note that the Ninja generator is marked experimental while the Visual Studio, Makefile, Xcode and compilation database paths are the mature ones.

Frequently asked questions

Official sources

1. bkaradzic/GENie on GitHub
2. Issues
3. Project website
4. README