Quarks are packages of SuperCollider code containing classes, extension methods, documentation and server UGen plugins. The Quarks class manages downloading these packages and installing or uninstalling them.
You can install Quarks using the interface:
This offers many community contributed packages most of which are hosted on github.
You can also add additional folders where you keep your personally developed quarks or those you have forked or downloaded. These will also be shown on the GUI as options for installing.
You can (un)install a Quark by name:
and you can install any local folder:
You can also add a folder where you keep your development quarks (your own and things you have forked):
Now each quark inside that folder will appear on the GUI for you to un/install.
If you wish to be able to uninstall local quarks, but still see them in the GUI, it is highly recommended to collect your local quark directories under a single primary directory. Then, use Quarks: *addFolder to add the primary directory. addFolder does not add individual quark directories.
After installing or uninstalling you need to Language > Recompile Class Library
If you've made a bit of a mess:
When you install one it is cloned using git into:
and this path is added to the LanguageConfig includePaths so that the classes are in SuperCollider's class path when you recompile the library.
You can view and edit the current include paths via Preferences > Interpreter > Include Paths.
You can also see or edit these settings in the file sclang_config.yaml
SuperCollider does not allow duplicate class definitions and will fail to compile if you've accidentally installed conflicting packages.
The Quarks interface can only work if SuperCollider is compiled and running, so if something goes wrong then you have to fix it manually.
If you are using the SC IDE then open Preferences > Interpreter and remove the paths from the Include Paths.
You can also manually edit sclang_config.yaml
To make project work simpler you can save and later reload your currently installed Quarks to and from a quarks.txt file. This is similar to what the LanguageConfig does but this also downloads the Quarks if needed and installs all dependencies.
This is very useful for projects because you can pin the exact releases of each Quark that your project depends on and you should be able to reload them exactly even years in the future.
This saves both what quarks you have and what git revision they are on. If you have uncommitted changes in one of the quarks then it will warn you that its dirty.
The save format specifies the revisions using git tags with a fall back to the full sha hash that specifies the revision. In git terminology this is known as a refspec.
If you have installed local paths that are not under git source control (your own work or things you have downloaded) then the paths will be saved without any version or refspec.
The file format looks like this:
Note that in this case `quarkname` was checked out to the tag 4.1.4, and `ddwCommon` was not on a tag so the refspec is the SHA hash. In both cases this results in an exact reference. `~/supercollider/quarks/my-thing` was not a git repo so the best it can do is to specify the path.
Even if a quark was installed by name using the directory, the full repository URL will be saved to ensure that the reference is unvarying (the directory.txt could be edited and the URL changed, and that might then point to different source code).
Any packages not under git source control are specified by path, abbreviated to the most logical path relative to the quark file, the home directory or by absolute path. They do not have a version or refspec.
Packages are a natural way to store your work.
Install any source code folder as a Quark:
Or create a folder where you do your development work and add that to the additional folders:
Now you can (un)install your own packages from your local folder.
Managing your code with git is optional, but you should consider using it early on. Even if you do not intend to share your code with anyone else, git provides a backup system and a time machine if you break something.
Bitbucket offers free hosting for private repositories, and you can setup your own git host on any machine that you have SSH access to. But you don't even need an externally hosted repository to use git.
Hard drives die, backups fail, people make mistakes. If you keep a copy on bitbucket then your work is that much safer.
Make a git repository and push it to github, gitlab, bitbucket or any publicly accessible git host.
Be sure to tag your releases. The name of a tag should be the release version to which it corresponds. Using Semantic Versioning (eg "v1.0.1") is strongly recommended. This provides the Quarks system with the ability to list available versions and allow the user to choose which version to checkout. Version tags also allow other quark developpers to pin their dependencies to specific release versions.
You can add your quark to the Community Quark Directory by adding its name and git URL to the following file:
https://github.com/supercollider-quarks/quarks/blob/master/directory.txt
Simply click edit, add in your quark's info, and submit a pull request. Here's an example of what an entry should look like in the Quark Directory:
I (felix) migrated the old SVN repository to github and preserved all the commits and authorship. You may find your old work in one of these quarks:
https://github.com/supercollider-quarks
Contact me to transfer ownership to your own github account. You may also just fork any repo there, or if you've already moved your code to github then just edit the directory to point to your preferred newer version.
Quarks with spaces in the name had to have those spaces removed. Quarks nested inside other quarks (dewdrop_lib) are now un-nested.
Releases are specified with a git tag which refers to a specific commit regardless of what branch it is on. The default branch is master, but the branch does not really matter, only the tag. If you are not tagging specific releases then Quarks will fetch the master branch.
The quark file is a SuperCollider code file containing authorship, version, copyright and dependency information. It is optional but recommended. None of the fields are required and you may include any custom fields you like.
The most important feature is to specify dependencies, version, summary and to specify the help file.
It's similar to the package.json file in npm (JavaScript package manager) or bower.json for Bower (web/frontend package manager).
The file name is the name of the quark followed by the .quark extension:
and is a SuperCollider file that returns an IdentityDictionary
Common fields
dependencies is a list of Quarks or git urls with optional an @refspec
path was used for SVN
helpdoc specifies an html help file in the Quark. It will still work and will load the helpfile, but schelp is preferred.
Best practice is to clone the quark into a folder where you do your development work. Make a ~/supercollider/quarks (or wherever you want it) and add this to the Quarks folders:
git clone the quark into that folder. You can do your development work / hacking there and submit a pull request to the repository owner.
There is a git extension that is quite useful for working with github repositories is https://hub.github.com
If you use Quarks.gui you should now be able to see both the downloaded version of the quark and also your own cloned version.
Quarks should be usable even when offline. The directory is cached, refreshed every four hours. Cloned quarks can switch versions without needing to be online.
You can download a zipped release of all quarks:
https://github.com/supercollider-quarks/quarks/releases