README.md
March 28, 2026 · View on GitHub
zidar is a Lua based build system framework built on top of GENie project generator. It minimizes the effort needed to maintain C/C++ project configurations and their physical organization on disk across different target platforms.
You describe your projects with minimal Lua — declare a project type and its dependencies — and zidar handles everything else: dependency resolution, compiler/linker flags, platform detection, project generation.
-- genie.lua
newoption { trigger = "zidar-path", description = "Path to zidar" }
dofile(_OPTIONS["zidar-path"] .. "/zidar.lua")
dofile("my_lib.lua")
dofile("my_game.lua")
solution "my_engine"
setPlatforms()
projectAdd("my_lib") -- recursively resolves and adds all dependencies
projectAdd("my_game")
-- my_lib.lua
function projectAdd_my_lib()
addProject_lib("my_lib")
end
-- my_game.lua
function projectDependencies_my_game()
return { "my_lib" }
end
function projectAdd_my_game()
addProject_game("my_game")
end
Features
- Automatic dependency resolution — recursively discovers, downloads (via git), and links project dependencies
- Cross-platform — Windows, Linux, macOS, iOS, tvOS, visionOS, Android, WebAssembly, FreeBSD, NetBSD, RISC-V, Raspberry Pi
- Multiple toolchains — Visual Studio 2017-2022, GCC, Clang, MinGW, Xcode, Android NDK, Emscripten
- Console support — PlayStation 4/5 (Orbis/Prospero), Xbox One (Durango), Nintendo Switch
- Qt 6 integration — automatic MOC, UIC, RCC, and translation file processing
- Shader compilation — bgfx shader cross-compilation (GLSL, SPIR-V, DirectX 9/11, Metal) as a pre-build step
- Third-party library management — build scripts for 63 common libraries
- Precompiled header support — automatic PCH detection and configuration
- Deployment — platform-specific packaging, icon generation, and manifest creation
Quick Start
1. Install GENie and place it in your PATH
2. Create a project script (scripts/my_app.lua):
function projectAdd_my_app()
addProject_cmd("my_app")
end
3. Create the entry point (scripts/genie.lua):
newoption { trigger = "zidar-path", description = "Path to zidar" }
dofile(_OPTIONS["zidar-path"] .. "/zidar.lua")
dofile("my_app.lua")
solution "my_app"
setPlatforms()
projectAdd("my_app")
4. Generate build files:
genie --zidar-path=/path/to/zidar vs2022 # Visual Studio 2022
genie --zidar-path=/path/to/zidar gmake # GNU Makefiles
genie --zidar-path=/path/to/zidar ninja # Ninja
genie --zidar-path=/path/to/zidar xcode9 # Xcode
Convention-Based Project Layout
Each project follows a directory convention that zidar uses for auto-discovery:
project_name/
scripts/
genie.lua -- standalone entry point
project_name.lua -- defines projectAdd_<name>(), projectDependencies_<name>(), etc.
src/ -- source files and private headers
include/ -- public headers (auto-added to dependents' include paths)
tests/ -- unit tests (added with --with-unittests)
samples/ -- sample projects (added with --with-samples)
tools/ -- tool projects (added with --with-tools)
3rd/ -- project-specific 3rd party code
Project Types
| Type | Function | Output |
|---|---|---|
| Library | addProject_lib | Static or shared library |
| 3rd party lib | addProject_3rdParty_lib | Static library with relaxed warnings |
| Command tool | addProject_cmd | Console executable |
| Game | addProject_game | Windowed (retail) / console (debug) executable |
| Qt project | addProject_qt | Qt application or static library |
| Library tool | addProject_lib_tool | Tool executable (part of a library) |
| Library sample | addProject_lib_sample | Sample executable for a library |
| Library test | addProject_lib_test | Unit test executable |
Callback System
Projects are defined through named callback functions. Zidar calls them automatically during dependency resolution and project generation:
| Callback | Purpose |
|---|---|
projectAdd_<name>() | Required. Adds the project to the solution |
projectDependencies_<name>() | Returns a table of dependency names |
projectSource_<name>() | Returns a git URL for auto-download |
projectExtraConfig_<name>() | Per-configuration extra flags/defines/links |
projectExtraConfigExecutable_<name>() | Extra settings for executable targets |
projectDependencyConfig_<name>() | Settings applied when used as a dependency |
projectDescription_<name>() | Human-readable project description |
projectHeaderOnlyLib_<name> | Set to skip linking (header-only library) |
Build Configurations
| Configuration | Defines | Key Flags |
|---|---|---|
debug | RG_DEBUG_BUILD, _DEBUG | Symbols |
release | RG_RELEASE_BUILD, NDEBUG | OptimizeSpeed, Symbols |
retail | RG_RETAIL_BUILD, NDEBUG, RETAIL | OptimizeSpeed, no symbols |
Command Line Options
| Option | Description |
|---|---|
--zidar-path=PATH | Path to the zidar directory (required) |
--with-unittests | Generate library unit test projects |
--with-tools | Generate library tool projects |
--with-samples | Generate library sample projects |
--with-no-pch | Disable precompiled headers |
--gcc=VARIANT | GCC/Clang variant (linux-gcc, linux-clang, android-arm64, osx-arm64, wasm, ...) |
--vs=TOOLSET | Visual Studio toolset (vs2017-clang, winstore100, durango, orbis, prospero) |
--xcode=TARGET | Xcode target (osx, ios, tvos, xros) |
--with-android=LEVEL | Android API level (default: 24) |
--with-ios=VERSION | iOS minimum deployment target |
--with-macos=VERSION | macOS minimum deployment target |
--with-dynamic-runtime | Use dynamic runtime linking |
--with-avx | Enable AVX instruction set |
Third-Party Libraries
Zidar includes build scripts for 63 libraries in 3rd/. When a dependency isn't found locally, zidar automatically downloads it via git clone:
assimp basis_universal bgfx bimg bnet box2d bx cgltf curl DIA efsw enet enkiTS fcpp freetype2 imgui jolt libdom libparserutils librdkafka libsvgtiny libtess2 libuv libwapcaplet libxml2 lua mbedtls meshoptimizer minilua msdf_atlas_gen msdfgen nanosvg nanosvg2 nanovg ogg openssl raw_pdb sasl2 simple-svg soloud sparsehash spdlog squish stb subprocess.h ta_lib tbb tinygltf tinyspline tinyxml2 tomlplusplus ufbx unity unittest-cpp usockets uwebsockets vg_renderer vorbis wolfssl xxHash zfp zlib zstd
Samples
The samples/ directory contains five progressively complex examples:
| Sample | Description |
|---|---|
| 01_hello_world | Minimal console application |
| 02_hello_library | Static library with tests and samples |
| 03_tool_using_a_library | Command-line tool with a library dependency |
| 04_Qt_app_using_a_library | Qt GUI application with a library dependency |
| 05_fancy_game_engine | Multi-project setup: libraries, games, command-line and Qt tools |
Each sample includes a standalone genie.lua so it can be built independently.
Script Overview
| Script | Purpose |
|---|---|
zidar.lua | Main entry point — options, globals, dependency resolution, project loading |
toolchain.lua | Compiler and linker flags per platform/architecture |
configurations.lua | Per-project build configuration, vpath mapping, Qt/shader hooks |
project_lib.lua | Library project setup (static and shared) |
project_3rd.lua | Third-party library project setup |
project_cmdtool.lua | Command-line tool project setup |
project_game.lua | Game/application project setup |
project_lib_tool.lua | Library tool sub-project setup |
project_lib_sample.lua | Library sample sub-project setup |
project_lib_test.lua | Library test sub-project setup |
project_qt.lua | Qt application/library project setup |
qtpresets6.lua | Qt 6 MOC/QRC/UI/translation processing |
qtprebuild.lua | Qt pre-build file operations (standalone) |
embedded_files.lua | Shader compilation pre-build step configuration |
embedded_shader_prebuild.lua | Shader compilation script (standalone) |
deploy.lua | Platform-specific deployment and packaging |
3rd/*.lua | Individual build scripts for third-party libraries |
Documentation
Full documentation is available in the doc/ directory:
- Overview — architecture, conventions, and global variables
- Getting Started — setup, command line options, and environment
- Project Types — all project types, callbacks, and dependency resolution
- Custom Configurations — toolchains, Qt, shaders, 3rd party management
- Samples — walkthrough of all included sample projects
Dependencies
- GENie — project file generator (required)
- Lua — required for Qt-based projects (used in prebuild steps)
- Windows users should install GnuWin32 tools (
sed,make) git,make,ninja— must be in PATH
License (BSD 2-clause)
Copyright 2025-2026 by Milos Tosic. All rights reserved.
https://github.com/RudjiGames/zidar
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.