Debian Codegraph @

bin/dh_ruby

raw
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/>.