geminstaller 0.2.0

data/website/src/documentation/documentation.page

@@ -0,0 +1,417 @@
+h1. Detailed Documentation
+
+h2. Table of Contents
+
+* "Setup":#setup
+** "Requirements":#requirements
+** "Installation":#installation
+* "Command Line Options":#command_line_options
+** "Command Line Options Summary":#command_line_options_summary
+** "<code>--config</code> option":#config_option
+** "<code>--exceptions</code> option":#exceptions_option
+** "<code>--redirect-stderr-to-stdout</code> option":#redirect_stderr_to_stdout_option
+** "<code>--geminstaller-output</code> option":#geminstaller_output_option
+** "<code>--rubygems-output</code> option":#rubygems_output_option
+** "<code>--print-rogue-gems</code> option":#print_rogue_gems_option
+** "<code>--sudo</code> option":#sudo_option
+** "<code>--silent</code> option":#silent_option
+** "Unsuppressible Output":#unsuppressible_output
+* "Config File":#config_file
+** "Config File Syntax Summary":#config_file_syntax_summary
+** "<code>name</code> config property":#name_config_property
+** "<code>version</code> config property":#version_config_property
+** "<code>platform</code> config property":#platform_config_property
+** "<code>install_options</code> config property":#install_options_config_property
+** "<code>check_for_upgrade</code> config property":#check_for_upgrade_config_property
+** "<code>fix_dependencies</code> config property":#fix_dependencies_config_property
+** "<code>no_autogem</code> config property":#no_autogem_config_property
+** "<code>prefer_binary_platform</code> config property":#prefer_binary_platform_config_property
+* "Using GemInstaller with Ruby on Rails or Other Ruby Apps":#using_geminstaller_with_ruby_on_rails_or_other_ruby_apps
+** "Invoking <code>GemInstaller</code> from Rails":#invoking_geminstaller_from_rails
+** "Bootstrapping Rails with GemInstaller":#bootstrapping_rails_with_geminstaller
+** "Using GemInstaller from Other Ruby Apps":#using_geminstaller_from_other_ruby_apps
+* "Using <code>erb</code> in config files":#using_erb_in_config_files
+* "Automatic Platform Detection":#automatic_platform_detection
+* "Dealing with sudo and root-owned RubyGem installations":#dealing_with_sudo 
+** "Option 1 - Use the <code>-s</code>  or <code>--sudo</code> option on the <code>geminstaller</code> executable":#option_1
+** "Option 2 - Run <code>sudo</code> or log in as root yourself":#option_2
+** "Option 3 - Make everything owned by the local user that runs geminstaller":#option_3
+** "Tips on configuring sudo":#tips_on_configuring_sudo
+* "Automatically Requiring Gems with the <code>autogem</code> Method":#automatically_requiring_gems_with_the_autogem_method
+
+h2(#setup). Setup
+
+h3(#requirements). Requirements
+
+Runtime Requirements:
+* None. There are no dependencies required to run GemInstaller, other than an installation of RubyGems itself
+
+Build/Test requirements:
+* GemInstaller has a *geminstaller.yml* file to specify it's own dependencies.  After installing the geminstaller gem (via 'gem install geminstaller'), change to the root of the geminstaller source tree, and run 'geminstaller' to auto-install the dependencies.
+
+h3(#installation). Installation
+
+*Installing Latest Release:*  Run <code>'gem install geminstaller'</code> to install GemInstaller from RubyForge.  Run it via <code>'sudo'</code> if necessary, but first read the section on "Dealing with sudo and root-owned RubyGem installations":#dealing_with_sudo.
+
+*Installing Source Distribution:*  Run <code>'rake install_gem'</code> from the root of the GemInstaller source tree.  This assumes that Hoe and other required build/test dependencies are installed.  Note this currently won't work on windows because Hoe always tries to run sudo.  It will generate a pkg/geminstaller-version.gem file, though, which you can install with the <code>'gem install <pkgfile>'</code> command.  
+
+h2(#command_line_options). Command Line Options
+
+h3(#command_line_options_summary). Command Line Options Summary
+
+<pre>
+$ geminstaller --help
+Usage: geminstaller [options]
+
+    -c, --config=CONFIGPATHS         Comma-delimited path(s) to GemInstaller config file(s).
+    -e, --exceptions                 Raise any exceptions, rather than just printing them and exiting
+                                     with a non-zero return code.
+    -d, --redirect-stderr-to-stdout  Redirect all STDERR output to STDOUT.  Useful to get all output when
+                                     invoking GemInstaller via system().
+    -g, --geminstaller-output=TYPES  Comma-delimited list of output types to show from GemInstaller.
+                                       Examples:
+                                         --gall
+                                         --geminstaller-output=error,install,commandecho
+                                       Default: error,install,info
+                                       Valid types:
+                                         - none:        print only fatal errors
+                                         - error:       print error messages
+                                         - install:     print install messages
+                                         - info:        print informational messages
+                                         - commandecho: print rubygems commands as they are invoked
+                                         - debug:       print debug messages
+                                         - all:         print all messages
+    -h, --help                       Show this message.
+    -p, --print-rogue-gems           Print a report of all locally installed gems which are not specified
+                                     in the geminstaller config file.
+    -r, --rubygems-output=TYPES      Comma-delimited list of output types to show from internal:
+                                       RubyGems command invocation.
+                                       Examples:
+                                         --rall
+                                         --rubygems-output=stderr
+                                       Default: stderr
+                                       Valid types:
+                                         - none:        print no output
+                                         - stdout:      print standard output stream
+                                         - stderr:      print standard error stream
+                                         - all:         print all output
+    -s, --sudo                       Perform all gem operations under sudo (as root).  Will only work on
+                                     correctly configured, supported systems.  See docs for more info.
+    -t, --silent                     Suppress all output except fatal exceptions, and output from
+                                     rogue-gems option.
+    -v, --version                    Show GemInstaller version and exit.
+</pre>
+
+h3(#config_option). <code>--config</code> option
+
+By default, GemInstaller will look for a config file named <code>geminstaller.yml</code> in the working directory.  The <code>'--config'</code> option allows you to override this with a different file name or path.  You can also have multiple comma-delimited paths to custom-named config files.  This is useful if you have multiple projects, and want them to share a common config file, but still have project-specific overrides.  You could also have a standard set of gems across multiple systems, with additional custom gems specified by individual projects.  The last entries in the list will override the first ones.  For example: 
+
+<pre>
+geminstaller --config=../common-config/geminstaller-common-across-projects.yml,geminstaller-custom-for-myproject.yml
+</pre>
+
+h3(#exceptions_option). <code>--exceptions</code> option
+
+By default, GemInstaller will not throw exceptions for errors when invoked via <code>GemInstaller.run</code> or <code>GemInstaller.autogem</code>.  This is so that any GemInstaller errors will not abort startup of Rails or any other app other apps.  However, if you do want errors to abort startup of Rails or your app, you can set this option.
+
+h3(#redirect_stderr_to_stdout_option). <code>--redirect-stderr-to-stdout</code> option
+
+Currently, the GemInstaller <code>--sudo</code> option works by recursively re-invoking the <code>geminstaller</code> executable via <code>system()</code>.  This option is automatically added in this case to ensure that errors that would normally go to <code>stderr</code> are printed to <code>stdout</code>.  There are other solutions to this problem, but as of Ruby 1.8.5, there is no _easy_ way to make a system call which will give a return code AND show both stderr and stdout _synchronously_.  GemInstaller does not have and will not have any third-party runtime dependencies, so I needed to roll my own solution, and this was The Simplest Thing That Could Possibly Work.
+
+When RubyGems supports platform specification from the command line, I won't have to select platforms programatically via stdin, and I'll be able to invoke <code>gem</code> directly via sudo.  Until then, though, there must be this recursive hackishness to handle sudo.
+
+h3(#geminstaller_output_option). <code>--geminstaller-output</code> option
+
+The <code>--geminstaller-output</code> option controls what GemInstaller prints out about it's internal activity.  It is a comma-delimited list (no spaces), which can specify any of these output types:
+
+* none: Prints only fatal errors/exceptions which cause geminstaller to fail.  The same as specifying none of the other types.
+* error: Prints error messages.
+* install: Prints messages indicating when gems are going to be installed.  This may be gems which are directly specified in a GemInstaller config file, or dependency gems which are automatically installed to meet the requirments of a dependent gem.
+* info: Prints informational messages.
+* commandecho: Print rubygems commands as they are automatically invoked by GemInstaller.
+* debug: Prints debug messages
+* all: Prints all messages.  This is the same as specifying all of the other types (except 'none')
+
+This option works in conjuntion the <code>--rubygems-output</code>, which is used similarly, but controls output which is generated by RubyGems itself.
+
+h3(#rubygems_output_option). <code>--rubygems-output</code> option
+
+GemInstaller works by automatically invoking RubyGems commands.  The <code>--rubygems-output</code> option controls what types of output from RubyGems is printed out.  It is a comma-delimited list (no spaces), which can specify any of these output types:
+
+* none: Prints no output from RubyGems.  
+* stdout: Prints standard output stream from RubyGems.
+* stderr: Prints standard error stream from RubyGems.
+* all: Prints all messages.  This is the same as specifying all of the other types (except 'none')
+
+h3(#print_rogue_gems_option). <code>--print-rogue-gems</code> option
+
+The <code>--print-rogue-gems</code> option prints a report of all locally installed gems which are not specified in the active loaded GemInstaller config file(s).  GemInstaller, being "Narcissistic Software" (tm), considers these "rogue gems".  The output format is in YAML, so it can be cut and pasted or piped directly into a new or existing config file.  This allows you to bootstrap a new system, by creating an empty config file with no gems specified, and running geminstaller with the <code>--print-rogue-gems</code> option to identify all gems which are currently installed on the system.  It can also be used to identify gems which were manually installed without being entered into a GemInstaller config.
+
+Some gems are automatically installed with RubyGems itself.  The 'sources' gem always exists, and the Ruby Windows One Click Installer installs several windows-specific gems.  The <code>--print-rogue-gems</code> option will include these gems, but will mark them with a comment indicating that they may have been automatically installed by RubyGems.  
+
+h3(#sudo_option). <code>--sudo</code> option
+
+The <code>--sudo</code> option runs GemInstaller as root by using the <code>sudo</code> command.  This command is neither valid nor necessary on Windows platforms.  See the "Dealing with sudo and root-owned RubyGem installations":#dealing_with_sudo section for more details.
+
+h3(#silent_option). <code>--silent</code> option
+
+The <code>--silent</code> option suppresses all RubyGems output except fatal errors/exceptions.  It overrides the <code>--geminstaller-output</code> and <code>--rubygems-output</code> options.
+
+h3(#unsuppressible_output). Unsuppressible Output
+
+Sometimes, errors from RubyGems activity will still be printed even if the <code>'--geminstaller-output=none'</code> or <code>--silent</code> options are specified.  This usually due to some failure when building gem docs, or on a windows platform.  This is probably due to a gem directly printing to stderr or stdout.  GemInstaller does not currently capture this type of output, only messages which are directly generated by RubyGems itself.  This may be fixed in a later release.
+
+h2(#config_file). Config File
+
+The GemInstaller config file is simple YAML file.  It contains a section specifying all the gems you want to install, and their associated options/properties, and another section which contains defaults to apply to all gems.  By default, GemInstaller will look for a config file named *<code>geminstaller.yml</code>* in the working directory, but you can override this file name (and specify multiple config files) with the "<code>--config</code> option":#config_option.
+
+GemInstaller offers a great deal of flexibility in configuration.  By creatively using multiple config files, defaults within single config files, "<code>erb</code> in config files":#using_erb_in_config_files, and the features of YAML itself, you should be able to come up with a unified GemInstaller config approach that works for multiple applications across multiple machines, platforms, and environments, with a minimum of duplication.
+
+NOTE: Currently, the order of gems in the config file matters.  It will install them, and any dependencies, in the order listed.  This means if you have a gem listed explicitly, but it is a dependency of an earlier gem, it won't use the options you set - it will use default/inherited options from it's dependent gem.  Perhaps a future version of GemInstaller will be smart enough to handle this better.
+
+h3(#config_file_syntax_summary). Config File Syntax Summary
+
+This is an example config file template showing all the valid properties (boolean defaults capitalized):
+
+<pre>
+\---
+defaults:
+  install_options: [ any valid option for the RubyGems 'gem install' command ]
+  check_for_upgrade: [ true | FALSE ]
+  fix_dependencies: [ true | FALSE ]
+  no_autogem: [ true | FALSE ]
+  prefer_binary_platform:  [ TRUE | false ]
+gems:
+- name: [ gem name ]
+  version: '[ any valid version specification for this gem, e.g. >= 1.0.0 ]'
+  platform: [ any valid platform for this Gem and version specification ]
+  install_options: [ any valid option for the RubyGems 'gem' command ]
+  check_for_upgrade: [ true | FALSE ]
+  fix_dependencies: [ true | FALSE ]
+  no_autogem: [ true | FALSE ]
+  prefer_binary_platform: [ TRUE | false ]
+- name: [ another gem name ]
+- name: [ yet another gem name ]
+  (etc...)
+</pre>
+
+All properties are optional, except for the gem name.  If a default is specified, it will be used unless the gem specifically overrides it.
+
+h3(#name_config_property). <code>name</code> config property
+
+Required, no default.  This is the name of the gem to install.  GemInstaller always does an exact match on the name, a substring will not match.  
+
+h3(#version_config_property). <code>version</code> config property
+
+Defaults to '> 0'.  This is the version specification used to select a gem.  The highest version which meets the specification will be installed.  GemInstaller always does an exact match on the name, a substring will not match.
+
+You should enclose the version specification in single quotes.  This is not always necessary, but sometimes YAML will have trouble parsing it if you don't, so it's best to always use quotes.
+
+There are many different options for version specifications.  For more info, see the section on "Specifying Versions":http://rubygems.org/read/chapter/16 in the RubyGems User Guide.
+
+h3(#platform_config_property). <code>platform</code> config property
+
+Defaults to 'ruby'.  This is the platform for the gem.  This must match a platform which is valid and available for the gem name and version specification.  See the sections on "Automatic Platform Detection":#automatic_platform_detection and the "<code>prefer_binary_platform</code> config property":#prefer_binary_platform for more info on how platforms are handled.
+
+h3(#install_options_config_property). <code>install_options</code> config property
+
+Defaults to empty string.  The <code>install_options</code> config property can contain any option which is valid to pass to the RubyGems <code>'gem install'</code> command.  These options will be passed on when GemInstaller internally invokes RubyGems.  Type <code>gem install --help</code> to list the options.  
+
+h3(#check_for_upgrade_config_property). <code>check_for_upgrade</code> config property
+
+Defaults to false.  By default, GemInstaller will not perform any remote operations unless they are necessary to install a required gem.  In other words, if there is a local gem which meets the specs, nothing will be done.  This allows GemInstaller to still run normally when you are not connected to a network.  
+
+However, if you are using a non-specific version spec (for example, '>= 1.0.0), there COULD be a higher version available on the remote gem server.  If set to true, <code>check_for_upgrade</code> will force GemInstaller to check for a higher-versioned gem on the server which still matches the version specification, and install it if one is found.  
+
+h3(#fix_dependencies_config_property). <code>fix_dependencies</code> config property
+
+Defaults to false.  Ruby Gems can depend on other gems, but the other gem might still get manually uninstalled (by using the <code>gem uninstall --ignore-dependencies GEMNAME</code>) option.  The <code>--fix_dependencies</code> option will detect these missing dependencies, and automatically fix them.  You shouldn't need this unless you go around uninstalling gems with the <code>--ignore-dependencies</code> option.  WARNING: This option can GREATLY increase the time it takes to run GemInstaller, especially if you have a lot of gems in your config, and especially on Windows.  You probably always want it left as the default of false unless you suspect that some dependencies have been uninstalled.
+
+h3(#no_autogem_config_property). <code>no_autogem</code> config property
+
+Defaults to false.  This option will prevent the <code>autogem</code> command from automatically requiring a gem.  If you only want to require a few gems, you could set the default for this property to true, and only enable it (by setting a false value) for specific gems.  For more details see "Automatically Requiring Gems with the <code>autogem</code> Method":#automatically_requiring_gems_with_the_autogem_method.
+
+h3(#prefer_binary_platform_config_property). <code>prefer_binary_platform</code> config property
+
+Defaults to true.  GemInstaller automatically guesses at the correct platform for gem which have no platform specified.  Any platform which is not 'ruby' is considered a 'binary' platform.  
+
+This option determines whether the 'ruby' platform, or a 'binary' platform will be chosen first.  By default, binary platforms will be chosen if there is one available which seems to match the platform of the current machine.  In practice, this usually only applies to windows, since (hopefully) most gems which need to be compiled distribute a windows-specific precompiled gem version.  See "Automatic Platform Detection":#automatic_platform_detection for more info.
+
+h2(#using_geminstaller_with_ruby_on_rails_or_other_ruby_apps). Using GemInstaller with Ruby on Rails or Other Ruby Apps
+
+GemInstaller can also be embedded in another application, such as a Rails app.  This is done by invoking the GemInstaller class or the geminstaller executable directly from Ruby.  This section only contains a brief explanation, see the tutorial on "Integrating GemInstaller into Ruby on Rails":#integrating_geminstaller_into_ruby_on_rails for detailed explanation.
+
+IMPORTANT NOTE: You need to know whether you run on unix and need root/sudo access to install gems and/or gem executables.  See "Dealing with sudo and root-owned RubyGem installations":#dealing_with_sudo section for more details.
+
+First, you need to create <code>geminstaller.yml</code> in the <code>RAILS_ROOT/config</code> directory (See also "Bootstrapping your GemInstaller Config with the <code>--print-rogue-gems</code> option":#bootstrapping_your_geminstaller_config).  Here's an example config file which will install (an old version of) Rails and Mongrel:
+
+<pre>
+\---
+defaults:
+  install_options: --include-dependencies
+gems:
+- name: rails
+  version: '= 1.1.6'
+- name: mongrel
+  version: '= 1.0.1'
+  platform: <%= RUBY_PLATFORM =~ /mswin/ ? 'mswin32' : 'ruby'%>
+</pre>
+
+h3(#invoking_geminstaller_from_rails). Invoking <code>GemInstaller</code> from Rails
+
+Once you have your *<code>geminstaller.yml</code>* created, invoke the GemInstaller on app startup in your boot.rb.  It should be placed right after the block which defines the RAILS_ROOT constant, as shown below ("..." indicates omitted lines):
+
+
+*RAILS_ROOT/config/boot.rb*:
+<pre>
+...
+unless defined?(RAILS_ROOT)
+...
+end
+
+############# Begin GemInstaller config - see http://geminstaller.rubyforge.org
+require "rubygems"
+require "geminstaller"
+
+# Path(s) to your GemInstaller config file(s)
+config_paths = "#{File.expand_path(RAILS_ROOT)}/config/geminstaller.yml" 
+
+# Arguments which will be passed to GemInstaller (you can add any extra ones)
+args = "--config #{config_paths}" 
+
+# The 'exceptions' flag determines whether errors encountered while running GemInstaller
+# should raise exceptions (and abort Rails), or just return a nonzero return code
+args += " --exceptions"
+
+# This will use sudo by default on all non-windows platforms, but requires an entry in your
+# sudoers file to avoid having to type a password.  It can be omitted if you don't want to use sudo.
+# See http://geminstaller.rubyforge.org/documentation/documentation.html#dealing_with_sudo
+args += " --sudo" unless RUBY_PLATFORM =~ /mswin/ 
+
+# The 'install' method will auto-install gems as specified by the args and config
+GemInstaller.run(args)
+
+# The 'autogem' method will automatically add all gems in the GemInstaller config to your load path, using the 'gem'
+# or 'require_gem' command.  Note that only the *first* version of any given gem will be loaded.
+GemInstaller.autogem(args)
+############# End GemInstaller config
+
+unless defined?(Rails::Initializer)
+...
+</pre>
+
+As you can see, this example contains several comments which are hopefully self-explanatory.  See the "Command Line Options Summary":#command_line_options_summary, especially the "<code>--config</code>":#config_option, "<code>--exceptions</code>":#exceptions_option, and "<code>--sudo</code>":#sudo_option options for more details, as well as the "Integrating GemInstaller into Ruby on Rails":#integrating_geminstaller_into_ruby_on_rails tutorial.
+
+h3(#bootstrapping_rails_with_geminstaller). Bootstrapping Rails with GemInstaller
+
+If you don't already have Rails or Mongrel installed (you've just checked your app out or deployed onto a new machine), you obviously can't use the above boot.rb method to run GemInstaller.  In this case, you just need to run GemInstaller from the command line once to "bootstrap" and install the Rails/Mongrel gems.  This assumes you already have your <code>geminstaller.yml</code> config file in the Rails <code>config</code> dir:
+
+<pre>
+$ cd [RAILS_APP_ROOT]/config
+$ geminstaller --sudo # only use the -sudo option if necessary
+</pre>
+
+h3(#using_geminstaller_from_other_ruby_apps). Using GemInstaller from Other Ruby Apps
+
+If you want to automatically invoke GemInstaller from some other Ruby application, the approach will be very similar to the Rails approach shown above.  Instead of boot.rb, put the GemInstaller invocation into the class or script which is the very first one run when your application starts up.  To use it in build scripts such as <code>rake</code>, include it in a task.  GemInstaller (obviously) must run before any gems are loaded or referenced.
+
+h2(#using_erb_in_config_files). Using <code>erb</code> in config files
+
+The GemInstaller config file(s) are also run through erb, so you can embed any custom ruby code to dynamically generate portions of your config.  This can be used to have the same config file select gems differently on different platforms or environments.  Below is an example of using erb to detect and choose the platform.  This is necessary with some gems, even though GemInstaller attempts to guess at the platform.  See "Automatic Platform Detection":#automatic_platform_detection for more info.
+
+    <pre>
+\---
+# geminstaller-detect-platform.yml
+gems:
+- name: x10-cm17a
+  version: '> 1.0.0'
+  platform: <%= RUBY_PLATFORM =~ /mswin/ ? 'i386-mswin32' : 'ruby'%>
+</pre>
+
+h2(#automatic_platform_detection). Automatic Platform Detection
+
+Currently (as of version 0.9.2), RubyGems does not provide any way to specify a platform programatically or via the command line.  If the specified version of a gem has any binary or platform-specific releases, a list will be presented, and RubyGems will halt until input is provided via stdin.  This means that even if you write a script to install your required gems, you still have to deal with parsing the list and providing stdin input to select multi-platform gems.  To make it even more confusing, there are enforced requirements for what platforms are valid in a Gem specification file - the gem author can put whatever they want.  The RubyGems developers plan to deal with this situation in a future release, but until then...
+
+...GemInstaller solves this problem!  If a multi-platform gem version is found, GemInstaller will handle the list prompt, and automatically select the correct platform.
+
+The "correct" platform can be determined in a few ways.  The easiest way is to let GemInstaller guess at the platform for you.  It contains logic which will attempt to determine the correct platform to choose, based on the platform of the current machine.
+
+However, GemInstaller may not always guess right, especially for uncommon platforms, or gems which do not have a standard platform string specified.  In these cases, the <code>'platform'</code> property for a gems can be specified in the geminstaller config file.  If you know what platform you want for a specific gem, and you only run GemInstaller on one platform, you can hardcode this value.  Even if you run GemInstaller on multiple platforms (and therefore can't hardcode the platform string), you can use <code>erb</code> to programatically pick the correct platform.  See "Using <code>erb</code> in config files":#using_erb_in_config_files for an example.
+
+See the section on the "<code>prefer_binary_platform</code> config property":#prefer_binary_platform for more info.
+
+h2(#dealing_with_sudo). Dealing with sudo and root-owned RubyGem installations 
+
+If you only run geminstaller on Windows, you don't have to worry about this section :)
+
+On many unix-like systems (Mac, Linux, etc.), the root user will own the local installation of RubyGems (often /usr/local/ruby) and/or the executable directory where gem executables are installed (often /usr/local/bin).  If this is the case, then gems must be installed and uninstalled by the root user, or via the sudo command.  This presents a problem for geminstaller, which must have this same permission to automatically install gems.
+
+There are several different solutions this problem.  The solutions that are available are also determined by the way you use geminstaller (whether you call it from the executable, or use the GemInstaller classes directly from Ruby).
+
+A transparent solution to this problem is planned for a future release of GemInstaller.  For now, however, you will need to pick one of the following approaches below.  If you use sudo, you should also read the docs on configuring sudo.
+
+h3(#option_1). Option 1 - Use the <code>-s</code>  or <code>--sudo</code> option on the <code>geminstaller</code> executable
+
+Examples:
+<pre>
+$ geminstaller -s
+$ geminstaller --sudo
+</pre>
+
+h3(#option_2). Option 2 - Run <code>sudo</code> or log in as root yourself
+
+Example of using sudo:
+<pre>
+$ sudo geminstaller
+</pre>
+
+Examples of running geminstaller as root
+<pre>
+$ su -      # if you can log in as root on your system, OR
+$ sudo -s   # if you must use sudo to log in as root on your system 
+# geminstaller
+</pre>
+
+h3(#option_3). Option 3 - Make everything owned by the local user that runs geminstaller
+
+(replace <code><local user></code> with your username)
+<pre>
+$ cd /usr/local/lib/ruby # or wherever you have ruby installed
+$ sudo chown -R <local user> .
+</pre>
+
+h3(#tips_on_configuring_sudo). Tips on configuring sudo
+
+Sudo can be configured to not ask for a password for certain commands.  This will be useful if you want to run geminstaller against a root-owned gem repository without being prompted (such as a Rails app being deployed via Capistrano).
+
+You should consult the man or info pages on sudoers and visudo for more info (<code>man sudoers</code> or <code>info sudoers</code>).  _*Make sure you understand the security implications of this approach*_.  
+
+Here's an example of how <code>sudoers</code> might be configured to allow the local user to run the <code>'gem'</code>, <code>'ruby'</code>, and <code>'geminstaller'</code> commands via <code>sudo</code> without being prompted for a password.  Replace <code><local user></code> with your username, and replace '/usr/local/bin/' with the appropriate path if it is different on your system:
+
+<pre>
+$ sudo visudo
+add this line:
+<local user> ALL = NOPASSWD: /usr/local/bin/geminstaller, /usr/local/bin/ruby, /usr/local/bin/gem
+</pre>
+
+h2(#automatically_requiring_gems_with_the_autogem_method). Automatically Requiring Gems with the <code>autogem</code> Method
+
+GemInstaller provides a <code>GemInstaller.autogem</code> class method which will automatically invoke RubyGems' 'gem' method to add all of the gems in your GemInstaller config file(s) to the load path.  On RubyGems versions 0.8.x, the 'require_gem' method is used instead.  
+
+If there are some gems you don't want to auto-require, you can set the '<code>no_autogem: true</code> config config property in the GemInstaller config file.  This can be set for individual gems, or as a default.
+
+To use it, invoke the <code>autogem</code> method, and pass a string of arguments, just like the GemInstaller command line, but it ignores arguments which are not applicable (such as -r or -s):
+
+<pre>
+...
+GemInstaller.autogem('--config=/path/to/one/geminstaller.yml,/path/to/another/geminstaller.yml')
+...
+</pre>
+
+Alternately, you are not required to pass any args if you invoke the command from a ruby file which is in the same directory as a default-named <code>'geminstaller.yml'</code> file.
+
+You can also use the "--exceptions" argument to cause <code>autogem</code> to throw an exception if it encounters any error.  This is useful if you want to abort your application startup if any gems failed to load.
+
+*IMPORTANT NOTE*: The RubyGems <code>'gem'</code> and <code>'require_gem'</code> commands will only load a single version of any given gem onto the load path.  Because of this, the GemInstaller autogem command will only process the first version that it finds of any given gem.
+
+For more info on the RubyGems 'gem and 'require_gem' commands, see "Using Explicit Versions":http://docs.rubygems.org/read/chapter/4#page71 in the RubyGems docs.

data/website/src/documentation/index.page

@@ -0,0 +1,88 @@
+---
+title: Quick Start
+---
+h1. Quick Start
+
+h2. Basic Usage - "Hello Doom"
+
+* Install GemInstaller: <code>[sudo] gem install geminstaller</code>
+* Create a <code>geminstaller.yml</code> file:
+
+    <pre>
+\---
+# geminstaller.yml sample config
+gems:
+- name: ruby-doom
+  version: '>= 0.8'
+</pre>
+
+* Run GemInstaller from the directory containing geminstaller.yml: <code>geminstaller</code>.  You should see a message indicating that the gem is being installed.
+* Verify that the ruby-doom gem was installed: <code>gem list ruby-doom</code>
+
+h2. Using GemInstaller with Ruby on Rails
+
+* Create geminstaller.yml in the RAILS_ROOT/config directory.  Include entries for your Rails version, and any other gems your app needs (Note: If you are too lazy to make your config file manually, or don't know what gems you need, see the tutorial on "Bootstrapping your GemInstaller Config with the <code>--print-rogue-gems</code> option":tutorials#bootstrapping_your_geminstaller_config):
+
+    <pre>
+\---
+# geminstaller.yml rails app config
+defaults:
+  install_options: --include-dependencies
+gems:
+- name: rails
+  version: '= 1.1.6'
+</pre>
+
+
+
+* Determine whether you run on unix and need root/sudo access to install gems.  If you do, edit your <code>sudoers</code> file to allow the current user to run the <code>'gem'</code> command via sudo without a password.  See the documentation on the GemInstaller "<code>--sudo</code> option":documentation.html#dealing_with_sudo for more details.
+
+* Edit your Rails <code>config/boot.rb</code> to invoke GemInstaller on startup to install gems and auto-require them.  The following lines should be placed right after the block which defines the RAILS_ROOT constant ("..." indicates omitted lines).  If you want to know what the heck this does before sticking it in your app, there are more details in the tutorial "Integrating GemInstaller into Ruby on Rails":#integrating_geminstaller_into_ruby_on_rails
+
+    <pre>
+\---
+RAILS_ROOT/config/boot.rb:
+...
+unless defined?(RAILS_ROOT)
+...
+end
+
+############# Begin GemInstaller config - see http://geminstaller.rubyforge.org
+require "rubygems"
+require "geminstaller"
+
+# Path(s) to your GemInstaller config file(s)
+config_paths = "#{File.expand_path(RAILS_ROOT)}/config/geminstaller.yml" 
+
+# Arguments which will be passed to GemInstaller
+args = "--config #{config_paths}" 
+
+# The 'exceptions' flag determines whether errors encountered while running GemInstaller
+# should raise exceptions (and abort Rails), or just return a nonzero return code
+exceptions = true 
+args += " --exceptions" if exceptions
+
+# This will use sudo by default on all non-windows platforms, but requires an entry in your
+# sudoers file to avoid having to type a password.  It can be omitted if you don't want to use sudo.
+# See http://geminstaller.rubyforge.org/documentation/documentation.html#dealing_with_sudo
+args += " --sudo" unless RUBY_PLATFORM =~ /mswin/ 
+
+# The 'install' method will auto-install gems as specified by the args and config
+GemInstaller.run(args)
+
+# The 'autogem' method will automatically add all gems in the GemInstaller config to your load path, using the 'gem'
+# or 'require_gem' command.  If you want to use other config file path(s), pass them as an array or comma-delimited list.
+# Note that only the *first* version of any given gem will be loaded.
+GemInstaller.autogem(config_paths, exceptions)
+############# End GemInstaller config
+
+unless defined?(Rails::Initializer)
+...
+</pre>
+
+* Start your app: <code>ruby script/server</code>.  You should see messages indicating the gems (and dependency gems) are being installed and auto-required.
+* Stop the app, and verify the gems are installed: <code>gem list rails</code>
+
+h2. Where to go next
+
+See the "Tutorials":documentation/tutorials.html or the "Detailed Documentation":documentation/documentation.html for examples of more GemInstaller features.

data/website/src/documentation/tutorials.page

@@ -0,0 +1,94 @@
+h1. Tutorials
+
+These are tutorials which show how to use the various features of GemInstaller.  They are mostly brief, only showing the commands you need to type.
+
+If anything is unclear, or if you'd like to see a tutorial on a topic, please submit a request on the mailing list.
+
+* "Installing GemInstaller":#installing_geminstaller
+* "Bootstrapping your GemInstaller Config with the <code>--print-rogue-gems</code> option":#bootstrapping_your_geminstaller_config
+* "Using the <code>autogem</code> Option to Automatically Require Gems":#using_the_autogem_option_to_automatically_require_gems
+* "Integrating GemInstaller into Ruby on Rails":#integrating_geminstaller_into_ruby_on_rails
+* "Using Common or Shared Config Files":#using_common_or_shared_config_files
+* "Running GemInstaller from Capistrano":#running_geminstaller_from_capistrano
+
+h2(#installing_geminstaller). Installing GemInstaller
+
+<pre>
+$ gem install geminstaller
+   - OR, if you get a permission error -
+$ sudo gem install geminstaller 
+</pre>
+
+See also: Docs on "installation":documentation.html#installation.
+
+h2(#bootstrapping_your_geminstaller_config). Bootstrapping your GemInstaller Config with the <code>--print-rogue-gems</code> option
+
+You may have no idea what gems your app uses, or you might just want to create a GemInstaller config file with all the gems currently on your system, in order to install the same gems on a different system.  This tutorial will show you how to use the <code>--print-rogue-gems</code> option to automatically create a GemInstaller config file.
+
+<pre>
+$ geminstaller --print-rogue-gems > geminstaller.yml
+</pre>
+
+That was easy, wasn't it?  This config file should specify the exact versions for all of the gems which are currently installed on your system.
+
+Gotchas/Notes:
+
+# If you generated the file on a unix/mac system with compiled gems and then try to run it on a different platform (like windows) which does not have a compiler, you may get errors.  The "<code>prefer_binary_platform</code> config property":documentation.html#prefer_binary_platform_config_property will try to guess at the correct platform, but if a binary version of the gem does not exist for your platform, or if <code>prefer_binary_platform</code> fails to guess the right platform, you may still fail.
+# The <code>--print-rogue-gems</code> option generates *exact* version specifications.  This means that you won't ever get any gem upgrades by running GemInstaller with the standard generated file.  This may be good (an upgrade can never break your app unexpectedly).  However, you may wish to modify some of the version specifications to allow for upgrades.  If you do this, remember to set the "<code>check_for_upgrade</code> config property":documentation.html#check_for_upgrade_config_property to true, but be aware that this will cause GemInstaller to check the remote gem server for upgrades each time it runs, and cause it to run slow or fail if the server is unavailable.    
+
+See also: Docs on "<code>--print-rogue-gems</code> option":documentation.html#print_rogue_gems_option, "<code>prefer_binary_platform</code> config property":documentation.html#prefer_binary_platform_config_property, and "<code>check_for_upgrade</code> config property":documentation.html#check_for_upgrade_config_property
+
+h2(#using_the_autogem_option_to_automatically_require_gems). Using the <code>autogem</code> Option to Automatically Require Gems option
+
+GemInstaller can automatically run the RubyGems 'gem' or 'require_gem' method to automatically add all of the gems in your GemInstaller config file(s) to the load path.  Here's an example.
+
+First, create a simple *<code>geminstaller.yml</code>* file:
+<pre>
+\---
+gems:
+- name: ruby-doom
+  version: '= 0.8'
+</pre>
+
+Now, we'll use <code>irb</code> to test autogem, and verify that it can add the ruby-doom gem to the load path:
+<pre>
+$ irb
+irb(main):001:0> require 'rubygems'
+=> true
+irb(main):002:0> require 'geminstaller'
+=> true
+irb(main):003:0> GemInstaller.autogem('--config=geminstaller.yml')
+=> autogem returns the gem object(s) as it's return value...
+irb(main):004:0> $: # Now verify the gem was added to the load path
+=> ["/usr/local/lib/ruby/gems/1.8/gems/ruby-doom-0.8/lib", ...]
+</pre>
+
+Note that <code>autogem</code> takes arguments in the same format as the GemInstaller command line and <code>run</code> method, but it ignores arguments which are not applicable (such as -r or -s).  You could also specify no argument at all if you wanted to simply use the default <code>geminstaller.yml</code> file in the current directory.  If you don't want a certain gem to be loaded, you can set the <code>no-autogem</code> property to true for that gem in your config file.
+
+You can also put a call to <code>autogem</code> during your application startup to automatically load all the correct gem versions which are specified by your config file.  See "Integrating GemInstaller into Ruby on Rails":#integrating_geminstaller_into_ruby_on_rails for an example.
+
+See also:  Docs on "Automatically Requiring Gems with the <code>autogem</code> Method":documentation.html#automatically_requiring_gems_with_the_autogem_method
+
+
+
+
+h2(#integrating_geminstaller_into_ruby_on_rails). Integrating GemInstaller into Ruby on Rails
+
+TODO: Write this, for now see docs on "Using GemInstaller with Ruby on Rails or Other Ruby Apps":documentation.html#using_geminstaller_with_ruby_on_rails_or_other_ruby_apps. 
+
+See also: Docs on "Using GemInstaller with Ruby on Rails or Other Ruby Apps":documentation.html#using_geminstaller_with_ruby_on_rails_or_other_ruby_apps. 
+
+
+h2(#using_common_or_shared_config_files). Using Common or Shared Config Files
+
+TODO: Write this, for now see docs on the "<code>--config</code>":documentation.html#config_option option. 
+
+See also: Docs on the "<code>--config</code>":documentation.html#config_option option. 
+
+
+h2(#running_geminstaller_from_capistrano). Running GemInstaller from Capistrano
+
+TODO: Write this, for now see docs on  "Using GemInstaller from Other Ruby Apps":documentation.html#using_geminstaller_from_other_ruby_apps
+
+See also: Docs on "Using GemInstaller from Other Ruby Apps":documentation.html#using_geminstaller_from_other_ruby_apps.
+

data/website/src/download.page

@@ -0,0 +1,12 @@
+---
+title: Download
+---
+h1. Installation / Download
+
+GemInstaller is a standard RubyGem, and can be installed as usual (prefix with <code>sudo</code> if necessary):
+
+<pre>
+gem install geminstaller
+</pre>
+
+Alternately, you can download and install the gem file from the GemInstaller RubyForge download page:  "http://rubyforge.org/frs/?group_id=1902":http://rubyforge.org/frs/?group_id=1902

data/website/src/faq.page

@@ -0,0 +1,7 @@
+---
+title: FAQ
+---
+h1. Frequently Asked Questions
+
+Q: Why don't the tests/specs run on Windows?<br/>
+A: Dunno, something with the process handling on windows for TestGemHome and EmbeddedGemServer.  The manual application tests under spec/smoketest/ work on windows, though.