console_setup

Console Setup

This page covers build configuration for console targets: Nintendo Switch, PlayStation 4 (ORBIS), and PlayStation 5 (Prospero).

All console builds follow the same pattern:

1. Install the platform SDK and set the required environment variable.
2. Create CMakeUserPresets.json from the provided template and fill in your SDK paths.
3. Configure and build using the platform preset.

Important

Console SDK paths are never stored in the repository. CMakeUserPresets.json is gitignored by default and must be created locally on each machine.

---

Requirements

Requirement	Switch	PS4	PS5
OS	Windows	Windows	Windows
IDE	Visual Studio 2022	Visual Studio 2022	Visual Studio 2022
CMake	3.25+	3.25+	3.25+
SDK env var	NINTENDO_SDK_ROOT	SCE_ORBIS_SDK_DIR	SCE_PROSPERO_SDK_DIR
CMakeUserPresets.json	Required	Required	Required

---

CMakeUserPresets.json

All console SDK paths live in CMakeUserPresets.json, which is gitignored. A template is provided at templates/CMakeUserPresets.json.template.

cp templates/CMakeUserPresets.json.template CMakeUserPresets.json

Edit the copy for your local SDK installation. The sections for each platform are described below.

---

Nintendo Switch

SDK environment variable

Set NINTENDO_SDK_ROOT to the root of your Nintendo SDK installation.

NINTENDO_SDK_ROOT=D:\Nintendo\NintendoSDK

Setting this as a system environment variable (Control Panel → System → Environment Variables) ensures it is picked up by both the command line and Visual Studio.

CMakeUserPresets.json - switch-paths

{
  "name": "switch-paths",
  "hidden": true,
  "cacheVariables": {
    "CMAKE_C_COMPILER": {
      "type": "FILEPATH",
      "value": "$env{NINTENDO_SDK_ROOT}/path/to/clang-cl.exe"
    },
    "CMAKE_CXX_COMPILER": {
      "type": "FILEPATH",
      "value": "$env{NINTENDO_SDK_ROOT}/path/to/bin/clang-cl.exe"
    },
    "NINTENDO_SDK_PROPS_PATH": "relative/path/to/ImportNintendoSdk.props"
  }
}

NINTENDO_SDK_PROPS_PATH is a path relative to NINTENDO_SDK_ROOT that points to the Nintendo SDK MSBuild props file. The value above is correct for most SDK versions; adjust if your installation differs.

Configure and build

cmake --preset switch-debug
cmake --build --preset switch-debug

cmake --preset switch-release
cmake --build --preset switch-release

Output

The post-build step copies the following to the extension output folder:

File	Description
<ProjectName>.nro	Nintendo Relocatable Object
<ProjectName>.nrr	Nintendo Relocatable Resource
<ProjectName>.nrs	Debug symbols

Platform define

Use OS_SWITCH to guard Switch-specific code:

#ifdef OS_SWITCH
    // Switch implementation
#endif

---

PlayStation 4 (ORBIS)

SDK environment variable

The SCE ORBIS SDK installer sets SCE_ORBIS_SDK_DIR automatically. Verify it is set before configuring:

SCE_ORBIS_SDK_DIR=C:\Program Files (x86)\SCE\ORBIS SDKs\<version>

CMakeUserPresets.json - ps4-paths

{
  "name": "ps4-paths",
  "hidden": true,
  "cacheVariables": {
    "CMAKE_C_COMPILER": {
      "type": "FILEPATH",
      "value": "$env{SCE_ORBIS_SDK_DIR}/path/to/orbis-clang.exe"
    },
    "CMAKE_CXX_COMPILER": {
      "type": "FILEPATH",
      "value": "$env{SCE_ORBIS_SDK_DIR}/path/to/orbis-clang++.exe"
    },
    "CMAKE_LINKER": {
      "type": "FILEPATH",
      "value": "$env{SCE_ORBIS_SDK_DIR}/path/to/bin/orbis-ld.exe"
    }
  }
}

All three paths are required. CMake cannot auto-detect the ORBIS compiler because ORBIS executables cannot run on Windows during configure.

Configure and build

cmake --preset ps4-debug
cmake --build --preset ps4-debug

cmake --preset ps4-release
cmake --build --preset ps4-release

Output

File	Description
<ProjectName>_ps4.prx	ORBIS shared library, copied to extension folder

Platform define

#ifdef OS_PS4
    // PS4 implementation
#endif

C++ exceptions

The ORBIS toolset disables C++ exceptions by default. throw statements in the generated bridge code (GMExtWire.h) are handled via the GMWIRE_THROW macro, which calls std::abort() with a log message on platforms where exceptions are off. This applies to both Debug and Release builds - unlike assert(), it is not stripped in Release.

If your own extension code uses exceptions, wrap it in a try/catch at the boundary, or avoid exceptions entirely for the PS4 target.

---

PlayStation 5 (Prospero)

SDK environment variable

The SCE Prospero SDK installer sets SCE_PROSPERO_SDK_DIR automatically. Verify it is set before configuring:

SCE_PROSPERO_SDK_DIR=C:\Program Files (x86)\SCE\Prospero SDKs\<version>

CMakeUserPresets.json - ps5-paths

{
  "name": "ps5-paths",
  "hidden": true,
  "cacheVariables": {
    "CMAKE_C_COMPILER": {
      "type": "FILEPATH",
      "value": "$env{SCE_PROSPERO_SDK_DIR}/path/to/prospero-clang.exe"
    },
    "CMAKE_CXX_COMPILER": {
      "type": "FILEPATH",
      "value": "$env{SCE_PROSPERO_SDK_DIR}/path/to/prospero-clang.exe"
    },
    "CMAKE_LINKER": {
      "type": "FILEPATH",
      "value": "$env{SCE_PROSPERO_SDK_DIR}/path/to/prospero-lld.exe"
    }
  }
}

Note

CMAKE_C_COMPILER and CMAKE_CXX_COMPILER both point to prospero-clang.exe. Unlike ORBIS, the Prospero SDK does not ship a separate prospero-clang++.exe; the same binary handles both C and C++ with the appropriate flags injected by the toolset.

Configure and build

cmake --preset ps5-debug
cmake --build --preset ps5-debug

cmake --preset ps5-release
cmake --build --preset ps5-release

Output

File	Description
<ProjectName>_ps5.prx	Prospero shared library, copied to extension folder

Platform define

#ifdef OS_PS5
    // PS5 implementation
#endif

C++ standard

The Prospero SDK 13+ standard library requires C++20. The CMake project sets CXX_STANDARD 20 on the PS5 target automatically. The project-wide default (C++17) is not affected; only the Prospero build uses C++20.

C++ exceptions

The Prospero toolset disables C++ exceptions by default. The same GMWIRE_THROW macro described for PS4 applies here.

---

How the build system works

The CMake project uses the Visual Studio generator with the platform architecture (NX64, ORBIS, Prospero) set via CMakePresets.json. This is what causes Visual Studio to load the correct platform toolset - the SCE and Nintendo MSBuild props that configure compilers, linkers, and system libraries are injected automatically at build time.

The console preset structure splits across two files:

File	Contents	Committed
CMakePresets.json	Base architecture presets (base-vs-ps4, base-vs-ps5, base-vs-switch)	Yes
CMakeUserPresets.json	SDK paths and final configure + build presets	No (gitignored)

This means the repository contains no SDK-specific paths. Each developer provides their own CMakeUserPresets.json.

---

Troubleshooting

No CMAKE_CXX_COMPILER could be found

The compiler paths in ps4-paths / ps5-paths / switch-paths are missing or incorrect. Verify CMakeUserPresets.json exists and that the environment variable (SCE_ORBIS_SDK_DIR, etc.) resolves to a valid SDK installation.

ConfigurationType shows Utility in the generated .vcxproj

Delete the build folder and reconfigure. Stale CMake cache files from a previous configure can persist incorrect project properties.

cannot use 'throw' with exceptions disabled

This error in user code (not GMExtWire.h) means your extension is using C++ exceptions on a platform that disables them. Replace throw with GMWIRE_THROW, or restructure error handling to use return codes for those paths.

PS5: compiler mode older than C++20

The PS5 target requires C++20 and the project sets this automatically. If you see this error, the build folder has a stale cache. Delete it and reconfigure.