0
@@ -1,6 +1,99 @@
0
 h1. More Stuff
0
 
0
 
0
+h2.  Using Gems
0
+
0
+The purpose of the buildfile is to define your projects, and the various tasks
0
+and functions used for building them.  Some of these are specific to your
0
+projects, others are more general in nature, and you may want to share them
0
+across projects.
0
+
0
+There are several mechanisms for developing extensions and build features
0
+across projects which we cover in more details in the section "Extending
0
+Buildr":extending.html.  Here we will talk about using extensions that are
0
+distributed in the form of RubyGems.
0
+
0
+"RubyGems":http://rubygems.rubyforge.org provides the @gem@ command line tool
0
+that you can use to search, install, upgrade, package and distribute gems. It
0
+installs all gems into a local repository that is shared across your builds and
0
+all other Ruby applications you may have running.  You can install a gem from a
0
+local file, or download and install it from any number of remote repositories.
0
+
0
+RubyGems is preconfigured to use the "RubyForge":http://rubyforge.org
0
+repository.  You'll find a large number of open source Ruby libraries there,
0
+including Buildr itself and all its dependencies.  RubyForge provides a free
0
+account that you can use to host your projects and distribute your gems (you
0
+can use RubyForge strictly for distribution, as we do with Buildr).
0
+
0
+You can also set up your own private repository and use it instead or in
0
+addition to RubyForge.  Use the @gem sources@ command to add repositories, and
0
+the @gem server@ command to run a remote repository.  You can see all available
0
+options by running @gem help@.
0
+
0
+If your build depends on other gems, you will want to specify these
0
+dependencies as part of your build and check that configuration into source
0
+control.  That way you can have a specific environment that will guarantee
0
+repeatable builds, whether you're building a particular version, moving between
0
+branches, or joining an existing project.  Buildr will take care of installing
0
+all the necessary dependencies, which you can then manage with the @gem@
0
+command.
0
+
0
+Use the @build.yaml@ file to specify these dependencies (see "Build
0
+Settings":settings_profiles.html#build_settings for more information), for
0
+example:
0
+
0
+{{{!yaml
0
+# This project requires the following gems
0
+gems: 
0
+  # Suppose we want to notify developers when testcases fail.
0
+  - buildr-twitter-notifier-addon >=1
0
+  # we test with ruby mock objects
0
+  - mocha
0
+  - ci_reporter
0
+}}}
0
+
0
+Gems contain executable code, and for that reason Buildr will not install gems
0
+without your permission.  When you run a build that includes any dependencies
0
+that are not already installed on your machine, Buildr will ask for permission
0
+before installing them.  On Unix-based operating systems, you will also need
0
+sudo privileges and will be asked for your password before proceeding.
0
+
0
+Since this step requires your input, it will only happen when running Buildr
0
+interactively from the command line.  In all other cases, Buildr will fail and
0
+report the missing dependencies.  If you have an automated build environment,
0
+make sure to run the build once manually to install all the necessary
0
+dependencies.
0
+
0
+When installing a gem for the first time, Buildr will automatically look for
0
+the latest available version.  You can specify a particular version number, or
0
+a set of version numbers known to work with that build.  You can use equality
0
+operations to specify a range of versions, for example, @1.2.3@ to install only
0
+version 1.2.3, and @=> 1.2.3@ to install version 1.2.3 or later.
0
+
0
+You can also specify a range up to one version bump, for example, @~> 1.2.3@ is
0
+the same as @>= 1.2.3 < 1.3.0@, and @~> 1.2@ is the same as @>= 1.2.0 < 2.0.0@.
0
+If necessary, you can exclude a particular version number, for example, @~>
0
+1.2.3 != 1.2.7@.
0
+
0
+Buildr will install the latest version that matches the version requirement.
0
+To keep up with newer versions, execute the @gem update@ command periodically.
0
+You can also use @gem outdated@ to determine which new versions are available.
0
+
0
+Most gems include documentation that you can access in several forms.  You can
0
+use the @ri@ command line tool to find out more about a class, module or
0
+specific method.  For example:
0
+
0
+{{{!sh
0
+$ ri Buildr::Jetty
0
+$ ri Buildr::Jetty.start
0
+}}}
0
+
0
+You can also access documentation from a Web browser by running @gem server@
0
+and pointing your browser to "http://localhost:8808":http://localhost:8808.
0
+Note that after installing a new gem, you will need to restart the gem server
0
+to see its documentation.
0
+
0
+
0
 h2.  Using Java Libraries
0
 
0
 Buildr runs along side a JVM, using either RJB or JRuby.  The Java module

0
@@ -236,6 +236,39 @@ jira:
0
 "Read more ...":settings_profiles.html#build_settings
0
 
0
 
0
+h3.  Using Gems for extensions and 3rd party libraries
0
+
0
+"RubyGems":http://rubygems.rubyforge.org provides the @gem@ command line tool
0
+that you can use to search, install, upgrade, package and distribute gems. It
0
+installs all gems into a local repository that is shared across your builds and
0
+all other Ruby applications you may have running.  You can install a gem from a
0
+local file, or download and install it from any number of remote repositories.
0
+
0
+If your build depends on other gems, you will want to specify these
0
+dependencies as part of your build and check that configuration into source
0
+control.  That way you can have a specific environment that will guarantee
0
+repeatable builds, whether you're building a particular version, moving between
0
+branches, or joining an existing project.  Buildr will take care of installing
0
+all the necessary dependencies, which you can then manage with the @gem@
0
+command.
0
+
0
+Use the @build.yaml@ file to specify these dependencies (see "Build
0
+Settings":settings_profiles.html#build_settings for more information), for
0
+example:
0
+
0
+{{{!yaml
0
+# This project requires the following gems
0
+gems: 
0
+  # Suppose we want to notify developers when testcases fail.
0
+  - buildr-twitter-notifier-addon >=1
0
+  # we test with ruby mock objects
0
+  - mocha
0
+  - ci_reporter
0
+}}}
0
+
0
+"Read more ...":more_stuff.html#using_gems
0
+
0
+
0
 h3.  New API for accessing Java libraries
0
 
0
 Java classes are accessed as static methods on the @Java@ module, for example: