Project Tool

Table of Contents

About

The Project Tool creates project files for Microsoft Visual Studio or Apple Xcode. The tool automatically detects new files and resources and correctly handles - depending on the platform - all the required dependencies. It creates project files for solutions, frameworks and plugins.

The Project Tool can be obtained from developers.maxon.net.

Note
The Project Tool can only be used to create project files for the corresponding Cinema 4D version.
For general information on how to create new plugins, frameworks and solutions see Getting Started: First Steps.
Warning
Changing the generated project files (editing compiler or linker settings etc.) may result in compile errors or incompatible plugins.

Running the Project Tool

The Project Tool application is configured using a command line argument:

  • g_updateproject: Defines the folder the tool should work on. Currently the tool only accepts absolute paths. This is typically the location of the SDK including frameworks and plugins. See Getting Started: First Steps.
// This example shows how to run the Project Tool using command line arguments.
// Windows
kernel_app_64bit.exe g_updateproject=C:\development\sdk
// MacOS
kernel_app.app/Contents/MacOS/kernel_app g_updateproject=/Volumes/development/sdk
C
C
Quality C.
Definition: macros.h:3
Note
The output window of the Project Tool can be hidden using the command line argument g_disableConsoleOutput=true.
Warning
On MacOS Catalina, the Project Tool needs a few further steps - they might require an elevated prompt - to run due to the security measures introduced by Apple Notarization.
  1. Remove the quaratine xattr
    $ xattr -d "com.apple.quarantine" <ProjectTool ZIP file>.zip
    ZIP
    ZIP
    Definition: network_smtpmail.h:21
    file
    const char const char const char * file
    Definition: object.h:439
  2. Set the executable permission
    $ chmod 744 <ProjectTool Path>/kernel_app.app/Contents/MacOS/kernel_app

projectdefinition.txt

A projectdefinition.txt file defines the basic settings of a solution, framework or plugin. The Project Tool creates project files based on theses settings.

General formatting rules for projectdefinition.txt files are:

  • No spaces around "=" symbols are allowed.
  • A line break must be indicated using a backslash "\\".
  • Comments start with "//".
  • Multiple arguments for a parameter must be separated with a semicolon ";".

Additional, the file also defines how the Source Processor analyses the code. See Stylecheck.

General Settings

These settings are relevant for all framework and plugin projects:

  • Platform: The supported platforms. Can be Win64, OSX or Linux.
  • Type: The type of the project. Can be Lib, DLL or Solution.
  • APIS: The frameworks that should be included.
  • C4D: Defines if the project is a classic API Cinema 4D component. It enables some additional classic API support and disables automatic style checks. Can be either true or false.
  • ModuleId: Defines the framework or module/plugin ID. Must be a unique identifier in inverse domain notation, following the pattern xyz.mycompany.product. Ideally you should own the domain xyz.mycompany.`
Note
The ID of a framework must include the ".framework" suffix; the ID of a module must NOT include ".module".
Warning
You cannot use module identifiers in the domain net.maxon. as they are reserved for MAXON Computer GmbH. Plugins using such identifiers will not be loaded by Cinema 4D.

A typical example looks like this:

// Configuration of a custom plugin in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a plugin
Type=DLL
// this plugin depends on these frameworks:
APIS=\
cinema.framework; \
misc.framework; \
image.framework; \
core.framework
// defines the level of rigour of the source processor's style check
stylecheck.level=3
// plugin/module ID
ModuleId=com.examplecompany.myplugin
OSX
OSX
OS X.
Definition: ge_prepass.h:1

A projectdefinition.txt file that support code in a custom style can look like this:

// The platforms this project is targeting - can be [Win64;OSX;Linux].
Platform=Win64;OSX;Linux
// Type of project - can be [Lib;DLL;Solution].
Type=DLL
// The frameworks dependencies of this project as shipped in the frameworks folder of an SDK. You
// can only include header files from frameworks that are listed here. This plugin uses only the
// classic API frameworks cinema.framework and cinema_hybrid.framework and the maxon API framework
// core.framework. This means for example that you could not use the nodes or asset API. But for
// getting started these three frameworks are enough.
APIS=\
cinema.framework;\
cinema_hybrid.framework;\
core.framework
// If this is a classic API plugin, enabling some classic API features and disabling automatic style
// checks.
C4D=true
// Sets the rigidity of the style check. The minimum is 0 (checks disabled), the maximum is 3 (very
// strict).
stylecheck.level=3
// The ID of the module/plugin which is being compiled. You should use here the "net.mycompany.xyz"
// format. You cannot use a module ID of the format "net.maxon.xyz" as this domain is reserved
// for Maxon and plugins ignoring this will not be loaded.
ModuleId=net.maxonexample.myplugin
C4D
C4D
Definition: lib_net.h:1
Warning
You cannot use module identifiers in the domain net.maxon. as they are reserved for MAXON Computer GmbH. Plugins using such identifiers will not be loaded by Cinema 4D.

Further generic project settings are:

  • AdditionalPreprocessorDefinitions: Preprocessor definitions.
  • ExceptionHandling: Enables or disables exception handling for the project.
  • RuntimeTypeInfo: Enables runtime type information for the project.
  • encoding: Set to a specific encoding to hande sorce code files using that encoding e.g. encoding=utf-8 for Unicode. See this list of encodings.

Stylecheck

The "stylecheck" setting defines how rigid the source processor checks the source code (see Source Processor):

  • stylecheck.level: The code check level. The minimum is 0 (check disabled), the maximum is 3 (very strict).
  • stylecheck=false: Disables the style check completely.
  • stylecheck.aswarnings: Turns style errors into warnings.
  • stylecheck.domains: Can be used to set a list of accepted custom domains for any kind of custom ID.

Checks enabled in level 1 are:

  • stylecheck.whitespace: Set to true or false to check for missing whitespaces in "if(condition)".
  • stylecheck.indentation: Set to true or false to check for correct indentation.
  • stylecheck.todo: Set to true or false to check for style of TODO comments.
  • stylecheck.case-break: Set to true or false to check that a switch case has a break statement at its end (or MAXON_SWITCH_FALLTHROUGH).
  • stylecheck.virtual: Set to true or false to check for virtual functions in frameworks.
  • stylecheck.static-within-type: Set to true or false to check for declarations like const static Int x = 0; which should be written as static const Int x = 0;.
  • stylecheck.supercall: Set to true or false to check if the super call is present in comparison functions of components.

Additional checks enabled in level 2 are:

  • stylecheck.no-whitespace: Set to true or false to check for forbidden whitespace as in "if ( condition )".
  • stylecheck.consistent-blocks: Set to true or false to check that either both or none of if/else use a {}-block, same for switch.
  • stylecheck.newline-for-substatement: Set to true or false to check that the substatement of if or a loop is within a new line.
  • stylecheck.explicit: Set to true or false to check that constructors which can be used as conversion constructors are marked by either explicit or MAXON_IMPLICIT.

Additional checks enabled in level 3 are:

  • stylecheck.typedef-struct: Set to true or false to check for C-style struct declarations as in typedef struct { ... } S;.
  • stylecheck.enum-class: Set to true or false to check that scoped enums are used (enum class instead of just enum).
  • stylecheck.enum-registration: Set to true or false to check that enums are ended with one of the enum macros (MAXON_ENUM_LIST etc.).
  • stylecheck.class-for-templateparam: Set to true or false to check that a template type parameter is introduced by typename (template <typename T> instead of template <class T>).
  • stylecheck.void-paramlist: Set to true or false to check for C-style function declarations with empty parameter list as in void Func(void);.
  • stylecheck.max-linecount=number: Sets the maximum line count a function may have. Default value is 500.
  • stylecheck.naming: Set to true or false to check for correct naming of global variables.
Note
By default all checks are enabled. The style check level is used to disable certain checks.
The settings are processed from top to bottom. A later setting can overwrite a previous one.

With 2024, custom qualifier support has been added to avoid source processor parsing errors. Use it to register custom variable or function qualifiers you want to use in the code of the project. The syntax is stylecheck.register-qualifiers = A [; B; C; ...] where A, B, and C are then new custom qualifiers you have registered. See Support for Custom Qualifiers for details.

// set the style check level to 2
// this will disable all settings enabled with level 3
stylecheck.level=2
// set line length settings manually
stylecheck.max-linecount=300

Certain checks can be disabled in code using these macros:

Includes

The Project Tool automatically includes source code files found in the project folder.

  • Include: Includes the given file or files in the project.
  • Exclude: Excludes the given file or files from the project.
  • ExcludeFromBuild: Excludes the file or files from the build process, but not from the project file.
  • StrictIncludeDirectories: If set to true, the locations of included files are not added to the include directories.
Warning
The Source Processor will only handle source code files stored in the "source" folder. It is advised to store all source code files in a "source" folder.
Exclude and ExcludeFromBuild do not use file paths. They define filters that are used to remove files that contain the given filter in the file path.
// the following files should be added to the Visual Studio project
Include.Win=../../files/someclass.h;\
../../files/someclass.cpp;
// the following files should be added to the Xcode project
Include.OSX=../../files/someclass.h;\
../../files/someclass.cpp;
// exclude OS specific code
Exclude.Win=/source/mac/
Exclude.OSX=/source/win/
source
const Py_UNICODE * source
Definition: unicodeobject.h:54

It also possible to exclude files from being checked by the Source Processor using the a specific syntax.

// This example excludes all files which have /fist_6_4/src/ in their path.
DontUncrustify="/fist_6_4/src/";

Visual Studio Specific

Specific settings for Visual Studio projects. The settings can be specified for different build targets e.g. "Win64", "Debug" etc.

  • AdditionalLibraryDirectories: Search paths for libraries.
  • AdditionalDependencies: Library dependencies.
  • AdditionalIncludeDirectories: Include directories.
  • AdditionalCompileOptions: Compile options.
  • AdditionalLinkOptions: Linker options
  • DisableSpecificWarnings: Disables the warnings with the given numbers.
  • AdditionalSolutionFiles: Adds the given files to a solution. See Solutions.
// additional lib folder for all targets not defined otherwise
AdditionalLibraryDirectories=...
// explicit lib foder for all debug versions
AdditionalLibraryDirectories.Debug=...
// explicit lib folder for 64bit release version
AdditionalLibraryDirectories.Win64.Release=...
AdditionalDependencies=...
AdditionalDependencies.Debug=...
AdditionalDependencies.Win64.Release=...
AdditionalDependencies.Win64.Debug=...
AdditionalIncludeDirectories=...
AdditionalIncludeDirectories.Debug=...
AdditionalIncludeDirectories.Win64=...
// the typical way to include a lib
AdditionalLibraryDirectories.Win64.Debug=../../mylib/bin/
AdditionalDependencies=mylib_debug_64.lib
AdditionalIncludeDirectories=../../mylib/include
DisableSpecificWarnings=...
DisableSpecificWarnings.Win64=...
Note
If you want to include inherit include paths you have to add "AdditionalIncludeDirectories".
AdditionalIncludeDirectories=../../mylib/include;\
%(AdditionalIncludeDirectories)

Xcode Specific

Specific settings for Xcode projects. The settings can be specified for different targets e.g. "64" and "Release".

  • OTHER_LDFLAGS: Search paths for library dependencies.
  • FRAMEWORK_SEARCH_PATHS: Search paths for frameworks.
  • HEADER_SEARCH_PATHS: Search paths for frameworks includes like include <...>
  • USER_HEADER_SEARCH_PATHS: Search paths for project includes like include "..."
  • Frameworks.OSX: Adds frameworks like CoreFoundation.framework.
// additional paths for all targets not defined otherwise
OTHER_LDFLAGS=...
// explicit paths for all debug versions
OTHER_LDFLAGS.Debug=...
// explicit paths for 64bit release version
OTHER_LDFLAGS.64.Release=...
FRAMEWORK_SEARCH_PATHS=...
HEADER_SEARCH_PATHS=...
USER_HEADER_SEARCH_PATHS=...
Frameworks.OSX=System/Library/Frameworks/CoreFoundation.framework;

Plugins

A simple plugin's projectdefinition.txt can look like this:

// Configuration of a custom plugin in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a plugin
Type=DLL
// this plugin depends on these frameworks:
APIS=\
cinema.framework; \
misc.framework; \
image.framework; \
core.framework
// defines the level of rigour of the source processor's style check
stylecheck.level=3
// plugin/module ID
ModuleId=com.examplecompany.myplugin

Frameworks

A frameworks's projectdefinition.txt can look like this:

// Configuration of a custom framework in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a framework
Type=Lib
// this framework depends on the listed frameworks:
APIS=core.framework
// framework ID
ModuleId=com.examplecompany.myplugin.framework

Solutions

A solution's projectdefinition.txt can look like this:

// Configuration of a custom solution in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a solution
Type=Solution
// included plugin projects
Solution=\
plugins/pluginA;\
plugins/pluginB
// include natvis files in Visual Studio solution file
AdditionalSolutionFiles=\
..\..\frameworks\core.framework\project\typeviewer\msvc\maxon.natvis;\
..\..\frameworks\cinema.framework\project\typeviewer\msvc\c4dapi.natvis

Further Reading