Build Systems

Table of Contents

Describes how to generate build systems for Cinema 4D API projects.

Warning
Never modify the frameworks of the SDK and always use the CMake build systems shipped with the SDK. Ignoring any of these rules may create plugins that are binary incompatible with Cinema 4D. We will refuse development support for any plugins that do not comply with these requirements.

Overview

A build system (also - build tool) is a system that allows users to define a set of build configurations required for building a software project from its source code and resources. Build systems can be invoked with a build configuration to run a build pipeline using compilers and similar tools to generate and compile output such as executables, libraries, debug information, and other meta-information for a project. Very tangible examples of build systems are apps such as Visual Studio and Xcode, which define build configurations in their project files which can then be built running these IDEs. But also more technical command-line tools such as Make, Ninja, or MSBuild are build systems. To build software for multiple operating systems one often requires multiple build systems.

The idea of build systems is complemented by build system generators (also - meta-build system). A build system generator generates configurations for a build system derived from its own configuration syntax. This is done to further simplify defining a build system by letting the build system generator handle common configuration options, and to bundle multiple build systems under one set of unified configuration files.

The Cinema 4D C++ SDK uses CMake as a build system generator and supports build systems for Windows (Visual Studio + Clang/MSVC), macOS (Xcode + Clang), and Linux (Ninja + GCC). The plugins/example.build module is a concrete SDK 2027 build example demonstrating native module configuration, platform-specific sources, and linking against additional libraries. The project structure shown below demonstrates common parts of a Cinema 4D C++ SDK project, especially in the context of build systems.

+ my_project // A Cinema 4D C++ project root.
├── + _build_v143 // An MSVC build system, a project can have multiple build systems.
│ ├── + bin // The binary output of a build system.
│ │ ├── + libs // The compiled libs for the MSVC build system.
│ │ └── + plugins // The compiled plugins for the MSVC build system.
│ │ └── my_module // The compiled output for 'my_module'.
│ │ ├── + res // A symlink to the resource folder of the module.
│ │ ├── my_module.xdl64 // The compiled plugin binary for the module.
│ │ └── my_module.pdb // The debug symbols for the module.
│ ├── + generated // The auto-generated source code for each module and framework.
│ ├── c4d-sdk.sln // The solution file for the project for Visual Studio.
│ └─┄ // A build system has more content; which is here ignored.
├── + cmake // The CMake scripts for a Cinema 4D plugin project.
├── + frameworks // The Cinema 4D API used by the project.
├── + plugins // The modules directory of the project, all your work goes here.
│ ├── + my_module // A module folder, a project must have at least one module.
│ │ ├── + project // The build system configuration for the module.
│ │ │ └── CMakeLists.txt // The native build configuration for the module.
│ │ ├── + res // The resources for the module.
│ │ │ ├── + description // The description (a form of UI definition) files for the module.
│ │ │ ├── + dialogs // The dialog (a form of UI definition) files for the module.
│ │ │ ├── + strings_en_US // The English language strings for the module.
│ │ │ └── c4d_symbols.h // The primary symbol file for the module.
│ │ └── + source // The source code for the module.
│ │ ├── + foo // A custom subfolder for a 'foo' plugin.
│ │ │ ├── foo_plugin.h
│ │ │ └── foo_plugin.cpp
│ │ ├── + bar // A custom subfolder for a 'bar' plugin.
│ │ │ ├── bar_plugin.h
│ │ │ └── bar_plugin.cpp
│ │ ├── main.cpp // The entry point for the module that registers the two plugins.
│ │ └── main.h
│ └─┄ // A project can contain many modules.
├── + tools // SDK build tools; do not modify.
│ └── + sourceprocessor // The source processor executed during builds.
├── CMakeLists.txt // The primary CMake script for generating the project.
└── CMakePresets.json // The preset values for CMake when using the CMake GUI.
Fig. I: The structure of a Cinema 4D C++ SDK project will generally follow the form shown here.

Central Concepts

A Cinema 4D C++ project is structured into distinct components called modules which by default are located in a folder named plugins in a project. Each module will compile into a dedicated binary which is meant to be loaded by a Cinema 4D instance on startup. Each module binary has an identifier and can either succeed or fail to register with Cinema 4D on startup. And while a module binary file such as my_module.xdl64 is usually referred to as 'a plugin' by users, it can actually contain the implementation and registration of zero-to-many plugin hooks. This means a module loaded by Cinema 4D could manifest as many plugins such as commands, objects, or tags; or alternatively only contain module code and do not register any plugin hooks. The latter case is very rare. The source code of a module is usually only found in its main.cpp/.h file, while plugin code is conventionally given dedicated source code files as shown in Fig. I.

Besides its source code, a module can also contain resources in a folder called res - resources include things such as UI definitions and string translations. But not all modules have such a folder, as not all plugins require resources. A module also always contains a project folder with a native CMakeLists.txt. It defines the frameworks accessible to the module, its identifier, source directories, compiler and linker settings, and source-processor style settings.

Warning
SDK 2027 and later use native CMakeLists.txt files for module configuration. The legacy projectdefinition.txt format is supported only as migration input. See Configuring Build Systems for the supported configuration contract.

A project will also always contain a frameworks folder which holds the Cinema 4D API against which the plugins in the project will link. This folder must never be modified, as plugins otherwise might become binary incompatible with Cinema 4D. The framework content is documented in the documentation you are reading right now. Once you have generated a build system for your project, you will also find a build system folder in it, as for example _build_v143 in Fig. I. It contains all the files generated for that build system, such as IDE files like a Visual Studio solution file, the compiled binaries and debug information, and the auto-generated and copied source code.

Note
Contrary to the legacy Project Tool system, build system output such as project files, binaries, debug databases, and auto-generated code will not be placed in module folders anymore. This makes it much easier to manually clean up a project. Simply delete a build system to delete all generated output for a specific build system.

Important Paths

The following table highlights important paths in a Cinema 4D project and notes their purpose.

Purpose Example Path Description
Project Root /my_project Contains all files of a project. The project name must be composed of characters from the alphabet, digits, and the underscore and point characters, but otherwise can be chosen freely.
Warning
Ignoring the naming limitations might result in malfunctioning projects. E.g., myProject#123 will not generate, as the hashtag is not a supported project character.
Note
See Source Files and Platform Selection for how to configure source files and platform selection.
Build System /my_project/_build_v143 Contains a build system. Build systems are not present by default in a project and must first be generated with CMake. A project can have multiple build systems.
Binary Output /my_project/_build_v143/bin Contains the compiled plugins for a build system. Only present once a project has been compiled at least once.
CMake Scripts /my_project/cmake Contains the scripts and settings such as compiler/linker options and warning/error settings which make up the Cinema 4D C++ SDK project generation logic.
Warning
Never modify the content of this folder. Modifications might result in binary incompatible plugins. Any problems arising from ignoring this restriction are out of scope of support.
SDK Frameworks /my_project/frameworks Contains the API declarations of the Cinema 4D API against which modules of this project will link.
Warning
Never modify the content of this folder. Modifications might result in binary incompatible plugins. Any problems arising from ignoring this restriction are out of scope of support.
SDK Tools /my_project/tools Contains SDK-owned build tools, including the source processor in tools/sourceprocessor. CMake adds the source processor to module and framework build targets, and it executes during builds. These tools must not be modified.
Module Folder /my_project/plugins/my_module A module folder contains the source code, resources, and module definition of a module. It will compile into a dedicated module binary with the name of the module, e.g., my_module.xdl64 for a build system for Windows. This module binary is then loaded and registered by Cinema 4D on startup. A module can contain zero-to-many plugins.
Module Project Folder /my_project/plugins/my_module/project Contains the required native CMakeLists.txt build definition. The SDK can convert a legacy projectdefinition.txt when MAXON_MIGRATE_LEGACY_PROJECTS is enabled during CMake configuration.
Module Source Code /my_project/plugins/my_module/source Contains the source code and other files that are automatically included for this module.
Module Resources /my_project/plugins/my_module/res Optionally contains the resources for a module. Resources usually contain GUI definitions, interface strings, symbol tables, and icon files. Not all plugin types use or need resources.
Fig. II: Important locations in a Cinema 4D C++ SDK project. The example paths align with the example shown in Fig. I.

Further Reading

While generating a build system from a build system configuration is the second step in the process of configuring and generating a build system, we recommend reading the generation guide first, as it will allow you to build the SDK. When you are already familiar with the generation process, you can directly proceed with the configuration guide.