Difference between revisions of "Ruby Gem package guidelines"

From ArchWiki
Jump to: navigation, search
(Package naming)
(versioned packages should not install shared files)
Line 8: Line 8:
 
For libraries, use {{Ic|ruby-$gemname}}. For applications, use the program name. In either case, the name should be entirely lowercase.
 
For libraries, use {{Ic|ruby-$gemname}}. For applications, use the program name. In either case, the name should be entirely lowercase.
  
Always use {{Ic|ruby}} even if {{Ic|$gemname}} already starts with word {{Ic|ruby}}. It is needed to avoid future name clashes in case if a gem with shorter name appear. It also makes names more easily parseble by tools (think about PKGBUILD generators/version or dependency checkers, etc...). Examples: {{AUR|ruby-ruby-protocol-buffers}}.
+
Always use {{Ic|ruby-}} prefix even if {{Ic|$gemname}} already starts with word {{Ic|ruby}}. It is needed to avoid future name clashes in case if a gem with shorter name appear. It also makes names more easily parseble by tools (think about PKGBUILD generators/version or dependency checkers, etc...). Examples: {{AUR|ruby-ruby-protocol-buffers}}.
  
If you need to add a versioned package then use {{Ic|ruby-$gemname-$version}}, e.g. {{Ic|ruby-builder-3.2.1}}. So rubygem dependency {{Ic|builder=3.2.1}} will turn into {{Ic|ruby-builder-3.2.1}}. In case if you need to resolve "approximately greater" dependency {{Ic|~>}} then package should use version without the last part, e.g. rubygem dependency {{Ic|builder~>3.2.1}} will turn into {{Ic|ruby-builder-3.2}}. An exception for this rule is when "approximately greater" dependency matches the latest version of the gem - in this case avoid introducing a new versioned package and use just {{Ic|ruby-$gemname}} instead.
+
====Versioned packages====
 +
If you need to add a versioned package then use {{Ic|ruby-$gemname-$version}}, e.g. {{Ic|ruby-builder-3.2.1}}. So rubygem dependency {{Ic|builder=3.2.1}} will turn into {{Ic|ruby-builder-3.2.1}} Arch package.
 +
 
 +
In case if you need to resolve "approximately greater" dependency {{Ic|~>}} then package should use version without the last part, e.g. rubygem dependency {{Ic|builder~>3.2.1}} will turn into {{Ic|ruby-builder-3.2}}. An exception for this rule is when "approximately greater" dependency matches the latest version of the gem - in this case avoid introducing a new versioned package and use just {{Ic|ruby-$gemname}} instead (the HEAD version).
 +
 
 +
Another problem with versioned packages is that it can conflict with other versions, e.g. because the packages install the same files in /usr/bin. One solution for this problem is that versioned packages should not install such files - only HEAD version package can do this.
  
 
== Examples ==
 
== Examples ==

Revision as of 03:32, 14 December 2013

Template:Package Guidelines

Writing PKGBUILDs for software written in Ruby.

Package naming

For libraries, use ruby-$gemname. For applications, use the program name. In either case, the name should be entirely lowercase.

Always use ruby- prefix even if $gemname already starts with word ruby. It is needed to avoid future name clashes in case if a gem with shorter name appear. It also makes names more easily parseble by tools (think about PKGBUILD generators/version or dependency checkers, etc...). Examples: ruby-ruby-protocol-buffersAUR.

Versioned packages

If you need to add a versioned package then use ruby-$gemname-$version, e.g. ruby-builder-3.2.1. So rubygem dependency builder=3.2.1 will turn into ruby-builder-3.2.1 Arch package.

In case if you need to resolve "approximately greater" dependency ~> then package should use version without the last part, e.g. rubygem dependency builder~>3.2.1 will turn into ruby-builder-3.2. An exception for this rule is when "approximately greater" dependency matches the latest version of the gem - in this case avoid introducing a new versioned package and use just ruby-$gemname instead (the HEAD version).

Another problem with versioned packages is that it can conflict with other versions, e.g. because the packages install the same files in /usr/bin. One solution for this problem is that versioned packages should not install such files - only HEAD version package can do this.

Examples

For examples, please see ruby-rethinkdbAUR ruby-json_pureAUR ruby-hpricotAUR.

Notes

Add --verbose to gem arguments to receive additional information in case of troubles.

Note: Usage of --no-user-install gem argument is mandatory since latest Ruby versions (See FS#28681 for details).

Example PKGBUILD

An example PKGBUILD can be found at /usr/share/pacman/PKGBUILD-rubygem.proto, which is in the abs package.

Automation

The gem installation can be automated completely with the tool pacgemAUR which creates a temporary PKGBUILD, calls makepkg and namcap. The resulting package is then installed with sudo pacman.

There is also gem2archAUR tools which aid in automating the process of creating a ruby gem PKGBUILD. Make sure to manually check the PKGBUILD after generation.