doc/images/1442160941-frontcover.jpg
doc/images/asf-logo.png
@@ -28,7 +28,7 @@ end
# Load the Gem specification for the current platform (Ruby or JRuby).
def spec(platform = RUBY_PLATFORM[/java/] || 'ruby')
- @specs ||= ['ruby', 'java'].inject({}) { |hash, spec_platform|
+ @specs ||= ['ruby', 'java', 'x86-mswin32'].inject({}) { |hash, spec_platform|
$platform = spec_platform
hash.update(spec_platform=>Gem::Specification.load('buildr.gemspec'))
}
Rakefile
@@ -55,9 +55,10 @@ for those one-off tasks, with a language that's a joy to use.
spec.add_dependency 'highline', '1.5.1'
spec.add_dependency 'rubyforge', '1.0.3'
spec.add_dependency 'hoe', '~>2.0'
- spec.add_dependency 'rjb', '1.1.6' if spec.platform.to_s == 'ruby'
+ spec.add_dependency 'rjb', '1.1.7' if spec.platform.to_s == 'ruby'
+ spec.add_dependency 'rjb', '1.1.6' if spec.platform.to_s == 'x86-mswin32'
spec.add_dependency 'Antwrap', '0.7.0'
- spec.add_dependency 'rspec', '1.2.6'
+ spec.add_dependency 'rspec', '1.2.7'
spec.add_dependency 'xml-simple', '1.0.12'
spec.add_dependency 'archive-tar-minitar', '0.5.2'
spec.add_dependency 'jruby-openssl', '0.5.1' if spec.platform.to_s == 'java'
buildr.gemspec
@@ -1,6 +1,6 @@
<html>
<head>
- <meta content='text/html;charset=UTF-8' http-equiv='Content-Type' />
+ <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
<title>buildr — {{ page.title }}</title>
<style type='text/css'>
@import 'css/default.css';
@@ -9,16 +9,14 @@
<style media='print' type='text/css'>
@import 'css/print.css';
</style>
- <meta content='Official Buildr documentation from the people in the know' name='subject' />
- <link href='images/favicon.png' rel='shortcut icon' />
+ <meta content='Official Buildr documentation from the people in the know' name='subject'>
+ <link href='images/favicon.png' rel='shortcut icon'>
</head>
<body>
<div id='wrap'>
<div id='header'>
- <a href='http://buildr.apache.org/'>
- <img alt='buildr' src='images/buildr.png' />
- </a>
- <div class='tagline'></div>
+ <a href='http://buildr.apache.org/' title="The build system that doesn't suck"><img alt='buildr' src='images/buildr.png'></a>
+ <div class='tagline'>The build system that doesn't suck</div>
</div>
<div id='pages'>
<ol class='toc'>
@@ -46,7 +44,7 @@
</ol>
</li>
<li>Reference
- <ol class="toc">
+ <ol class="toc">
<li><a href='rdoc'>API</a></li>
<li><a href='http://docs.rubyrake.org'>Rake</a></li>
<li><a href='http://antwrap.rubyforge.org'>Antwrap</a></li>
@@ -54,7 +52,7 @@
</ol>
</li>
<li>Get Involved
- <ol class="toc">
+ <ol class="toc">
<li><a href='mailing_lists.html'>Mailing Lists</a></li>
<li><a href='http://issues.apache.org/jira/browse/Buildr'>Issues/Bugs</a></li>
<li><a href='contributing.html'>Contributing</a></li>
@@ -62,14 +60,21 @@
<li><a href='coverage/index.html'>Coverage</a></li>
</ol>
</li>
+ <li>
+ <form action='http://www.google.com/cse' id='searchbox_003673095760649043902:ogcgrzu0l2y'>
+ <input name='cx' type='hidden' value='003673095760649043902:ogcgrzu0l2y'>
+ <input name='cof' type='hidden' value='FORID:0'>
+ <input name='q' size='20' type='text'>
+ <input name='sa' type='submit' value='Search'>
+ <img alt='Google Custom Search' src='http://www.google.com/coop/images/google_custom_search_smnar.gif'>
+ </form>
+ </li>
+ <li>The Buildr Book
+ <p><a href='http://www.amazon.com/Buildr/dp/1442160942/'><img src='images/1442160941-frontcover.jpg' style='width:120px'></a></p>
+ <p>Based on the Buildr documentation, available from <a href='http://www.amazon.com/Buildr/dp/1442160942/'>Amazon</a> and
+ <a href='http://www.createspace.com/3382199'>CreateSpace</a></p>
+ </li>
</ol>
- <form action='http://www.google.com/cse' id='searchbox_003673095760649043902:ogcgrzu0l2y'>
- <input name='cx' type='hidden' value='003673095760649043902:ogcgrzu0l2y' />
- <input name='cof' type='hidden' value='FORID:0' />
- <input name='q' size='20' type='text' />
- <input name='sa' type='submit' value='Search' />
- <img alt='Google Custom Search' src='http://www.google.com/coop/images/google_custom_search_smnar.gif' />
- </form>
</div>
<div id='content'>
<h1 id='{{ page.title | downcase | replace(' ', '_') }}'>{{ page.title }}</h1>
doc/_layouts/default.html
@@ -176,17 +176,45 @@ Yes, we do make typos, spelling errors and sometimes we write things that don't
For simple typos and quick fixes, just send a message to the mailing list or log an issue in JIRA.
-If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch. Making documentation patches is fairly easy. All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from SVN, edit, and @svn diff@ to create a patch.
+If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch. Making documentation patches is fairly easy. All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from Git/SVN, edit, and @svn diff@ to create a patch.
We use "Textile":http://www.textism.com/tools/textile/ as the markup language, it takes all of a few minutes to learn, it's intuitive to use, and produces clean HTML. You can learn it all in a few minutes from the "Textile Reference Manual":http://redcloth.org/textile. Also check out the "Textile Quick Reference":http://hobix.com/textile/quick.html.
-You can always check the documentation to see which conventions we use, and also a couple of extensions we have for styling source code (with syntax highlighting!) and handling footnotes. The table of contents is auto-generated form H1/H2 headers.
+Syntax highlighting handled by "Pygments":http://pygments.org. Use the special @highlight@ tag to separate code sample from the rest of the text and to tell Pygments which language to use. For example:
-The tool we use for this is called Docter, which we developed specifically for Buildr, and use to create the Web site and printable PDF. If you want to try it out you'll need to first @gem install docter@. To generate a copy of the Web site, simple run @rake html@ .
+<notextile><pre>
+{% highlight ruby %}
+define 'project' do
+ # Just a sample
+end
+{% endhighlight %}
+</pre></notextile>
-If you're thinking of editing the docs, and using @rake html@ to see what the HTML looks like, you may want to try something simpler. Start by running the Docter Web server with @rake docter@ and then point your browser at @http://localhost:3000@. To see your edits, simply refresh the page.
+Have a look at existing documentation to see writing conventions, specifically:
-Generating the PDF is a bit more tricky, we use the HTML in combination with print media CSS stylesheets and run them through the wonderful "PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML first before you can @rake pdf@.
+* Separate paragraphs with two newlines.
+* Use one newline only if you need a <br> tag, otherwise, no newlines inside the paragraph.
+* When creating a new page, don't forget the YAML premable at the top (Jekyll needs the page title and layout).
+* The layout uses H1 to render the page title; only use H2 through H4 for the page content.
+* Use H2 headers for the major page sections. Give each H2 header a unique ID so the table of contents can link to it.
+* Separating sentences with two spaces, just a convenience when editing in a text editor using monospaced fonts.
+* If in doubt, ask.
+
+To go from Textile to HTML we use "Jekyll":http://github.com/mojombo/jekyll. You can use the @jekyll@ rake task to transform the files under @doc@ and create a copy of the Web site in the directory @_site@. For example:
+
+{% highlight sh %}
+$ rake jekyll
+$ open _site/index.html
+{% endhighlight %}
+
+There is no live editing, but you can run @rake jekyll auto=true@, and when you update and save a Textile page it will regenerate the corresponding HTML page.
+
+To go from HTML to PDF we use "PrinceXML":http://www.princexml.com/. The target file @buildr.pdf@ is generated by first running Jekyll and then merging the generated HTML pages into a single PDF document. For example:
+
+{% highlight sh %}
+$ rake buildr.pdf
+$ open buildr.pdf
+{% endhighlight %}
h2(#contributors). Contributors
doc/contributing.textile
@@ -79,7 +79,7 @@ blockquote {
padding-right: 2em;
margin-left: 0.3em;
margin-right: 0;
- border-left: 1px solid #3c78b5;
+ font-style: italic;
}
ul {
@@ -121,14 +121,16 @@ th, thead td {
#header {
margin: 0 0 3em 18em;
+ position: relative;
}
#header .tagline {
float: right;
- font-size: 1.5em;
+ font-size: 1.2em;
font-weight: bold;
- position: relative;
- bottom: 4.5em;
+ position: absolute;
+ top: 0.6em;
+ right: 0;
}
@@ -168,6 +170,11 @@ th, thead td {
margin-top: 2em;
padding: 0.3em 0 0.5em 0.5em;
}
+#pages ol li p {
+ font-weight: normal;
+ color: #000;
+ vertical-align: center;
+}
#content { /* Parent Wrapper for inside boxes */
doc/css/default.css
@@ -93,5 +93,9 @@
page-break-before: always;
padding-top: 1.5in;
}
+ div.preface.quotes {
+ page-break-before: always;
+ padding-top: 1in;
+ }
}
doc/css/print.css
@@ -1,13 +1,31 @@
---
layout: default
-title: Welcome
+title: Apache Buildr
---
-h2(#what_is_apache_buildr). What is Apache Buildr?
-
Apache Buildr is a build system for Java-based applications, including support for Scala, Groovy and a growing number of JVM languages and tools. 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:
+
+h2(#why). Why Buildr Rocks
+
+"Daniel Spiewak":http://www.codecommit.com/blog:
+
+bq. If you think about it, the question isn’t “Why use Buildr?”, it’s really “Why use anything else?” The advantages afforded by Buildr are so substantial, I really can’t see myself going with any other tool, at least not when I have a choice.
+
+"Tristan Juricek":http://tristanhunt.com/:
+
+bq. That’s still the strongest sell: it builds everything I need, and as I’ve needed more, I just got things working without a lot of fuss.
+
+"Matthieu Riou":http://offthelip.org/:
+
+bq. We used to rely on Ant, with a fairly extensive set of scripts. It worked but was expensive to maintain. The biggest mistake afterward was to migrate to Maven2. I could write pages of rants explaining all the problems we ran into and we still ended up with thousands of lines of XML.
+
+"Martin Grotzke":http://www.javakaffee.de/blog/:
+
+bq. The positive side effect for me as a java user is that I learn a little ruby, and that’s easy but lots of fun… :-)
+
+
+h2(#what). What You Get
* 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.
@@ -23,7 +41,7 @@ Here's what we got:
So let's get started. You can "read the documentation online":getting_started.html, or "download the PDF":buildr.pdf.
-h2(#news). Project News
+h2(#news). What's New
New in Buildr 1.3.4:
@@ -38,8 +56,12 @@ New in Buildr 1.3.4:
See the "CHANGELOG":CHANGELOG for full details.
-h2(#legal). Legal Notices
+h2(#notices). Credits & Notices
+
+!http://www.apache.org/images/asf-logo.gif(A project of the Apache Software Foundation)!:http://www.apache.org
The Apache Software Foundation is a non-profit organization, consider "sponsoring":http://www.apache.org/foundation/sponsorship.html and check the "thanks":http://www.apache.org/foundation/thanks.html page.
"ColorCons":http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html, copyright of Ken Saunders. "DejaVu fonts":http://dejavu.sourceforge.net, copyright of Bitstream, Inc.
+
+Community member quotes from a thread on "Stack Overflow":http://stackoverflow.com/questions/1015525/why-use-buildr-instead-of-ant-or-maven/1055864.
doc/index.textile
@@ -4,24 +4,50 @@ layout: preface
p(title). !images/zbuildr.png!
-#(toc) "Getting Started":getting_started.html
-# "Projects":projects.html
-# "Building":building.html
-# "Artifacts":artifacts.html
-# "Packaging":packaging.html
-# "Testing":testing.html
-# "Settings & Profiles":settings_profiles.html
-# "Languages":languages.html
-# "More Stuff":more_stuff.html
-# "Extending Buildr":extending.html
-# "Contributing":contributing.html
+<ol class='toc'>
+ <li>"Getting Started":getting_started.html</li>
+ <li>"Projects":projects.html</li>
+ <li>"Building":building.html</li>
+ <li>"Artifacts":artifacts.html</li>
+ <li>"Packaging":packaging.html</li>
+ <li>"Testing":testing.html</li>
+ <li>"Settings & Profiles":settings_profiles.html</li>
+ <li>"Languages":languages.html</li>
+ <li>"More Stuff":more_stuff.html</li>
+ <li>"Extending Buildr":extending.html</li>
+ <li>"Contributing":contributing.html</li>
+</ol>
-p(preface). Copyright 2007-2009 Apache Buildr
+p(preface). !images/asf-logo.png!
+
+Copyright 2007-2009 Apache Buildr
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
-http://www.apache.org/licenses/LICENSE-2.0
+ http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+
+<div class='preface quotes'>
+"Daniel Spiewak":http://www.codecommit.com/blog:
+
+bq. If you think about it, the question isn’t “Why use Buildr?”, it’s really “Why use anything else?” The advantages afforded by Buildr are so substantial, I really can’t see myself going with any other tool, at least not when I have a choice.
+
+"Tristan Juricek":http://tristanhunt.com/:
+
+bq. That’s still the strongest sell: it builds everything I need, and as I’ve needed more, I just got things working without a lot of fuss.
+
+"Matthieu Riou":http://offthelip.org/:
+
+bq. We used to rely on Ant, with a fairly extensive set of scripts. It worked but was expensive to maintain. The biggest mistake afterward was to migrate to Maven2. I could write pages of rants explaining all the problems we ran into and we still ended up with thousands of lines of XML.
+
+"Martin Grotzke":http://www.javakaffee.de/blog/:
+
+bq. The positive side effect for me as a java user is that I learn a little ruby, and that’s easy but lots of fun… :-)
+</div>
+
+
+p(preface).
doc/preface.textile
@@ -108,8 +108,7 @@ module Buildr
module Git #:nodoc:
-
- module_function
+ module_function
# :call-seq:
# git(*args)
@@ -148,23 +147,19 @@ module Buildr
# Return the name of the remote repository whose branch the current local branch tracks,
# or nil if none.
def remote(branch = current_branch)
- remote = git('config', '--get', "branch.#{branch}.remote").strip
- remote if git('remote').include?(remote)
- rescue
- nil
+ remote = git('config', '--get', "branch.#{branch}.remote").to_s.strip
+ remote if !remote.empty? && git('remote').include?(remote)
end
# Return the name of the current branch
def current_branch
git('branch')[/^\* (.*)$/, 1]
end
-
end
module Svn #:nodoc:
-
- module_function
+ module_function
# :call-seq:
# svn(*args)
lib/buildr/core/build.rb
@@ -317,11 +317,12 @@ module Buildr
#
# The optional block is called with the project name when the task executes
# and returns a message that, for example "Building project #{name}".
- def local_task(args, &block)
- task args do |task|
+ def local_task(*args, &block)
+ task *args do |task, args|
+ args = task.arg_names.map {|n| args[n]}
local_projects do |project|
info block.call(project.name) if block
- task("#{project.name}:#{task.name}").invoke
+ task("#{project.name}:#{task.name}").invoke *args
end
end
end
lib/buildr/core/project.rb
@@ -7,7 +7,7 @@ module Buildr
class JIRB < Base
include JavaRebel
- JRUBY_VERSION = '1.1.6'
+ JRUBY_VERSION = '1.3.1'
class << self
def lang
@@ -54,7 +54,7 @@ module Buildr
]
Java::Commands.java 'org.jruby.Main', "#{jruby_home}#{File::SEPARATOR}bin#{File::SEPARATOR}jirb", {
- :properties => props.merge(rebel_props project),
+ :properties => props.merge(rebel_props(project)),
:classpath => cp,
:java_args => args + rebel_args
}
lib/buildr/core/shell.rb
@@ -367,7 +367,7 @@ if Buildr::Util.java_platform?
end
module FileUtils
- extend extend FFI::Library
+ extend FFI::Library
attach_function :system, [:string], :int
alias_method :__native_system__, :system
@@ -407,4 +407,4 @@ if Buildr::Util.java_platform?
end
end
-end
\ No newline at end of file
+end
lib/buildr/core/util.rb
@@ -236,8 +236,7 @@ module Buildr
end
def tests(dependencies) #:nodoc:
- Dir[task.project.path_to(:source, bdd_dir, lang, '**/*_spec.rb')].
- select do |name|
+ Dir[task.project.path_to(:source, bdd_dir, lang, '**/*_spec.rb')].select do |name|
selector = ENV['SPEC']
selector.nil? || Regexp.new(selector) === name
end
lib/buildr/java/bdd.rb
@@ -74,8 +74,9 @@ module Buildr
elsif content.nil? || File.directory?(content.to_s)
mkpath.call path
else
- zip.put_next_entry(path, compression_level)
+ entry = zip.put_next_entry(path, compression_level)
File.open content.to_s, 'rb' do |is|
+ entry.unix_perms = is.stat.mode & 07777
while data = is.read(4096)
zip << data
end
@@ -155,6 +156,7 @@ module Buildr
dest = File.expand_path(dest, target.to_s)
trace "Extracting #{dest}"
mkpath File.dirname(dest) rescue nil
+ entry.restore_permissions = true
entry.extract(dest) { true }
end
end
lib/buildr/packaging/ziptask.rb
@@ -27,7 +27,7 @@ module Buildr
}
Java::Commands.java 'scala.tools.nsc.MainGenericRunner', {
- :properties => props.merge(rebel_props project),
+ :properties => props.merge(rebel_props(project)),
:classpath => cp,
:java_args => rebel_args
}
lib/buildr/scala/shell.rb
@@ -59,7 +59,7 @@ end
desc "Generate Buildr documentation as buildr.pdf"
file 'buildr.pdf'=>'_site' do |task|
- pages = File.read('doc/preface.textile').scan(/^#.*":(\S*)$/).flatten.map { |f| "_site/#{f}" }
+ pages = File.read('_site/preface.html').scan(/<li><a href=['"]([^'"]+)/).flatten.map { |f| "_site/#{f}" }
sh 'prince', '--input=html', '--no-network', '--log=prince_errors.log', "--output=#{task.name}", '_site/preface.html', *pages
end
rakelib/doc.rake
@@ -14,7 +14,7 @@
# the License.
-#gem 'RedCloth', '4.2.0'
+gem 'mojombo-jekyll', '~> 0.5.2' # skip past some buggy versions
require 'rake/tasklib'
require 'jekyll'
@@ -84,3 +84,37 @@ module TocFilter
end
end
Liquid::Template.register_filter(TocFilter)
+
+
+
+# Under Ruby 1.9 [a,b,c].to_s doesn't join the array first. (Jekyll 0.5.2 requires this)
+module Jekyll
+ class HighlightBlock < Liquid::Block
+ def render(context)
+ if context.registers[:site].pygments
+ render_pygments(context, super.join)
+ else
+ render_codehighlighter(context, super.join)
+ end
+ end
+ end
+end
+
+# Ruby 1.9 has sane closure scoping which manages to mess Liquid filters. (Liquid 2.0.0 requires this)
+module Liquid
+ class Variable
+ def render(context)
+ return '' if @name.nil?
+ @filters.inject(context[@name]) do |output, filter|
+ filterargs = filter[1].to_a.collect do |a|
+ context[a]
+ end
+ begin
+ context.invoke(filter[0], output, *filterargs)
+ rescue FilterNotFound
+ raise FilterNotFound, "Error - filter '#{filter[0]}' in '#{@markup.strip}' could not be found."
+ end
+ end
+ end
+ end
+end
rakelib/jekylltask.rb
@@ -51,9 +51,11 @@ end
file Rake::GemPackageTask.new(spec).package_dir=>:compile
file Rake::GemPackageTask.new(spec).package_dir_path=>:compile
-# We also need the other package (JRuby if building on Ruby, and vice versa)
+# We also need the other packages (JRuby if building on Ruby, and vice versa)
# Must call new with block, even if block does nothing, otherwise bad things happen.
-Rake::GemPackageTask.new(spec(RUBY_PLATFORM[/java/] ? 'ruby' : 'java')) { |task| }
+@specs.values.each do |s|
+ Rake::GemPackageTask.new(s) { |task| }
+end
desc "Upload snapshot packages over to people.apache.org"
rakelib/package.rake
@@ -511,7 +511,7 @@ describe URI::SFTP, '#write' do
end
it 'should create missing paths on server' do
- @sftp_session.should_receive(:opendir!).twice { |path| fail unless path == '/root' }
+ @sftp_session.should_receive(:opendir!) { |path| fail unless path == '/root' }
@sftp_session.should_receive(:mkdir!).once.with('/root/path', {})
@uri.write @content
end
spec/core/transport_spec.rb
@@ -375,6 +375,15 @@ describe ZipTask do
archive(@archive).invoke
inspect_archive { |archive| archive.keys.should include('code/') }
end
+
+ it 'should preserve file permissions' do
+ write 'src/main/bin/hello', 'echo hi'
+ chmod 0777, 'src/main/bin/hello'
+ zip('foo.zip').include('src/main/bin/*').invoke
+ unzip('target' => 'foo.zip').extract
+ (File.stat('target/hello').mode & 0777).should == 0777
+ end
+
end
spec/packaging/archive_spec.rb
9b09a448e05be08b3ae4eb5970daee85457ed87c
761abbffa1e551911fb22e87eb27a6b5be79df42
b52963ea67501984efdbf13cd192670a2d4a37ca
Daniel Spiewak
djspiewak@apache.org
http://github.com/djspiewak/buildr/commit/df1ef5c4a2c9e5633e262e3d61ea762d5a73b19a
df1ef5c4a2c9e5633e262e3d61ea762d5a73b19a
2009-07-08T18:35:46-07:00
2009-07-08T18:35:46-07:00
Merge branches 'trunk' and 'process-status' into HEAD
a3a702663db549f83dd6dc37390e890e9c9c151a
Daniel Spiewak
djspiewak@apache.org