2.16 · Project / Build

A Premake5-driven workspace that emits native build files per platform, with Conan supplying the heavy third-party dependencies and a thin script layer wrapping the everyday developer loop.

premake5.lua Dependencies.lua conanfile.py C++20 x86_64 Debug / Release / Dist ~38 vendor libs

Build pipeline: Premake5 ingests workspace + vendor maps + Conan output, emits native project files per platform.

Overview

LuckyEngine uses Premake5 as its single source of build truth. On Linux and macOS it emits gmake2 Makefiles; on Windows it emits a vs2022 solution. The codebase is C++20 across the board: clang++ on Linux/Mac (with the mold linker on Linux), MSVC on Windows. External C++ packages — anything too gnarly to vendor by hand — flow through Conan. Everything else is dropped into the in-tree vendor/ directories, of which there are roughly thirty-eight.

Build files

File	Role
`premake5.lua`	Root workspace. Sets C++20, x86_64, configs `Debug` / `Release` / `Dist`. Declares projects: `Hazel` (StaticLib), `LuckyEditor` (ConsoleApp), `Hazel-ScriptCore`, `Hazel-ScriptGen`, `LuckyRuntime`, and others.
`Dependencies.lua`	Vendor path mappings — the table every `premake5.lua` imports to resolve includes and links into `Hazel/vendor/`.
`conanfile.py`	External package list pulled from Conan Center: `ffmpeg`, `arrow` (Parquet), `onnxruntime`, `assimp`, `grpc`, `protobuf`, `openssl`, `zlib`, `abseil`, `re2`, `cares`, `nlohmann_json`.

Configurations

CFG

Debug

Full symbols, asserts on (HZ_CORE_ASSERT), no optimization. The day-to-day developer build.

CFG

Release

Optimized but still keeps HZ_CORE_VERIFY on. Use for performance work and most CI runs.

CFG

Dist

Shippable build. HZ_CORE_ASSERT compiled out; HZ_CORE_VERIFY still fires FatalBreak on failure.

Build scripts

The day-to-day loop lives in scripts/:

# first-time setup (Conan install, premake gen, etc.)
source .venv/bin/activate
./scripts/Linux-Setup.sh

# subsequent builds
./scripts/Linux-Build.sh Debug      # or Release / Dist

Activate the venv first

The setup and build scripts assume source .venv/bin/activate has been run — Conan, Premake, and a handful of Python codegen tools all live in the project venv. Skipping it is the most common reason a fresh checkout refuses to build.

Vendor & Conan

Roughly thirty-eight vendor libraries sit under Hazel/vendor/ as in-tree sources or pre-built binaries. Conan handles the dozen or so packages where vendoring would be painful — the FFmpeg toolchain, Apache Arrow / Parquet for dataset I/O, ONNX Runtime for inference, gRPC / protobuf for the cross-process surface, and the usual networking / crypto / JSON deps.

New dependency? Pick the right lane

A new header-only or small static library belongs in Hazel/vendor/ with a path entry in Dependencies.lua and a link line in Hazel/premake5.lua. A new chunky external (anything with a non-trivial build system of its own) belongs in conanfile.py followed by conan install.

CI

Workflow	Trigger	Purpose
`.github/workflows/build.yml`	push	Builds the workspace across configurations / platforms.
`.github/workflows/pr-review.yml`	pull_request	Runs the PR-time review pipeline.
`.github/workflows/release.yml`	tag	Produces the shippable Dist artifacts.

Pitfalls

Don't edit generated project files

Visual Studio's .sln / .vcxproj and the gmake2 Makefiles are generated. Any edit you make there is erased the next time someone re-runs Premake. Changes belong in premake5.lua.

Conan and Premake are sequenced

Premake assumes the Conan packages are already on disk. Run Linux-Setup.sh (or its Windows equivalent) once after each Conan change before regenerating project files.

Extending

New vendor library — drop sources into Hazel/vendor/, add path mapping in Dependencies.lua, link in Hazel/premake5.lua.
New Conan package — add to conanfile.py, then conan install.
New platform — branch on the platform detection block in premake5.lua, drop implementation under Hazel/src/Hazel/Platform/<Platform>/.
New project — add a project "Name" stanza in the root premake5.lua referencing its own premake5.lua beside the source.