[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [sc-dev] Quarks help first draft



excellent! this is such a big step.

(minor) comment:

shouldn't 

Quarks.folder;
be
Quarks.path;
?


> On 21.01.2015, at 21:48, felix <felix@xxxxxxxxxxxxxxxxxxx> wrote:
> 
> 
> Nearly there !  This is first draft of the help file. It will be improved. I will push the topic branch soon. Just seeing if I should rethink or refactor certain things. Overall though, it seems quite nice now.
> 
> Feedback and questions appreciated. It will help to resolve any confusion that I've overlooked. Complaints are useful too.
> 
> thanks.
> 
> 
> 
> Using Quarks
> A guide to Quarks
> See also: Quark, Quarks
> Quarks are packages of SuperCollider code, containing classes, extension methods, documentation and server UGen plugins. The Quarks system manages downloading these packages and installing or uninstalling them.
> Installing quarks
> You can install Quarks using the interface:
> Quarks.gui
> This offers many community contributed packages most of which are hosted on github.
> When you install one, it is cloned using git into:
> Quarks.folder;
> // open the folder and have a look
> Quarks.openFolder;
> and this path is added to the LanguageConfig includePaths so that the classes are in SuperCollider's class compile path when you recompile the library.
> To see the changes you've made open Preferences > Interpreter > Include Paths. All the paths you've added are visible there.
> If the Quark is in the community directory then you can (un)install it using just the name:
> Quarks.install("UnitTesting");
> Quarks.uninstall("UnitTesting");
> You may also install any package from any git URL:
> Quarks.install("https://github.com/supercollider-quarks/UnitTesting.git";);
> // uninstall it
> Quarks.uninstall("https://github.com/supercollider-quarks/UnitTesting.git";);
> You can install any local folder:
> // add your own classes
> Quarks.install("~/supercollider/quarks/my-thing");
> // install something that you downloaded and want to try out
> Quarks.install("~/Downloads/something-i-found");
> After installing or uninstalling you need to Language > Recompile Class Library
> // remove everything
> Quarks.clear
> Fixing Conflicts
> 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
> Saving and Loading quarks files
> To make project work simpler you can save and later reload your currently installed Quarks. This is similar to what the LanguageConfig does, but it also downloads the Quarks if needed and resolves dependencies.
> // save your current state
> Quarks.save("~/supercollider/quarks.txt");
> // load
> Quarks.load("~/supercollider/quarks.txt");
> This saves both what quarks you have and what git revision they are on. If you have uncommited changes in one of the quarks then it will warn you.
> 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 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.
> 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.
> The file format looks like this:
> git://github.com/crucialfelix/crucial-library@tags/4.1.4
> git://github.com/supercollider-quarks/ddwCommon@8ae156b460dcb08285013265cf3a1c7172bba665
> ~/supercollider/quarks/my-thing
> Note that in this case crucial-library 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 and your project should be able to later reinstall the exact same packages.
> 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 of by absolute path. They do not have a version or refspec.
> Making your own Quark
> Packages are a natural way to store your work. You can start by just installing any folder you are working on.
> The use of 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, but you don't even need an externally hosted respository to use git.
> # in the terminal, its easy as this:
> git init
> Publishing a Quark
> Make a git repo and push it to github, bitbucket or any publicly accessible git host.
> tag your releases. The name of the tag is the name of the release version. Using semver (eg "1.0.1") is recommended. This provides the Quarks system with a way to checkout a version and also provides a downloadable version on your github releases page.
> Add your quark to the community index. The index is this file:
> https://github.com/supercollider-quarks/quarks/blob/master/directory.txt
> Where you specify the name, the git url and the most recent version as @tags/{version-name}
> cruciallib=git://github.com/crucialfelix/crucial-library@tags/4.1.4
> Simply click edit on github, make any changes and this will submit a pull request.
> git branches
> The default branch for releases is master. If you have wish to release something that is not on master, then just tag it. The tag refers to a specific commit regardless of what branch it is on.
> Quark file
> The quark file is a SuperCollider code file containing authorship, version, copyright and dependency information. It's just like package.json in NPM (JavaScript package manager) or bower.json in Bower (web/frontend package manager).
> TODO - work in progress
> required info dependencies
> Contributing fixes to a quark
> work on it in place vs. clone it separately make a pull request
> Offline
> can download a release of everything
> "https://github.com/supercollider-quarks/quarks/releases";
> when a quark is cloned it can switch versions even if offline.
> Useful API
> Quarks.installed
> Quarks.openFolder
> 
> Quark(name).definesClasses
> Quark(name).definesExtensionMethods
> 


_______________________________________________
sc-dev mailing list

info (subscription, etc.): http://www.beast.bham.ac.uk/research/sc_mailing_lists.shtml
archive: https://listarc.bham.ac.uk/marchives/sc-dev/
search: https://listarc.bham.ac.uk/lists/sc-dev/search/