Build Systems

Table of Contents

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

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 example 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 // A CMake build system configuration for the module.
│ │ │ └── projectdefinition.txt // A projectdefinition build configuration file 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.
├── CMakeLists.txt // The primary CMake script for generating the project.
├── CMakePresets.json // The preset values for CMake when using the CMake GUI.
└── sdk_modules.txt // An optional module paths file for the project.
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 which holds the build system settings of that module. These settings contain instructions for CMake on how the build system for this module should be set up. Common settings are frameworks that should be accessible in the module, module identifiers, custom linker and compiler settings, and style settings. These settings can be provided in two manners, as projectdefinition.txt files - the module definition format of the former Cinema 4D SDK build system generator - and native CMakeLists.txt files.

Warning
The recommended way to define a module is using project definition files. Only experts should use native CMake files. See Pure CMake Workflow for details on how to use such native setups.

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 (that are automatically ingested). 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 In- and Exclude Settings for how to include files from outside of the project root and how to exclude files inside the project root.
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.
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 build system definition for the module. This can either be provided as a projectdefinition.txt or CMakeLists.txt file, where the former is the recommended form. When both files are present, as shown in the example above, the CMake config will take precedence.
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.