Module: Buildr

Extended by:
Buildr
Includes:
Ant
Included in:
Buildr, Artifact, Project
Defined in:
lib/buildr.rb,
lib/buildr/run.rb,
lib/buildr/shell.rb,
lib/buildr/core/cc.rb,
lib/buildr/version.rb,
lib/buildr/core/doc.rb,
lib/buildr/core/run.rb,
lib/buildr/ide/idea.rb,
lib/buildr/java/ant.rb,
lib/buildr/java/bdd.rb,
lib/buildr/java/doc.rb,
lib/buildr/java/ecj.rb,
lib/buildr/java/pom.rb,
lib/buildr/core/help.rb,
lib/buildr/core/help.rb,
lib/buildr/core/test.rb,
lib/buildr/core/util.rb,
lib/buildr/core/util.rb,
lib/buildr/java/emma.rb,
lib/buildr/scala/bdd.rb,
lib/buildr/scala/doc.rb,
lib/buildr/core/build.rb,
lib/buildr/core/shell.rb,
lib/buildr/groovy/doc.rb,
lib/buildr/java/tests.rb,
lib/buildr/core/checks.rb,
lib/buildr/core/common.rb,
lib/buildr/core/filter.rb,
lib/buildr/core/jrebel.rb,
lib/buildr/ide/eclipse.rb,
lib/buildr/scala/shell.rb,
lib/buildr/scala/tests.rb,
lib/buildr/core/compile.rb,
lib/buildr/core/project.rb,
lib/buildr/groovy/shell.rb,
lib/buildr/core/generate.rb,
lib/buildr/java/compiler.rb,
lib/buildr/java/external.rb,
lib/buildr/packaging/tar.rb,
lib/buildr/java/cobertura.rb,
lib/buildr/java/packaging.rb,
lib/buildr/packaging/gems.rb,
lib/buildr/core/application.rb,
lib/buildr/core/environment.rb,
lib/buildr/ide/eclipse/java.rb,
lib/buildr/java/test_result.rb,
lib/buildr/ide/eclipse/scala.rb,
lib/buildr/packaging/archive.rb,
lib/buildr/packaging/package.rb,
lib/buildr/packaging/ziptask.rb,
lib/buildr/ide/eclipse/plugin.rb,
lib/buildr/java/jtestr_result.rb,
lib/buildr/packaging/artifact.rb,
lib/buildr/java/version_requirement.rb,
lib/buildr/packaging/artifact_search.rb,
lib/buildr/packaging/repository_array.rb,
lib/buildr/packaging/artifact_namespace.rb,
lib/buildr/packaging/version_requirement.rb

Overview

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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

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.

Defined Under Namespace

Modules: ActsAsArtifact, Ant, Apt, ArtifactSearch, Build, CC, Checks, Clojure, Cobertura, Compile, Compiler, Doc, Eclipse, Emma, Extension, Generate, Git, Groovy, Help, IntellijIdea, JMock, JRebel, Package, PackageAsGem, Packaging, Run, Scala, Shell, Svn, Test, TestFramework, Util Classes: Application, ArchiveTask, Artifact, ArtifactNamespace, BuildfileTask, CCTask, CompileTask, ConcatTask, Filter, GitRelease, IntegrationTestsTask, JBehave, JUnit, JtestR, Layout, OptionalArtifact, Options, POM, PackageGemTask, ProcessStatus, Project, RSpec, Release, Repositories, RepositoryArray, ResourcesTask, Settings, SvnRelease, TarEntry, TarTask, TestNG, TestTask, Unzip, VersionRequirement, ZipTask

Constant Summary collapse

VERSION = 
'1.4.5'.freeze
ScalaSpecs = 
Scala::Specs
ScalaCheck = 
Scala::Check
ScalaTest = 
Scala::ScalaTest

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Ant

#ant, dependencies, version

Class Method Details

.application ⇒ Object

Returns the Buildr::Application object.



576
577
578
 
# File 'lib/buildr/core/application.rb', line 576

def application
  Rake.application
end

.application=(app) ⇒ Object

:nodoc:



580
581
582
 
# File 'lib/buildr/core/application.rb', line 580

def application=(app) #:nodoc:
  Rake.application = app
end

.environment ⇒ Object

Copied from BUILD_ENV.



590
591
592
 
# File 'lib/buildr/core/application.rb', line 590

def environment
  Buildr.application.environment
end

.help(&block) ⇒ Object 



47
48
49
50
 
# File 'lib/buildr/core/help.rb', line 47

def help(&block)
  Help << block if block_given?
  Help
end

.options ⇒ Object

:call-seq:

options => Options

Returns the Buildr options. See Options.



115
116
117
 
# File 'lib/buildr/core/environment.rb', line 115

def options
  @options ||= Options.new
end

.settings ⇒ Object

Returns the Settings associated with this build.



585
586
587
 
# File 'lib/buildr/core/application.rb', line 585

def settings
  Buildr.application.settings
end

Instance Method Details

#artifact(spec, path = nil, &block) ⇒ Object

:call-seq:

artifact(spec) => Artifact
artifact(spec) { |task| ... } => Artifact

Creates a file task to download and install the specified artifact in the local repository.

You can use a String or a Hash for the artifact specification. The file task will point at the artifact’s path inside the local repository. You can then use this tasks as a prerequisite for other tasks.

This task will download and install the artifact only once. In fact, it will download and install the artifact if the artifact does not already exist. You can enhance it if you have a different way of creating the artifact in the local repository. See Artifact for more details.

For example, to specify an artifact:

artifact('log4j:log4j:jar:1.1')

To use the artifact in a task:

compile.with artifact('log4j:log4j:jar:1.1')

To specify an artifact and the means for creating it:

download(artifact('dojo:dojo-widget:zip:2.0')=>
  'http://download.dojotoolkit.org/release-2.0/dojo-2.0-widget.zip')



753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
 
# File 'lib/buildr/packaging/artifact.rb', line 753

def artifact(spec, path = nil, &block) #:yields:task
  spec = artifact_ns.fetch(spec) if spec.kind_of?(Symbol)
  spec = Artifact.to_hash(spec)
  unless task = Artifact.lookup(spec)
    task = Artifact.define_task(path || repositories.locate(spec))
    task.send :apply_spec, spec
    Rake::Task['rake:artifacts'].enhance [task]
    Artifact.register(task)
    unless spec[:type] == :pom
      Rake::Task['artifacts:sources'].enhance [task.sources_artifact]
      Rake::Task['artifacts:javadoc'].enhance [task.javadoc_artifact]
    end
  end
  task.enhance &block
end

#artifact_ns(name = nil, &block) ⇒ Object

:call-seq:

project.artifact_ns -> ArtifactNamespace
Buildr.artifact_ns(name) -> ArtifactNamespace
Buildr.artifact_ns -> ArtifactNamespace for the currently running Project

Open an ArtifactNamespace. If a block is provided, the namespace is yielded to it.

See also ArtifactNamespace.instance



977
978
979
980
 
# File 'lib/buildr/packaging/artifact_namespace.rb', line 977

def artifact_ns(name = nil, &block)
  name = self if name.nil? && self.kind_of?(Project)
  ArtifactNamespace.instance(name, &block)
end

#artifacts(*specs, &block) ⇒ Object

:call-seq:

artifacts(*spec) => artifacts

Handles multiple artifacts at a time. This method is the plural equivalent of #artifact, but can do more things.

Returns an array of artifacts built using the supplied specifications, each of which can be:

  • An artifact specification (String or Hash). Returns the appropriate Artifact task.

  • An artifact of any other task. Returns the task as is.

  • A project. Returns all artifacts created (packaged) by that project.

  • A string. Returns that string, assumed to be a file name.

  • An array of artifacts or a Struct.

  • A symbol. Returns the named artifact from the current ArtifactNamespace

For example, handling a collection of artifacts:

xml = [ xerces, xalan, jaxp ]
ws = [ axis, jax-ws, jaxb ]
db = [ jpa, mysql, sqltools ]
artifacts(xml, ws, db)

Using artifacts created by a project:

artifacts project('my-app')               # All packages
artifacts project('my-app').package(:war) # Only the WAR



793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
 
# File 'lib/buildr/packaging/artifact.rb', line 793

def artifacts(*specs, &block)
  specs.flatten.inject([]) do |set, spec|
    case spec
    when ArtifactNamespace
      set |= spec.artifacts
    when Symbol, Hash
      set |= [artifact(spec)]
    when /([^:]+:){2,4}/ # A spec as opposed to a file name.
      set |= [artifact(spec)]
    when String # Must always expand path.
      set |= [File.expand_path(spec)]
    when Project
      set |= artifacts(spec.packages)
    when Rake::Task
      set |= [spec]
    when Struct
      set |= artifacts(spec.values)
    else
      fail "Invalid artifact specification in #{specs.inspect}"
    end
  end
end

#concat(args) ⇒ Object

:call-seq:

concat(target=>files) => task

Creates and returns a file task that concatenates all its prerequisites to create a new file. See #ConcatTask.

For example:

concat("master.sql"=>["users.sql", "orders.sql", reports.sql"]



146
147
148
149
 
# File 'lib/buildr/core/common.rb', line 146

def concat(args)
  file, arg_names, deps = Buildr.application.resolve_args([args])
  ConcatTask.define_task(File.expand_path(file)=>deps)
end

#define(name, properties = nil, &block) ⇒ Object

:call-seq:

define(name, properties?) { |project| ... } => project

Defines a new project.

The first argument is the project name. Each project must have a unique name. For a sub-project, the actual project name is created by prefixing the parent project’s name.

The second argument is optional and contains a hash or properties that are set on the project. You can only use properties that are supported by the project definition, e.g. :group and :version. You can also set these properties from the project definition.

You pass a block that is executed in the context of the project definition. This block is used to define the project and tasks that are part of the project. Do not perform any work inside the project itself, as it will execute each time the Buildfile is loaded. Instead, use it to create and extend tasks that are related to the project.

For example:

define 'foo', :version=>'1.0' do

  define 'bar' do
    compile.with 'org.apache.axis2:axis2:jar:1.1'
  end
end

puts project('foo').version
=> '1.0'
puts project('foo:bar').compile.classpath.map(&:to_spec)
=> 'org.apache.axis2:axis2:jar:1.1'
% buildr build
=> Compiling 14 source files in foo:bar



909
910
911
 
# File 'lib/buildr/core/project.rb', line 909

def define(name, properties = nil, &block) #:yields:project
  Project.define(name, properties, &block)
end

#download(args) ⇒ Object

:call-seq:

download(url_or_uri) => task
download(path=>url_or_uri) =>task

Create a task that will download a file from a URL.

Takes a single argument, a hash with one pair. The key is the file being created, the value if the URL to download. The task executes only if the file does not exist; the URL is not checked for updates.

The task will show download progress on the console; if there are MD5/SHA1 checksums on the server it will verify the download before saving it.

For example:

download 'image.jpg'=>'http://example.com/theme/image.jpg'



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/buildr/core/common.rb', line 95

def download(args)
  args = URI.parse(args) if String === args
  if URI === args
    # Given only a download URL, download into a temporary file.
    # You can infer the file from task name.
    temp = Tempfile.open(File.basename(args.to_s))
    file(temp.path).tap do |task|
      # Since temporary file exists, force a download.
      class << task ; def needed? ; true ; end ; end
      task.sources << args
      task.enhance { args.download temp }
    end
  else
    # Download to a file created by the task.
    fail unless args.keys.size == 1
    uri = URI.parse(args.values.first.to_s)
    file(args.keys.first.to_s).tap do |task|
      task.sources << uri
      task.enhance { uri.download task.name }
    end
  end

end

#filter(*sources) ⇒ Object

:call-seq:

filter(*source) => Filter

Creates a filter that will copy files from the source directory(ies) into the target directory. You can extend the filter to modify files by mapping ${key} into values in each of the copied files, and by including or excluding specific files.

A filter is not a task, you must call the Filter#run method to execute it.

For example, to copy all files from one directory to another:

filter('src/files').into('target/classes').run

To include only the text files, and replace each instance of ${build} with the current date/time:

filter('src/files').into('target/classes').include('*.txt').using('build'=>Time.now).run



400
401
402
 
# File 'lib/buildr/core/filter.rb', line 400

def filter(*sources)
  Filter.new.from(*sources)
end

#group(*args) ⇒ Object

:call-seq:

group(ids, :under=>group_name, :version=>number) => artifacts

Convenience method for defining multiple artifacts that belong to the same group, type and version. Accepts multiple artifact identifiers followed by two or three hash values:

  • :under – The group identifier

  • :version – The version number

  • :type – The artifact type (optional)

  • :classifier – The artifact classifier (optional)

For example:

group 'xbean', 'xbean_xpath', 'xmlpublic', :under=>'xmlbeans', :version=>'2.1.0'

Or:

group %w{xbean xbean_xpath xmlpublic}, :under=>'xmlbeans', :version=>'2.1.0'



853
854
855
856
857
858
859
860
861
862
 
# File 'lib/buildr/packaging/artifact.rb', line 853

def group(*args)
  hash = args.pop
  args.flatten.map do |id|
    artifact :group   => hash[:under],
             :type    => hash[:type],
             :version => hash[:version],
             :classifier => hash[:classifier],
             :id => id
  end
end

#help(&block) ⇒ Object

:call-seq:

help() { ... }

Use this to enhance the help task, e.g. to print some important information about your build, configuration options, build instructions, etc.



91
92
93
 
# File 'lib/buildr/core/help.rb', line 91

def help(&block)
  Buildr.help << block
end

#install(*args, &block) ⇒ Object

:call-seq:

install(artifacts) => install_task

Installs the specified artifacts in the local repository as part of the install task.

You can use this to install various files in the local repository, for example:

install artifact('group:id:jar:1.0').from('some_jar.jar')
$ buildr install

Raises:

  • (ArgumentError) 


872
873
874
875
876
877
878
879
880
881
882
883
884
 
# File 'lib/buildr/packaging/artifact.rb', line 872

def install(*args, &block)
  artifacts = artifacts(args).uniq
  raise ArgumentError, 'This method can only install artifacts' unless artifacts.all? { |f| f.respond_to?(:to_spec) }
  task('install').tap do |install|
    install.enhance(artifacts) do
      artifacts.each(&:install)
    end
    install.enhance &block if block
    task('uninstall') do
      artifacts.map(&:to_s ).each { |file| rm file if File.exist?(file) }
    end
  end
end

#integration(*deps, &block) ⇒ Object

:call-seq:

integration { |task| .... }
integration => IntegrationTestTask

Use this method to return the integration tests task.



780
781
782
 
# File 'lib/buildr/core/test.rb', line 780

def integration(*deps, &block)
  Rake::Task['rake:integration'].enhance deps, &block
end

#options ⇒ Object

:call-seq:

options => Options

Returns the Buildr options. See Options.



125
126
127
 
# File 'lib/buildr/core/environment.rb', line 125

def options
  Buildr.options
end

#project(*args, &block) ⇒ Object

:call-seq:

project(name) => project

Returns a project definition.

When called from outside a project definition, must reference the project by its full name, e.g. ‘foo:bar’ to access the sub-project ‘bar’ in ‘foo’. When called from inside a project, relative names are sufficient, e.g. project('foo').project('bar') will find the sub-project ‘bar’ in ‘foo’.

You cannot reference a project before the project is defined. When working with sub-projects, the project definition is stored by calling #define, and evaluated before a call to the parent project’s #define method returns.

However, if you call #project with the name of another sub-project, its definition is evaluated immediately. So the returned project definition is always complete, and you can access its definition (e.g. to find files relative to the base directory, or packages created by that project).

For example:

define 'myapp' do
  self.version = '1.1'

  define 'webapp' do
    # webapp is defined first, but beans is evaluated first
    compile.with project('beans')
    package :war
  end

  define 'beans' do
    package :jar
  end
end

puts project('myapp:beans').version



948
949
950
 
# File 'lib/buildr/core/project.rb', line 948

def project(*args, &block)
  Project.project *args, &block
end

#projects(*args) ⇒ Object

:call-seq:

projects(*names) => projects

With no arguments, returns a list of all projects defined so far. When called on a project, returns all its sub-projects (direct descendants).

With arguments, returns a list of named projects, fails on any name that does not exist. As with #project, you can use relative names when calling this method on a project.

Like #project, this method evaluates the definition of each project before returning it. Be advised of circular dependencies.

For example:

files = projects.map { |prj| FileList[prj.path_to('src/**/*.java') }.flatten
puts "There are #{files.size} source files in #{projects.size} projects"

puts projects('myapp:beans', 'myapp:webapp').map(&:name)

Same as:

puts project('myapp').projects.map(&:name)



971
972
973
 
# File 'lib/buildr/core/project.rb', line 971

def projects(*args)
  Project.projects *args
end

#read(*args) ⇒ Object

:call-seq:

read(args) => string
read(args) { |string| ... } => result

Reads and returns the contents of a file. The second form yields to the block and returns the result of the block. The args passed to read are passed on to File.open.

For example:

puts read('README')
read('README') { |text| puts text }



70
71
72
73
74
75
76
77
78
 
# File 'lib/buildr/core/common.rb', line 70

def read(*args)
  args[0] = args[0].to_s
  contents = File.open(*args) { |f| f.read }
  if block_given?
    yield contents
  else
    contents
  end
end

#repositories ⇒ Object

:call-seq:

repositories => Repositories

Returns an object you can use for setting the local repository path, remote repositories URL and release server settings.

See Repositories.



726
727
728
 
# File 'lib/buildr/packaging/artifact.rb', line 726

def repositories
  Repositories.instance
end

#struct(hash) ⇒ Object

:call-seq:

struct(hash) => Struct

Convenience method for creating an anonymous Struct.

For example:

COMMONS             = struct(
  :collections      =>'commons-collections:commons-collections:jar:3.1',
  :lang             =>'commons-lang:commons-lang:jar:2.1',
  :logging          =>'commons-logging:commons-logging:jar:1.0.3',
)

compile.with COMMONS.logging



36
37
38
 
# File 'lib/buildr/core/common.rb', line 36

def struct(hash)
  Struct.new(nil, *hash.keys).new(*hash.values)
end

#transitive(*specs) ⇒ Object 



816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
 
# File 'lib/buildr/packaging/artifact.rb', line 816

def transitive(*specs)
  specs.flatten.inject([]) do |set, spec|
    case spec
    when /([^:]+:){2,4}/ # A spec as opposed to a file name.
      artifact = artifact(spec)
      set |= [artifact] unless artifact.type == :pom
      set |= POM.load(artifact.pom).dependencies.map { |spec| artifact(spec) }
    when Hash
      set |= [transitive(spec)]
    when String # Must always expand path.
      set |= transitive(file(File.expand_path(spec)))
    when Project
      set |= transitive(spec.packages)
    when Rake::Task
      set |= spec.respond_to?(:to_spec) ? transitive(spec.to_spec) : [spec]
    when Struct
      set |= transitive(spec.values)
    else
      fail "Invalid artifact specification in: #{specs.to_s}"
    end
  end
end

#unzip(args) ⇒ Object

:call-seq:

unzip(to_dir=>zip_file) => Zip

Creates a task that will unzip a file into the target directory. The task name is the target directory, the prerequisite is the file to unzip.

This method creates a file task to expand the zip file. It returns an Unzip object that specifies how the file will be extracted. You can include or exclude specific files from within the zip, and map to different paths.

The Unzip object’s to_s method return the path to the target directory, so you can use it as a prerequisite. By keeping the Unzip object separate from the file task, you overlay additional work on top of the file task.

For example:

unzip('all'=>'test.zip')
unzip('src'=>'test.zip').include('README', 'LICENSE')
unzip('libs'=>'test.zip').from_path('libs')



348
349
350
351
352
353
354
 
# File 'lib/buildr/packaging/ziptask.rb', line 348

def unzip(args)
  target, arg_names, zip_file = Buildr.application.resolve_args([args])
  task = file(File.expand_path(target.to_s)=>zip_file)
  Unzip.new(task=>zip_file).tap do |setup|
    task.enhance { setup.extract }
  end
end

#upload(*args, &block) ⇒ Object

:call-seq:

upload(artifacts)

Uploads the specified artifacts to the release server as part of the upload task.

You can use this to upload various files to the release server, for example:

upload artifact('group:id:jar:1.0').from('some_jar.jar')
$ buildr upload

Raises:

  • (ArgumentError) 


894
895
896
897
898
899
900
901
902
 
# File 'lib/buildr/packaging/artifact.rb', line 894

def upload(*args, &block)
  artifacts = artifacts(args)
  raise ArgumentError, 'This method can only upload artifacts' unless artifacts.all? { |f| f.respond_to?(:to_spec) }
  upload_artifacts_tasks = artifacts.map { |artifact| artifact.upload_task }
  task('upload').tap do |task|
    task.enhance &block if block
    task.enhance upload_artifacts_tasks
  end
end

#write(name, content = nil) ⇒ Object

:call-seq:

write(name, content)
write(name) { ... }

Write the contents into a file. The second form calls the block and writes the result.

For example:

write 'TIMESTAMP', Time.now
write('TIMESTAMP') { Time.now }

Yields to the block before writing the file, so you can chain read and write together. For example:

write('README') { read('README').sub("${build}", Time.now) }



53
54
55
56
57
58
 
# File 'lib/buildr/core/common.rb', line 53

def write(name, content = nil)
  mkpath File.dirname(name)
  content = yield if block_given?
  File.open(name.to_s, 'wb') { |file| file.write content.to_s }
  content.to_s
end

#zip(file) ⇒ Object

:call-seq:

zip(file) => ZipTask

The ZipTask creates a new Zip file. You can include any number of files and and directories, use exclusion patterns, and include files into specific directories.

For example:

zip('test.zip').tap do |task|
  task.include 'srcs'
  task.include 'README', 'LICENSE'
end



106
107
108
 
# File 'lib/buildr/packaging/ziptask.rb', line 106

def zip(file)
  ZipTask.define_task(file)
end