outsider 0.0.1

data/README.rdoc

@@ -0,0 +1,160 @@
+==Introduction
+Outsider is a rubygems plugin which allows a gem to install files outside its own directory.
+
+===History
+Outsider was born because an application I am developing needed to install icons and desktop
+files in a system wide directory (such as <tt>/usr/share</tt>) to correctly integrate
+with the desktop environment. Since (as far as I know) rubygems doesn't offer this
+possibility, but I definitly wanted the user to install my application using a
+simple <tt>gem install</tt> command, rather than using a more complicated build
+system, I decided to write a general rubygems plugin allowing this.
+
+===Features
+* Allows a gem developer to specify which files should be installed system-wide,
+  and where exactly to install them, in a YAML file called outsider_files
+  placed in the top level directory of the gem
+* Missing directories in the installation path are created automatically
+* Allows ERB tags in the installation paths, so that they can be tailored on the
+  user's system
+* Automatically detects whether the gem is being installed globally or in the user's
+  home directory. Allows to specify two different installation paths or changes
+  the default installation path so that files are installed in the home directory
+  in case of a user install
+* Automatically handles uninstalls of the files when the gem is installed
+* In case two gems (including multiple versions of the same gem) install a file
+  in the same place, automatically reinstalls the file owned by the older gem when
+  the newer one is installed
+  
+===Drawbacks
+* To find out whether a user or a system-wide install is being performed, Outsider
+  checks whether the gem installation directory is a subdirectory of <tt>ENV['HOME']</tt>.
+  This means that things will break if you have the +GEM_HOME+ environment variable
+  also pointing to a subdirectory of your home directory. This should be a rare
+  situation, however.
+* When multiple gems install a file in the same place, the gem installed last will
+  overwrite the file installed by the other gem, so only the last version of the
+  file will be availlable. This should only be an issue when having different versions
+  of the same gem installed (as different gems shouldn't install the same file).
+  This can lead to problems if an older version of the gem is loaded and if the
+  files installed by different versions of the gem are incompatible.
+* It is only tested on linux. It should work on UNIX-like systems. As it is, I'm
+  almost positive it doesn't work on Windows. Most of the plugin is system-independent,
+  but there will be issues with default paths and user-installs.
+  
+==Usage
+To have Outsider install files outside the gem directory, you need to include in
+the gem sources a file called +outsider_files+ containing a YAML hash. Note that
+both the +outsider_files+ and the files to install should be added to the +source+
+attribute of the gem specification object.
+
+Keys in the hash represent the paths of the files to install relative to the gem directory,
+while entries can be either strings or arrays with two elements. If the entry is
+an array, the first element is the installation path in case of a system-wide install,
+while the second is the the path in case of a user install. In all cases, installation
+paths can contain ERB templates. In the case of a user install, you can specify
+the user's home directory with ~ (but only at the beginning of the file). You *can't*
+use this way to specify another user's home directory, however.
+
+In all cases, if the destination path (after all replacements have been carried out)
+ends with a slash (+/+), the name of the original file (as returned by File.basename)
+is appended to it.
+
+===User installs
+The following algorithm is used to determine the path to install a given file
+in case of user install:
+* if the entry associated with a file is an array, the second value in the array
+  will be used. If it's a relative path (that is, it doesn't start with +/+), then
+  it is assumed to be relative to the home directory. For example, if the second
+  entry of the array is <tt>abc/def.rb</tt>, then the file will be installed in
+  <tt>ENV['HOME']/abc/def.rb</tt>
+* if the entry associated with the file is a string, the path it contains is considered
+  relative to the user's home directory (even if the path is absolute). So, if the
+  path is <tt>/xyz/abc.rb</tt>, it will be installed in <tt>ENV['HOME']/xyz/abc.rb</tt>.
+  However, often this is not what one wants. For example, a file usually installed
+  in <tt>/usr/local/</tt> should be installed directly in <tt>ENV['HOME']</tt>,
+  not in <tt>ENV['HOME']/usr/local</tt>. To avoid this, the following replacements
+  are performed *at the beginning of the string*:
+  * <tt>/bin/</tt> -> <tt>ENV['HOME']/bin</tt>
+  * <tt>/sbin/</tt> -> <tt>ENV['HOME']/bin</tt>
+  * <tt>/usr/sbin/</tt> -> <tt>ENV['HOME']/bin</tt>
+  * <tt>/usr/local/share/</tt> -> <tt>ENV['HOME']/.local/share</tt>
+  * <tt>/usr/share/</tt> -> <tt>ENV['HOME']/.local/share</tt>
+  * <tt>/usr/</tt> -> <tt>ENV['HOME']</tt>
+  * <tt>/usr/local/</tt> -> <tt>ENV['HOME']</tt>
+  * <tt>/var/</tt> -> <tt>ENV['HOME']</tt>
+  * <tt>/opt/</tt> -> <tt>ENV['HOME']</tt>
+  * <tt>/etc/</tt> -> <tt>ENV['HOME']</tt>
+  
+  For example, if the installation path is <tt>/usr/local/share/my_dir/my_file</tt>,
+  in case of a user install the file will be installed in <tt>ENV['HOME']/.local/share/my_dir/my_file</tt>.
+  If you don't want this replacements to be performed, then you need to specify
+  a separate path for the user install (by using an array rather than a string
+  in +outsider_files+).
+
+In all cases, all these operations are carried out *after* having expanded the
+ERB templates.
+
+===Example
+
+This is an example +outsider_files+.
+
+ file1: /usr/share/file1
+ file2: "<%= `kde4-config --path apps`.strip.split(':')[-1]%/file2>"
+ dir/file3: [/usr/file3, "<%=File.join ENV['HOME'], 'dir', 'file3'%>"]
+ file4: [/etc/file4, my_dir/file4]
+ file5: /usr/dir/
+ file6: [/usr/file6, ~/test/file6]
+ 
+In case of a global installation, this produces the following files (note that the
+third entry depends on your system and will break if you dont't have the kde4-config
+program in your PATH):
+* <tt>/usr/share/file1</tt>
+* <tt>/usr/share/applnk/file2</tt>
+* <tt>/usr/file3</tt>
+* <tt>/etc/file4</tt>
+* <tt>/usr/dir/file5</tt>
+* <tt>/usr/file6</tt>
+
+In case of a user install, this is what you'd get (assuming your home directory
+is <tt>/home/your_name</tt>):
+* <tt>/home/your_name/.local/share/file1</tt>
+* <tt>/home/your_name/applnk/file2</tt>
+* <tt>/home/your_name/dir/file3</tt>
+* <tt>/home/your_name/file4</tt>
+* <tt>/home/your_name/file5</tt>
+* <tt>/home/your_name/test/file6</tt>
+
+=== The record file
+To keep track of which files each gem has installed, Outsider uses files called
++record_files+.
+
+A record file contains a list of files installed using Outsider, together with
+the gems which installed them and the _full path_ of the original files from which
+they were installed.
+
+There are two record files, one used to keep trace of files installed during global
+installations and one used for user installations. The latter is always
+<tt>ENV['HOME']/.outsider/installed_files</tt>, while the former is determined
+according to the following algorithm:
+* if the +OUTSIDER_RECORD_FILE+ environment variable is set, the path it contains
+  will be used (this is mainly for testing, you shouldn't use it)
+* if the +OUTSIDER_RECORD_FILE+ environment variable isn't set and the file
+  <tt>/etc/outsider.conf</tt> exists and contains a single filename, then that
+  file will be used
+* otherwise the file <tt>/var/lib/outsider/installed_files</tt> will be used
+
+If a file with the same name as the record file already exists but is not a valid
+record file, a warning will be issued, the file will be renamed and a new record
+file will be created.
+
+If the record file is deleted or becomes broken, already installed files won't
+be uninstalled any more. The next time you install a gem, a new record file will
+be created.
+
+==Author
+Stefano Crocco (stefano.crocco@alice.it)
+
+== License
+Outsider is Copyright © 2010 Stefano Crocco.
+
+Outside is free software and is distributed under the terms of the Ruby license

data/lib/outsider/outsider.rb

@@ -0,0 +1,305 @@
+# Copyright (c) 2010 Stefano Crocco <stefano.crocco@alice.it>
+# Distributed under the terms of the Ruby license
+
+require 'yaml'
+require 'fileutils'
+require 'erb'
+require 'pathname'
+
+# Namespace for the Outsider gem
+module Outsider
+  
+  # Class which installs and uninstalls files
+  class Installer
+    
+    # The path of the record file to use if the +OUTSIDER_RECORD_FILE+
+    # environment variable is unset
+    DEFAULT_RECORD_FILE = File.join '/', 'var', 'lib', 'outsider', 'installed_files'
+    
+    # Exception raised when the record file is not a valid record file
+    class InvalidRecordFile < StandardError
+      
+      # The path of the invalid record file
+      attr_reader :file
+      
+      # Creates a new instance
+      # 
+      # _file_ is the name of the invalid record file, while _msg_ is a message
+      # describing why the file is invalid
+      def initialize file, msg
+        @file = file
+        super msg + ": #{@file}"
+      end
+      
+    end
+    
+    # Creates a new instance
+    # 
+    # _dir_ is the directory where to look for the outsider_files file and the
+    # files to install
+    def initialize dir
+      @gem_dir = dir
+      @user_install = dir.start_with? ENV['HOME']
+      @data = begin 
+        YAML.load File.read(File.join(dir, 'outsider_files'))
+      rescue SystemCallError
+      end
+      # If either the outsider_files file doesn't exist or it's empt
+      # (in which case YAML.load returns false), set @data to an empty hash
+      @data ||={}
+      @gem_name = File.basename(dir)
+    end
+    
+    # Installs the files according to the instructions in the outsider_files
+    # file
+    # 
+    # Returns *nil*
+    def install_files
+      installed_files = []
+      @data.each_pair do |k, v|
+        dest = install_destination v
+        dest = File.join dest, File.basename(k) if dest.end_with? '/'
+        orig = File.join(@gem_dir, k)
+        installed_files << [orig, dest] if install_file orig, dest
+      end
+      record_installed_files installed_files unless installed_files.empty?
+      nil
+    end
+    
+    # Uninstalls the files associated with the gem in the current directory
+    # 
+    # If any of those file is owned also by other gems (including by other versions
+    # of the same gem), then the files are only uninstalled if the gem is the last to
+    # have been installed. In this case, the file belonging to the previously installed
+    # gem is copied. If that file doesn't exist, then the one previous to it is tried,
+    # and so on.
+    # 
+    # The record is updated to remove all mentions of the gem being uninstalled
+    # 
+    # Returns *nil*
+    def uninstall_files
+      rec_file = record_file
+      files = begin read_record_file rec_file
+      rescue InvalidRecordFile then nil
+      end
+      return unless files
+      files.each_pair do |f, data|
+        gem_data = data.find{|i| i[:gem] == @gem_name}
+        next unless gem_data
+        if data.last[:gem] == @gem_name
+          FileUtils.rm_f f 
+          data[0..-2].reverse_each do |d|
+            if File.exist? d[:origin]
+              FileUtils.cp d[:origin], f 
+              break
+            end
+          end
+        end
+        data.delete gem_data
+      end
+      files.delete_if{|k, v| v.empty?}
+      write_record_file rec_file, files
+      nil
+    end
+    
+    private
+    
+    # The path of the record file
+    # 
+    # In case of a user install, the file is always <tt>ENV['HOME']/.outsider/installed_files</tt>.
+    # In case of a global install, instead, the following algorithm is used:
+    # * if the +OUTSIDER_RECORD_FILE+ environment variable is set,
+    #   its value is used
+    # * otherwise, if the file /etc/outsider.conf exists and isn't
+    #   empty, the name of the record file is read from there
+    # * if all the above fails, then DEFAULT_RECORD_FILE is used
+    # 
+    # Returns the name of the record file to use 
+    def record_file
+      if @user_install then File.join ENV["HOME"], '.outsider', 'installed_files'
+      elsif ENV['OUTSIDER_RECORD_FILE'] then ENV['OUTSIDER_RECORD_FILE']
+      elsif File.exist?('/etc/outsider.conf')
+        file = File.read '/etc/outsider.conf'
+        file.empty? ? DEFAULT_RECORD_FILE : file
+      else DEFAULT_RECORD_FILE
+      end
+    end
+
+    # Creates the installation path for an entry in the +outsider_files+ file
+    # 
+    # _data_ is the entry and can be a string or an array with two elements. If
+    # doing a global install, then the destination file is found simply by passing the
+    # string or the first entry of the array through ERB.
+    # 
+    # In case of a user install, things are a bit more complex and change depending
+    # on whether _data_ is an array or a string
+    # * if it is an array, then the second entry will be used as path, after passing
+    #   it through ERB. If it isn't an absolute file, it'll be considered relative
+    #   to the user's home page.
+    # * if it is a string, what ERB returns will be considered a path relative to the user's
+    #   home directory. There are a few exceptions, however. If the path starts
+    #   with /usr/, /usr/local/, /var/, /opt/ or /etc/ then that directory will be
+    #   replaced with the home directory. If it starts with /usr/share or /usr/local/share,
+    #   that directory will be replaced with <tt>ENV["HOME"]/.local/share</tt>.
+    #   If it starts with /bin/, /sbin/ or /usr/sbin/, that directory will be 
+    #   replaced by <tt>ENV["HOME"]/bin</tt>.
+    #   
+    # Returns the destination path
+    def install_destination data
+      home = ENV['HOME']
+      if data.is_a? Array then path = data[@user_install ? 1 : 0]
+      else path = data
+      end
+      path = ERB.new(path).result
+      if @user_install and data.is_a? Array
+        File.expand_path path, home
+      elsif @user_install
+        replacements = [
+          [%r{^/bin/}, File.join(home, 'bin')],
+          [%r{^/sbin/}, File.join(home, 'bin')],
+          [%r{^/usr/sbin/}, File.join(home, 'bin')],
+          [%r{^/usr/local/share/}, File.join(home, '.local', 'share')],
+          [%r{^/usr/share/}, File.join(home, '.local', 'share')],
+          [%r{^/usr/local/}, home],
+          [%r{^/usr/}, home],
+          [%r[^/var/], home],
+          [%r[^/opt/], home],
+          [%r[^/etc/], home],
+          [%r{^~/}, home],
+          [%r{^(?=.)}, home]
+        ]
+        match = replacements.find{|reg, _| path.match reg}
+        File.join match[1], path.sub(match[0], '')
+      else path
+      end
+    end
+    
+# Copies the file _orig_ to _dest_
+# 
+# If the path to _dest_ doesn't exist, then the missing directories are created.
+# If the file _orig_ doesn't exist, nothing is done.
+# 
+# Returns _dest_ if the file was installed successfully and *nil* if _orig_ didn't
+# exist. Raises a subclass of SystemCallError if the file couldn't be copied, for
+# example due to wrong permissions
+    def install_file orig, dest
+      if File.exist? orig
+        begin FileUtils.cp orig, dest
+        rescue SystemCallError
+          path = Pathname.new dest
+          path.descend do |pth|
+            if pth.exist? then next
+            elsif pth == path
+              FileUtils.cp orig, dest
+            else FileUtils.mkdir pth.to_s
+            end
+          end
+        end
+        dest
+      else nil
+      end
+    end
+    
+# Adds the given files to the record file
+# 
+# The path to the record file is given by the OUTSIDER_RECORD_FILE
+# environment variable. If the variable is unset, +/var/lib/outsider/installed_files+
+# is used.
+# 
+# If the record file doesn't exist, it's created, together with any missing directory.
+# 
+# If a file with the same name as the record file exists but it's not a valid record
+# file, it will be renamed by appending a <tt>-n</tt> suffix, where _n_ is a number,
+# and a new record file will be created. A warning will be issued in this case
+# 
+# Returns *nil*
+    def record_installed_files files
+      file = record_file
+      begin 
+        data = read_record_file file
+        data ||= {}
+      rescue InvalidRecordFile 
+        data = rename_invalid_record_file file
+        retry
+      end
+      files.each do |f| 
+        (data[f[1]] ||= []) << {:gem => @gem_name, :origin => File.join(@gem_dir, f[0])}
+      end
+      write_record_file file, data
+      nil
+    end
+    
+# Write data to a given record file
+# 
+# _file_ is the name of the record file and will be created, if it doesn't exist,
+# together with the directory composing its path. _data_ is the hash to write.
+# 
+# Returns *nil*
+    def write_record_file file, data
+      record_dir = File.dirname(file)
+      FileUtils.mkdir_p record_dir unless File.directory? record_dir
+      File.open(file, 'w'){|f| YAML.dump(data, f)}
+      nil
+    end
+    
+# Reads the files installed from the given record file
+# 
+# If the file isn't a valid record file, InvalidRecordFile is raised.
+# 
+# _file_ is the name of the record file
+# 
+# Returns the hash contained in the record file or *nil* if the file doesn't exist
+    def read_record_file file
+      data = begin YAML.load File.read(file)
+      rescue ArgumentError then raise InvalidRecordFile.new file, "Invalid YAML file"
+      rescue SystemCallError 
+        return nil if !File.exist? file
+        raise
+      end
+      unless valid_record_contents? data
+        raise InvalidRecordFile.new file, "Invalid record file format" 
+      end
+      data
+    end
+    
+# Checks whether the given object is valid content for a record file
+# 
+# Returns *true* if _data_ is a legitimate content for a record file and *false*
+# otherwise
+# 
+# A valid record file has the following format (in YAML):
+# 
+#  /path/to/installed_file_1:
+#   - {:gem: name_and_version_of_gem1, :origin: path/to/original/file1}
+#   - {:gem: name_and_version_of_gem2, :origin: path/to/original/file2}
+#  /path/to/installed_file_2
+#   - {:gem: name_and_version_of_gem3, :origin: path/to/original/file3}
+#   - {:gem: name_and_version_of_gem4, :origin: path/to/original/file4}
+    def valid_record_contents? data
+      return false unless data.is_a? Hash
+      data.each_pair do |dest, v|
+        return false unless dest.is_a? String and v.is_a? Array
+        v.each do |gem|
+          return false unless gem.is_a? Hash
+          return false unless gem[:gem].is_a? String and gem[:origin].is_a? String
+        end
+      end
+      true
+    end
+    
+# Renames the invalid record file _file_ giving it a new unique name and issues a
+# warning
+# 
+# Returns *nil*
+    def rename_invalid_record_file file
+      n = 1
+      n+=1 while File.exist?( file + "-#{n}")
+      new_file = file + "-#{n}"
+      warn "The file #{file} isn't a valid record file and will be moved to #{new_file}"
+      FileUtils.mv file, new_file
+      nil
+    end
+    
+  end
+  
+end

data/lib/rubygems_plugin.rb

@@ -0,0 +1,11 @@
+require File.join(File.dirname(__FILE__), 'outsider','outsider')
+
+Gem.post_install do |inst|
+  global = Outsider::Installer.new inst.spec.full_gem_path
+  global.install_files
+end
+
+Gem.pre_uninstall do |uninst|
+  global = Outsider::Installer.new uninst.spec.full_gem_path
+  global.uninstall_files
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: outsider
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Stefano Crocco
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-04 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: 
+email: stefano.crocco@alice.it
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/rubygems_plugin.rb
+- lib/outsider/outsider.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/stcrocco/outsider
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: rubygems plugin to allow a gem to install files outside its own directory
+test_files: []
+