Customisable Cinema 4D Plugin Installer

Easily create an installer for your Cinema 4D plugin for Windows and Mac OS.
Replace the banner and icon, update some configuration, build & done.

Check out the Milestones page for what’s still to do.

Features

Very customisable
Automatically finds available Cinema 4D installations on the system
Supports installing dependencies from redistributable installers
Optional Uninstaller

Requirements

CPython 3.3 or 3.4 (3.5 not supported by PyInstaller)
PyInstaller 3.3*
PyQt5**
GNU Make***

* At the time of this writing (2016-12-06), PyInstaller 3.3 is not released
and must be installed from the development branch using
pip install git+https://github.com/pyinstaller/pyinstaller

** On Windows, it is highly recommended to use an official PyQt5 installer
from Riverbank Software rather than
installing it with Pip as it can lead to issues with finding all dependencies
when building the installer. The official installers can be found on
SourceForge.

Also note that the installer is known to put the development tools into
the wrong directory. If pyuic5 can not be found, copy it from
YourPythonInstall/Libs/site-packages/PyQt5/pyuic5.bat to the
YourPythonInstall/Scripts folder.

*** Windows builds of GNU Make can be found here.
The Makefile is known to work with GNU Make 3.8.1

Configuration & Customisation

The main configuration file is data/config.json. There
you need to specify the following information:

Basic installer info, like the generated executable/bundle name and the
OSX bundle identifier.
Features that will be displayed in the “Features” page of the installer.
Note that if no features are configured, the page will not be displayed.
The files that need to be copied for each feature and where they need to
be copied to.

Text

The strings that are displayed in the dialog are defined in
data/strings/en.json. In every string you can use variables in the format
$varname or ${varname}. These variables are defined in the "__vars__"
section of the same string file.

Colors

In data/config.json you can find a "palette" field which describes the
colors of window components as RGB values.

  "palette": {
    "background": [40, 40, 40],
    "foreground": [200, 200, 200],
    "alternate_background": [70, 70, 70],
    "button_background": [50, 50, 50],
    "button_foreground": [220, 220, 220],
    "button_disabled_background": [70, 70, 70],
    "button_disabled_foreground": [160, 160, 160]
  }

Feature Configuration

Note that these variables are also supported in the "features" object
in data/config.json. The demo configuration contains the following feature
declaration:

  "features": {
    "!plugin": "$plugin",
    "docs": "$documentation",
    "presets": "$presets"
  }

On the left side you can see the identifiers. These identifiers are used
in the "install" section. On the right side are the names of the features
that are displayed in the installer. In the example above, they reference
variables in the string file. The ! prefix makes the feature always enabled
and prevents the user from turning it of (used for the “main” feature that
is always required).

Install Configuration

Files that are to be installed should be placed into the data/install
directory. By default, there’s a sample Python plugin, a material preview
preset and a plugin documentation file (respective to the default features).

The "install" section lists which files or directoriees are to be copied
where in the Cinema 4D application directory. Available variables:

$src for the data/install directory
$c4d for the C4D target installation directory (note that theoretically
this could also be an arbitrary directory, depending on what the user
chose as target installation path)
$systemappdir for the system application folder, this is either C:\Program Files
on Windows or /Applications on Mac OS. Some plugins might need to install
stuff there.

  "install": {
    "slowdown": 0.5,
    "copyfiles": {
      "plugin": {
        "$src/plugin/": "$c4d/plugins/C4DInstaller_ExamplePlugin/"
      },
      "docs": {
        "$src/doc/": "$c4d/plugins/C4DInstaller_ExamplePlugin/doc/"
      },
      "presets": {
        "$src/library/": "$c4d/library/"
      }
    },
    "dependencies": [
    ]
  }

For testing purposes, you may choose a number in seconds for "slowdown".
This is the time that will be waited after each update to the installation
progress to slow down and make it easier to track what’s happening.

The "dependencies" section is used to specify additional installers that
need to be installed for the plugin to function. Variable substition is
supported in the "name", "file" and "args" fields. The fields
"returncode", "args" and "features" are optional. Valid values for
"platform" are "windows" and "osx". Example:

In the "features" field, you must list the IDs of the features that cause
this dependency to be installed. In the example below, the dependency will
only be installed if the plugin feature is selected to be installed by the
user.

    "dependencies": [
      {
        "name": "MSVC++ 2015 Redistributable (x64) - 14.0.23026",
        "platform": "windows",
        "features": ["plugin"],
        "file": "$src/redist/windows/vc_redist-2015-14.0.23026-x64.exe",
        "args": ["/install"],
        "returncodes": [0, 1638]
      }
    ]

Uninstaller

The default configuration for the uninstaller is this:

  "uninstaller": {
    "enabled": true,
    "target_directory": "$c4d/plugins/C4DInstaller_ExamplePlugin/",
    "name": "uninstall",
    "bundle_identifier": "com.niklasrosenstein.c4dinstaller_uninstaller"
  },

You can choose to disable the uninstaller. The uninstaller will be placed
into the directory you specify with "target_directory". In the same directory
a file will be created called ${name}.data which contains all the names of
the files that have been installed, so that the installer knows what to
uninstall.

EULA

The EULA can be in data/eula.txt and should be updated before building the
installer. If you don’t want to display an EULA, you can delete the file
entirely.

Summary

To summarise, these are the steps to configure the installer:

Change the installer and bundle name in data/config.json
Add or remove features from the "features" section in data/config.json
Add the files to be installed to data/install and update the "install"
section in data/config.json
Update the strings in data/strings/en.json
Test and build the installer

Testing

In order to run the installer or uninstaller for testing purposes, use

make run-installer
make run-uninstaller

The Makefile supports a PYTHON environment version, so if python is not
the program where all of the dependencies are installed, you should use this
variable to point to the correct program, eg. PYTHON=py -3.4 or
PYTHON=python3.

Building the Installer

It is important to build the uninstaller before the installer.

make uninstaller
make installer

Installer admin privileges

On Windows, the installer is built with UAC enabled. Note that there is
currently nothing implemented to have make run-installer run as administrator.

On Mac OS, the /usr/bin/osascript workaround is used to ask the user for
elevated privileges and then execute the installer in that environment.