Group Your Builds

Often in the prototyping process you’ll find yourself cycling between running your overall build and building a single card. You’ll probably be commenting out code in the process.

And even after your code is stable, you’ll probably want to build your deck multiple ways: maybe a printer-friendly black-and-white version for print-and-play and then a full color version.

Squib’s Build Groups help you with these situations. By grouping your Squib code into different groups, you can run parts of it at a time without having to go back and commenting out code.

Here’s a basic example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
require 'squib'

Squib::Deck.new(width: 75, height: 75, cards: 2) do
  # puts "Groups enabled by environment: #{groups.to_a}"

  text str: ['A', 'B']

  build :print_n_play do
    rect
    save_sheet prefix: 'build_groups_bw_'
  end

  build :color do
    rect stroke_color: :red, dash: '5 5'
    save_png prefix: 'build_groups_color_'
  end

  build :test do
    save_png range: 0, prefix: 'build_groups_'
  end

end

# Here's how you can run this on the command line:
#
# --- OSX/Linux (bash or similar shells) ---
# $ ruby build_groups.rb
# $ SQUIB_BUILD=color ruby build_groups.rb
# $ SQUIB_BUILD=print_n_play,test ruby build_groups.rb
#
# --- Windows CMD ---
# $ ruby build_groups.rb
# $ set SQUIB_BUILD=color && ruby build_groups.rb
# $ set SQUIB_BUILD=print_n_play,test && ruby build_groups.rb
#
# Or, better yet... use a Rakefile like the one provided in this gist!

Only one group is enabled by default: :all. All other groups are disabled by default. To see which groups are enabled currently, the build_groups returns the set.

Groups can be enabled and disabled in several ways:

  • The enable_build and disable_build DSL methods within a given Squib::Deck can explicitly enable/disable a group. Again, you’re back to commenting out the enable_group call, but that’s easier than remembering what lines to comment out each time.
  • When a Squib::Deck is initialized, the environment variable SQUIB_BUILD is consulted for a comma-separated string. These are converted to Ruby symbols and the corresponding groups are enabled. This is handy for enabling builds on the command line (e.g. turn on color, work in that for a while, then turn it off)
  • Furthermore, you can use Squib.enable_build_globally and Squib.disable_build_globally to manipulate SQUIB_BUILD environment variable programmatically (e.g. from a Rakefile, inside a Guard session, or other build script).

The The Squib Way pt 3: Workflows tutorial covers how to work these features into your workflow.

Note

There should be no need to set the SQUIB_BUILD variable globally on your system (e.g. at boot). The intent is to set SQUIB_BUILD as part of your session.

One adaptation of this is to do the environment setting in a Rakefile. Rake is the build utility that comes with Ruby, and it allows us to set different tasks exactly in this way. This Rakefile works nicely with our above code example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Example Rakefile that makes use of build groups
require 'squib'

desc 'Build black-and-white by default'
task default: [:pnp]

desc 'Build both bw and color'
task both: [:pnp, :color]

desc 'Build black-and-white only'
task :pnp do
  Squib.enable_build_globally :print_n_play
  load 'build_groups.rb'
end

desc 'Build the color version only'
task :color do
  Squib.enable_build_globally :color
  load 'build_groups.rb'
end

desc 'Build a test card'
task :test do
  Squib.enable_build_globally :test
  load 'build_groups.rb'
end

Thus, you can just run this code on the command line like these:

$ rake
$ rake pnp
$ rake color
$ rake test
$ rake both