RubyGem - Introduction

Introduction éclair

Question : « J’ai installé RubyGems et je veux installer Ruby on Rails (par exemple). Comment faire ça ? »

Réponse :

gem install rails

Répondez ensuite Y à la question qui vous est posée sur les dépendances.

Introduction

Sont ici couvertes les fonctionnalités les plus importantes de RubyGems, de façon rapide et générale. Il s’agit de donner au lecteur une vue générale de l’application et de son mode de fonctionnement. De plus amples détails sont disponibles dans le Guide de l’utilisateur RubyGems et dans le Guide du développeur RubyGems.

Voici les opérations documentées ici :

Listage des gemmes distantes disponibles
Recherche de gemmes distantes à installer
Installation de gemmes distantes
Obtention d’informations sur une gemme installée
Utilisation d’une gemme dans votre code
Désinstallation d’une gemme
Listage de toutes les gemmes installés
Une note sur les opérations locales et distantes
Navigation dans les gemmes installées et leurs documentations
Utilisation d’un fichier de configuration
Fabrication d’une gemme
Distribution d’une gemme

Tout cela concerne la version 0.6.0 de RubyGems.

RubyGems en dix secondes

Une application ou une bibliothèque est rassemblée dans une gemme, qui est un élément d’installation unique.

RubyGems utilise exclusivement son propre système de fichier, plutôt que d’installer les fichiers à leurs emplacements « habituels ». Cela permet d’obtenir de nouvelles fonctionnalités et augmente la fiabilité du système.

Fonctionnalités importantes

Installation distante de paquets
Gestion des dépendances
Désinstallation facile et fiable
Fonctionnalités de requête, locale et distante
Possibilité d’avoir plusieurs versions du même paquet installées
Interface web pour visualiser la documentation de vos gemmes

Avantages

En utilisant RubyGems, vous pouvez :

télécharger et installer des librairies Ruby facilement ;
ne pas vous soucier des dépendances entre telle librairie A et telle autre librairie B par rapport à une librairie C sous différentes versions ;
retirer facilement des librairies que vous n’utiliseriez plus ;
avoir un contrôle sur votre plateforme Ruby !

Utiliser RubyGems

Ici, nous montrons diverses situations d’utilisation sans trop les commenter. Pour plus d’informations, reportez-vous au Guide de l’utilisateur RubyGems.

Installer RubyGems

Récupérez RubyGems depuis http://rubyforge.org/frs/?group_id=126 et lancez (en tant que root si approprié et nécessaire, avec su ou sudo) :

ruby install.rb

C’est simple. Cela installe les fichiers de bibliothèques requis et la commande gem. Cette commande vous permet de faire tout ce qui se trouve dans ce document, excepté la distribution de gemmes (pour le moment !).

[Note] Linux Debian : Debian n’inclut pas actuellement toutes les bibliothèques Ruby standards dans le paquet de base Ruby. Cela implique que vous aurez certainement besoin de faire apt-get libyaml-ruby et libzlib-ruby avant que vous puissiez installer RubyGems.

Lister les gems distants disponibles

Lorsque vous lancez

gem query --remote        # raccourcir : gem q -r

vous obtenez une liste de tous les gems présents sur le serveur distant.

Court extrait de la liste retournée :

*** REMOTE GEMS ***

activerecord (0.8.4, 0.8.3, 0.8.2, 0.8.1, 0.8.0, 0.7.6, 0.7.5)
   Implements the ActiveRecord pattern for ORM.

BlueCloth (0.0.4, 0.0.3, 0.0.2)
   BlueCloth is a Ruby implementation of Markdown, a text-to-HTML
   conversion tool for web writers. Markdown allows you to write using
   an easy-to-read, easy-to-write plain text format, then convert it to
   structurally valid XHTML (or HTML).

captcha (0.1.2)
   Ruby/CAPTCHA is an implementation of the 'Completely Automated
   Public Turing Test to Tell Computers and Humans Apart'.

cardinal (0.0.4)
   Ruby to Parrot compiler.

cgikit (1.1.0)
   CGIKit is a componented-oriented web application framework like
   Apple Computers WebObjects.  This framework services
   Model-View-Controller architecture programming by components based
   on a HTML file, a definition file and a Ruby source.
 
progressbar (0.0.3)

   Ruby/ProgressBar is a text progress bar library for Ruby.  It can
   indicate progress with percentage, a progress bar, and estimated
   remaining time.

rake (0.4.0, 0.3.2)
   Ruby based make-like utility.

Le gem progressbar est un utilitaire simple qui va nous servir à expérimenter d’autres fonctionnalités.

Rechercher des gems distants disponibles

Lorsque vous lancez

gem query --remote --name-matches doom    # raccourci : gem q -r -n doom

vous obtenez une liste détaillée de gems correspondant à votre recherche et disponibles sur le serveur.

Extrait :

REMOTE GEMS *

ruby-doom (0.8, 0.0.7)
Ruby-DOOM provides a scripting API for creating DOOM maps. It also
provides higher-level APIs to make map creation easier.

Installer un gem distant

Lorsque vous lancerez (en tant que root, si approprié et nécessaire)

gem install --remote progressbar         # raccourci : gem i -r progressbar

le gem progressbar sera installé sur votre ordinateur. Notez que vous n’avez pas besoin de spécifier la version, mais vous pouvez si vous le voulez. Par défaut, c’est la dernière version qui sera installé.

gem ins -r progressbar-0.0.3

gem ins -r progressbar --version '> 0.0.1'

Dans ces deux cas, vous obtiendrez simplement :

Attempting remote installation of 'progressbar'
Successfully installed progressbar, version 0.0.3

RubyGems vous autorise à avoir plusieurs versions d’une librairie installées et de choisir dans votre code quelle version vous souhaitez utiliser.

Parmi les options d’installation utiles, on trouve —gen-rdoc qui génère la documentation RDoc du gem, et —run-test qui lance les unités de test du gem, s’il en existe.

Notez également que lorsque vous installer un gem distant, cela téléchargera et installera également toute dépendance nécessaire. Vous pouvez essayer d’installer copland et voir que RubyGems vous demande si vous acceptez d’installer log4r également (s’il n’est pas déjà installé).

Obtenir des informations sur un gem installé

Lorsque vous lancez

gem query --local progressbar         # raccourci: gem q -l progressbar

vous obtenez tous les détails sur le gem progressbar.

Extrait :

 --- !ruby/object:Gem::Specification
 rubygems_version: "1.0"
 name: progressbar
 version: !ruby/object:Gem::Version
   version: 0.0.3
 date: 2004-03-20 20:03:00.679937 +11:00
 platform:
 summary: "Ruby/ProgressBar is a text progress bar library for Ruby.  It can
           indicate progress with percentage, a progress bar, and estimated
           remaining time."
 require_paths:
   - lib
 files:
   - sample/test.rb
   - lib/progressbar.rb
   - docs/progressbar.en.rd
   - docs/progressbar.ja.rd
   - ChangeLog
 autorequire: progressbar
 author: Satoru Takabayashi
 email: satoru@namazu.org
 homepage: http://namazu.org/~satoru/ruby-progressbar/

C’est un moyen simple d’accéder à quelques informations utiles sur l’auteur, la version et la description du gem.

Sont également mentionnées des informations techniques importantes pour que RubyGems utilise correctement ce gem. Cela inclus la liste des fichiers du gem, où inclure ces fichiers, et quelle information passer à require par défaut (plus d’informations sur ce point par la suite).

Utiliser un gem dans votre code

Prenons le gem progressbar comme exemple. Cette librairie peut toutefois utiliser des fonctionnalités que votre console ne possède pas sur votre système.

Si vous le souhaitez, écrivez le code suivant dans un fichier et lancez-le.


require 'rubygems'
require_gem 'progressbar'

# Crée une barre de progression qui va de 0 à 100% par palier aléatoires.

barre = ProgressBar.new("Programme exemple", 100)
total = 0
until total >= 100
  sleep(rand(2)/2.0)
  increment = (rand(6) + 3)
  barre.inc(increment)
  total += increment
end

Voici un « aperçu » de la barre en cours de progression.

Programme exemple :  29% |ooooooooooo                             | ETA:  00:00:04

Il y a deux lignes importantes dans ce bout de code, toutes deux en haut.

require 'rubygems'

Sans cela, on ne peut pas accéder aux fonctionnalités de RubyGems.

require_gem 'progressbar'

C’est le point central. Avec cette ligne, RubyGems autorise l’utilisation du gem progressbar que nous avons installé. La librairie par défaut (également nommée progressbar) a été implicitement chargée pour nous. Si nous avons besoin de le faire, nous pouvons charger plus de fichiers provenant de librairie de ce gem, comme s’il avait été installé « normalement. »

[Note] : vous pourriez essayer, à titre d’exercice, de lancer ce code avec puis sans le gem progressbar installé. Voyez ci-dessous pour la désinstallation d’un gem.

Spécifier une version

Imaginons qu’à moyen terme, l’auteur de progressbar mette à disposition la version 1.0 avec une API qui serait incompatible avec ce que nous aurions codé auparavant. Ce que nous pouvons faire, pour nous assurer que notre code sera toujours fonctionnel, c’est de remplacer la ligne require_gem par celle-ci :

require_gem 'progressbar', '< 1.0'

Ainsi, si nous mettons à disposition notre code sous la forme d’un gem, nous pouvons spécifier explicitement quelle version de progressbar sera requise, de sorte que les utilisateurs qui installeront notre gem installent dans le même temps une version appropriée de progressbar.

Désinstaller un gem

Comme nous en avons terminé avec progressbar, nous pouvons le désinstaller.

gem uninstall progressbar

Extrait :

Successfully uninstalled progressbar version 0.0.3

S’il y a plus d’une version du gem installées, la commande gem vous demandera quelle version supprimer.

Lister tous les gems installés

Rien de plus simple :

gem query --local         # raccourci : 'gem q -L'

Note sur les opérations locales et distantes

Vous avez sans doute remarqué que les options —local et —remote figurent sur la plupart des lignes de commandes vues jusqu’à présent. Si vous ne spécifiez aucune de ces deux options, la commande gem essayera (en général) les deux localisations (locale et distante). Par exemple :

gem ins rake             # Essaye une installation locale ;
                        # se connecte au serveur distant si nécessaire.
gem list -b ^C           # Liste tous les gems locaux ET distants commençant par « C »

Navigation dans les gems installés et leurs documentation

Vous pouvez lancer votre propre serveur gem. Cela signifie que les utilisateurs externes peuvent (potentiellement) installer des gems depuis votre ordinateur. En contre-partie, vous pouvez voir vos propres gems installés via votre navigateur. Faites simplement :

gem_server

et connectez-vous à l’adresse http://localhost:8808.

Vous serez alors en mesure de consulter la documentation pour chaque gem, si tant est que vous avez demandé à ce qu’elle soit générée lors de leur installation.

Utiliser un fichier de configuration

Si vous souhaitez que la documentation RDoc soit toujours générée et lancer les unités de test pour chaque gem que vous installez, vous pouvez spécifier ces options de la commande gem directement dans un fichier de configuration (.gemrc dans votre répertoire personnel).

gem: --gen-rdoc --run-tests

Il y a plusieurs autres choses que vous pouvez manipuler avec un fichier de configuration (les paramètres de RDoc, de GEMPATH). Voyez Référence Gem pour plus de détails.

Fabriquer un gem

mise à jour : pour obtenir un squelette de gem a modifier, utiliser les commandes suivantes:



 gem install newgem

 newgem foo

Le répertoire foo a été créé et contient un fichier foo/Rakefile qui doit être modifié en premier. Pour la
suite il faut lire le code et parler a ses amis.

Il ne s’agit ici que d’un aperçu très rapide. Consultez le Guide du développeur RubyGems pour une documentation complète.

Disons que nous avons un paquet nommé rmagic qui en est à sa version 2.1

Fabriquer un gem se fait en deux étapes :

créer un fichier de spécification pour le gem (rmagic.gemspec), qui est du code Ruby
lancer gem build my.gemspec pour créer le fichier gem (rmagic-2.1.gem)

La spécification contient du code Ruby qui crée un objet Gem::Specification, ayant pour fonction de définir toutes les informations que nous avons vu plus avant dans la section Lister les informations d’un gem.

Le fichier gem contient tout ce qui est nécessaire pour s’installer lui-même sur un autre ordinateur, y compris la spécification et les fichiers de données.

Créer un gem n’est pas plus compliqué !

[Note] : rake est une aide précieuse pour gérer les gems successifs d’un projet, où les numéros de versions changent constamment etc.

Autres fonctionnalités

gem check —alien indiquera la présence de tout fichier corrompu dans le dépôt RubyGems. gem check —verify progressbar vérifiera la validité du gem progressbar installé par rapport à son checksum.

Distribuer un gem

Vous pouvez mettre à disposition un gem en téléchargement manuel. Dans cette introduction, l’installation d’un gem en local n’est pas présentée car il est plus pratique pour un utilisateur courant d’installer un gem depuis le serveur distant.

Rubyforge ajoutera automatiquement tout fichier .gem que vous chargerez sur le site dans une zone de projet. Pour distribuer un gem, il est conseillé de se créer un compte RubyForge et de lancer un projet indépendant. Même si vous n’utilisez que la partie de téléchargement, cela vous fournit un site miroir pour votre applications, au cas où votre propre site ne serait plus accessible.

Remarques finales

Ce guide a abordé toutes les fonctionnalités de bases de RubyGems, et devrait vous avoir donné une idée de ce dont il s’agit, ainsi que la confiance nécessaire pour tester RubyGems.

RubyGems fonctionne grâce au soutien des programmeurs fournissant des paquets, et par l’essor de Ruby lui-même. Même sans savoir que YAML, Rdoc, ZLib, MD5 et même WEBrick font souvent parti des nouvelles applications Ruby, la création d’un gem avec RubyGems ne devrait pas vous poser de problème.

L’intérêt de RubyGems est que les gems sont faciles à utiliser et à fabriquer. Vous pouvez contribuer à la reconnaissance de RubyGems par divers moyens :

si vous êtes un auteur de paquet, créez un gem et soumettez-la au dépôt central ;
si vous êtes un utilisateur de Ruby et/ou de RubyGems, encouragez et aidez les auteurs de gems à en fournir d’avantage.

Les sujets suivants n’ont pas été abordés dans la présente introduction :

installation locale et autres opérations
spécifier le dépôt de base de RubyGems
manipuler différentes versions d’un gem
gérer les dépendances

[Note finale] : bien que RubyGems marche bien, il s’agit toujours d’une application récente. Ce document sera mis à jour en suivant au mieux les sorties de nouvelles versions de RubyGems.