Release file API

From RubyPackager

Jump to: navigation, search

Contents

[edit] Description

A release file will give all information needed to release a library/binary. Information provided in this file does not depend on a specific release (don't specify version, release comment...).

[edit] File structure

[edit] Overview

A release file is basically a Ruby file that has to return a Ruby object describing the project. Please note that no Ruby knowledge is needed to write simple release files (should be most of the time, or else there is something wrong with RubyPackager).

A release information is composed of a set of sections:

  • Author: Information shared by all projects made by the same author.
  • Project: Information specific to this given project.
  • Executable: Information useful to release executable projects.
  • Install: Information useful to installers only.
  • Gem: Information useful to generate Gems for RubyGems only.
  • SourceForge: Information describing SourceForge's properties for this project.
  • RubyForge: Information describing RubyForge's properties for this project.
  • Core files: List of files to include in the release, or part of the final executable.
  • Additional files: List of files to add to the release, not part of the executable itself (README...)
  • Test files: List of files needed to test your project (useful for development releases for example).

Each section is optional (RubyPackager will then define default values on its sole discretion).

If you don't want to dive into Rubish internals of this file, you can skip to the examples provided below, they should be explicit enough for you to write your release file.

[edit] Ruby description

The Ruby object to return is of class RubyPackager::ReleaseInfo. This class has distinct methods to declare each information section:

  • A set of methods taking a map of symbols and objects describing each section:
  • A set of methods adding files to release:
  • A method checking if everything is releasable (can be defined optionally if needed)
    • check_ready_for_release

Each one of these methods (except check_ready_for_release) returns the same RubyPackager::ReleaseInfo object, allowing cascading calls to the methods (author( ... ).project( ... ).gem( ... )) therefore greatly improving readability and maintenance of release info files.

[edit] Examples

[edit] A simple Ruby executable: The RubyPackager itself release file

RubyPackager is considered as an executable Gem.

RubyPackager::ReleaseInfo.new.
 author(
   :name => 'Muriel Salvan',
   :email => 'muriel@x-aeon.com',
   :web_page_url => 'http://murielsalvan.users.sourceforge.net'
 ).
 project(
   :name => 'RubyPackager',
   :web_page_url => 'http://rubypackager.sourceforge.net/',
   :summary => 'Solution to release Ruby programs on any platform.',
   :description => 'Generate installable binary distributions of Ruby programs for many platforms (many OS, with or without Ruby installed on clients...). Fit to distribute extensible (plugins) Ruby programs also. Handles also libraries and uploads on websites (SF.net...).',
   :image_url => 'http://rubypackager.sourceforge.net/wiki/images/c/c9/Logo.png',
   :favicon_url => 'http://rubypackager.sourceforge.net/wiki/images/2/26/Favicon.png',
   :browse_source_url => 'http://github.com/Muriel-Salvan/Ruby-Packager',
   :dev_status => 'Beta'
 ).
 add_core_files( [
   '{lib,bin}/**/*'
 ] ).
 add_test_files( [
   'test/**/*'
 ] ).
 add_additional_files( [
   'README',
   'LICENSE',
   'AUTHORS',
   'Credits',
   'ChangeLog'
 ] ).
 gem(
   :gem_name => 'RubyPackager',
   :gem_platform_class_name => 'Gem::Platform::RUBY',
   :require_path => 'lib',
   :has_rdoc => true,
   :test_file => 'test/run.rb',
   :gem_dependencies => [
     [ 'rUtilAnts', '>= 1.0' ],
     'allinoneruby',
     'highline'
   ]
 ).
 source_forge(
   :login => 'murielsalvan',
   :project_unix_name => 'rubypackager',
   :ask_for_key_passphrase => true
 ).
 ruby_forge(
   :project_unix_name => 'rubypackager'
 ).
 executable(
   :startup_rb_file => 'bin/Release.rb'
 )

[edit] A simple library: The RDI release file

RDI is considered as a library.

RubyPackager::ReleaseInfo.new.
 author(
   :name => 'Muriel Salvan',
   :email => 'muriel@x-aeon.com',
   :web_page_url => 'http://murielsalvan.users.sourceforge.net'
 ).
 project(
   :name => 'RDI: Runtime Dependencies Installer',
   :web_page_url => 'http://rdi.sourceforge.net/',
   :summary => 'Library allowing applications to ensure their dependencies at runtime with UI support.',
   :description => 'RDI is a library that gives your application the ability to install its dependencies at runtime. Perfect for plugins oriented architectures. Many kind of deps: RPMs, DEBs, .so, .dll, RubyGems... Easily extensible to new kinds.',
   :image_url => 'http://rdi.sourceforge.net/wiki/images/c/c9/Logo.png',
   :favicon_url => 'http://rdi.sourceforge.net/wiki/images/2/26/Favicon.png',
   :browse_source_url => 'http://rdi.svn.sourceforge.net/viewvc/rdi/',
   :dev_status => 'Alpha'
 ).
 add_core_files( [
   'lib/**/*'
 ] ).
 add_test_files( [
   'test/**/*'
 ] ).
 add_additional_files( [
   'README',
   'LICENSE',
   'AUTHORS',
   'Credits',
   'ChangeLog'
 ] ).
 gem(
   :gem_name => 'RDI',
   :gem_platform_class_name => 'Gem::Platform::RUBY',
   :require_path => 'lib',
   :has_rdoc => true,
   :test_file => 'test/run.rb',
   :gem_dependencies => [
     [ 'rUtilAnts', '>= 0.1' ]
   ]
 ).
 source_forge(
   :login => 'murielsalvan',
   :project_unix_name => 'rdi'
 ).
 ruby_forge(
   :project_unix_name => 'rdi'
 )

[edit] A more complexe example: The PBS release file

PBS is considered as a running executable needing a NSIS installer for Windows. You can see in this release file that the ReleaseInfo class was derived to implement the checkReadyForRelease method and to adapt the files to include in the release dynamically. Please also note that the different sections' descriptions have been put in the constructor in a non-cascaded way, but in subsequent calls instead.

module PBS
 
 class ReleaseInfo < RubyPackager::ReleaseInfo
   
   # Constructor
   # 
   # Parameters::
   # * *iRootDir* (_String_): The root dir
   # * *iIncludeRubyGems* (_Boolean_): Do we include RubyGems in the release ?
   # * *iIncludeWxRuby* (_Boolean_): Do we include WxRuby in the release ?
   # * *iIncludeAllExt* (_Boolean_): Do we include all ext directory in the release ?
   def initialize(iRootDir, iIncludeRubyGems, iIncludeWxRuby, iIncludeAllExt)
     super()
     @IncludeWxRuby = iIncludeWxRuby
     # Define needed attributes
     author(
       :name => 'Muriel Salvan',
       :email => 'murielsalvan@users.sourceforge.net',
       :web_page_url => 'http://murielsalvan.users.sourceforge.net'
     )
     project(
       :name => 'PBS: Portable Bookmarks and Shortcuts',
       :web_page_url => 'http://pbstool.sourceforge.net/',
       :summary => 'Cross-platform explorer shipping your Internet bookmarks and workspace\'s shortcuts.',
       :description => 'Cross platform GUI managing bookmarks and shortcuts in a portable way. Support import/export, search, encryption, hierarchical tags, USB key installation, various environments integration, OS-dependent shortcuts, plugins extensibility.',
       :image_url => 'http://pbstool.sourceforge.net/wiki/images/2/26/Favicon.png',
       :favicon_url => 'http://pbstool.sourceforge.net/wiki/images/2/26/Favicon.png',
       :browse_source_url => 'http://pbstool.svn.sourceforge.net/viewvc/pbstool/',
       :dev_status => 'Alpha'
     )
     add_core_files( [
       'Tips.txt',
       'lib/pbs/*.rb',
       'lib/pbs/Common/*.rb',
       'lib/pbs/Controller/*.rb',
       'lib/pbs/Model/*.rb',
       'lib/pbs/Windows/*.rb',
       'lib/pbs/Windows/OptionsPanels/*.rb',
       'ext/rUtilAnts/**/*',
       'ext/RDI/**/*',
       'bin/pbs.rb'
     ] )
     add_additional_files( [
       'AUTHORS',
       'LICENSE',
       'README',
       'ChangeLog',
       'Credits',
       'lib/pbs/Plugins/**/*',
       'lib/pbs/Graphics/**/*'
     ] )
     if (iIncludeAllExt)
       # Include everything in the external directory
       add_additional_files( [
         "ext/#{RUBY_PLATFORM}/**/*"
       ] )
     elsif (iIncludeWxRuby)
       # Include WxRuby from the external directory
       lFound = false
       Dir.glob("#{iRootDir}/ext/#{RUBY_PLATFORM}/LocalGems/gems/wxruby*").each do |iFileName|
         if (File.directory?(iFileName))
           add_additional_files( [
             "#{iFileName}/**/*"
           ] )
           lFound = true
         end
       end
       if (!lFound)
         puts "!!! No delivery of wxruby has been found in #{iRootDir}/ext/#{RUBY_PLATFORM}/wxruby*"
       end
     end
     gem(
       :gem_name => 'PBS',
       :gem_platform_class_name => 'Gem::Platform::RUBY',
       :require_path => 'lib',
       :has_rdoc => true,
       :gem_dependencies => [
         [ 'rUtilAnts', '>= 0.1' ],
         [ 'RDI', '>= 0.1' ]
       ]
     )
     source_forge(
       :login => 'murielsalvan',
       :project_unix_name => 'pbstool'
     )
     ruby_forge(
       :project_unix_name => 'pbs'
     )
     executable(
       :startup_rb_file => 'bin/pbs.rb',
       :exe_name => 'pbs',
       :icon_name => "Distribution/#{RUBY_PLATFORM}/Icon.ico",
       :terminal_application => false
     )
     install(
       :nsis_file_name => "Distribution/#{RUBY_PLATFORM}/Installer/install.nsi"
     )
   end
   
   # Check if the tools needed for the release are ok
   # This is meant to be overriden if needed
   #
   # Parameters:
   # * *iRootDir* (_String_): Root directory from where the release is happening
   # Return:
   # * _Boolean_: Success ?
   def check_ready_for_release(iRootDir)
     rSuccess = true
     
     # Check that the tools we need to release are indeed here
     if (@IncludeWxRuby)
       if ((!File.exists?("#{iRootDir}/ext/#{RUBY_PLATFORM}/LocalGems/gems")) or
           (Dir.glob("#{iRootDir}/ext/#{RUBY_PLATFORM}/LocalGems/gems/wxruby*").empty?))
         puts "!!! Need to have wxruby installed in #{iRootDir}/ext/#{RUBY_PLATFORM}/LocalGems/gems to release including wxruby."
         rSuccess = false
       end
     end
     
     return rSuccess
   end
   
 end
 
end

PBS::ReleaseInfo.new(Dir.getwd, true, true, true)
Personal tools