Nexus Build

Nexus Build builds projects described in Nexus Script. It loads the complete declared dependency graph, builds producers before consumers, and passes published source, header, object, and library directories to dependent projects.

A project may compile an application, build a library, generate an input, or publish existing sources without compiling anything.

A Pascal project

The first application guide contains a complete project using NXPC and the installed Tools.Defaults.Pascal settings.

NXPC selects the Nexus compiler. FPC is a separate operation for genuine upstream Free Pascal use, including the initial Nexus bootstrap. An installed Nexus application should use Nexus Pascal.

Commands

nxbuild /action=validate /project=Hello.nxproject /targetos=linux /targetcpu=x86_64
nxbuild /action=plan /project=Hello.nxproject /targetos=linux /targetcpu=x86_64
nxbuild /action=build /project=Hello.nxproject /targetos=linux /targetcpu=x86_64 /buildconfiguration=Release

Use win64 on Windows. The CLI defaults to its native OS/CPU and Debug configuration when those arguments are omitted. Explicit selections make a documented command reproducible.

Action	Work performed
validate	Compile and validate the project/dependency graph; no tools are run
plan	Validate explicit tool locations and display operations; no build outputs are created
build	Execute the dependency-first plan, stopping at failure

A bare tool command is passed unchanged to process launching. Nexus Build does not search PATH itself or append executable suffixes. Explicit paths select specific tools.

Dependencies and publications

Use an explicitly imported project catalog. For example, save Projects.nxscript beside a consumer:

dialect "projects/nxbuild/language/nxbuild.Language.nxscript";
ProjectIndex Projects {
    ProjectReference Shared {
        Id: "Example.Shared";
        Descriptor: "shared/Shared.nxproject";
    }
}

The referenced descriptor declares that same identity and its publications:

dialect "projects/nxbuild/language/nxbuild.Language.nxscript";
Project Shared {
    Id: "Example.Shared";
    Publishes Directories {
        Sources: ["src"];
        Headers: ["include"];
    }
}

The consumer imports the catalog and declares:

module Projects "Projects.nxscript";
// Inside the consumer Project:
Requires: [@Projects.Shared];

Descriptor paths resolve from their declaring catalog. Published paths resolve from their publishing project, not from the consumer. A shared dependency builds once per invocation. Missing dependencies, identity conflicts, and cycles are errors.

Publishing a directory does not compile its contents or choose linker inputs. Keep source files, library names, and package dependencies explicit.

Native dependencies for Pascal applications

C and C++ producers can participate in the same dependency graph as Pascal projects. Build them with the appropriate native operation, publish their object and library directories, and require them from the consuming project. Nexus Build coordinates construction and propagates lookup paths; Pascal declarations and explicit linker inputs define how the application uses the result.

The native integration guide follows the Abbrevia-derived NXArchive codec producers and Nexus Gear's engine/plugin boundary. It explains link-time versus runtime requirements and why native linking does not imply automatic access to arbitrary C++ classes.

C++ applications

Select C/C++ development in Setup. Save hello.cpp:

#include <iostream>
int main() {
    std::cout << "Hello from C++\n";
}

A Windows project:

dialect "projects/nxbuild/language/nxbuild.Language.nxscript";
module Tools "NXBuild.Environment.nxscript";

Project HelloCPP {
    Id: "Example.HelloCPP";
    LLVM Application (Tools.Defaults.CPP) {
        SourceFiles: ["hello.cpp"];
        OutputPath: "build";
        RawOptions: ["-o", "hello.exe"];
    }
}

On Linux, change the explicit output filename to hello and select TargetOS:linux. Tools.Defaults.CPP selects Clang's C++ driver and configured native headers/libraries.

Operations and configuration

Operation	Purpose
NXPC / FPC	Nexus / upstream Pascal compilation
LLVM	Clang C/C++ compilation and linking
CMake	Configure or build a CMake project
MSBuild	Build an explicit solution/project
MSVC	Invoke the configured Microsoft native compiler
Process	Run an explicitly declared executable and argument array

Operations run sequentially after dependencies. Source masks expand when an operation executes, so earlier producers can create the inputs.

RootDirectory normally defaults to the descriptor directory. /root-directory=<path> explicitly overrides the entry project's root; dependencies keep their own roots. Output locations are recipe properties and expressions, not inferred project names.

Additional target selections use /targets=Name:Value,Other:Value. The standard and additional selections reach dependencies unchanged. They select definitions; compiler switches still belong to those definitions.

See Tool environment, Nexus Script, and the detailed Nexus Build reference.