| 1 |
#!/usr/bin/ruby -EUTF-8 |
| 2 |
# |
| 3 |
# Copyright © 2011, Lucas Nussbaum <[email protected]> |
| 4 |
# |
| 5 |
# This program is free software: you can redistribute it and/or modify |
| 6 |
# it under the terms of the GNU General Public License as published by |
| 7 |
# the Free Software Foundation, either version 3 of the License, or |
| 8 |
# (at your option) any later version. |
| 9 |
# |
| 10 |
# This program is distributed in the hope that it will be useful, |
| 11 |
# but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 |
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 |
# GNU General Public License for more details. |
| 14 |
# |
| 15 |
# You should have received a copy of the GNU General Public License |
| 16 |
# along with this program. If not, see <http://www.gnu.org/licenses/>. |
| 17 |
|
| 18 |
require 'gem2deb' |
| 19 |
require 'gem2deb/dh_ruby' |
| 20 |
require 'gem2deb/gem_installer' |
| 21 |
require 'optparse' |
| 22 |
require 'shellwords' |
| 23 |
include Gem2Deb |
| 24 |
|
| 25 |
if ENV['DH_RUBY'] |
| 26 |
opts = Shellwords.split(ENV['DH_RUBY']) |
| 27 |
ARGV.unshift(*opts) |
| 28 |
end |
| 29 |
|
| 30 |
engine = Gem2Deb::DhRuby.new |
| 31 |
action = nil |
| 32 |
|
| 33 |
optparse = OptionParser.new do |opts| |
| 34 |
opts.banner = "Usage: dh_ruby [OPTIONS] ACTION" |
| 35 |
opts.separator "Options:" |
| 36 |
|
| 37 |
opts.on('-h', '--help', 'show help') do |
| 38 |
puts opts |
| 39 |
exit |
| 40 |
end |
| 41 |
|
| 42 |
opts.on('--gem-install', 'install files as a gem') do |
| 43 |
engine.installer_class = Gem2Deb::GemInstaller |
| 44 |
end |
| 45 |
|
| 46 |
opts.on('-v', '--version', 'show dh_ruby version') do |
| 47 |
puts "dh_ruby version #{Gem2Deb::VERSION}" |
| 48 |
exit |
| 49 |
end |
| 50 |
|
| 51 |
opts.on('--print-supported', 'prints supported Ruby versions') do |
| 52 |
Gem2Deb::SUPPORTED_RUBY_VERSIONS.keys.each do |v| |
| 53 |
puts v |
| 54 |
end |
| 55 |
exit |
| 56 |
end |
| 57 |
|
| 58 |
opts.separator "ACTION must be one of:" |
| 59 |
opts.on('--clean', 'debhelper clean helper') do |
| 60 |
action = :clean |
| 61 |
end |
| 62 |
|
| 63 |
opts.on('--configure', 'debhelper configure helper') do |
| 64 |
action = :configure |
| 65 |
end |
| 66 |
|
| 67 |
opts.on('--build', 'debhelper build helper') do |
| 68 |
action = :build |
| 69 |
end |
| 70 |
|
| 71 |
opts.on('--test', 'debhelper test helper') do |
| 72 |
action = :test |
| 73 |
end |
| 74 |
|
| 75 |
opts.on('--install', 'debhelper install helper') do |
| 76 |
action = :install |
| 77 |
end |
| 78 |
end |
| 79 |
optparse.parse! |
| 80 |
|
| 81 |
if action.nil? |
| 82 |
puts "E: no action selected. You must pass one (and only one) of:" |
| 83 |
puts " --install, --clean, --configure, --build, --test" |
| 84 |
puts optparse |
| 85 |
exit(1) |
| 86 |
end |
| 87 |
|
| 88 |
if action == :install |
| 89 |
engine.install(ARGV) |
| 90 |
else |
| 91 |
engine.send(action) |
| 92 |
end |
| 93 |
|
| 94 |
__END__ |
| 95 |
=head1 NAME |
| 96 |
|
| 97 |
dh_ruby - debhelper build system for Ruby software |
| 98 |
|
| 99 |
=head1 SYNOPSIS |
| 100 |
|
| 101 |
|
| 102 |
B<dh_ruby> [I<OPTIONS>] |
| 103 |
|
| 104 |
=head1 DESCRIPTION |
| 105 |
|
| 106 |
B<dh_ruby> is a Debhelper build system for Ruby software. It will |
| 107 |
automatically build and install files contained in Ruby packages, trying to |
| 108 |
work as close to Rubygems as possible but respecting Debian standards for Ruby |
| 109 |
packages. |
| 110 |
|
| 111 |
dh_ruby can automatically run your tests against all supported Ruby versions, |
| 112 |
see the "FILES" section below. |
| 113 |
|
| 114 |
See dh_ruby --help for details. |
| 115 |
|
| 116 |
=head1 SOURCE PACKAGE LAYOUT |
| 117 |
|
| 118 |
B<dh_ruby> supports two different source package styles: single-binary source |
| 119 |
packages, and multi-binary source packages. |
| 120 |
|
| 121 |
=head2 Single-binary layout |
| 122 |
|
| 123 |
The default layout is the B<single-binary> layout. This is the layout used by |
| 124 |
most Ruby packages upstream, i.e. Ruby code in I<lib>/, executable programs in |
| 125 |
I<bin>/, etc. Packages imported from Rubygems using B<gem2deb(1)> will have |
| 126 |
this layout. |
| 127 |
|
| 128 |
When using this layout, B<dh_ruby> will install files (Ruby code, |
| 129 |
executables, gemspecs) to the I<first binary package> listed in |
| 130 |
I<debian/control>. |
| 131 |
|
| 132 |
=head2 Multi-binary layout |
| 133 |
|
| 134 |
B<gem2deb> version I<0.4.0> introduced support for the B<multi-binary> |
| 135 |
layout. This layout should be used when you have a set of different Ruby |
| 136 |
packages maintained upstream in a single VCS, and you decide that you |
| 137 |
also want to maintain a single source package in Debian having the |
| 138 |
different components as separate binary packages. |
| 139 |
|
| 140 |
In this layout, the source package contains the separate components in |
| 141 |
subdirectories where each of them will use the standard Ruby layout |
| 142 |
(I<lib>/, I<bin>/, etc). |
| 143 |
|
| 144 |
This layout does not support creating separate binary packages from the same |
| 145 |
root directory. For those cases, see the documentation on |
| 146 |
I<DH_RUBY_USE_DH_AUTO_INSTALL_DESTDIR> below. |
| 147 |
|
| 148 |
To indicate that you want to use a multi-binary layout, we have to 1) |
| 149 |
list your multiple binary packages in I<debian/control> as usual, and |
| 150 |
add an extra-field called I<X-DhRuby-Root> to each binary package |
| 151 |
stanza, indicating which directory has to be used as the root for that |
| 152 |
binary package. |
| 153 |
|
| 154 |
An example: |
| 155 |
|
| 156 |
Source: mymultibinarypackage |
| 157 |
[...] |
| 158 |
|
| 159 |
Package: ruby-foo |
| 160 |
X-DhRuby-Root: path/to/foo |
| 161 |
[...] |
| 162 |
|
| 163 |
Package: ruby-bar |
| 164 |
X-DhRuby-Root: path/to/bar |
| 165 |
|
| 166 |
The corresponding source package should be layed out like this: |
| 167 |
|
| 168 |
foo/ |
| 169 |
foo.gemspec |
| 170 |
lib/ |
| 171 |
foo.rb |
| 172 |
bin/foo |
| 173 |
bar/ |
| 174 |
bar.gemspec |
| 175 |
lib/ |
| 176 |
bar.rb |
| 177 |
bin/ |
| 178 |
bar |
| 179 |
|
| 180 |
Important notes about multi-binary packages and the usage of |
| 181 |
I<X-DhRuby-Root>: |
| 182 |
|
| 183 |
=over |
| 184 |
|
| 185 |
=item |
| 186 |
|
| 187 |
If your package uses the multi-binary layout, it must include |
| 188 |
`I<gem2deb> (>= 0.4.0~)` in I<Build-Depends>. |
| 189 |
|
| 190 |
B<Version 0.4.0 had a bug in the support for native extensions> in |
| 191 |
multi-binary packages, so if your package uses the multi-binary feature |
| 192 |
and at least one of the sub-components has native extensions, you must |
| 193 |
use `I<gem2deb> (>= 0.4.1~)` in I<Build-Depends> instead. |
| 194 |
|
| 195 |
=item |
| 196 |
|
| 197 |
The path indicated in I<X-DhRuby-Root>, as you have probably guessed by |
| 198 |
now, must be relative to the root of the source package. |
| 199 |
|
| 200 |
=item |
| 201 |
|
| 202 |
If any binary package declares a I<X-DhRuby-Root> field, all other |
| 203 |
binary packages that don't have one will be ignored by B<dh_ruby>. |
| 204 |
|
| 205 |
=back |
| 206 |
|
| 207 |
=head1 OPTIONS |
| 208 |
|
| 209 |
=over |
| 210 |
|
| 211 |
=item B<--clean>, B<--configure>, B<--build>, B<--test>, B<--install> |
| 212 |
|
| 213 |
Commands called by debhelper at various steps of the build process. |
| 214 |
|
| 215 |
=item B<--print-supported> |
| 216 |
|
| 217 |
Prints the supported Ruby versions. |
| 218 |
|
| 219 |
=item B<-h>, B<--help> |
| 220 |
|
| 221 |
Displays B<dh_ruby> usage information. |
| 222 |
|
| 223 |
=item B<-v>, B<--version> |
| 224 |
|
| 225 |
Displays B<dh_ruby> version information. |
| 226 |
|
| 227 |
=item B<--gem-install> |
| 228 |
|
| 229 |
This option indicates that the build should use the B<gem> command to install |
| 230 |
the files, instead of the homegrown installer. Native packages will be |
| 231 |
installed to I</usr/lib/$ARCH/rubygems-integration/$RUBY_VERSION>, while pure |
| 232 |
Ruby packages will be installed to I</usr/share/rubygems-integration/all>. |
| 233 |
|
| 234 |
There is an internal include list of directories from the source package that need |
| 235 |
to be installed, but we can't possibly know all possibilities: if a package |
| 236 |
needs to install a directory that is not automatically installed, use |
| 237 |
I<DH_RUBY_GEM_INSTALL_INCLUDE>. If you want to exclude a directory |
| 238 |
from being installed, use I<DH_RUBY_GEM_INSTALL_EXCLUDE>. Note that for using |
| 239 |
those variables, you need to build depend on gem2deb (>= 1.6~). |
| 240 |
|
| 241 |
=back |
| 242 |
|
| 243 |
=head1 COMPATIBILITY LEVELS |
| 244 |
|
| 245 |
dh_ruby reuses the L<B<debhelper>>(7) compatibility levels for introducing |
| 246 |
behavior changes that might be backwards-incompatible. |
| 247 |
|
| 248 |
=over |
| 249 |
|
| 250 |
=item v14 |
| 251 |
|
| 252 |
This level is still open for development; use with caution. |
| 253 |
|
| 254 |
Changes from v13 are: |
| 255 |
|
| 256 |
Packages are built and tested when executing the B<build> target of |
| 257 |
I<debian/rules>. The build is done as part of B<dh_auto_build>, and the tests |
| 258 |
are run as part of B<dh_auto_test>. The installation into debian/ is performed |
| 259 |
during the B<install> target, i.e. during B<dh_auto_install>. This means that |
| 260 |
you can intercept the build between these steps using targets such |
| 261 |
B<execute_after_dh_auto_build>, B<override_dh_auto_build>, |
| 262 |
B<override_dh_auto_test>, B<execute_before_dh_auto_install> etc. |
| 263 |
|
| 264 |
=item v13 |
| 265 |
|
| 266 |
This is the recommended mode of operation. |
| 267 |
|
| 268 |
This was the current compatibility level at the point where this mechanism was |
| 269 |
introduced. So even packages with compatibility levels lower than 13 use this |
| 270 |
mode. |
| 271 |
|
| 272 |
In this this compatibility level, dh_ruby exhibits its classic behavior. In |
| 273 |
particular, packages are built, installed and tested during the |
| 274 |
B<dh_auto_install> phase of the build process, i.e. when dpkg-buildpackage is |
| 275 |
invoking the B<install> target of I<debian/rules>. |
| 276 |
|
| 277 |
=back |
| 278 |
|
| 279 |
=head1 SUBSTITUTION VARIABLES |
| 280 |
|
| 281 |
=over |
| 282 |
|
| 283 |
=item I<${ruby:Depends}> |
| 284 |
|
| 285 |
${ruby:Depends} will expand to the runtime dependencies of the package. This is |
| 286 |
determined by taking the runtime dependencies from the Rubygems metadata, and |
| 287 |
then mapping them to Debian package names. |
| 288 |
|
| 289 |
The relevant packages must be installed during the package build for the |
| 290 |
mapping to be successful (normally they should be hardcoded in the |
| 291 |
Build-Depends: field). |
| 292 |
|
| 293 |
=back |
| 294 |
|
| 295 |
=head1 ENVIRONMENT VARIABLES |
| 296 |
|
| 297 |
=over |
| 298 |
|
| 299 |
=item I<DH_RUBY> |
| 300 |
|
| 301 |
Use this variable to pass command line parameters to dh_ruby. For example in |
| 302 |
debian/rules: |
| 303 |
|
| 304 |
export DH_RUBY = --gem-install |
| 305 |
|
| 306 |
=item I<DH_RUBY_IGNORE_TESTS> |
| 307 |
|
| 308 |
This is a space-separated list of tests that dh_ruby will ignore during package |
| 309 |
build. The available test names are the names of all supported Ruby versions |
| 310 |
(you can list them with `dh_ruby --print-supported`). |
| 311 |
|
| 312 |
If set to "all", all tests will be ignored during the package build. |
| 313 |
|
| 314 |
=item I<DH_RUBY_USE_DH_AUTO_INSTALL_DESTDIR> |
| 315 |
|
| 316 |
If this variable is defined (to anything), dh_ruby will respect the directory |
| 317 |
informed by dh_auto_install(1), usually I<debian/tmp>. By default, gem2deb will |
| 318 |
install files to debian/I<package>, where I<package> is the first binary |
| 319 |
package listed in debian/control. |
| 320 |
|
| 321 |
This is useful for multi-binary source packages that don't conform to |
| 322 |
the supported layout (i.e. separate subdirectories each with I<lib>/, |
| 323 |
I<bin>/ etc). Using this, all files will be installed to I<debian/tmp>, and |
| 324 |
you can them distribute them into separate binary packages by using |
| 325 |
I<debian/$package.install> files or explicit shell calls in |
| 326 |
I<debian/rules>. |
| 327 |
|
| 328 |
Mixing I<DH_RUBY_USE_DH_AUTO_INSTALL_DESTDIR> and multi-binary layout (using |
| 329 |
`X-DhRuby-Root:`) is NOT SUPPORTED. |
| 330 |
|
| 331 |
=item I<DH_RUBY_GEMSPEC> |
| 332 |
|
| 333 |
Determines which file contain the gem specification with package metadata. By |
| 334 |
default, dh_ruby will read metadata from a .gemspec file in the root of source |
| 335 |
package directory. You can use this variable to override that if you want to |
| 336 |
provide custom metadata for the Debian package. |
| 337 |
|
| 338 |
In the case there are more than one .gemspec in the source package root, you |
| 339 |
will I<need> to use DH_RUBY_GEMSPEC to instruct dh_ruby about which one to use. |
| 340 |
|
| 341 |
=item I<DH_RUBY_GEM_INSTALL_INCLUDE>. |
| 342 |
|
| 343 |
When using --gem-install, this variable adds B<files> to the list of files that |
| 344 |
need to be installed. Entries must be separated by spaces, and can be either |
| 345 |
exact filenames, of glob expressions (e.g. I<*.txt>, I<foo/*>). |
| 346 |
|
| 347 |
Directories cannot be added directly, only files. If you want to include an |
| 348 |
entire directory, say I<foo>, use a glob expression like I<foo/*>. |
| 349 |
|
| 350 |
Note that by default all top-level files are automatically excluded, except |
| 351 |
I<VERSION*> which is used by some packages. If you need a top-level file to be |
| 352 |
installed, you need to explicit list it as included. |
| 353 |
|
| 354 |
=item I<DH_RUBY_GEM_INSTALL_EXCLUDE>. |
| 355 |
|
| 356 |
When using --gem-install, this variable adds files to the list of files that |
| 357 |
SHOULD NOT be installed. Entries must be separated by spaces, and must be |
| 358 |
either specific filenames, or glob expressions (e.g. I<*.txt>). |
| 359 |
|
| 360 |
Directories cannot be excluded directly. To exclude an entire directory, |
| 361 |
use a glob expression such as I<foo/*>. |
| 362 |
|
| 363 |
=back |
| 364 |
|
| 365 |
=head1 FILES |
| 366 |
|
| 367 |
=over |
| 368 |
|
| 369 |
=item debian/I<ruby-test-files.yaml>, debian/I<ruby-tests.rake>, debian/I<ruby-tests.rb> |
| 370 |
|
| 371 |
Theses files can be used to explicitly tell dh_ruby how to run the tests in your |
| 372 |
package. When running the tests, dh_ruby will automatically set RUBYLIB to |
| 373 |
include the appropriate directories where the package files were installed in |
| 374 |
your package to make sure the tests use them instead of the files in the source |
| 375 |
directory. |
| 376 |
|
| 377 |
B<Your package can only contain at most one of these files.> |
| 378 |
|
| 379 |
debian/I<ruby-test-files.yaml> must contain a YAML document with a list of test |
| 380 |
files to be run. If the package metadata contains an explicit list of test |
| 381 |
files, gem2deb(1) will automatically generate this file for you. Example from |
| 382 |
ruby-mime-types: |
| 383 |
|
| 384 |
--- |
| 385 |
- test/test_mime_type.rb |
| 386 |
- test/test_mime_types.rb |
| 387 |
|
| 388 |
debian/I<ruby-tests.rake> can be used to run the tests with rake(1). You can |
| 389 |
use anything you would use in a regular Rakefile, but you must define a default |
| 390 |
task. gem2deb includes a utility test task that makes it easier for you by |
| 391 |
creating a default task automatically. Example: |
| 392 |
|
| 393 |
require 'gem2deb/rake/testtask' |
| 394 |
Gem2Deb::Rake::TestTask.new do |t| |
| 395 |
t.test_files = FileList['test/*_test.rb'] |
| 396 |
end |
| 397 |
|
| 398 |
You can also use the equivalent RSpec task: |
| 399 |
|
| 400 |
require 'gem2deb/rake/spectask' |
| 401 |
Gem2Deb::Rake::RSpecTask.new do |spec| |
| 402 |
spec.pattern = './spec/**/*_spec.rb' |
| 403 |
end |
| 404 |
|
| 405 |
If debian/I<ruby-tests.rb> exists, it will be run with each supported Ruby |
| 406 |
version, and must finish with a exit status of I<0>, otherwise dh_ruby assumes |
| 407 |
the tests failed. A simple example: |
| 408 |
|
| 409 |
require 'test/unit' |
| 410 |
require 'mypackage' # if 'mypackage.rb' or 'mypackage.so' was not installed properly, this will fail |
| 411 |
class MyPackageTest < Test::Unit::TestCase |
| 412 |
def test_features |
| 413 |
assert_equal 4, MyPackage.sum(2,2) |
| 414 |
end |
| 415 |
end |
| 416 |
|
| 417 |
=item debian/tests/assets (directory) |
| 418 |
|
| 419 |
For Rails assets packages (ruby-rails-assets-*), the presence of this directory |
| 420 |
will cause the Rails assets smoke test to be run. During the test run, this |
| 421 |
directory will be copied into under app/ in a freshly created rails |
| 422 |
application, and `bundle exec rake assets:precompile` will be called. |
| 423 |
|
| 424 |
B<debian/tests/assets> should contain example usage of the given package, e.g.: |
| 425 |
|
| 426 |
=over |
| 427 |
|
| 428 |
=item B<debian/tests/assets/javascripts/application.js> |
| 429 |
|
| 430 |
=item B<debian/tests/assets/stylesheets/application.scss> |
| 431 |
|
| 432 |
=back |
| 433 |
|
| 434 |
In the above example, those files will be copied at the following location in |
| 435 |
the test Rails app: |
| 436 |
|
| 437 |
=over |
| 438 |
|
| 439 |
=item B<app/assets/javascripts/application.js> |
| 440 |
|
| 441 |
=item B<app/assets/stylesheets/application.scss> |
| 442 |
|
| 443 |
=back |
| 444 |
|
| 445 |
B<Note>: any dependencies needed to run this smoke test must be specified |
| 446 |
explicitly as package build dependencies. |
| 447 |
|
| 448 |
=item debian/I<dh_ruby.mk> |
| 449 |
|
| 450 |
If this file is present, dh_ruby will call B<make> passing it as the makefile |
| 451 |
during the build, in the I<clean>, I<build>, and I<install> steps, like this: |
| 452 |
|
| 453 |
=over |
| 454 |
|
| 455 |
=item clean: B<make -f debian/dh_ruby.mk clean> |
| 456 |
|
| 457 |
=item build: B<make -f debian/dh_ruby.mk> |
| 458 |
|
| 459 |
=item install: B<make -f debian/dh_ruby.mk install> |
| 460 |
|
| 461 |
=back |
| 462 |
|
| 463 |
If you want the upstream Makefile to be used, just make I<debian/dh_ruby.mk> a |
| 464 |
symlink to I<../Makefile>. |
| 465 |
|
| 466 |
=item debian/I<dh_ruby.rake> |
| 467 |
|
| 468 |
If this file is present, dh_ruby will call B<rake> passing it as the rakefile |
| 469 |
during the build, in the I<clean>, I<build>, and I<install> steps, like this: |
| 470 |
|
| 471 |
=over |
| 472 |
|
| 473 |
=item clean: B<rake -f debian/dh_ruby.rake clean> |
| 474 |
|
| 475 |
=item build: B<rake -f debian/dh_ruby.rake> |
| 476 |
|
| 477 |
=item install: B<rake -f debian/dh_ruby.rake install> |
| 478 |
|
| 479 |
=back |
| 480 |
|
| 481 |
If you want the upstream Rakefile to be used, just make I<debian/dh_ruby.rake> a |
| 482 |
symlink to I<../Rakefile>. |
| 483 |
|
| 484 |
=item debian/I<gemspec> |
| 485 |
|
| 486 |
If this file exists, it will be used as the package gemspec, regardless of |
| 487 |
I<metadata.yml> and any I<*.gemspec> that exists in the upstream source. Using |
| 488 |
this is only advised on single-binary source packages, and the behavior of this |
| 489 |
feature is undefined for multi-binary source packages (see B<SOURCE PACKAGE |
| 490 |
LAYOUT> above). |
| 491 |
|
| 492 |
If debian/I<gemspec> is a symlink, it will first be expanded, and then the |
| 493 |
symlink target will be used as a gemspec. |
| 494 |
|
| 495 |
Hint: for packages with multiple gemspec, you can have debian/I<gemspec> as a |
| 496 |
symlink pointing to the one you want to use. |
| 497 |
|
| 498 |
=back |
| 499 |
|
| 500 |
=head1 SEE ALSO |
| 501 |
|
| 502 |
L<B<gem2deb>>(1) |
| 503 |
|
| 504 |
=head1 COPYRIGHT AND AUTHORS |
| 505 |
|
| 506 |
Copyright (c) 2011, Lucas Nussbaum <[email protected]> |
| 507 |
|
| 508 |
This program is free software: you can redistribute it and/or modify |
| 509 |
it under the terms of the GNU General Public License as published by |
| 510 |
the Free Software Foundation, either version 3 of the License, or |
| 511 |
(at your option) any later version. |
| 512 |
|
| 513 |
This program is distributed in the hope that it will be useful, |
| 514 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 515 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 516 |
GNU General Public License for more details. |
| 517 |
|
| 518 |
You should have received a copy of the GNU General Public License |
| 519 |
along with this program. If not, see <http://www.gnu.org/licenses/>. |