Projects

In the legacy Quark system all Quarks are globally installed to a local Quarks.folder and will be implicitly added to the currently active LanguageConfig. While this is an easy way to install legacy Quarks, it also tends to clutter the global environment which will eventually lead to conflicting Quarks due namespace collision through classes or methods.

This setup is practical to provide a default setup to sketch out things, but at the point the sketch needs to be reproducible, reliable and shared it can create all sorts of problems. In general: The more dependencies, the more possible conflicts, either now or in the future - so it is best practice to pursuit a minimal environment for each project.

Many scripting languages (mainly Python though) suffer from a similar problem: A project relies on some dependencies, but accumulating dependencies in a global environment results in conflicts - at least if project A depends on v1 of X, but project B depends on v2 of X.

The common solution for this is to set up an “isolated environment” for each project (also often called virtual environment), which encapsulates all necessary dependencies for the project. Magnet will do exactly this - instead of a global Quarks.folder, every project will have a sub-folder where all necessary dependencies are stored and loaded when a project is opened.

Project folders

When creating a new magnet project the following folders will be created

• classes/ - SC classes of the project
• dist/ - stores created packages of the project, .gitignore this
• HelpSource/ - schelp documentation of the project, since SCDoc only finds help files in folders with this name
• magnet_packages/ - storing all dependencies - managed by magnet, .gitignore this
  • magnet_packages/quarks
  • magnet_packages/leptons - which will include scsynth and supernova versions, depending on if both are available via the index
  • magnet_packages/gluons
• tests/ - code related to testing
• sclang_conf.yaml - a language config file to be picked up by the IDE, .gitignore this since it will be generated by magnet. This may disappear in future magnet versions in case the language config file will be replaced.

Each dependency is placed within the folder of its kind, e.g. magnet_packages/leptons/foo, such that it is visible on a folder level which dependencies bring binaries and scsynth only needs to look into magnet_packages/leptons for plugins. Legacy quarks and git dependencies are placed into magnet_packages/quarks. The folder is named after magnet such that it does not collide with folders of other tools, e.g. an external folder which holds the C++ dependencies of a lepton.

Since sclang can only have one class declaration for a name, only one version of each package can be installed, so dependencies are not nested or versioned like in npm.

Having this standardized approach allows easier packaging of the source code for releases, yet the exact location of the files can still be changed within the manifest file.

Contents of package folders

Each folder magnet_packages/<kind>s/<dependency-name> mirrors the files which have been selected by the global-paths of the package (see Packaging), relative to the root of its project. This allows legacy quarks to keep their existing folder structure, such that e.g. relative paths to resources or the structure of HelpSource keep working.

Leptons additionally contain a plugins folder with the scsynth and, if available, supernova binaries (see Lepton artifacts).

sclang_conf.yaml

This is open to change in future version of magnet.

After magnet install, add, remove, update or run, it will create (or update) a sclang_conf.yaml in the root folder of the project. This can be used by the IDE to pick up all dependencies and code of the magnet project, e.g. via sclang -l sclang_conf.yaml. Note that this sync goes only one-way, so any user changes to sclang_conf.yaml would be overwritten when the state of the magnet project changes.

The content of the file is

excludeDefaultPaths: true

includePaths:
  # the class library of the found sclang
  - "/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary"
  # base directories of the global-paths of the project, i.e. "classes/" by default
  - "/path/to/project/classes"
  - "/path/to/project/magnet_packages"
  # local dependencies are added via the base directories of their global-paths

The base directory of a global path is the part before the first wildcard, e.g. Classes/**.sc results in Classes/. All paths are absolute, since sclang resolves relative paths against its working directory, which is not the project root when sclang gets started by the IDE.

excludeDefaultPaths keeps globally installed extensions out of the project, but it also excludes the class library of SuperCollider itself, so magnet adds the SCClassLibrary of the sclang it finds (via MAGNET_SCLANG, the PATH or the default installation) as first entry. If magnet can not find sclang, it writes excludeDefaultPaths: false instead and warns that globally installed extensions are compiled as well.

The plugin paths of the server are set up in a similar way, see Server plugins.