Project Contract

TL;DR

Every deployable Aurum project has a literal name, a version, and one exported sdk::Application. The aurum_project CMake declaration is the public build contract that both the CLI and Forge read. Published versions are immutable — increment the version before each push.

Why this matters

Before Aurum, strategy deployment was ad hoc: copy a binary to a server, edit a config file, hope the right version starts. When something went wrong, there was no reliable way to know which code was running.

The project contract solves this by giving every deployable unit a stable, machine-readable identity. The CLI, Forge, and Terminal all read the same NAME and VERSION from the same CMakeLists.txt. There is one source of truth for project identity, and it is checked at compile time, push time, and runtime.

Project layout

signal-watch/
|-- CMakeLists.txt
|-- main.cpp
`-- config.hpp

Create this layout with aurum create <name>. Additional source files and private project directories are allowed; generated build output is not part of the deployed source package.

Tip

Keep your project root clean. aurum push packages the source tree excluding build artifacts. If you have large data files or private credentials in the project directory, they will be included in the package unless you add them to .gitignore or move them outside the project root.

Identity and version

aurum_project is the public build contract:

cmake_minimum_required(VERSION 3.25)

if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
  project(signal-watch VERSION 0.0.1 LANGUAGES CXX)
  find_package(Aurum CONFIG REQUIRED)
endif()

aurum_project(
  NAME signal-watch
  VERSION 0.0.1
)

Both values must be literal strings. CMake variables and generator expressions are not accepted for NAME and VERSION.

Warning

aurum push reads these values and rejects the operation if the version already exists on the target. A published name@version is immutable — you cannot overwrite it. Increment VERSION before each push. This is not a limitation; it is the mechanism that makes every deployment auditable and every version rollback-capable.

Application entry point

Derive from sdk::Application and export exactly one application type:

class SignalWatch final : public aurum::sdk::Application {
public:
  SignalWatch()
    : sdk::Application({.mode = sdk::RuntimeMode::LIVE}) {}
};

AURUM_EXPORT(SignalWatch)

AURUM_EXPORT(Type) supplies main(), initializes logging, constructs the application, and returns its run result. A project exports exactly one application type — if you need multiple strategies, create multiple projects.

Common commands

Command

Result

aurum compile .

Compile without starting the application.

aurum run .

Compile when required and run in the foreground.

aurum install .

Register the version in the local Aurum home.

aurum push . prod

Package source and register the version on remote prod.

Project arguments can be passed after --:

aurum run . -- --config strategy.toml

Common mistakes

Forgetting to increment VERSION before push.

Forge rejects name@version that already exists. The error message tells you the existing version. Increment the version in CMakeLists.txt and push again.

Using CMake variables for NAME or VERSION.

aurum_project(NAME ${PROJECT_NAME} VERSION ${PROJECT_VER}) will not work. Both values must be literal strings so the CLI can read them without running CMake.

Exporting multiple AURUM_EXPORT types in one project.

A project exports exactly one application. If you have multiple strategy variants, create separate projects that share source files through a library.

Including build output in the source package.

aurum push packages the project directory. Build directories, object files, and compiled binaries bloat the package and may cause build failures on the Forge side. Keep build output in a separate directory or in .gitignore.

Next steps