Author: assaf
Date: Sun Jan 6 21:18:05 2008
New Revision: 609516
URL: http://svn.apache.org/viewvc?rev=609516&view=rev
Log:
New download/installation instructions and troubleshooting
Added:
incubator/buildr/trunk/doc/pages/download.textile
Modified:
incubator/buildr/trunk/README
incubator/buildr/trunk/Rakefile
incubator/buildr/trunk/doc/css/default.css
incubator/buildr/trunk/doc/css/print.css
incubator/buildr/trunk/doc/pages/contributing.textile
incubator/buildr/trunk/doc/pages/getting_started.textile
incubator/buildr/trunk/doc/pages/index.textile
incubator/buildr/trunk/doc/pages/troubleshooting.textile
incubator/buildr/trunk/doc/print.haml
incubator/buildr/trunk/doc/web.haml
incubator/buildr/trunk/doc/web.toc.yaml
Modified: incubator/buildr/trunk/README
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/README?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/README (original)
+++ incubator/buildr/trunk/README Sun Jan 6 21:18:05 2008
@@ -4,22 +4,39 @@
http://incubator.apache.org/buildr/
+
== Get Started
-=== Install Buildr:
+=== Install Buildr
+
+Buildr needs Ruby 1.8 or later and RubyGems 0.9 or later.
+
+Windows users can get the one-click Ruby installer, which includes the latest
+version of Ruby and RubyGems:
+
+http://rubyinstaller.rubyforge.org
+
+
+
+
Make sure to set JAVA_HOME environment variable first, then:
gem install buildr
-(Use su for Linux and OS/X)
+(Use sudo for Linux and OS/X)
+
+More installation and setup instructions available online
+http://incubator.apache.org/buildr/
-=== RTFM:
+
+=== RTFM
* Buildr documentation: http://incubator.apache.org/buildr/
* More about Rake: http://docs.rubyrake.org
* Antwrap documentation: http://antwrap.rubyforge.org
-=== Mailing list:
+
+=== Mailing list
* Users: [EMAIL PROTECTED] (subscribe:
[EMAIL PROTECTED], archive:
@@ -46,22 +63,41 @@
http://rubyinstaller.rubyforge.org
-=== Linux and OS/X
+Before installing Buildr, please set the JAVA_HOME environment variable to
+point to your JDK distribution. Next, use Ruby Gem to install Buildr:
+
+ > gem install buildr
+
+When prompted for a platform, select mswin32.
-If you're running Linux or OS/X you may already have Ruby installed, or you can
-get it through the usual channels:
+=== Linux, BSD, Cygwin
- yum install ruby
- apt-get install ruby
- emerge ruby
-
-You can get RubyGems here: http://rubyforge.org/frs/?group_id=126
-
-To install:
- tar -xz < rubygems-0.9.2.tgz
- cd rubygems-0.9.2
- sudo ruby setup.rb
- sudo gem install rubygems-update
+On Linux/BSD/Cygwin, use your default package manager, for example, for Ubuntu:
+
+$ sudo apt-get install ruby
+$ sudo apt-get install ruby1.8-dev
+$ sudo apt-get install build-essential
+$ sudo apt-get install libopenssl-ruby
+
+Before installing Buildr, please set the JAVA_HOME environment variable to
+point to your JDK distribution. Next, use Ruby Gem to install Buildr:
+
+ $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+
+When prompted for a platform, select ruby.
+
+=== OS/X
+
+Leopard includes the latest version of Ruby, if you are using Tiger or an older
+release, we recommend re-installing the latest:
+
+http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx
+
+To install Buildr:
+
+ $ sudo gem install buildr
+
+When prompted for a platform, select ruby.
== Living On the Edge
@@ -73,13 +109,21 @@
Or browse the SVN repository online:
http://svn.apache.org/repos/asf/incubator/buildr
-To install Buildr locally from source, do:
+To install Buildr locally from source:
cd buildr
rake install
If the cutting edge doesn't work, make sure to check the CHANGELOG, to see
-which changes might have broken your build.
+which changes might have broken your build. To run all the test cases:
+
+ rake spec
+
+
+== Disclaimer
+
+:include:DISCLAIMER
+
== License
Modified: incubator/buildr/trunk/Rakefile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/Rakefile?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/Rakefile (original)
+++ incubator/buildr/trunk/Rakefile Sun Jan 6 21:18:05 2008
@@ -14,12 +14,11 @@
spec.email = '[EMAIL PROTECTED]'
spec.homepage = "http://incubator.apache.org/#{spec.name}/";
spec.summary = 'A build system that doesn\'t suck'
- spec.files = FileList['lib/**/*', 'CHANGELOG', 'README', 'LICENSE',
'NOTICE', 'DISCLAIMER',
+ spec.files = FileList['lib/**/*', 'README', 'CHANGELOG', 'LICENSE',
'NOTICE', 'DISCLAIMER',
'Rakefile', 'spec/**/*', 'doc/**/*'].collect
spec.require_path = 'lib'
- spec.autorequire = 'buildr.rb'
spec.has_rdoc = true
- spec.extra_rdoc_files = ['README', 'CHANGELOG', 'LICENSE']
+ spec.extra_rdoc_files = ['README', 'CHANGELOG', 'LICENSE', 'NOTICE',
'DISCLAIMER']
spec.rdoc_options << '--title' << "Buildr -- #{spec.summary}" <<
'--main' << 'README' << '--line-numbers' <<
'--inline-source' << '-p' <<
'--webcvs' <<
'http://svn.apache.org/repos/asf/incubator/buildr/trunk/'
Modified: incubator/buildr/trunk/doc/css/default.css
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/css/default.css?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/css/default.css (original)
+++ incubator/buildr/trunk/doc/css/default.css Sun Jan 6 21:18:05 2008
@@ -137,7 +137,7 @@
font-size: 0.9em;
padding: 0.3em;
clear: both;
- margin: 0 0 3em 19em;
+ margin: 0 0 3em 0em;
}
Modified: incubator/buildr/trunk/doc/css/print.css
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/css/print.css?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/css/print.css (original)
+++ incubator/buildr/trunk/doc/css/print.css Sun Jan 6 21:18:05 2008
@@ -65,6 +65,10 @@
line-height: 1.3em;
}
+#license+ol+pre {
+ page-break-inside: always !important;
+}
+
a:link, a:visited {
background: transparent;
text-decoration: underline;
Modified: incubator/buildr/trunk/doc/pages/contributing.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/contributing.textile?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/contributing.textile (original)
+++ incubator/buildr/trunk/doc/pages/contributing.textile Sun Jan 6 21:18:05
2008
@@ -3,6 +3,7 @@
Buildr is a community effort, and we welcome all contributors. Here's your
chance to get involved and help your fellow developers.
+
h2. Mailing Lists
We don't talk much, but when we do, we have interesting things to say, so start
@@ -40,6 +41,15 @@
will still use JIRA to log the progress, but the mailing list is a better place
for talking things through.
+When reporting a bug, please tell us which version of Ruby, Buildr and Java you
+are using, and also which operating system you are on:
+
+{{{!sh
+$ ruby --version
+$ builder --version
+$ java --version
+}}}
+
If you have a patch to submit, do it through
"JIRA":http://issues.apache.org/jira/browse/Buildr. We want to make sure
Apache gets the right to use your contribution, and the JIRA upload form
@@ -72,7 +82,7 @@
(Linux and OS/X, use @sudo rake install@)
-h2. Testing
+h2. Testing/Specs
Obviously we won't turn down patches, but we'll love you even more if you
include a test case. One that will fail without the patch, and run
Added: incubator/buildr/trunk/doc/pages/download.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/download.textile?rev=609516&view=auto
==============================================================================
--- incubator/buildr/trunk/doc/pages/download.textile (added)
+++ incubator/buildr/trunk/doc/pages/download.textile Sun Jan 6 21:18:05 2008
@@ -0,0 +1,113 @@
+h1. Download and Installation
+
+The current release of Buildr works with Ruby 1.8. We do not yet support Ruby
1.9 or JRuby.
+
+
+h2. Windows
+
+If you don't already have Ruby installed, now is the time to do it. The
+easiest way to install Ruby is using the "one-click
+installer":http://rubyinstaller.rubyforge.org/.
+
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to
+point to your JDK distribution. Next, use Ruby Gem to install Buildr:
+
+{{{!sh
+> gem install buildr
+}}}
+
+Buildr uses several libraries that include native extensions. During
+installation it will ask you to pick a platform for these libraries. By
+selecting @mswin32@ it will download and install pre-compiled DLLs for these
+extensions.
+
+To upgrade to a new version of Buildr:
+
+{{{!sh
+> gem update buildr
+}}}
+
+To install a specific version of Buildr:
+
+{{{!sh
+> gem install buildr -v 1.3.0
+}}}
+
+
+h2. Linux, BSD, Cygwin
+
+To get started you will need a recent version of Ruby, Ruby Gems and build
+tools for compiling native libraries (Make and GCC).
+
+On Ubuntu you can setup your environment by installing the following packages:
+
+{{{!sh
+$ sudo apt-get install ruby
+$ sudo apt-get install ruby1.8-dev
+$ sudo apt-get install build-essential
+$ sudo apt-get install libopenssl-ruby
+}}}
+
+Other distributions may use different package manages, like @yum@ and @[EMAIL
PROTECTED]
+
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to
+point to your JDK distribution. Next, use Ruby Gem to install Buildr:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+}}}
+
+Buildr uses several libraries that include native extensions. During
+installation it will ask you to pick a platform for these libraries. By
+selecting @ruby@ it will download the source code for these extensions and
+compile them to work on your machine.
+
+To upgrade to a new version of Buildr:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
+}}}
+
+To install a specific version of Buildr:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.0
+}}}
+
+
+h2. OS/X
+
+Leopard comes with the latest version of Ruby 1.8 and Ruby Gems. If you are
+using Tiger or an older release of OS/X, we recommend you first install a
+recent version of Ruby and Ruby Gems (see "Building Ruby on
+OS/X":http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx)
+
+To install Buildr:
+
+{{{!sh
+$ sudo gem install buildr
+}}}
+
+Buildr uses several libraries that include native extensions. During
+installation it will ask you to pick a platform for these libraries. By
+selecting @ruby@ it will download the source code for these extensions and
+compile them to work on your machine.
+
+To upgrade to a new version of Buildr:
+
+{{{!sh
+$ sudo gem update buildr
+}}}
+
+To install a specific version of Buildr:
+
+{{{!sh
+$ sudo gem install buildr -v 1.3.0
+}}}
+
+
+h2. Binaries and Source Code
+
+At the moment we do not make offical Apache binary and source distributions.
+Unofficial binary and source distributions are available form
+"RubyForge":http://rubyforge.org/projects/buildr.
Modified: incubator/buildr/trunk/doc/pages/getting_started.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/getting_started.textile?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/getting_started.textile (original)
+++ incubator/buildr/trunk/doc/pages/getting_started.textile Sun Jan 6
21:18:05 2008
@@ -1,5 +1,11 @@
h1. Getting Started
+h2. Installing Buildr
+
+More information about "downloading and installing
+Buildr":http://incubator.apache.org/buildr/downloading.html.
+
+
h2. Conventions
Lines that start with @$@ are command lines, for example:
@@ -9,56 +15,26 @@
$ buildr
}}}
-Lines that start with @=>@ show output from the console or the result of a
method, for example:
+Lines that start with @=>@ show output from the console or the result of a
+method, for example:
{{{!sh
-puts "Hello world"
+puts 'Hello world'
=> "Hello world"
}}}
-And as you guessed, everything else is Buildfile Ruby or Java code. You can
figure out which language is which.
-
-
-
-h2. Installing
-
-To use Buildr you need Ruby 1.8 with Gems.
-
-If you're running on Windows, you can get the "one-click
installer":http://rubyinstaller.rubyforge.org/ that includes both. On Linux,
depending on your distribution, you can get Ruby via @yum install ruby@,
@apt-get install ruby@, or @emerge [EMAIL PROTECTED]
-
-You will need to separately download and install
"RubyGems":http://rubyforge.org/frs/?group_id=126. Some distributions also
include a rubygem package that you can @apt-get@ or @yum install@ directly, so
try these options first.
-
-Got that? Moving on. Set the @JAVA_HOME@ environment variable and install
Buildr:
-
-{{{!sh
-$ gem install buildr
-}}}
-
-*Ubuntu:* Ubuntu is a popular Linux distribution. Here are specific
instructions for installing Buildr and its prerequisite packages on recent
versions of Ubuntu (Dapper, Edgy, Feisty and Gusty):
-
-{{{!sh
-$ sudo apt-get install ruby
-$ sudo apt-get install ruby1.8-dev
-$ sudo apt-get install build-essential
-$ sudo apt-get install libopenssl-ruby
-$ sudo gem install buildr
-}}}
-
-*Linux and OS/X:* You probably need to be super user to install new Gems.
Turns out, in some configurations using @sudo@ does not pass the @JAVA_HOME@
environment variable, so either login as super user, or try this:
-
-{{{
-$sudo env JAVA_HOME=$JAVA_HOME gem install buildr
-}}}
+And as you guessed, everything else is Buildfile Ruby or Java code. You can
+figure out which language is which.
-Buildr depends on other packages, so the next step is accepting these packages
for installation. For a couple, RJB and
-Antwrap, you'll need to select the right installation type.
-Now you're ready to start. Almost.
+h2. Running Buildr
-h2. Running
-
-You need a *Buildfile*, a build script that tells Buildr all about the
projects it's building, what they contain, what to produce, and so on. The
Buildfile resides in the root directory of your project. We'll talk more about
it in "the next chapter":projects.html. If you don't already have one, ask
Buildr to create it[1]:
+You need a *Buildfile*, a build script that tells Buildr all about the projects
+it's building, what they contain, what to produce, and so on. The Buildfile
+resides in the root directory of your project. We'll talk more about it in
+"the next chapter":projects.html. If you don't already have one, ask Buildr to
+create it[1]:
{{{!sh
$ buildr
@@ -76,28 +52,21 @@
buildr --help
}}}
-You can use the @--help@ option anytime. Once you have a Buildfile ready, you
can find out even more information by running the _help_ task:
+Once you have a Buildfile ready, you can find out even more information by
+running the _help_ task:
{{{!sh
buildr help
}}}
-And before we move to more serious matters, here's a reminder. If you want to
upgrade to a new version of Buildr, just:
-
-{{{!sh
-$ gem update buildr
-}}}
-
h2. More Info
-*Mailing List* Questions, ideas, comments and to report "features", join us on
the "Buildr user mailing list":mailing_lists.html.
+*API* The "Buildr API":http://incubator.apache.org/buildr/rdoc/index.html
documentation.
*Rake* Buildr is based on Rake, a Ruby build system that handles tasks and
dependencies. Check out the "Rake documentation":http://docs.rubyrake.org/ for
more information.
*AntWrap* Buildr uses AntWrap, for configuring and running Ant tasks. You can
learn more from the "Antwrap documentation":http://antwrap.rubyforge.org/.
-
-*Building Ruby* If you don't have Ruby installed or want to build a different
verions, here are instructions for "Building Ruby on
OS/X":http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx.
fn1. You'll notice that Buildr creates a file called @[EMAIL PROTECTED] It's
case sensitive, but Buildr will look for either @buildfile@ or @[EMAIL
PROTECTED] You can also use @Rakefile@ or @rakefile@ for compatibility with
previous versions of Buildr.
Modified: incubator/buildr/trunk/doc/pages/index.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/index.textile?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/index.textile (original)
+++ incubator/buildr/trunk/doc/pages/index.textile Sun Jan 6 21:18:05 2008
@@ -1,22 +1,39 @@
h1. Welcome
-Buildr is a build system for Java applications. We wanted something that's
simple and intuitive to use, so we only need to tell it what to do, and it
takes care of the rest. But also something we can easily extend for those
one-off tasks, with a language that's a joy to use. And of course, we wanted
it to be fast, reliable and have outstanding dependency management.
+Buildr is a build system for Java applications. We wanted something that's
+simple and intuitive to use, so we only need to tell it what to do, and it
+takes care of the rest. But also something we can easily extend for those
+one-off tasks, with a language that's a joy to use. And of course, we wanted
+it to be fast, reliable and have outstanding dependency management.
Here's what we got:
-* A simple way to specify projects, and build large projects out of smaller
sub-projects.
-* Pre-canned tasks that require the least amount of configuration, keeping the
build script DRY and simple.
-* Compiling, copying and filtering resources, JUnit/TestNG test cases, APT
source code generation, Javadoc and more.
-* A dependency mechanism that only builds what has changed since the last
release.
-* A drop-in replacement for Maven 2.0, Buildr uses the same file layout,
artifact specifications, local and remote repositories.
-* All your Ant tasks belong to us! Anything you can do with Ant, you can do
with Buildr.
-* No overhead for building "plugins" or configuration. Just write new tasks or
functions.
-* Buildr is Ruby all the way down. No one-off task is too demanding when you
write code using variables, functions and objects.
+* A simple way to specify projects, and build large projects out of smaller
+sub-projects.
+* Pre-canned tasks that require the least amount of configuration, keeping the
+build script DRY and simple.
+* Compiling, copying and filtering resources, JUnit/TestNG test cases, APT
+source code generation, Javadoc and more.
+* A dependency mechanism that only builds what has changed since the last
+release.
+* A drop-in replacement for Maven 2.0, Buildr uses the same file layout,
+artifact specifications, local and remote repositories.
+* All your Ant tasks belong to us! Anything you can do with Ant, you can do
+with Buildr.
+* No overhead for building "plugins" or configuration. Just write new tasks or
+functions.
+* Buildr is Ruby all the way down. No one-off task is too demanding when you
+write code using variables, functions and objects.
* Simple way to upgrade to new versions.
* Did we mention fast?
-h2. Disclaimer
-
-Apache Buildr is an effort undergoing incubation at The Apache Software
Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of
all newly accepted projects until a further review indicates that the
infrastructure, communications, and decision making process have stabilized in
a manner consistent with other successful ASF projects. While incubation status
is not necessarily a reflection of the completeness or stability of the code,
it does indicate that the project has yet to be fully endorsed by the ASF.
+*Disclaimer* Apache Buildr is an effort undergoing incubation at The Apache
+Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is
+required of all newly accepted projects until a further review indicates that
+the infrastructure, communications, and decision making process have stabilized
+in a manner consistent with other successful ASF projects. While incubation
+status is not necessarily a reflection of the completeness or stability of the
+code, it does indicate that the project has yet to be fully endorsed by the
+ASF.
"So let's get started":getting_started.html.
Modified: incubator/buildr/trunk/doc/pages/troubleshooting.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/troubleshooting.textile?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/troubleshooting.textile (original)
+++ incubator/buildr/trunk/doc/pages/troubleshooting.textile Sun Jan 6
21:18:05 2008
@@ -23,3 +23,38 @@
and periods which are small enough that you won't notice them from a cursory
glance at the code, so if all else fails, search for lines that end with one of
these characters.
+
+
+h2. RJB
+
+h3. RJB fails to compile
+
+On Linux, BSD and Cygwin, RJB locates the JDK headers files -- which it uses to
+compile a native C extension -- based on the @JAVA_HOME@ environment variable.
+Make sure @JAVA_HOME@ points to the JDK, not JRE.
+
+If you are using @sudo gem install@, note that some environments do not pass
+the @JAVA_HOME@ environment variable over to @[EMAIL PROTECTED] To get around
this, run
[EMAIL PROTECTED]@ with the @env JAVA_HOME=$JAVA_HOME@ option:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+}}}
+
+
+h3. Segmentation Fault when running Java code
+
+This is most likely a JVM inconsistency, for example, when part of the RJB
+library uses JDK 1.6, the other part uses JDK 1.5.
+
+During installation RJB builds a native C extension using header files
supplied by
+the JVM, and compiles a Java bridge class using the Javac. It is possible for
RJB
+to use two different versions of the JVM, for example, if @JAVA_HOME@ points to
+JDK 1.5, but @/usr/bin/javac@ points to JDK 1.6.
+
+Make sure @JAVA_HOME@ and @/usr/bin/javac@ both point to the same JDK:
+
+{{{!sh
+echo $JAVA_HOME
+ls -l /usr/bin/javac
+}}}
Modified: incubator/buildr/trunk/doc/print.haml
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/print.haml?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/print.haml (original)
+++ incubator/buildr/trunk/doc/print.haml Sun Jan 6 21:18:05 2008
@@ -22,4 +22,3 @@
~ collect_links(renumber_footnotes(page.content))
%h1 References
~ list_links('footnote-links')
- #footer
Modified: incubator/buildr/trunk/doc/web.haml
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/web.haml?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/web.haml (original)
+++ incubator/buildr/trunk/doc/web.haml Sun Jan 6 21:18:05 2008
@@ -36,3 +36,4 @@
- if next_page = collection.next(page)
%a{ :href=>next_page.path, :class=>'next' }= next_page.title + '
»'
#footer
+ Copyright © 2007-2008 The Apache Software Foundation
Modified: incubator/buildr/trunk/doc/web.toc.yaml
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/web.toc.yaml?rev=609516&r1=609515&r2=609516&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/web.toc.yaml (original)
+++ incubator/buildr/trunk/doc/web.toc.yaml Sun Jan 6 21:18:05 2008
@@ -1,6 +1,6 @@
- Main:
- Welcome: index.html
- - Download
+ - Download and Installation: download.html
- Printable PDF: buildr.pdf
- Using Buildr:
- Getting Started: getting_started.html
