buildr 0.19.0 → 0.20.0

data/CHANGELOG

@@ -1,3 +1,11 @@
+0.20 (4/18/2007)
+* Added: JavadocTask to generate Javadoc documentation for the project, javadoc method on the project itself to return its javadoc task, and Java.javadoc to do all the heavy lifting.
+* Changed: Release code is now implemented as module instead of class. SVN copy made from working copy instead of double commit.
+* Removed: package :file_name options. Does not work with deployed artifacts or POMs.
+* Fixed: Packages not deployed in the right path (but POMs are).
+* Fixed: JARs and WARs include redundant META-INF directory.
+* Fixed: The local package task is now a dependency for install/deploy, and build is dependency for package.
+
 0.19 (4/13/2007)
 * Fixed: Eclipse task correctly handles FileTasks
 * Fixed: Eclipse task output directory is "target/classes" (Project.compile.target) instead of "/target"

data/lib/buildr.rb

@@ -8,11 +8,14 @@ require "facet/string/blank"
 require "facet/nilclass/blank"
 # x.in?(y) is better than y.include?(x)
 require "facet/kernel/in"
+# Allows binding[]
+require "facet/binding"
 # What it says.
 require "facet/kernel/__DIR__"
 require "facet/kernel/instance_exec"
 require "facet/module/alias_method_chain"
 require "facet/module/memoize"
+require "facet/array/head"
 require "facet/string/starts_with"
 require "facet/openobject"
 require "facets/core/kernel/tap"
@@ -27,7 +30,7 @@ end
 
 
 module Buildr
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
 end
 
 

data/lib/core/build.rb

@@ -8,13 +8,13 @@ module Buildr
   desc "Clean files generated during a build"
   Project.local_task("clean") { |name| "Cleaning #{name}" }
   desc "Create packages"
-  Project.local_task("package") { |name| "Packaging #{name}" }
+  Project.local_task("package"=>"build") { |name| "Packaging #{name}" }
   desc "Install packages created by the project"
-  Project.local_task("install") { |name| "Installing packages from #{name}" }
+  Project.local_task("install"=>"package") { |name| "Installing packages from #{name}" }
   desc "Remove previously installed packages"
   Project.local_task("uninstall") { |name| "Uninstalling packages from #{name}" }
   desc "Deploy packages created by the project"
-  Project.local_task("deploy") { |name| "Deploying packages from #{name}" }
+  Project.local_task("deploy"=>"package") { |name| "Deploying packages from #{name}" }
 
   [ :build, :clean, :package, :install, :uninstall, :deploy ].each do |name|
     Project.on_define { |project| project.recursive_task name }
@@ -45,129 +45,135 @@ module Buildr
   desc "The default task it build"
   task "default"=>"build"
 
-  class Release #:nodoc:
 
-    VERSION_NUMBER_PATTERN  = /VERSION_NUMBER\s*=\s*(["'])(.*)\1/
-    NEXT_VERSION_PATTERN    = /NEXT_VERSION\s*=\s*(["'])(.*)\1/
+  class Release
 
-    class << self
-      def svn_ignores()
-        @ignores = (@ignores || []).map { |pat| pat.is_a?(Regexp) ? pat : Regexp.new("^.*\s+#{Regexp.escape pat}$") }
-      end
-    end
-
-    def initialize(rakefile = nil)
-      @rakefile = rakefile || Rake.application.rakefile
-    end
-
-    attr_reader :rakefile
-
-    def invoke()
-      # Make sure we don't have anything uncommitted in SVN.
-      check_status
-      # Update current version to next version before deploying.
-      next_ver = update_version
-      # Run the deployment externally using the new version number
-      # (from the modified Rakefile).
-      sh "rake deploy"
-      # Update the next version as well to the next increment and commit.
-      update_next_version next_ver
-      # Tag the repository for this release.
-      tag_repository next_ver
-      # Update the next version to end with -SNAPSHOT.
-      update_version_to_snapshot next_ver
-    end
+    THIS_VERSION_PATTERN  = /THIS_VERSION|VERSION_NUMBER\s*=\s*(["'])(.*)\1/
+    NEXT_VERSION_PATTERN  = /NEXT_VERSION\s*=\s*(["'])(.*)\1/
 
-    def check_status()
-      ignores = Release.svn_ignores
-      status = svn("status", "--ignore-externals", :verbose=>false).
-        reject { |line| line =~ /^X\s/ || ignores.any? { |pat| line =~ pat } }
-      fail "Uncommitted SVN files violate the First Principle Of Release!\n#{status}" unless
-        status.empty?
-    end
+    class << self
 
-    # Change the Rakefile and update the current version number to the
-    # next version number (VERSION_NUMBER = NEXT_VERSION). We need this
-    # before making a release with the next version. Return the next version.
-    def update_version()
-      rakefile = read_rakefile
-      version = rakefile.scan(VERSION_NUMBER_PATTERN)[0][1] or
-        fail "Looking for VERSION_NUMBER = \"...\" in your Rakefile, none found"
-      next_ver = rakefile.scan(NEXT_VERSION_PATTERN)[0][1] or
-        fail "Looking for NEXT_VERSION = \"...\" in your Rakefile, none found"
-      if verbose
-        puts "Current version:  #{version}"
-        puts "Next version:     #{next_ver}"
+      # :call-seq:
+      #   make()
+      #
+      # Make a release.
+      def make()
+        check
+        version = with_next_version { |filename, version| sh "rake deploy --rakefile #{filename}" }
+        tag version
+        commit version + "-SNAPSHOT"
       end
-      # Switch version numbers.
-      write_rakefile rakefile.gsub(VERSION_NUMBER_PATTERN) { |ver| ver.sub(/(["']).*\1/, %Q{"#{next_ver}"}) }
-      next_ver
-    end
-
-    # Change the Rakefile and update the next version number to one after
-    # (NEXT_VERSION = NEXT_VERSION + 1). We do this to automatically increment
-    # future version number after each successful release.
-    def update_next_version(version)
-      # Update to new version number.
-      nums = version.split(".")
-      nums[-1] = nums[-1].to_i + 1
-      next_ver = nums.join(".")
-      write_rakefile read_rakefile.gsub(NEXT_VERSION_PATTERN) { |ver| ver.sub(/(["']).*\1/, %Q{"#{next_ver}"}) }
-      # Commit new version number.
-      svn "commit", "-m", "Changed version number to #{version}", rakefile
-    end
-
-    # Create a tag in the SVN repository.
-    def tag_repository(version)
-      # Copy to tag.
-      cur_url = svn("info").scan(/URL: (.*)/)[0][0]
-      new_url = cur_url.sub(/trunk$/, "tags/#{version}")
-      svn "remove", new_url, "-m", "Removing old copy" rescue nil
-      svn "copy", cur_url, new_url, "-m", "Release #{version}"
-    end
-
-    def update_version_to_snapshot(version)
-      version += "-SNAPSHOT"
-      write_rakefile read_rakefile.gsub(VERSION_NUMBER_PATTERN) { |ver| ver.sub(/(["']).*\1/, %Q{"#{version}"}) }
-      # Commit new version number.
-      svn "commit", "-m", "Changed version number to #{version}", rakefile
-    end
 
-  protected
+    protected
+
+      # :call-seq:
+      #   check()
+      #
+      # Check that we don't have any local changes in the working copy. Fails if it finds anything
+      # in the working copy that is not checked into source control.
+      def check()
+        # Status check reveals modified file, but also SVN externals which we can safely ignore.
+        status = svn("status", "--ignore-externals").reject { |line| line =~ /^X\s/ }
+        fail "Uncommitted SVN files violate the First Principle Of Release!\n#{status}" unless
+          status.empty?
+      end
+     
+      # :call-seq:
+      #   with_next_version() { |filename| ... } => version
+      #
+      # Yields to block with upgraded version number, before committing to use it. Returns the *new*
+      # current version number.
+      #
+      # We need a Rakefile with upgraded version numbers to run the build, but we don't want the
+      # Rakefile modified unless the build succeeds. So this method updates the version numbers in
+      # a separate (Rakefile.next) file, yields to the block with that filename, and if successful
+      # copies the new file over the existing one.
+      #
+      # Version numbers are updated as follows. The next release version becomes the current one,
+      # and the next version is upgraded by one to become the new next version. So:
+      #   THIS_VERSION = 1.1.0
+      #   NEXT_VERSION = 1.2.0
+      # becomes:
+      #   THIS_VERSION = 1.2.0
+      #   NEXT_VERSION = 1.2.1
+      # and the method will return 1.2.0.
+      def with_next_version()
+        new_filename = Rake.application.rakefile + ".next"
+        modified = change_version do |this_version, next_version|
+          one_after = next_version.split(".")
+          one_after[-1] = one_after[-1].to_i + 1
+          [ next_version, one_after.join(".") ]
+        end
+        File.open(new_filename, "w") { |file| file.write modified }
+        begin
+          yield new_filename
+          mv new_filename, Rake.application.rakefile
+        ensure
+          rm new_filename rescue nil
+        end
+        File.read(Rake.application.rakefile).scan(THIS_VERSION_PATTERN)[0][1]
+      end
 
-    def read_rakefile()
-      File.read(rakefile)
-    end
+      # :call-seq:
+      #   change_version() { |this, next| ... } => rakefile
+      #
+      # Change version numbers in the current Rakefile, but without writing a new file (yet).
+      # Returns the contents of the Rakefile with the modified version numbers.
+      #
+      # This method yields to the block with the current (this) and next version numbers and expects
+      # an array with the new this and next version numbers.
+      def change_version()
+        rakefile = File.read(Rake.application.rakefile)
+        this_version = rakefile.scan(THIS_VERSION_PATTERN)[0][1] or
+          fail "Looking for THIS_VERSION = \"...\" in your Rakefile, none found"
+        next_version = rakefile.scan(NEXT_VERSION_PATTERN)[0][1] or
+          fail "Looking for NEXT_VERSION = \"...\" in your Rakefile, none found"
+        this_version, next_version = yield(this_version, next_version)
+        if verbose
+          puts "Upgrading version numbers:"
+          puts "  This:  #{this_version}"
+          puts "  Next:  #{next_version}"
+        end
+        rakefile.gsub(THIS_VERSION_PATTERN) { |ver| ver.sub(/(["']).*\1/, %Q{"#{this_version}"}) }.
+          gsub(NEXT_VERSION_PATTERN) { |ver| ver.sub(/(["']).*\1/, %Q{"#{next_version}"}) }
+      end
 
-    def write_rakefile(contents)
-      File.open(rakefile, "w") { |file| file.write contents }
-    end
+      # :call-seq:
+      #   tag(version)
+      #
+      # Tags the current working copy with the release version number.
+      def tag(version)
+        url = svn("info").scan(/URL: (.*)/)[0][0].sub(/trunk$/, "tags/#{version}")
+        svn "remove", url, "-m", "Removing old copy" rescue nil
+        svn "copy", Dir.pwd, url, "-m", "Release #{version}"
+      end
 
-    def svn(*args)
-      if Hash === args.last
-        options = args.pop
-      else
-        options = { :verbose=>verbose }
+      # :call-seq:
+      #   commit(version)
+      #
+      # Last, we commit what we currently have in the working copy.
+      def commit(version)
+        rakefile = File.read(Rake.application.rakefile).
+          gsub(THIS_VERSION_PATTERN) { |ver| ver.sub(/(["']).*\1/, %Q{"#{version}"}) }.
+        File.open(Rake.application.rakefile, "w") { |file| file.write rakefile }
+        svn "commit", "-m", "Changed version number to #{version}", Rake.application.rakefile
       end
-      puts ["svn", *args].join(" ") if options[:verbose]
-      Open3.popen3("svn", *args) do |stdin, stdout, stderr|
-        stdin.close
-        error = stderr.read
-        fail error unless error.empty?
-        stdout.read.tap { |output| puts output if Rake.application.options.trace }
+
+      # :call-seq:
+      #   svn(*args)
+      #
+      # Executes SVN command and returns the output.
+      def svn(*args)
+        cmd = "svn " + args.map { |arg| arg[" "] ? %Q{"#{arg}"} : arg }.join(" ")
+        puts cmd if verbose
+        `#{cmd}`.tap { fail "SVN command failed" unless $?.exitstatus == 0 }
       end
     end
 
   end
 
-
   desc "Make a release"
-  task("release").tap do |task|
-    class << task
-      def release()
-        @release ||= Release.new
-      end
-    end
-    task.enhance { task.release.invoke }
+  task "release" do |task|
+    Release.make
   end
 end

data/lib/java/artifact.rb

@@ -498,7 +498,7 @@ module Buildr
         else
           # Upload artifact to URL.
           puts "Deploying #{artifact}" if verbose
-          session.upload artifact, File.basename(artifact)
+          session.upload artifact.to_s, File.basename(artifact.to_s)
         end
       end
     end

data/lib/java/compile.rb

@@ -281,6 +281,144 @@ module Buildr
 
     end
 
+
+    # A convenient task for creating Javadocs from the project's compile task. Minimizes all
+    # the hard work to calling #from and #using.
+    #
+    # For example:
+    #   javadoc.from(projects("myapp:foo", "myapp:bar")).using(:windowtitle=>"My App")
+    # Or, short and sweet:
+    #   desc "My App"
+    #   define "myapp" do
+    #     . . .
+    #     javadoc projects("myapp:foo", "myapp:bar")
+    #   end
+    class JavadocTask < Rake::Task
+
+      def initialize(*args) #:nodoc:
+        super
+        @options = {}
+        @classpath = []
+        @sourcepath = []
+        @files = FileList[]
+        enhance do |task|
+          rm_rf target.to_s, :verbose=>false
+          Java.javadoc source_files, options.merge(:classpath=>classpath, :sourcepath=>sourcepath, :name=>name, :output=>target.to_s)
+          touch target.to_s, :verbose=>false
+        end
+      end
+
+      # The target directory for the generated Javadoc files.
+      attr_reader :target
+
+      # :call-seq:
+      #   into(path) => self
+      #
+      # Sets the target directory and returns self. This will also set the Javadoc task
+      # as a prerequisite to a file task on the target directory.
+      #
+      # For example:
+      #   package :zip, :classifier=>"docs", :include=>javadoc.target
+      def into(path)
+        path = File.expand_path(path.to_s)
+        @target = file(path).enhance([self]) unless @target && @target.to_s == path
+        self
+      end
+
+      # :call-seq:
+      #   include(*files) => self
+      #
+      # Includes additional source files and directories when generating the documentation
+      # and returns self. When specifying a directory, includes all .java files in that directory.
+      def include(*files)
+        @files.include *files
+        self
+      end
+
+      # :call-seq:
+      #   exclude(*files) => self
+      #
+      # Excludes source files and directories from generating the documentation.
+      def exclude(*files)
+        @files.exclude *files
+        self
+      end
+
+      # Classpath dependencies.
+      attr_accessor :classpath
+
+      # :call-seq:
+      #   with(*artifacts) => self
+      #
+      # Adds files and artifacts as classpath dependencies, and returns self.
+      def with(*specs)
+        @classpath |= artifacts(specs.flatten).uniq
+        self
+      end
+
+      # Additional sourcepaths that are not part of the documented files.
+      attr_accessor :sourcepath
+        
+      # Returns the Javadoc options.
+      attr_reader :options
+
+      # :call-seq:
+      #   using(options) => self
+      #
+      # Sets the Javadoc options from a hash and returns self.
+      #
+      # For example:
+      #   javadoc.using :windowtitle=>"My application"
+      def using(options)
+        options.each { |key, value| @options[key] = value }
+        self
+      end
+
+      # :call-seq:
+      #   from(*sources) => self
+      #
+      # Includes files, directories and projects in the Javadoc documentation and returns self.
+      #
+      # You can call this method with Java source files and directories containing Java source files
+      # to include these files in the Javadoc documentation, similar to #include. You can also call
+      # this method with projects. When called with a project, it includes all the source files compiled
+      # by that project and classpath dependencies used when compiling.
+      #
+      # For example:
+      #   javadoc.from projects("myapp:foo", "myapp:bar")
+      def from(*sources)
+        sources.flatten.each do |source|
+          case source
+          when Project
+            self.include source.compile.sources
+            self.with source.compile.classpath 
+          when Rake::Task, String
+            self.include source
+          else
+            fail "Don't know how to generate Javadocs from #{source || 'nil'}"
+          end
+        end
+        self
+      end
+
+      def prerequisites() #:nodoc:
+        super + @files + classpath + sourcepath
+      end
+
+      def source_files() #:nodoc:
+        @source_files ||= @files.map(&:to_s).
+          map { |file| File.directory?(file) ? FileList[File.join(file, "**/*.java")] : file }.
+          flatten.reject { |file| @files.exclude?(file) }
+      end
+
+      def needed?() #:nodoc:
+        return false if source_files.empty?
+        return true unless File.exist?(target.to_s)
+        source_files.map { |src| File.stat(src.to_s).mtime }.max > File.stat(target.to_s).mtime
+      end
+
+    end
+
   end
 
 
@@ -289,6 +427,9 @@ module Buildr
   desc "Compile all projects"
   Project.local_task("compile") { |name| "Compiling #{name}" }
 
+  desc "Create the Javadocs for this project"
+  Project.local_task("javadoc")
+
   class Project
 
     # :call-seq:
@@ -356,6 +497,23 @@ module Buildr
       task("resources").enhance prereqs, &block
     end
 
+    # :call-seq:
+    #   javadoc(*sources) => JavadocTask
+    #
+    # This method returns the project's Javadoc task. It also accepts a list of source files,
+    # directories and projects to include when generating the Javadocs.
+    #
+    # By default the Javadoc task uses all the source directories from compile.sources and generates
+    # Javadocs in the target/javadoc directory. This method accepts sources and adds them by calling
+    # JavadocsTask#from.
+    #
+    # For example, if you want to generate Javadocs for a given project that includes all source files
+    # in two of its sub-projects:
+    #   javadoc projects("myapp:foo", "myapp:bar").using(:windowtitle=>"Docs for foo and bar")
+    def javadoc(*sources, &block)
+      task("javadoc").from(*sources).enhance &block
+    end
+
   end
 
   Project.on_define do |project|
@@ -368,11 +526,18 @@ module Buildr
     project.path_to("src/main/java").tap { |dir| compile.from dir if File.exist?(dir) }
     compile.into project.path_to("target/classes")
     resources.filter.into project.compile.target
+    Java::JavadocTask.define_task("javadoc"=>prepare).tap do |javadoc|
+      javadoc.into project.path_to("target/javadoc")
+      javadoc.using :windowtitle=>project.comment || project.name
+    end
     project.recursive_task("compile")
     project.clean { verbose(false) { rm_rf project.path_to("target") } }
 
     project.enhance do |project|
+      # This comes last because the target path may change.
       project.build project.compile.target
+      # This comes last so we can determine all the source paths and classpath dependencies.
+      project.javadoc.from project
     end
   end
 

data/lib/java/java.rb

@@ -194,6 +194,62 @@ module Buildr
         end
       end
 
+      # :call-seq:
+      #   javadoc(*files, options)
+      #
+      # Runs Javadocs with the specified files and options.
+      #
+      # This method accepts the following special options:
+      # * :output -- The output directory
+      # * :classpath -- Array of classpath dependencies.
+      # * :sourcepath -- Array of sourcepaths (paths or tasks).
+      # * :name -- Shows this name, otherwise shows the working directory.
+      # * :verbose -- If you want an overload of details.
+      #
+      # All other options are passed to Javadoc as following:
+      # * true -- As is, for example, :author=>true becomes -author
+      # * false -- Prefixed, for example, :index=>false becomes -noindex
+      # * string -- Option with value, for example, :windowtitle=>"My project" becomes -windowtitle "My project"
+      # * array -- Option with set of values separated by spaces.
+      def javadoc(*args)
+        options = Hash === args.last ? args.pop : {}
+        options[:verbose] ||= Rake.application.options.trace || false
+
+        Tempfile.open("javadoc") do |opt_file|
+          options.reject { |key, value| [:output, :verbose, :name, :sourcepath, :classpath].include?(key) }.
+            each { |key, value| value.invoke if value.respond_to?(:invoke) }.
+            each do |key, value|
+              case value
+              when true, nil
+                opt_file.puts "-#{key}"
+              when false
+                opt_file.puts "-no#{key}"
+              when Array
+                opt_file.puts "-#{key} " << value.map { |val| %q{"#{val}"} }.join(" ")
+              when Hash
+                value.each { |k,v| opt_file.puts "-#{key} #{k} #{v}" }
+              else
+                opt_file.puts "-#{key} \"#{value}\""
+              end
+            end
+          [:sourcepath, :classpath].each do |option|
+            options[option].to_a.flatten.tap do |paths|
+              opt_file.puts "-#{option} " << paths.flatten.map(&:to_s).join(File::PATH_SEPARATOR) unless paths.empty?
+            end
+          end
+          opt_file.puts args.flatten.uniq.join(" ")
+          opt_file.flush
+          cmd_args = [ "-d", options[:output], options[:verbose] ? "-verbose" : "-quiet", "@#{opt_file.path}"]
+          cmd_args << { :verbose=>options[:verbose] }
+          name = options[:name] || Dir.pwd
+          unless Rake.application.options.dryrun
+            puts "Generating Javadoc for #{name}" if verbose
+            puts File.read(opt_file.path) if options[:verbose]
+            sh(path_to_bin("javadoc"), *cmd_args) { |ok, res| fail "Failed to generate Javadocs, see errors above" unless ok }
+          end
+        end
+      end
+
       # :call-seq:
       #   junit(*classes, options) => [ passed, failed ]
       #

data/lib/java/packaging.rb

@@ -65,7 +65,6 @@ module Buildr
       protected
 
         def create(zip) #:nodoc:
-          zip.mkdir "META-INF"
           meta_inf.map(&:to_s).uniq.each { |file| zip.add "META-INF/#{File.basename(file)}", file }
           unless manifest == false
             zip.file.open("META-INF/MANIFEST.MF", "w") do |output|
@@ -164,8 +163,6 @@ module Buildr
     # The second argument provides additional options used when defining the package.
     #
     # The following options are supported by all package types:
-    # * :file_name -- The package file name. By default it uses the artifact identifier,
-    #   version number and file type to create a file name (id-version.type).
     # * :id -- The artifact identifier. By default, uses the project's #id property.
     # * :group -- The group identifier. By default, uses the project's #group property.
     # * :version -- The version number. By default, uses the project's #version property.
@@ -230,7 +227,7 @@ module Buildr
       options[:group] ||= self.group
       options[:version] ||= self.version
       options[:type] = type
-      file_name = options[:file_name] || path_to("target", Artifact.hash_to_file_name(options))
+      file_name = path_to("target", Artifact.hash_to_file_name(options))
 
       packager = method("package_as_#{type}") rescue
         fail("Do not know how to create a package of type #{:type}")
@@ -274,7 +271,7 @@ module Buildr
             [ installed, package.pom ].map(&:to_s).each { |file| rm file if File.exist?(file) } 
           end
         end
-        task("deploy") { deploy(installed, package.pom) }
+        task("deploy") { deploy(package, package.pom) }
 
         # 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

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: buildr
 version: !ruby/object:Gem::Version 
-  version: 0.19.0
-date: 2007-04-13 00:00:00 -07:00
+  version: 0.20.0
+date: 2007-04-18 00:00:00 -07:00
 summary: A build system that doesn't suck
 require_paths: 
 - lib