0.0
No commit activity in last 3 years
No release in over 3 years
Guard::Sclang automatically runs sclang commands when watched files are modified.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 1.13.0
~> 12.3
~> 3.1

Runtime

>= 2.0.0, ~> 2.0
 Project Readme

Build Status

Guard::Sclang

This Guard plugin allows you to run SuperCollider UnitTest test suites automatically when files are added or altered, so that you can immediately see the impact of code changes on your tests.

Installation

Make sure you have Guard installed.

Install the gem with:

gem install guard-sclang

Or, better, add it to your Gemfile, and then use Bundler to install it:

echo "gem 'guard-sclang'" >> Gemfile
bundle install

Configuring a Guardfile

Before you can launch Guard, you need to configure a Guardfile which tells Guard which of your SuperCollider tests to run via the guard-sclang plugin.

You can create a stub Guardfile from a built-in template via:

bundle exec guard init sclang

The rest of this section explains how to configure the Guardfile.

When one or more files matching a watch block's regular expression changes, guard-sclang simply runs the UnitTest subclass returned by that block:

guard :sclang do
  # Run any tests which are added or changed under lib/tests/
  watch(%r{lib/tests/\w.*\.sc})

  # For any class Foo added or changed under lib/classes/, run
  # the corresponding test class TestFoo
  watch(%r{lib/classes/(\w.*)\.sc}) do |m|
    classname = "Test#{m[1]}"
    puts "#{m[0]} changed; running #{classname}"
    classname
  end
end

sclang CLI arguments

You can optionally provide arguments to be passed to sclang, e.g.

# Load the ScQT IDE classes
guard :sclang, args: ["-i", "scqt"] do
  ...
end

sclang execution timeout

If sclang experiences a compilation error, it will hang, so invocation of sclang is currently wrapped by timeout(1). (This currently prevents guard-sclang from working outside Linux, but it should not be hard to convert the timeout mechanism to native Ruby to fix that.)

The timeout defaults to 3 seconds, but can be changed:

guard :sclang, timeout: 10 do
  ...
end

Other options

To run everything on start, pass :all_on_start to #guard:

guard :sclang, all_on_start: true do
  ...
end

To run everything after previously failing tests succeeded, pass :all_after_pass to #guard:

guard :sclang, all_after_pass: true do
  ...
end

Usage

Once you have set up your Guardfile with the guard-sclang plugin enabled, you are ready to launch Guard.

guard-sclang assumes that the sclang interpreter is to be found somewhere on your $PATH. If you installed SuperCollider on Linux via a distribution package, this should happen automatically, in which case you can simply launch Guard by typing this into your shell:

bundle exec guard

However if you installed from source, or you are using MacOS, maybe sclang won't be on the $PATH, in which case you will need to set it. This can either be done temporarily for each invocation of Guard, e.g.

PATH=/path/to/dir/containing/sclang:$PATH bundle exec guard

or by configuring your interactive shell setup (e.g. ~/.bashrc) to set $PATH on startup.

Development / support / feedback

Please see the CONTRIBUTING file.

History and license

This plugin was based on guard-shell by Joshua Hawxwell, so the original license has been preserved - see LICENSE.