Module: Buildr

Extended by:
Buildr
Includes:
Ant
Included in:
Buildr, Project
Defined in:
lib/buildr.rb,
lib/buildr.rb,
lib/buildr/ide/idea.rb,
lib/buildr/java/ant.rb,
lib/buildr/java/bdd.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/java/emma.rb,
lib/buildr/core/build.rb,
lib/buildr/ide/idea7x.rb,
lib/buildr/java/tests.rb,
lib/buildr/core/checks.rb,
lib/buildr/core/common.rb,
lib/buildr/core/filter.rb,
lib/buildr/ide/eclipse.rb,
lib/buildr/scala/tests.rb,
lib/buildr/core/compile.rb,
lib/buildr/core/project.rb,
lib/buildr/core/generate.rb,
lib/buildr/java/compiler.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/java/test_result.rb,
lib/buildr/packaging/archive.rb,
lib/buildr/packaging/package.rb,
lib/buildr/packaging/ziptask.rb,
lib/buildr/packaging/artifact.rb,
lib/buildr/java/version_requirement.rb,
lib/buildr/packaging/artifact_search.rb,
lib/buildr/packaging/artifact_namespace.rb,
lib/buildr/packaging/version_requirement.rb

Overview

:nodoc:

Defined Under Namespace

Modules: ActsAsArtifact, Ant, Apt, ArtifactSearch, Build, Checks, Cobertura, Compile, Compiler, Eclipse, Emma, Extension, Generate, Groovy, Help, Idea, Idea7x, JMock, Javadoc, Package, PackageAsGem, Packaging, Scala, Test, TestFramework, Util Classes: Application, ArchiveTask, Artifact, ArtifactNamespace, BuildfileTask, CompileTask, ConcatTask, Filter, IntegrationTestsTask, JBehave, JUnit, JtestR, Layout, OptionalArtifact, Options, POM, PackageGemTask, Project, RSpec, Release, Repositories, ResourcesTask, Settings, Svn, TarEntry, TarTask, TestNG, TestTask, Unzip, VersionRequirement, ZipTask

Constant Summary collapse

VERSION = 
'1.3.4'.freeze
ScalaSpecs = 
Scala::ScalaSpecs
ScalaCheck = 
Scala::ScalaCheck
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.



545
546
547
 
# File 'lib/buildr/core/application.rb', line 545

def application
  Rake.application
end

.application=(app) ⇒ Object

:nodoc:



549
550
551
 
# File 'lib/buildr/core/application.rb', line 549

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

.environment ⇒ Object

Copied from BUILD_ENV.



559
560
561
 
# File 'lib/buildr/core/application.rb', line 559

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.



103
104
105
 
# File 'lib/buildr/core/environment.rb', line 103

def options
  @options ||= Options.new
end

.settings ⇒ Object

Returns the Settings associated with this build.



554
555
556
 
# File 'lib/buildr/core/application.rb', line 554

def settings
  Buildr.application.settings
end

Instance Method Details

#artifact(spec, &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')



617
618
619
620
621
622
623
624
625
626
627
628
 
# File 'lib/buildr/packaging/artifact.rb', line 617

def artifact(spec, &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(repositories.locate(spec))
    task.send :apply_spec, spec
    Rake::Task['rake:artifacts'].enhance [task]
    Artifact.register(task)
    Rake::Task['artifacts:sources'].enhance [task.sources_artifact] unless spec[:type] == :pom
  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



965
966
967
968
 
# File 'lib/buildr/packaging/artifact_namespace.rb', line 965

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



654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
 
# File 'lib/buildr/packaging/artifact.rb', line 654

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"]



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

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



799
800
801
 
# File 'lib/buildr/core/project.rb', line 799

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'



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

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



362
363
364
 
# File 'lib/buildr/core/filter.rb', line 362

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)

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'



713
714
715
716
 
# File 'lib/buildr/packaging/artifact.rb', line 713

def group(*args)
  hash = args.pop
  args.flatten.map { |id| artifact :group=>hash[:under], :type=>hash[:type], :version=>hash[:version], :id=>id }
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)

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) 


726
727
728
729
730
731
732
733
734
735
736
737
738
 
# File 'lib/buildr/packaging/artifact.rb', line 726

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

#integration(*deps, &block) ⇒ Object

:call-seq:

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

Use this method to return the integration tests task.



654
655
656
 
# File 'lib/buildr/core/test.rb', line 654

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

#options ⇒ Object

:call-seq:

options => Options

Returns the Buildr options. See Options.



113
114
115
 
# File 'lib/buildr/core/environment.rb', line 113

def options
  Buildr.options
end

#project(*args) ⇒ 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



838
839
840
 
# File 'lib/buildr/core/project.rb', line 838

def project(*args)
  Project.project *args
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)



861
862
863
 
# File 'lib/buildr/core/project.rb', line 861

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

#read(name) ⇒ Object

:call-seq:

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

Reads and returns the contents of a file. The second form yields to the block and returns the result of the block.

For example:

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



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

def read(name)
  contents = File.open(name.to_s) { |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.



590
591
592
 
# File 'lib/buildr/packaging/artifact.rb', line 590

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 



677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
 
# File 'lib/buildr/packaging/artifact.rb', line 677

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')



305
306
307
308
309
310
311
 
# File 'lib/buildr/packaging/ziptask.rb', line 305

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) 


748
749
750
751
752
753
754
755
756
757
 
# File 'lib/buildr/packaging/artifact.rb', line 748

def upload(*args, &block)
  artifacts = artifacts(args)
  raise ArgumentError, 'This method can only upload artifacts' unless artifacts.all? { |f| f.respond_to?(:to_spec) }
  task('upload').tap do |task|
    task.enhance &block if block
    task.enhance artifacts do
      artifacts.each { |artifact| artifact.upload }
    end
  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), :verbose=>false
  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



103
104
105
 
# File 'lib/buildr/packaging/ziptask.rb', line 103

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