summaryrefslogtreecommitdiff
path: root/README.rubygems
blob: d7bf2bd490bbc544d660c0348287f3cee93f844f (plain)
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
Here is some information I have learned while importing RubyGem packages into
Baserock.

First, beware that RubyGem .gemspec files are actually normal Ruby programs,
and are executed when loaded. A Bundler Gemfile is also a Ruby program, and
could run arbitrary code when loaded.

Second, note that when I asked on the freenode #ruby-lang IRC channel about
associating Gems with their upstream repos, I got the impression that in
general Ruby developers aren't wild about the idea of people bypassing their
Gem releases and using their code straight from version control instead.

The rubygems.org site adds an extra point where code can be tampered with
by malicious folk looking to add backdoors and the like. While there is a
mechanism for signing Gems, I found only a few (the Net:SSH family) which
actually made use of it. (I am of course not saying that trusting upstream
version control systems is secure in itself, but it reduces risk).

The Standard Case
-----------------

Most Ruby projects provide one or more .gemspec files, which describe the
runtime and development dependencies of the Gem.

Using the .gemspec file and the `gem build` command it is possible to create
the .gem file. It can then be installed with `gem install`. The default
build instructions generated by the RubyGems importer use this method.

Note that use of `gem build` is discouraged by its own help file in favour
of using Rake, but there is much less standardisation among Rakefiles and they
may introduce requirements on Hoe, rake-compiler, Jeweler or other tools.

When looking at Gem dependencies, bear in mind that the 'development'
dependency set usually includes everything useful to test, document, and create
a Gem of the project. All we want to do as part of a Morph build is create and
install a Gem file. This can often be done with no build dependencies beyond
Ruby and Gem.


Bundler
-------

Many projects use Bundler, which allows you to collect dependency info in
a file named Gemfile. Most put the important dependency info in their .gemspec
file or files, and then include the .gemspec in the Gemfile. For this reason
the tool looks for .gemspec files directly and ignores Gemfiles.

Bundler allows you to lock the exact versions of all the project's
dependencies and write them to a file named 'Gemfile.lock'. The RubyGems
importer will make use of this information if it is available.


Gem with no .gemspec
--------------------

Some Gems choose not to include a .gemspec, like [Nokigori]. In the case of
Nokigori, and others, [Hoe] is used, which adds Rake tasks that create the Gem.
The `gem build` command cannot not be used in these cases.

You can often use the `rake gem` command instead of `gem build` in these cases.
The generated .gem will be in a subdirectory named 'pkg/'.

[Nokigori]: https://github.com/sparklemotion/nokogiri/blob/master/Y_U_NO_GEMSPEC.md
[Hoe]: http://www.zenspider.com/projects/hoe.html


Signed Gems
-----------

It's possible for a Gem maintainer to sign their Gems. See:

  - <http://blog.meldium.com/home/2013/3/3/signed-rubygems-part>
  - <http://www.ruby-doc.org/stdlib-1.9.3/libdoc/rubygems/rdoc/Gem/Security.html>

When building a Gem in Baserock, signing is unnecessary because it's not going
to be shared except as part of the build system. The .gemspec may include a
`signing_key` field, which will be a local path on the maintainer's system to
their private key. Removing this field causes an unsigned Gem to be built.

Known Gems that do this: 'net-ssh' and family.


setup.rb
--------

The setup.rb program is rather outdated and you should try to avoid using it.