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/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/packaging/zip.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/package.rb,
lib/buildr/packaging/artifact.rb,
lib/buildr/core/application_cli.rb,
lib/buildr/java/version_requirement.rb,
lib/buildr/packaging/artifact_search.rb,
lib/buildr/packaging/artifact_namespace.rb

Overview

:nodoc:

Defined Under Namespace

Modules: ActsAsArtifact, Ant, Apt, ArtifactSearch, Build, Checks, CommandLineInterface, Compile, Compiler, Eclipse, 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, Options, POM, PackageGemTask, Project, RSpec, Release, Repositories, ResourcesTask, Settings, Svn, TarTask, TestNG, TestTask, Unzip, VersionRequirement, ZipTask

Constant Summary collapse

VERSION = 
'1.3.3'.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.



365
366
367
 
# File 'lib/buildr/core/application.rb', line 365

def application
  Rake.application
end

.application=(app) ⇒ Object

:nodoc:



369
370
371
 
# File 'lib/buildr/core/application.rb', line 369

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

.environment ⇒ Object

Copied from BUILD_ENV.



379
380
381
 
# File 'lib/buildr/core/application.rb', line 379

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.



106
107
108
 
# File 'lib/buildr/core/environment.rb', line 106

def options
  @options ||= Options.new
end

.settings ⇒ Object

Returns the Settings associated with this build.



374
375
376
 
# File 'lib/buildr/core/application.rb', line 374

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



589
590
591
592
593
594
595
596
597
598
599
 
# File 'lib/buildr/packaging/artifact.rb', line 589

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



625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
 
# File 'lib/buildr/packaging/artifact.rb', line 625

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



149
150
151
152
 
# File 'lib/buildr/core/common.rb', line 149

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



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

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'



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

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



358
359
360
 
# File 'lib/buildr/core/filter.rb', line 358

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'



684
685
686
687
 
# File 'lib/buildr/packaging/artifact.rb', line 684

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.



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

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) 


697
698
699
700
701
702
703
704
705
706
707
708
709
 
# File 'lib/buildr/packaging/artifact.rb', line 697

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.



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

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



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

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)



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

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 }



74
75
76
77
78
79
80
81
 
# File 'lib/buildr/core/common.rb', line 74

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.



562
563
564
 
# File 'lib/buildr/packaging/artifact.rb', line 562

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



40
41
42
 
# File 'lib/buildr/core/common.rb', line 40

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

#transitive(*specs) ⇒ Object 



648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
 
# File 'lib/buildr/packaging/artifact.rb', line 648

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



700
701
702
703
704
705
706
 
# File 'lib/buildr/packaging/zip.rb', line 700

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) 


719
720
721
722
723
724
725
726
727
728
 
# File 'lib/buildr/packaging/artifact.rb', line 719

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



57
58
59
60
61
62
 
# File 'lib/buildr/core/common.rb', line 57

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



498
499
500
 
# File 'lib/buildr/packaging/zip.rb', line 498

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