A cookiecutter project template for SuperCollider server plugins.

To create a SuperCollider server plugin using this template, first install cookiecutter.

This cookiecutter template requires at least Python 3.2. If you have multiple versions of python and are installing via pip, you may need to be explicit about which version of Python you use to install it to ensure cookiecutter uses a compatible version. For example, on macOS with Python 3.7:

$ python3.7 -m pip install cookiecutter

Then run:

$ cookiecutter https://github.com/supercollider/cookiecutter-supercollider-plugin

and answer the questionnaire. See the cookiecutter documentation on how to change the default values for these prompts.

After filling out the questionnaire, cookiecutter will clone the project, fill in placeholders with your supplied information, run a Python script from the SuperCollider project to set up your CMake files, and finally set up a git repository.

Here is an example:

$ cookiecutter https://github.com/brianlheim/cookiecutter-supercollider-plugin
full_path_to_supercollider_source [/home/wendy/supercollider (if you haven't cloned it yet, do that first! Press Ctrl-C to exit this script.]: /Users/brianheim/git/supercollider
project_name [Simple Gain]:
project_namespace [SimpleGain]:
repo_name [simplegain]:
plugin_name [SimpleGain]:
plugin_description [A simple audio volume gain plugin]:
full_name [Wendy Carlos]: Brian Heim
github_username [brian.heim]: brianlheim
email [brianlheim@site.com]: brianlheim@gmail.com

Running pre-project-generation hook...

Checking Python version...

Checking for SuperCollider repository...

Running post-project-generation hook...

Initializing new Git repository
Initialized empty Git repository in /Users/brianheim/git/simplegain/.git/

Running CMake generation script
Wrote project file to /Users/brianheim/git/simplegain/CMakeLists.txt
Installed 2 CMake modules

Adding Git remote for plugin project

Making initial Git commit
[master (root-commit) 261d980] Initial commit
 12 files changed, 1031 insertions(+)
 create mode 100644 .appveyor.yml
 create mode 100644 .gitignore
 create mode 100644 .travis.yml
 create mode 100644 CMakeLists.txt
 create mode 100644 LICENSE
 create mode 100644 README.md
 create mode 100644 cmake_modules/SuperColliderCompilerConfig.cmake
 create mode 100644 cmake_modules/SuperColliderServerPlugin.cmake
 create mode 100644 plugins/SimpleGain/SimpleGain.cpp
 create mode 100644 plugins/SimpleGain/SimpleGain.hpp
 create mode 100644 plugins/SimpleGain/SimpleGain.sc
 create mode 100644 plugins/SimpleGain/SimpleGain.schelp

Done!

Enter the directory and build the project:

$ cd simplegain
$ mkdir build
$ cd build
$ cmake .. DSC_PATH=/path/to/supercollider/source -DCMAKE_BUILD_TYPE=Debug
$ cmake --build . --config Debug

If you add more plugins, or add or remove files, make sure to regenerate the CMakeLists.txt file using the generation script. See the README in tools/cmake_gen for more info, or run the script with --help.

$ python ../supercollider/tools/cmake_gen/generate_server_plugin_cmake.py --help

Explanation of questionnaire terms:

• project_name: The name of the project, used in the README and CMakeLists.txt. Furthermore, the project_name with spaces removed will be used as the base install folder.
• project_namespace: C++ namespace for your plugin(s).
• repo_name: GitHub repository name
• plugin_name: Name of the first plugin in your project

The generated project will be GPLv3-licensed. Make sure that you change the LICENSE file if you want to use a more permissive license!

When generating a project using this cookiecutter recipe, a config file is included in .github/workflows/build.yml containing an action for Github Actions to build, compile and zip up your code for MacOS, Linux and Windows.

It is set to trigger on one event: If you push a new tag prefixed with v (eg. v1.0 or v4.0.1) to your repo, Github Actions will activate and start the process of building and releasing. If succesful, your finished builds should appear in the Releases column.

You should get an email from Github once the run is finished, but otherwise you can navigate to the Actions pane on your Github repository to see the details and command outputs of each build.

• Basic development tools (C++ compiler, cmake, etc.)
• Python >= 3.2
• Git
• cookiecutter