Module: Buildr

Defined in:
lib/buildr.rb,
lib/core/core.rb,
lib/java/java.rb,
lib/java/test.rb,
lib/tasks/zip.rb,
lib/core/build.rb,
lib/java/jetty.rb,
lib/java/javacc.rb,
lib/core/project.rb,
lib/java/compile.rb,
lib/java/eclipse.rb,
lib/java/openjpa.rb,
lib/tasks/filter.rb,
lib/core/artifact.rb,
lib/java/xmlbeans.rb,
lib/java/packaging.rb,
lib/tasks/download.rb,
lib/core/transports.rb

Defined Under Namespace

Modules: ActsAsArtifact, Attributes, Java, JavaCC, Jetty, OpenJPA, Transports, XMLBeans Classes: Artifact, Filter, JUnitTask, Project, ReleaseTask, Repositories, Tests, UnzipTask, ZipTask

Constant Summary collapse

VERSION = 
"0.17.0"
BUILD_TASKS = 
{
  :build    =>"Build the project",
  :clean    =>"Clean files generated during a build",
  :package  =>"Create packages",
  :install  =>"Install packages created by the project",
  :uninstall=>"Remove previously installed packages",
  :deploy   =>"Deploy packages created by the project"
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.compile(*sources) ⇒ Object

Create and return a compiler task. The task is name “compile” in the current namespace. Method arguments are passed as sources to compile, and options are inherited from any compile task in a parent namespace.

For example:

compile("src").to("classes").with(artifact, file, task)



245
246
247
248
249
 
# File 'lib/java/compile.rb', line 245

def self.compile(*sources)
  returning(Java::CompileTask.define_task("compile")) do |task|
    task.sources |= sources
  end
end

Instance Method Details

#artifact(spec, &block) ⇒ Object

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

The artifact specification can be a string or a hash. The file task points to the artifact in the local repository.

You can provide alternative behavior to create the artifact instead of downloading it from a remote repository.

For example, to specify an artifact:

artifact("log4j:log4j:jar:1.1")

To use the artifact in a task:

unzip artifact("org.apache.pxe:db-derby:zip:1.2")

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



292
293
294
295
296
297
298
299
300
 
# File 'lib/core/artifact.rb', line 292

def artifact(spec, &block)
  spec = Artifact.to_hash(spec)
  unless task = Artifact.lookup(spec)
    task = Artifact.define_task(repositories.locate(spec))
    Artifact.register(task)
  end
  task.apply_spec spec
  task.enhance &block
end

#artifacts(*specs) ⇒ Object

Creates multiple artifacts from a set of specifications and returns an array of tasks.

You can pass any number of arguments, each of which can be:

  • An artifact specification, string or hash. Returns a new task for each specification, by calling #artifact.

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

  • A project. Returns all packaging tasks in that project.

  • An array of artifacts. Returns all the artifacts found there.

This method handles arrays of artifacts as if they are flattend, to help in managing large combinations of artifacts. For example:

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

You can also pass tasks and project. This is particularly useful for dealing with dependencies between projects that are part of the same build.

For example:

artifacts(base, models, services, module1, module2)

When passing a project as argument, it expands that project to all its packaging tasks. You can then use the resulting artifacts as dependencies that will force these packages to be build inside the project, without installing them in the local repository.



331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/core/artifact.rb', line 331

def artifacts(*specs)
  specs.inject([]) do |set, spec|
    case spec
    when Hash
      set |= [artifact(spec)]
    when /:/
      set |= [artifact(spec)]
    when String
      set |= [file(spec)]
    when Project
      set |= artifacts(spec.packages)
    when Rake::Task
      set |= [spec]
    when Array
      set |= artifacts(*spec)
    else
      fail "Invalid artifact specification: #{spec.to_s || 'nil'}"
    end
    set
  end
end

#define(*args, &block) ⇒ Object

:call-seq:

define name { |project| ... }
define name, properties { |project| ... }
define properties { |project| ... }

Defines a new project.

The first argument is the project name. Each project must have a unique name, and you can only define a project once.

The second argument contains any number of properties that are set on the project. The project must have attribute accessors to support these properties. You can also pass the project name in the properties hash.

The easiest way to define a project and configure its tasks is by passing a block. The #define method executes the block within the context of the project, as if with instance_eval. It also passes the project to the block.

For example:

define "foo", :version=>"1.0" do
  . . .
end

define "bar" do |project|
  project.version = "1.0"
  . . .
end

define "baz" do
  self.version = "1.0"
end

Each project also has a #define method that operates the same way, but defines a sub-project. A sub-project has a compound name using the parent project’s name, and also inherits some of its properties. You can only define a sub-project as part of the parent project’s definition.

For example:

define "foo", :version=>"1.0" do
  define "bar"
    puts name
    puts version
  end
end
=> "foo:bar"
"1.0"



436
437
438
 
# File 'lib/core/project.rb', line 436

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

#deploy(*args) ⇒ Object

Deploys all the specified artifacts/files. Specify the deployment server by passing a hash as the last argument, or have it use repositories.deploy_to.

For example:

deploy(*process.packages, :url=>"sftp://example.com/var/www/maven")



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
 
# File 'lib/core/artifact.rb', line 374

def deploy(*args)
  # Where do we release to?
  if Hash === args.last
    options = args.pop
  else
    options = repositories.deploy_to
    options = { :url=>options.to_s } unless Hash === options
  end
  url = options[:url]
  options = options.reject { |k,v| k === :url }
  fail "Don't know where to deploy, perhaps you forgot to set repositories.deploy_to" if url.blank?

  args.each { |arg| arg.invoke if arg.respond_to?(:invoke) }
  Transports.perform url, options do |session|
    args.each do |artifact|
      if artifact.respond_to?(:to_spec)
        # Upload artifact relative to base URL, need to create path before uploading.
        puts "Deploying #{artifact.to_spec}" if verbose
        spec = artifact.to_spec_hash
        path = spec[:group].gsub(".", "/") + "/#{spec[:id]}/#{spec[:version]}/"
        session.mkpath path
        session.upload artifact.to_s, path + Artifact.hash_to_file_name(spec)
      else
        # Upload artifact to URL.
        puts "Deploying #{artifact}" if verbose
        session.upload artifact, File.basename(artifact)
      end
    end
  end
end

#download(args) ⇒ Object

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"



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/tasks/download.rb', line 16

def download(args)
  if String === args || URI === args
    # Given only a download URL, download into a temporary file.
    # You can infer the file from task name.
    temp = Tempfile.new(File.basename(args.to_s))
    task = file_create(temp.path) do |task|
      Transports.download task.source, task.name
    end
    task.sources << args
  else
    # Download to a file created by the task.
    fail unless args.keys.size == 1
    url = args.values.first
    task = file_create(args.keys.first) do |task|
      mkpath File.dirname(task.name), :verbose=>false
      Transports.download task.source, task.name
    end
    task.sources << url
  end
  task
end

#filter(*files) ⇒ Object 



90
91
92
93
94
 
# File 'lib/tasks/filter.rb', line 90

def filter(*files)
  task = nil
  namespace { task = Filter.define_task("filter").include *files }
  task
end

#group(*args) ⇒ Object

Convenience method for defining multiple artifacts that belong to the same version and group. Accepts multiple artifact identifiers (or arrays of) followed by two has keys:

  • :under – The group identifier

  • :version – The version number

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"



363
364
365
366
 
# File 'lib/core/artifact.rb', line 363

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

#jar(file) ⇒ Object

Create a JAR from all the pre-requisites.

For example:

jar "lib-1.0.jar"=>["target/classes", "MANIFEST,MF"]



78
79
80
 
# File 'lib/java/packaging.rb', line 78

def jar(file)
  Packaging::JarTask.define_task(file)
end

#java(*args) ⇒ Object 



110
111
112
 
# File 'lib/java/java.rb', line 110

def java(*args)
  Java.java(*args)
end

#project(name) ⇒ Object

Returns the named project.

For a sub-project, use the full name, for example “foo:bar” to find the sub-project “bar” of the parent project “foo”.

You cannot reference a project before the project is defined, with one exception. When working with sub-projects, the project definitions are stored but not executed until the parent project is defined. So within a sub-project definition you can reference another sub-project definition. The definitions are then performed (invoked) based on that dependency. You cannot have circular references between project definitions.

For example:

define "project1" do
  self.version = "1.1"

  define "module1" do
    package :jar
  end

  define "module2" do
    compile.with project("project1:module1")
    package :jar
  end
end



465
466
467
 
# File 'lib/core/project.rb', line 465

def project(name)
  Project.project(name)
end

#projects(*args) ⇒ Object

With no arguments, returns a list of all the projects defined so far.

With arguments, returns a list of these projects. Equivalent to calling #project for each named project.

For example:

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

projects("project1", "project2").map(&:base_dir)



479
480
481
 
# File 'lib/core/project.rb', line 479

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

#repositories ⇒ Object

Returns a global object for setting local, remote and deploy repositories. See Repositories.



271
272
273
 
# File 'lib/core/artifact.rb', line 271

def repositories()
  Repositories.instance
end

#unzip(file) ⇒ Object

Defines a task that will unzip the specified file, into the directory specified by calling #into. It is the second call to into that creates and returns the task.

You can unzip only some files by specifying an inclusion or exclusion pattern, and unzip files from a path in the ZIP file. See UnzipTask for more information.

For example:

unzip("test.zip").into("test")
unzip("test.zip").into("etc").include("README", "LICENSE") 
unzip("test.zip").into("src").from_path("srcs")



416
417
418
419
420
 
# File 'lib/tasks/zip.rb', line 416

def unzip(file)
  task = nil
  namespace { task = UnzipTask.define_task("unzip"=>file) }
  task
end

#zip(file) ⇒ Object

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:

returning(zip("test.zip")) { |task|
  task.include "srcs"
  task.include "README", "LICENSE"
end



256
257
258
 
# File 'lib/tasks/zip.rb', line 256

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