Cliver
Sometimes Ruby apps shell out to command-line executables, but there is no standard way to ensure those underlying dependencies are met. Users usually find out via a nasty stack-trace and whatever wasn't captured on stderr, or by the odd behavior exposed by a version mismatch.
Cliver
is a simple gem that provides an easy way to detect and use
command-line dependencies. Under the covers, it uses rubygems/requirements
so it supports the version requirements you're used to providing in your
gemspec.
Usage
Get Out of My Way, CLIVER!
Sometimes even Cliver can't perfectly deduce the version of an executable given
its --version
output. If you're getting an exception with a mismatch, supply
the CLIVER_NO_VERIFY
environment variable, and it will assume that the first
executable on your path to match the name also matches the version
constraint. Please also create an issue here so I can help you resolve the root
issue.
$ command-that-uses-cliver # raises exception :(
$ export CLIVER_NO_VERIFY=1
$ command-that-uses-cliver # no cliver exception :)
Detect and Detect!
The detect methods search your entire path until they find a matching executable or run out of places to look.
# no version requirements
Cliver.detect('subl')
# => '/Users/yaauie/.bin/subl'
# one version requirement
Cliver.detect('bzip2', '~> 1.0.6')
# => '/usr/bin/bzip2'
# many version requirements
Cliver.detect('racc', '>= 1.0', '< 1.4.9')
# => '/Users/yaauie/.rbenv/versions/1.9.3-p194/bin/racc'
# dependency not met
Cliver.detect('racc', '~> 10.4.9')
# => nil
# detect! raises Cliver::Dependency::NotMet exceptions when the dependency
# cannot be met.
Cliver.detect!('ruby', '1.8.5')
# Cliver::Dependency::VersionMismatch
# Could not find an executable ruby that matched the
# requirements '1.8.5'. Found versions were {'/usr/bin/ruby'=> '1.8.7'}
Cliver.detect!('asdfasdf')
# Cliver::Dependency::NotFound
# Could not find an executable asdfasdf on your path
Assert
The assert method is useful when you do not have control over how the
dependency is shelled-out to and require that the first matching executable on
your path satisfies your version requirements. It is the equivalent of the
detect! method with strict: true
option.
Advanced Usage:
Version Detectors
Some programs don't provide nice 'version 1.2.3' strings in their --version
output; Cliver
lets you provide your own version detector with a pattern.
Cliver.assert('python', '~> 1.7',
detector: /(?<=Python )[0-9][.0-9a-z]+/)
Other programs don't provide a standard --version
; Cliver::Detector
also
allows you to provide your own arg to get the version:
# single-argument command
Cliver.assert('janky', '~> 10.1.alpha',
detector: '--release-version')
# multi-argument command
Cliver.detect('ruby', '~> 1.8.7',
detector: [['-e', 'puts RUBY_VERSION']])
You can use both custom pattern and custom command by supplying an array:
Cliver.assert('janky', '~> 10.1.alpha',
detector: ['--release-version', /.*/])
And even supply multiple arguments in an Array, too:
# multi-argument command
Cliver.detect('ruby', '~> 1.8.7',
detector: ['-e', 'puts RUBY_VERSION'])
Alternatively, you can supply your own detector (anything that responds to
#to_proc
) in the options hash or as a block, so long as it returns a
Gem::Version
-parsable version number; if it returns nil or false when
version requirements are given, a descriptive ArgumentError
is raised.
Cliver.assert('oddball', '~> 10.1.alpha') do |oddball_path|
File.read(File.expand_path('../VERSION', oddball_path)).chomp
end
And since some programs don't always spit out nice semver-friendly version numbers at all, a filter proc can be supplied to clean it up. Note how the filter is applied to both your requirements and the executable's output:
Filters
Cliver.assert('built-thing', '~> 2013.4r8273',
filter: proc { |ver| ver.tr('r','.') })
Since Cliver
uses Gem::Requirement
for version comparrisons, it obeys all
the same rules including pre-release semantics.
Search Path
By default, Cliver uses ENV['PATH']
as its search path, but you can provide
your own. If the asterisk symbol (*
) is included in your string, it is
replaced ENV['PATH']
.
Cliver.detect('gadget', path: './bins/:*')
# => 'Users/yaauie/src/project-a/bins/gadget'
Supported Platforms
The goal is to have full support for all platforms running ruby >= 1.9.2, including rubinius and jruby implementations, as well as basic support for legacy ruby 1.8.7. Windows has support in the codebase, but is not available as a build target in [travis_ci][].