Development workflow

From build instructions.

Build instructions

cd SuperCollider
mkdir -p build
cd build
cmake -G Xcode -DCMAKE_PREFIX_PATH=`brew --prefix qt5`  ..
# or, if you want to build with supernova:
cmake -G Xcode -DCMAKE_PREFIX_PATH=`brew --prefix qt5` -DSUPERNOVA=ON ..
# then start the build
cmake --build . --target install --config RelWithDebInfo

If successful this will build the application into build/Install/SuperCollider/

You can see the available build options with cmake -LH.

To install, you may move this to /Applications or use it in place from the build directory.

More info on supernova can be found in the section Frequently used cmake settings below.

Note: You can also open the produced SuperCollider.xcodeproj in Xcode, and build the "Install" scheme in place of the last step. Do make sure you run the previous configuration steps.

Step by step explanation of the Build instructions:

Create a build folder if one doesn't already exist:

mkdir -p build
cd build

Prepare for building by making a configuration file:

cmake -G Xcode -DCMAKE_PREFIX_PATH=`brew --prefix qt5`  ..

(The .. at the end is easy to miss. Don't forget it!)

This specifies to cmake that we will be using Xcode to build. It also specifies the location of qt so that the complier/linker can find it. Use brew info to confirm you are referring to the correct version of Qt.

If you are not using the Homebrew install then you should substitute the path to the parent folder of the bin/include/lib folders in that Qt tree.

Build

cmake --build . --target install --config RelWithDebInfo

Cmake will build the application looking up configuration information in the file CMakeCache.txt in the specified directory (the current directory: . ). By specifying '--target install' you build all targets and trigger the creation of a portable bundle containing all files contained in the SC distribution. The default install location is ./Install.

The flag --config RelWithDebInfo will build an optimized binary but will still include some useful debug information.

By default Xcode builds the application in debug mode which runs much slower and has a larger application size. It is intended for use with the XCode debugger. For normal usage you will want an optimized release version.

The four possible build configs are:

• Debug
• RelWithDebInfo
• Release
• MinSizeRel

From Setting-up-your-development-environment

2. Keep your fork updated

In order to keep your fork up-to-date, you need to point it to the main SuperCollider repository. This is done by adding the main repository as a remote, usually called upstream. Please note: naming the main repository upstream is just a convention, not a requirement. If you already have a differently named remote pointing to the main SuperCollider repository, you can use that name instead.

• If you haven't yet added the upstream remote, you can add it by doing the following:

  • Check the list of remotes: git remote -v. The output should look like this:

      origin	https://github.com/your-name/supercollider.git (fetch)
      origin	https://github.com/your-name/supercollider.git (push)
    

  • Add a new remote called upstream, pointing to the SuperCollider repository:

      git remote add upstream https://github.com/supercollider/supercollider.git
    

  • Check the list of remotes again: git remote -v. Now the output should look like this:

      origin	https://github.com/your-name/supercollider.git (fetch)
      origin	https://github.com/your-name/supercollider.git (push)
      upstream	https://github.com/supercollider/supercollider.git (fetch)
      upstream	https://github.com/supercollider/supercollider.git (push)
    

  • You can now proceed to update your fork.

• If you've already added the upstream remote, you can update your fork by doing the following:
  • Be sure to have all local changes committed before proceeding with the update
  • Fetch changes made to the upstream repository: git fetch upstream
  • Checkout the develop branch: git checkout develop
  • Pull changes into the develop branch: git pull upstream develop. Your develop branch is now up-to-date.
  • If you've already created your topic branch, you can update it with the changes in develop by either rebasing or pulling - see Notes on rebasing and merge conflicts.
  • If you haven't yet created your topic branch, proceed to creating it as described in Creating Pull Requests.

3. Tooling and contribution-type based setup

For C++ contributions

To contribute C++ code, you will need to install the tools necessary to run our automatic linting and formatting scripts. You can find more information about requirements here, and how to use these scripts here.

For schelp and SuperCollider contributions

In order to contribute code in the SuperCollider language and documentation in schelp, the easiest thing to do is to point sclang toward the files in SCClassLibrary and testsuite, and nothing else. This removes any possibility of interference from extensions and startup files, and will also ensure that the help browser and documentation renderer use the schelp files you are editing.

We would like to have a better workflow for this, but for now, here is a simple way to get set up:

1. Run this SuperCollider code to create a 'developer' sclang config file:

// edit this to the appropriate path!
~scGitPath = // "/path/to/your/supercollider";

// add paths from your clone
LanguageConfig.addIncludePath(~scGitPath +/+ "SCClassLibrary");
LanguageConfig.addIncludePath(~scGitPath +/+ "testsuite");

// disable startup files
LanguageConfig.addIncludePath(~scGitPath +/+ "platform/disable_startup_files");

// disable default search paths
LanguageConfig.addExcludePath(Platform.systemExtensionDir);
LanguageConfig.addExcludePath(Platform.userExtensionDir);
LanguageConfig.addExcludePath(Platform.resourceDir +/+ "SCClassLibrary");

// enable developer-oriented warning
LanguageConfig.postInlineWarnings = true;

~scConfPath = Platform.userConfigDir +/+ "sclang_conf_development.yaml";
LanguageConfig.store(~scConfPath);
postln("Language config stored to" + ~scConfPath);

2. In your IDE preferences, set this to be the sclang config file, and reboot sclang. In SCIDE, you can do this in the Preferences dialog. If you are using sclang by itself on the command line, run it with -l path/to/sclang_conf_development.yml.

3. When you want to switch back to using sclang for your own enjoyment, simply swap the config file to what it was previously.

C++ changes, sclang, and SCIDE

The IDE runs sclang using PATH on Windows and Linux, and assumes an App Bundle directory structure on macOS. This presents a difficulty if you want to use SCIDE to test C++ changes to sclang, because it may accidentally use your system installation of sclang.

The way to manage this is different on each platform:

• MacOS: always use the app bundle from the install or SuperCollider targets to run the IDE.
• Linux: run the IDE with PATH="/directory/with/sclang:$PATH" /path/to/scide (don't include sclang in the path, just its containing directory).
• Windows: since sclang is not usually in PATH by default, and "." is, always run the IDE from the install target.

From Creating-pull-requests

Before making changes

See Setting Up Your Development Environment, to make sure you have a working and updated fork of SuperCollider's source code. Then you can create a fresh new branch for your contribution:

Create a topic branch

• Create a topic branch from where you want to base your work.
  • Your topic branch should be based on develop, unless it is a trivial bug fix or documentation change, in which case it should be based on the latest release (3.x) branch.
  • Our branch naming convention is topic/branch-description: for example, topic/fix-sinosc or topic/document-object.
  • To quickly create a topic branch based on develop: git checkout -b topic/my-fix develop.
  • Please do not work off of the master branch, which is stable and only includes releases.
• As time passes, make sure to keep your fork updated - see Updating your fork.

Making changes

• Make commits of logical units.

• Please refer to Code Style Guide. Note that code style, such as whitespace conventions, depend on the language (C++ vs SuperCollider vs SCDoc Markup)

• Commit message format: make sure your commit messages are descriptive and in the proper format, following the schema "category: content", e.g. docs: Make the example in CONTRIBUTING imperative and concrete, or help: Update RunningSum2 help file, or class library: do this and that, or plugins: add missing function definition.

• Make sure you have added the necessary tests for your changes. All changes to code should include a test which checks for correct functionality, including regression tests for bug fixes. Info on best practice for Unit tests is available at https://github.com/supercollider/supercollider/wiki/Unit-Testing-Guide

• Make sure you have documented your changes, if necessary.

Submitting changes as Pull Requests

• Push your changes to a topic branch in your fork of the SuperCollider repository. If you are working locally, do this with git push -u origin topic/branch-description. origin should be the remote of your fork; check with git remote -v.
• Submit a pull request to the SuperCollider repository.
• The core team looks at pull requests on a regular basis in a public meeting that is held on a weekly basis. The meeting times are announced on the sc-dev mailing list.
• You may receive feedback and requests for changes. We expect changes to be made in a timely manner. We may close pull requests if they aren't showing any activity.

Skipping CI

We have CI provided by AppVeyor (Windows) and Travis (Linux, macOS). If a commit changes only non-schelp documentation, without renaming, adding, or removing files, you may want to consider adding [skip ci] to the commit message so it does not waste CI resources. See https://github.com/supercollider/supercollider/wiki/Continuous-Integration---Travis-&-Appveyor#skip-ci.

Notes on rebasing and merge conflicts

It is almost never a good idea to resolve merge conflicts via the GitHub interface or by merging the main branch in locally. This creates noise in commit history and makes it more difficult to perform other operations on branches later. In the SuperCollider project, the preferred way to resolve merge conflicts in a pull request is by rebasing.

See git help rebase for rebase usage examples that include graphical representations.

Rebasing (git help rebase) is a very useful command for four scenarios in particular:

1. If you'd like to incorporate new commits on the base branch that contain relevant fixes or features into your topic branch.
2. If you'd like to resolve merge conflicts.
3. If you'd like to change the branch your topic branch is based on. This may happen if, for instance, a maintainer requests that you make your bug fix merge request against a release branch (e.g. 3.9, 3.10) instead of develop. You will then need to rebase your topic branch onto the appropriate release branch.
4. If you'd like to rewrite your commit history by combining or reordering some commits (not recommended for those newer to git).

Rebase has an interactive mode (git rebase -i) which will show exactly which commits will be applied to the new base, and the order in which they will be applied. This can be very helpful when you're not completely sure what the result of a rebase will be.

For scenarios (1) and (2), suppose that the current branch is topic/foo, which is based on an old commit from the develop branch. To rebase, you can execute git rebase -i develop. You can examine the change list to make sure it's correct before continuing. Git will stop if it encounters a merge conflict, and give instructions on how to resolve it and continue the rebase.

For scenario (3), suppose that there are three branches: develop, the release branch 3.10, and the topic branch topic/foo which is based on develop. Suppose that topic/foo is currently checked out. You would like it to be based on 3.10 instead of develop. An easy way to do this is with git rebase -i --onto 3.10 develop topic/foo. Beware that you may need to resolve merge conflicts during this rebase.

After rebasing, you may find it helpful to display the pretty-printed commit log with git log --oneline --graph --decorate to make sure all is well.

In any case, after rebasing your local branch will now be out of sync with your remote branch. You will have to resolve this by force pushing: git push --force origin topic/foo. If you realize later that you made a mistake with your rebase, it's always possible to go back to your previous local state using git reflog.

For scenario (4), git help rebase's section "Interactive mode" has extensive documentation on how to reorder and recombine commits. Also refer to the section on --autosquash for ideas on how to combine these features into a streamlined rebase-oriented workflow.

Additional resources

More information can be found on the git workflow wiki page.

You can also refer to Github's guide to forking a repository and to syncing a fork.

Instructions on adding translation files for the IDE can be found in the Developer Reference (soon to be moved, please update that link when it does move...).