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
ou
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 fooLe 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.
