Difference between revisions of "Ruby Gem package guidelines"

From ArchWiki
Jump to: navigation, search
m (Prevent leading spaces when copy-pasting the example)
(Explain "Package contains reference to $pkgdir" warning)
(17 intermediate revisions by 10 users not shown)
Line 1: Line 1:
[[Category:Package development (English)]]
+
[[Category:Package development]]
{{i18n|Ruby Gem Package Guidelines}}
+
[[it:Ruby Gem Package Guidelines]]
 +
{{Package Guidelines}}
  
==Package Naming==
+
Writing [[PKGBUILD]]s for software written in [[Ruby]].
For libraries, use "ruby-gemname". For applications, use the program name. In either case, the pkgname should be entirely lowercase
+
  
==Examples==
+
== Package naming ==
For examples, please see [http://aur.archlinux.org/packages.php?ID=24484 github-gem] [http://aur.archlinux.org/packages.php?ID=24483 ruby-json_pure] [http://aur.archlinux.org/packages.php?ID=17121 ruby-hpricot]
+
For libraries, use {{Ic|ruby-$gemname}}. For applications, use the program name. In either case, the name should be entirely lowercase.
  
==Example PKGBUILD==
+
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}}.
<pre>
+
# Contributor: YourName <YourEmail AT example DOT com>
+
pkgname=ruby-GEMNAME # All lowercase
+
pkgver=GEMVERSION
+
pkgrel=1
+
pkgdesc="Ruby gem FooBar which implements BazQuux"
+
arch=(any)
+
url=""
+
license=()
+
depends=(ruby) # Gem may depend on other gems as well (you can get dependency information from the yaml specification)
+
makedepends=(rubygems)
+
source=(http://rubygems.org/downloads/GEMNAME-$pkgver.gem)
+
noextract=(GEMNAME-$pkgver.gem)
+
md5sums=()
+
  
build() {
+
====Versioned packages====
  cd $srcdir
+
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&#61;3.2.1}} will turn into {{Ic|ruby-builder-3.2.1}} Arch package.
  # _gemdir is defined inside build() because if ruby[gems] is not installed on the system
+
  # makepkg will barf when sourcing the PKGBUILD
+
  local _gemdir="$(ruby -rubygems -e'puts Gem.default_dir')"
+
  
  gem install --no-user-install --ignore-dependencies --verbose -i "$pkgdir$_gemdir" -n "$pkgdir"/usr/bin GEMNAME-$pkgver.gem
+
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).
}
+
  
# vim:set ts=2 sw=2 et:
+
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.
</pre>
+
  
==Automation==
+
== Examples ==
Abhishek Dasgupta wrote [http://github.com/abhidg/gem2arch/ gem2arch] to aid in automating the process of creating a ruby gem PKGBUILD. Make sure to manually check the PKGBUILD after generation. There are multiple versions of this tool in AUR ([https://aur.archlinux.org/packages.php?K=gem2arch Search for gem2arch]).
+
For examples, please see {{AUR|ruby-rethinkdb}} {{AUR|ruby-json_pure}} {{AUR|ruby-hpricot}}.
  
The gem installation can also be automated completely with the tool [https://aur.archlinux.org/packages.php?ID=46196 pacgem] which creates a temporary PKGBUILD, calls makepkg and namcap. The resulting package is then installed with sudo pacman.
+
== Notes ==
 +
Add {{Ic|--verbose}} to '''gem''' arguments to receive additional information in case of troubles.
 +
 
 +
{{Note|Usage of {{ic|--no-user-install}} '''gem''' argument is mandatory since latest Ruby versions (See {{Bug|28681}} for details).}}
 +
 
 +
== Gotchas ==
 +
=== Package contains reference to $pkgdir ===
 +
Sometimes when you build the package you can see following warning {{Ic|WARNING: Package contains reference to $pkgdir}}. Some packed files contain absolute path of directory where you built the package. To find these files run {{ic|cd pkg && grep -R "$(pwd)" .}} Most likely the reason will be hardcoded path in {{Ic|.../ext/Makefile}}.
 +
{{note|folder {{ic|ext}} contains native extension code usually written in C. During the package installation rubygems generates a Makefile using {{ic|mkmf}} library. Then {{Ic|make}} is called, it compiles a shared library and copies one to {{ic|lib}} gem directory.}}
 +
After {{ic|gem install}} is over the {{Ic|Makefile}} is not needed anymore. In fact none of the files in {{Ic|ext}} is needed and it can be completely removed by adding {{ic|rm -rf "$pkgdir/$_gemdir/gems/$_gemname-$pkgver/ext"}} to {{ic|package()}} function.
 +
 
 +
== Example PKGBUILD ==
 +
An example PKGBUILD can be found at {{Ic|/usr/share/pacman/PKGBUILD-rubygem.proto}}, which is in the {{Pkg|abs}} package.
 +
 
 +
== Automation ==
 +
The gem installation can be automated completely with the tool {{AUR|pacgem}} which creates a temporary PKGBUILD, calls [[makepkg]] and [[namcap]]. The resulting package is then installed with {{Ic|sudo pacman}}.
 +
 
 +
There is also {{AUR|gem2arch}} tools which aid in automating the process of creating a ruby gem PKGBUILD. Make sure to manually check the PKGBUILD after generation.

Revision as of 20:55, 16 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).

Gotchas

Package contains reference to $pkgdir

Sometimes when you build the package you can see following warning WARNING: Package contains reference to $pkgdir. Some packed files contain absolute path of directory where you built the package. To find these files run cd pkg && grep -R "$(pwd)" . Most likely the reason will be hardcoded path in .../ext/Makefile.

Note: folder ext contains native extension code usually written in C. During the package installation rubygems generates a Makefile using mkmf library. Then make is called, it compiles a shared library and copies one to lib gem directory.

After gem install is over the Makefile is not needed anymore. In fact none of the files in ext is needed and it can be completely removed by adding rm -rf "$pkgdir/$_gemdir/gems/$_gemname-$pkgver/ext" to package() function.

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.