+ module Buildr::Package +

+ +

Methods added to Project to support packaging +and tasks for packaging, installing and uploading packages.

+ +

+ + + + +

+ + + + + + + +

Attributes

+ + +

+ group[RW] +

+ +

Group used for packaging. Inherited from parent project. Defaults to the +top-level project name.

+ +

+ version[RW] +

+ +

Version used for packaging. Inherited from parent project.

+ +

+ + + +

Public Instance Methods

+ + +

+ +

+ id() + + click to toggle source + +

+ + +

+ +

The project's identifier. Same as the project name, with colons +replaced by dashes. The ID for project foo:bar is foo-bar.

+ + + + +

# File lib/buildr/packaging/package.rb, line 53
+def id
+  name.gsub(':', '-')
+end

+ +

+ + + + +

+ + +

+ + package(type, spec?) → task + + + click to toggle source + +

+ + + +

+ +

Defines and returns a package created by this project.

+ +

The first argument declares the package type. For example, :jar to create a +JAR file. The package is an artifact that takes its artifact specification +from the project. You can override the artifact specification by passing +various options in the second argument, for example:

+ +

package(:zip, :classifier=>'sources')
+

+ +

Packages that are ZIP files provides various ways to include additional +files, directories, and even merge ZIPs together. Have a look at ZipTask for more information. In case you're +wondering, JAR and WAR packages are ZIP files.

+ +

You can also enhance a JAR package using the Buildr::ArchiveTask#with method +that accepts the following options:

+
:manifest â Specifies how to create the MANIFEST.MF. By default, uses the +project's manifest property.
+
+
:meta_inf â Specifies files to be included in the META-INF directory. By +default, uses the project's meta-inf property.
+

+ +

The WAR package supports the same options and adds a few more:

+
:classes â Directories of class files to include in WEB-INF/classes. +Includes the compile target directory by default.
+
+
:libs â Artifacts and files to include in WEB-INF/libs. Includes the +compile classpath dependencies by default.
+

+ +

For example:

+ +

 define 'project' do
+   define 'beans' do
+     package :jar
+   end
+   define 'webapp' do
+     compile.with project('beans')
+     package(:war).with :libs=>MYSQL_JDBC
+   end
+   package(:zip, :classifier=>'sources').include path_to('.')
+end
+

+ +

Two other packaging types are:

+
package :sources â Creates a JAR file with the source code and classifier +'sources', for use by IDEs.
+
+
package :javadoc â Creates a ZIP file with the Javadocs and classifier +'javadoc'. You can use the javadoc method to further customize it.
+

+ +

A package is also an artifact. The following tasks operate on packages +created by the project:

+ +

buildr upload     # Upload packages created by the project
+buildr install    # Install packages created by the project
+buildr package    # Create packages
+buildr uninstall  # Remove previously installed packages
+

+ +

If you want to add additional packaging types, implement a method with the +name package_as_ that accepts a file name and returns an +appropriate Rake task. For example:

+ +

def package_as_zip(file_name) #:nodoc:
+  ZipTask.define_task(file_name)
+end
+

+ +

The file name is determined from the specification passed to the package +method, however, some packagers need to override this. For example, +package(:sources) produces a file with the extension 'jar' and the +classifier 'sources'. If you need to overwrite the default +implementation, you should also include a method named package_as__spec. For example:

+ +

def package_as_sources_spec(spec) #:nodoc:
+  # Change the source distribution to .zip extension
+  spec.merge({ :type=>:zip, :classifier=>'sources' })
+end
+

+ + + + +

# File lib/buildr/packaging/package.rb, line 127
+def package(*args)
+  spec = Hash === args.last ? args.pop.dup : {}
+  no_options = spec.empty? # since spec is mutated
+  if spec[:file]
+    rake_check_options spec, :file, :type
+    spec[:type] = args.shift || spec[:type] || spec[:file].split('.').last.to_sym
+    file_name = spec[:file]
+  else
+    rake_check_options spec, *ActsAsArtifact::ARTIFACT_ATTRIBUTES
+    spec[:id] ||= self.id
+    spec[:group] ||= self.group
+    spec[:version] ||= self.version
+    spec[:type] = args.shift || spec[:type] || compile.packaging || :zip
+  end
+
+  packager = method("package_as_#{spec[:type]}") rescue fail("Don't know how to create a package of type #{spec[:type]}")
+  if packager.arity == 1
+    unless file_name
+      spec = send("package_as_#{spec[:type]}_spec", spec) if respond_to?("package_as_#{spec[:type]}_spec")
+      file_name = path_to(:target, Artifact.hash_to_file_name(spec))
+    end
+    package = (no_options && packages.detect { |pkg| pkg.type == spec[:type] && (pkg.id.nil? || pkg.id == spec[:id]) &&
 ;
+      (pkg.respond_to?(:classifier) ? pkg.classifier : nil) == spec[:classifier]}) ||
+      packages.find { |pkg| pkg.name == file_name } ||
+      packager.call(file_name)
+  else
+    Buildr.application.deprecated "We changed the way package_as methods are implemented.  See the package method documentation for more details."
+    file_name ||= path_to(:target, Artifact.hash_to_file_name(spec))
+    package = packager.call(file_name, spec)
+  end
+
+  # First time: prepare package for install, uninstall and upload tasks.
+  unless packages.include?(package)
+    # We already run build before package, but we also need to do so if the package itself is
+    # used as a dependency, before we get to run the package task.
+    task 'package'=>package
+    package.enhance [task('build')]
+    package.enhance { info "Packaging #{File.basename(file_name)}" }
+    if spec[:file]
+      class << package ; self ; end.send(:define_method, :type) { spec[:type] }
+      class << package ; self ; end.send(:define_method, :id) { nil }
+    else
+      # Make it an artifact using the specifications, and tell it how to create a POM.
+      package.extend ActsAsArtifact
+      package.buildr_project = self
+      package.send :apply_spec, spec.only(*Artifact::ARTIFACT_ATTRIBUTES)
+
+      # Create pom associated with package
+      class << package
+        def pom
+          unless @pom
+            pom_filename = Util.replace_extension(self.name, 'pom')
+            spec = {:group=>group, :id=>id, :version=>version, :type=>:pom}
+            @pom = Buildr.artifact(spec, pom_filename)
+            @pom.content Buildr::CustomPom.pom_xml(self.buildr_project, self)
+          end
+          @pom
+        end
+      end
+
+      file(Buildr.repositories.locate(package)=>package) { package.install }
+
+      # Add the package to the list of packages created by this project, and
+      # register it as an artifact. The later is required so if we look up the spec
+      # we find the package in the project's target directory, instead of finding it
+      # in the local repository and attempting to install it.
+      Artifact.register package, package.pom
+    end
+
+    task('install')   { package.install if package.respond_to?(:install) }
+    task('uninstall') { package.uninstall if package.respond_to?(:uninstall) }
+    task('upload')    { package.upload if package.respond_to?(:upload) }
+
+    packages << package
+  end
+  package
+end

+ +

+ + + + +

+ + +

+ + packages → tasks + + + click to toggle source + +

+ + + +

+ +

Returns all packages created by this project. A project may create any +number of packages.

+ +

This method is used whenever you pass a project to Buildr#artifact or any +other method that accepts artifact specifications and projects. You can use +it to list all packages created by the project. If you want to return a +specific package, it is often more convenient to call package with the type.

+ + + + +

# File lib/buildr/packaging/package.rb, line 214
+def packages
+  @packages ||= []
+end

+ +

+ + + + +

+ + +

+ +

+ module Buildr::PackageAsTestJar +

+ +

+ + + + +

+ + + + + + + + + +

+ class Buildr::PackageGemTask +

+ +

+ + + + +

+ + + + + + + + + +

Public Class Methods

+ + +

+ +

+ new(*args) + + click to toggle source + +

+ + +

+ + + + +

+ Calls superclass method + +

+ + + +

# File lib/buildr/packaging/gems.rb, line 22
+def initialize(*args)
+  super
+  @spec = Gem::Specification.new
+end

+ +

+ + + + +

+ + +

+ +

Public Instance Methods

+ + +

+ +

+ spec() { |spec| ... } + + click to toggle source + +

+ + +

+ + + + + + +

# File lib/buildr/packaging/gems.rb, line 27
+def spec
+  yield @spec if block_given?
+  @spec
+end

+ +

+ + + + +

+ + +

+ +

+ upload() + + click to toggle source + +

+ + +

+ + + + + + +

# File lib/buildr/packaging/gems.rb, line 32
+def upload
+end

+ +

+ + + + +

+ + +

+ +

+ module Buildr::Packaging +

+ +

+ + + + +

+ + + + + + + + + +

+ module Buildr::Packaging::Java +

+ +

Adds packaging for Java projects: JAR, WAR, AAR, +EAR, Javadoc.

+ +

+ + + + +

+ + + + + + + +

Attributes

+ + +

+ manifest[RW] +

+ +

Manifest used for packaging. Inherited +from parent project. The default value is a hash that includes the +Build-By, Build-Jdk, Implementation-Title and Implementation-Version +values. The later are taken from the project's comment (or name) and +version number.

+ +

+ meta_inf[RW] +

+ +

Files to always include in the package META-INF directory. The default +value include the LICENSE file if one +exists in the project's base directory.

+ +

+ + + +

Public Instance Methods

+ + +

+ + package_with_javadoc(options?) + + + click to toggle source + +

+ + + +

+ +

Call this when you want the project (and all its sub-projects) to create a +JavaDoc distribution. You can use the JavaDoc distribution in an IDE when +coding against the API.

+ +

A JavaDoc distribution is a ZIP package with the classifier +'javadoc', which includes all the sources used by the compile task.

+ +

Packages use the project's manifest and #meta_inf properties, which you +can override by passing different values (e.g. false to exclude the +manifest) in the options.

+ +

To create JavaDoc distributions only for specific projects, use the :only +and :except options, for example:

+ +

package_with_javadoc :only=>['foo:bar', 'foo:baz']
+

+ +

(Same as calling package :javadoc on each project/sub-project that has +source directories.)

+ + + + +

# File lib/buildr/java/packaging.rb, line 661
+def package_with_javadoc(options = nil)
+  options ||= {}
+  enhance do
+    selected = options[:only] ? projects(options[:only]) :
+      options[:except] ? ([self] + projects - projects(options[:except])) :
+      [self] + projects
+    selected.reject { |project| project.compile.sources.empty? }.
+      each { |project| project.package(:javadoc) }
+  end
+end

+ +

+ + + + +

+ + +

+ + package_with_sources(options?) + + + click to toggle source + +

+ + + +

+ +

Call this when you want the project (and all its sub-projects) to create a +source distribution. You can use the source distribution in an IDE when +debugging.

+ +

A source distribution is a jar package with the classifier +'sources', which includes all the sources used by the compile task.

+ +

Packages use the project's manifest and #meta_inf properties, which you +can override by passing different values (e.g. false to exclude the +manifest) in the options.

+ +

To create source distributions only for specific projects, use the :only +and :except options, for example:

+ +

package_with_sources :only=>['foo:bar', 'foo:baz']
+

+ +

(Same as calling package :sources on each project/sub-project that has +source directories.)

+ + + + +

# File lib/buildr/java/packaging.rb, line 633
+def package_with_sources(options = nil)
+  options ||= {}
+  enhance do
+    selected = options[:only] ? projects(options[:only]) :
+      options[:except] ? ([self] + projects - projects(options[:except])) :
+      [self] + projects
+    selected.reject { |project| project.compile.sources.empty? && project.resources.target.nil? }.
+      each { |project| project.package(:sources) }
+  end
+end

+ +

+ + + + +

+ + +

+ +

+ class Buildr::Packaging::Java::AarTask +

+ +

Extends the JarTask to create an AAR file (Axis2 +service archive).

+ +

Supports all the same options as JarTask, with +the addition of :wsdls, :services_xml and :libs.

+
:wsdls â WSDL files to include (under META-INF). By default packaging will +include all WSDL files found under src/main/axis2.
+
+
:services_xml â Location of services.xml file (included under META-INF). +By default packaging takes this from src/main/axis2/services.xml. Use a +different path if you genereate the services.xml file as part of the build.
+
+
:libs â Array of files, tasks, artifact specifications, etc that will be +added to the /lib directory.
+

+ +

For example:

+ +

package(:aar).with(:libs=>'log4j:log4j:jar:1.1')
+
+filter.from('src/main/axis2').into('target').include('services.xml', '*.wsdl').using('http_port'=>'8080')
+package(:aar).wsdls.clear
+package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
+

+ +

+ + + + +

+ + + + + + + +

Attributes

+ + +

+ libs[RW] +

+ +

Artifacts to include under /lib.

+ +

+ services_xml[RW] +

+ +

Location of services.xml file (defaults to src/main/axis2/services.xml).

+ +

+ wsdls[RW] +

+ +

WSDLs to include under META-INF (defaults to all WSDLs under +src/main/axis2).

+ +

+ + + +