Merge pull request #506 from andrewcsmith/patch-2

[supercollider.git] / HelpSource / Guides / UsingQuarks.schelp

title:: Using Quarks
summary:: A guide to Quarks
categories:: Quarks
related:: Classes/Quark, Classes/Quarks

SC supports extensions to its class library, documentation, and server UGen plugins. These extensions are stored in
subfolders of code::Platform.userExtensionDir::. For more info see link::Guides/UsingExtensions::.

A Quark is a more formalized kind of extension folder. It can be shared with others and can be easily installed or
uninstalled using the Quarks package manager. The package manager has a directory of "quarkfiles" which describe the
quarks and how to install them automatically for you.

There is a shared library of these packages on SourceForge http://quarks.sourceforge.net offering a variety of useful
extra capabilities for SC.


section:: Obtaining quarks

There are two standard ways to obtain this shared Quarks library.

subsection:: Downloaded binary

If you have downloaded the full binary of SC then you already have them in the Optional Extras folder of the SC
download. If so, move the 'quarks' folder into this directory:

code::
// execute this code to post the directory path
Platform.userAppSupportDir
::

note:: do not place it inside Extensions. If you place all of them inside extensions, then they will all be in the
compile path. ::

The Quarks package manager will now be able to install and uninstall individual Quark packages.  It does so by making a
symlink in the Extensions/quarks/ folder, pointing back to the quark's source code which stays in the User App Support
directory.

code::
// manage Quarks packages from a gui
Quarks.gui
::

note:: Do not turn everything on. Start slowly::

Some Quarks depend on other Quarks and will automatically install the other ones they need. Conflicts of classes and
package dependencies are always a possibility, so be aware that you may "break" your SC so that it cannot compile what
has been placed in its compile path.

If this happens, simply open the extension folder (code::Platform.userExtensionDir::) and delete the symlinks inside the
quarks folder. (Remember: these symlinks point back to the actual quarks sitting harmlessly in your app support
directory)


subsection:: Getting Quarks from the SVN repository

The other way to obtain the Quarks library is to checkout a copy using Subversion (SVN). SC is fully integrated with SVN
and can checkout single quarks or update them whenever developers make changes.  This is a wonderful thing since you can
complain about a broken knob, somebody in Belgium will fix it and a few hours later its working for you.

You will need the subversion client software installed (link::http://subversion.tigris.org::). To check whether you
already have it, type "svn help" in a terminal window.

If you have previously installed the quarks library from the binary download, you should move or delete that folder now.

The Quarks class and the quarks gui manager will be executing subversion commands.

On Mac, those commands will launch in a terminal window. The first time you run a SourceForge quarks svn command you
will be asked whether to accept the SSL certificate for SourceForge.  Press 'p' to accept it permanently.

section:: Using Quarks
subsection:: The DIRECTORY

The quarks folder contains a folder called DIRECTORY filled with quarkfiles xxxxxxxxy.quark. These file describe the
quark, the developer and note any dependencies.  You can update the directory without downloading all of the quarks.

The following command will make sure you have an up-to-date directory listing (you can run this whether or not it's your
first time using quarks):

code::
Quarks.updateDirectory

// list all quarks in the repository
Quarks.repos.quarks
::

Note that checking out or updating the directory touches only the list of quarks. It does not check out or update any
code or help files that belong to a quark. If you want to get the latest code for an individual quark, use the
instructions in the next section. To checkout or update the entire Quarks repository:

code::
Quarks.checkoutAll; // NB: most users don't want ALL quarks, so getting them all might be a waste of disk space!
Quarks.update;
::

Individual Quarks can be updated by providing the name to the update method:

code::
Quarks.update("testquark"); // much better use of your hard disk. (NB this assumes you already have installed "testquark")
::

subsection:: Checking out and Installing a Quark

Either launch the package manager to install/uninstall individual Quarks:

code::
Quarks.gui
::

which we hope is somewhat self explanatory.  (and steadily improving)

...or use the "checkout" command directly:

code::
// checks it out from svn
Quarks.checkout("testquark");

// this installs it
Quarks.install("testquark");
::

This symlinks the quark's sourcecode folder into your Extensions directory.  The source code itself stays in the quarks
folder, but the symlink is in your Extensions directory (and thus in SC's compile path).

After a quark is installed you must recompile the language. Installing simply places the code into SC's compile path.
You must then recompile the class library.

Then you can use it:
code::
TestQuark.sayHello
::

subsection:: Uninstall

You can of course uninstall quarks if you decide you don't need them:

code::
Quarks.uninstall("testquark");

// list those installed
Quarks.installed
::

subsection:: Dependencies

Quarks may specify other quarks that they are dependent on. code::Quarks.install:: will also attempt to install those
other quarks that the desired quark depends upon, if not already installed. You can prevent this if neccessary by
passing false as the second argument to code::Quarks.install::.

code::
Quarks.install( "somequark", includeDependencies: false )
::

Similarly the install command will attempt to download quarks if you don't already have them locally. You can prevent
this using the allowCheckout argument:

code::
Quarks.install( "somequark", checkoutIfNeeded: false )

// list those in the repository that you could checkout
Quarks.repos.quarks

// list those that you have checked out and could now install
Quarks.local.quarks
::

subsection:: Check out all available Quarks

code::
Quarks.checkoutAll
::

This downloads all of them into {Application Support Directory}/quarks but does not yet install them into your class
library. It can be particularly helpful because you won't in future need to have an internet connection to install the
quarks: they are already downloaded even if not installed.

code::
// post those checked out
Quarks.checkedOut

// post those checked out with a description
Quarks.listCheckedOut

// post all available with a description
Quarks.listAvailable
::

subsection:: Standard SVN tools

The Quarks class interface mirrors the familar svn commands while substituting in the correct paths.

code::
Quarks.update( "testquark" )
Quarks.update // updates all

Quarks.status( "testquark" )
Quarks.status // status of all
::

You may also use any standard SVN tools which is probably easier especially for add and commit.

The principal repository is located at: link::https://quarks.svn.sourceforge.net/svnroot/quarks::


section:: Creating a Quark

Adding a Quark requires using standard SVN tools. Create your folder in {Application Support}/quarks/ (we'll assume it's
called quarkname). Place your classes in this folder. Place a quark file called quarkname.quark into {Application
Support}/quarks/DIRECTORY (see link::Classes/Quark:: for the format). You can now install, re-compile, test and
uninstall install the quark from your local system without having added it into the public repository. You can use
quarks for your own private purposes to install and uninstall packages of classes.

subsection:: Adding a quark to the public repository

You will need a SourceForge account to publish a quark to the subversion repository. You will need to be familiar with
the basics of svn. You also need the account to be added to the "quarks" project - contact one of the admins listed at
link::http://sourceforge.net/projects/quarks:: to do that.

Once you're authorised:

In a shell go to {Application Support}/quarks/ and execute:

teletype::
svn add quarkname

svn add DIRECTORY/quarkname.quark

svn commit -m "adding quarkname" quarkname
svn commit -m "adding directory entry for quarkname" DIRECTORY/quarkname.quark
::

Be careful to commit only changes to your own quark and to the directory entry you have added.


subsection:: Local Repository Example

Besides the public repos at sourceforge you can use any other subversion host including a repository running on your
local machine. Running a local repository is suprisingly easy. This is useful in that you get version control and an
easy way to manage package installation.

For obvious reasons you need to have a running subversion system somewhere in order to use this feature.  Nevertheless
it is possible to use alreadily existing subversion quarks directories (as the SonEnvir one).

numberedList::

## Create a directory in svn-repos (e.g. quarks-<yourname/id/institution>). note:: This name has to be unique across all
Quark repositories you will ever check out! :: Create a dir within it called "DIRECTORY" containing quark files.

## Fill repos with your work

## Now use Quarks to make it accessible in SC (shown at hand of the existing and publicly available SonEnvir quarks):

code::
~qSonEnvir = Quarks(
    reposPath: "https://svn.sonenvir.at/repos/SonEnvir/trunk/src/quarks-sonenvir",
    localPath: Platform.userAppSupportDir ++ "/quarks-sonenvir"
);

~qSonEnvir.checkoutAll;
// or, if alreadily checked out at the appropriate place:
~qSonEnvir.update;
::

## now install your quarks:

code::
// post all checked out
~qSonEnvir.listCheckedOut;

// or post all available with a description
~qSonEnvir.listAvailable

~qSonEnvir.install("sonenvir-testquark");
~qSonEnvir.isInstalled("sonenvir-testquark");

~qSonEnvir.listInstalled
::

## recompile
## test

code::
SonEnvirTestQuark.sayHello

~qSonEnvir = Quarks(
    reposPath: "https://svn.sonenvir.at/repos/SonEnvir/trunk/src/quarks-sonenvir",
    localPath: Platform.userAppSupportDir ++ "/quarks-sonenvir"
);
::

## remove what you're don't need
code::
~qSonEnvir.uninstall("sonenvir-testquark")

// recompile
SonEnvirTestQuark.sayHello
// -> error
::


## update

code::
~qSonEnvir.updateDirectory
~qSonEnvir.update
::
::