Skip to content

Build Nexus from source

End users should install a prebuilt release. Use this guide to build the compiler, tools, engine and release installers from source.

Checkout and tools

Keep nexus, nexus-fpc, nexus-mobile, and nexus-lab as sibling repositories under a source directory. The package repositories live under nexus/packages/. Keep generated products in a separate worktree.

Configure the installed NXBuild.Environment.nxscript for local compilers, LLVM, and native SDKs. The source-only projects/nxbuild/Nexus.Environment.nxscript supplies Development.OutputRoot and NXPCSource. Review those paths for your checkout.

Full source builds require more than the end-user runtime: installed Nexus tools, matching compiler/RTL, package sources, platform SDK/native build tools, Node/npm, and engine prerequisites. The top-level build does not provision them.

Native product build

From the Nexus repository root:

nxforge /input=Nexus.Forge.nxscript /targets=TargetOS:win64,TargetCPU:x86_64,BuildConfiguration:Release

On Linux, select TargetOS:linux. Build Linux releases against Ubuntu 24.04 libraries so they can also run on newer supported Ubuntu versions.

The recipe composes the engine build, applications, complete Nexus Pascal compiler product, extension packaging, and staging. The running Nexus Forge remains in use for the entire invocation. If new recipe operations require a newer Nexus Forge, build Nexus Forge separately first.

Windows engine construction retains MSBuild and its native dependencies. Linux uses the engine's Nexus Build project. The shared task name is BuildSolarEngine; target filters select its implementation.

Release outputs are staged under <Development.OutputRoot>/system/<cpu>-<os>/Release/host. The Debug recipe also publishes the completed stage to the local current toolchain; use an isolated checkout/output configuration for validation.

Compiler bootstrap

From nexus-fpc, on Windows:

nxforge /input=NXPC.Forge.nxscript /targets=HostOS:win64,TargetOS:win64,TargetCPU:x86_64,BuildConfiguration:Release,BuildRoot:C:/dev/worktree/nxpc-release

The Windows seed is stock FPC 3.2.2 i386-win32, with its matching RTL. Its hardware Extended support is required for the initial transition to Nexus Pascal Win64. Stock FPC 3.2.2 Win64 is not an interchangeable seed.

On Linux, supply the actual seed/compiler pair and an external output directory:

nxforge /input=NXPC.Forge.nxscript "/targets=HostOS:linux,TargetOS:linux,TargetCPU:x86_64,BuildConfiguration:Release,BuildRoot:/path/to/worktree/nxpc-release,SeedCompiler:/usr/bin/ppcx64,SeedRTL:/usr/lib/x86_64-linux-gnu/fpc/3.2.2/units/x86_64-linux/rtl"

The sequence is:

  1. Stage source and identity; build seed generators and the initial compiler with FPC.
  2. Establish the native Nexus Pascal compiler/RTL, including the Windows Win32-to-Win64 transition.
  3. Build three compiler/RTL generations and verify convergence.
  4. Build host compiler backends, all destination RTLs, delivered compilers, and utilities.
  5. Build the delivered platform's package SDK, assemble the distribution, and run applicable checks.

Subsequent Pascal compilation uses Nexus Pascal. Projects/groups organize this work; there is no separate Stage:cycle1 command-line workflow.

HostOS describes the construction machine. TargetOS/TargetCPU describe where the delivered compiler tools run. Every invocation includes all supported compiler backends and RTL destinations.

The completed distribution is <BuildRoot>/distribution, with compiler bins, thirteen RTLs, the package SDK, configuration, and build identity. Installation/promotion is separate through NXPC.Install.nxscript.

Cross-host Linux construction from Windows requires an explicitly provisioned Linux sysroot. The recipe does not acquire it.

Create an installer

After a successful native Release build, from the Nexus root:

nxforge /input=Nexus.Setup.Forge.nxscript /targets=TargetOS:win64,TargetCPU:x86_64,BuildConfiguration:Release,Version:2026.10.0

Use the release's actual version and TargetOS:linux for Ubuntu. Packaging consumes the completed host stage and fails if required files are missing. It does not rebuild the tools.

Installers are written under <Development.OutputRoot>/system/installers/ as a Windows executable or Ubuntu Debian package.

Publishing documentation is separate: see Documentation workflow.

Engine build prerequisites

For native Linux engine construction, install the development packages used by its graphics, input, audio, font, image and network APIs:

sudo apt-get install --no-install-recommends \
    libsdl2-dev libgl-dev libopenal-dev libfreetype-dev libpng-dev \
    libjpeg-dev libcurl4-openssl-dev libssl-dev zlib1g-dev

Windows engine construction uses Visual Studio 2022 Build Tools, the v142 C++ toolset with ATL/MFC, Windows SDK 10.0.19041.0, CMake, Ninja, OpenSSL development files, Git and Python. Configure actual locations in the Nexus Build environment and nexus-mobile/Nexus2D.BuildTools.nxscript before invoking Nexus Forge.

For Android, use the engine's Gradle wrapper under platform/android and the Android development components. Apple engine builds require native Xcode/Apple SDKs; they are outside the validated Windows/Linux release workflow. A desktop simulator build does not update device application templates.