You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildr.apache.org by as...@apache.org on 2008/01/08 10:01:11 UTC
svn commit: r609910 [1/2] - in /incubator/buildr/trunk:
doc/pages/artifacts.textile doc/pages/building.textile
doc/pages/packaging.textile doc/pages/projects.textile
doc/pages/testing.textile lib/java/packaging.rb
Author: assaf
Date: Tue Jan 8 01:01:03 2008
New Revision: 609910
URL: http://svn.apache.org/viewvc?rev=609910&view=rev
Log:
Documentation update no longer assumes Java is the only language
Modified:
incubator/buildr/trunk/doc/pages/artifacts.textile
incubator/buildr/trunk/doc/pages/building.textile
incubator/buildr/trunk/doc/pages/packaging.textile
incubator/buildr/trunk/doc/pages/projects.textile
incubator/buildr/trunk/doc/pages/testing.textile
incubator/buildr/trunk/lib/java/packaging.rb
Modified: incubator/buildr/trunk/doc/pages/artifacts.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/artifacts.textile?rev=609910&r1=609909&r2=609910&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/artifacts.textile (original)
+++ incubator/buildr/trunk/doc/pages/artifacts.textile Tue Jan 8 01:01:03 2008
@@ -1,127 +1,172 @@
h1. Artifacts
-In Buildr, almost everything is a file or a file task. You compile source files that come from the file system using classpath dependencies found on the file system, generating even more files. But how do you get these classpath dependencies to start with, and how do you share them with others?
+In Buildr, almost everything is a file or a file task. You compile source files
+that come from the file system using dependencies found on the file system,
+generating even more files. But how do you get these dependencies to start
+with, and how do you share them with others?
+
+Artifacts. We designed Buildr to work as a drop-in replacement for Maven 2.0,
+and share artifacts through the same local and remote repositories. Artifact
+tasks know how to download a file from one of the remote repositories, and
+install it in the local repository, where Buildr can find it. Packages know how
+to create files and upload them to remote repositories.
-Artifacts. We designed Buildr to work as a drop-in replacement for Maven 2.0, and share artifacts through the same local and remote repositories. Artifact tasks know how to download a file from one of the remote repositories, and install it in the local repository, where Buildr can find it. Packages know how to create files and upload them to remote repositories.
-
-We'll get into all of that in a second, but first, let's introduce the artifact specification. It's a simple string that takes one of two forms:
+We'll get into all of that in a second, but first, let's introduce the artifact
+specification. It's a simple string that takes one of two forms:
{{{
group:id:type:version
group:id:type:classifier:version
}}}
-For example, @"org.apache.axis2:axis2:jar:1.2"@ refers to an artifact with group identifier org.apache.axis2, artifact identifier axis2, a JAR file with version 1.2. Classifiers are typically used to distinguish between similar file types, for example, a source distribution and binary distribution that otherwise have the same identifier and are both ZIP files.
+For example, @'org.apache.axis2:axis2:jar:1.2'@ refers to an artifact with
+group identifier org.apache.axis2, artifact identifier axis2, a JAR file with
+version 1.2. Classifiers are typically used to distinguish between similar
+file types, for example, a source distribution and binary distribution that
+otherwise have the same identifier and are both ZIP files.
h2. Specifying Artifacts
-If your Buildfile spells out @"org.apache.axis2:axis2:jar:1.2"@ more than once, you're doing something wrong. Repeating the same string over and over will make your code harder to maintain. You'll know that when you upgrade to a new version in one place, forget to do it in another, and end up with a mismatch.
+If your Buildfile spells out @'org.apache.axis2:axis2:jar:1.2'@ more than once,
+you're doing something wrong. Repeating the same string over and over will
+make your code harder to maintain. You'll know that when you upgrade to a new
+version in one place, forget to do it in another, and end up with a mismatch.
You can use Ruby's syntax to do simple string substitution, for example:
{{{!ruby
-AXIS_VERSION = "1.2"
+AXIS_VERSION = '1.2'
compile.with "org.apache.axis2:axis2:jar:#{AXIS_VERSION}"
}}}
-Better yet, you can define all your artifacts at the top of the Buildfile and use constants to reference them in your project definition. For example:
+Better yet, you can define all your artifacts at the top of the Buildfile and
+use constants to reference them in your project definition. For example:
{{{!ruby
-AXIS2 = "org.apache.axis2:axis2:jar:1.2"
+AXIS2 = 'org.apache.axis2:axis2:jar:1.2'
compile.with AXIS2
}}}
-Note that we're not using a separate constant for the version number. In our experience, it's unnecessary. The version number intentionally appears at the end of the string, where it stands out easily.
+Note that we're not using a separate constant for the version number. In our
+experience, it's unnecessary. The version number intentionally appears at the
+end of the string, where it stands out easily.
-If you have a set of artifacts that belong to the same group and version, and that's quite common, you can use the @group@ shortcut:
+If you have a set of artifacts that belong to the same group and version, and
+that's quite common, you can use the @group@ shortcut:
{{{!ruby
-AXIOM = group("axiom-api", "axiom-impl", "axiom-dom",
- :under=>"org.apache.ws.commons.axiom", :version=>"1.2.4")
+AXIOM = group('axiom-api', 'axiom-impl', 'axiom-dom',
+ :under=>'org.apache.ws.commons.axiom', :version=>'1.2.4')
}}}
-If you have several artifacts you always use together, consider placing them in an array. Methods that accept lists of artifacts also accept arrays. For example:
+If you have several artifacts you always use together, consider placing them in
+an array. Methods that accept lists of artifacts also accept arrays. For
+example:
{{{!ruby
-OPENJPA = ["org.apache.openjpa:openjpa-all:jar:0.9.7",
- "net.sourceforge.serp:serp:jar:1.12.0"]
+OPENJPA = ['org.apache.openjpa:openjpa-all:jar:0.9.7',
+ 'net.sourceforge.serp:serp:jar:1.12.0']
AXIS_OF_WS = [AXIS2, AXIOM]
compile.with OPENJPA, AXIS_OF_WS
}}}
-Another way to group related artifacts together and access them individually is using the @struct@ shortcut. For example:
+Another way to group related artifacts together and access them individually is
+using the @struct@ shortcut. For example:
{{{!ruby
JAVAX = struct(
- :activation =>"javax.activation:activation:jar:1.1",
- :persistence =>"javax.persistence:persistence-api:jar:1.0",
- :stream =>"stax:stax-api:jar:1.0.1",
+ :activation =>'javax.activation:activation:jar:1.1',
+ :persistence =>'javax.persistence:persistence-api:jar:1.0',
+ :stream =>'stax:stax-api:jar:1.0.1',
)
compile.with JAVAX.persistence, OPENJPA
}}}
-In our experience, using constants in this manner makes your Buildfile much easier to write and maintain.
+In our experience, using constants in this manner makes your Buildfile much
+easier to write and maintain.
-And, of course, you can always place your artifact specifications in a separate file and require it into your Buildfile. For example, if you're working on several different projects that all share the same artifacts:
+And, of course, you can always place your artifact specifications in a separate
+file and require it into your Buildfile. For example, if you're working on
+several different projects that all share the same artifacts:
{{{!ruby
-require "../shared/artifacts"
+require '../shared/artifacts'
}}}
-When you use @require@, Ruby always looks for a filename with the @.rb@ extension, so in this case if expects to find @artifacts.rb@ in the @shared@ directory.
+When you use @require@, Ruby always looks for a filename with the @.rb@
+extension, so in this case if expects to find @artifacts.rb@ in the @shared@
+directory.
-One last thing. You can also treat artifact specifications as hashes. For example:
+One last thing. You can also treat artifact specifications as hashes. For
+example:
{{{!ruby
-AXIS = { :group=>"org.apache.axis2", :id=>"axis2", :version=>"1.2" }
+AXIS = { :group=>'org.apache.axis2', :id=>'axis2', :version=>'1.2' }
compile.with AXIS
-puts compile.classpath.first.to_hash
-=> { :group=>"org.apache.axis2", :id=>"axis2",
- :version=>"1.2", :type=>:jar }
+puts compile.dependencies.first.to_hash
+=> { :group=>'org.apache.axis2', :id=>'axis2',
+ :version=>'1.2', :type=>:jar }
}}}
h2. Specifying Repositories
-Buildr can download artifacts for you, but only if you tell it where to find them. You need to specify at least one remote repository, from which to download these artifacts.
+Buildr can download artifacts for you, but only if you tell it where to find
+them. You need to specify at least one remote repository, from which to
+download these artifacts.
-When you call @repositories.remote@, you get an array of URLs for the various remote repositories. Initially, it's an empty array, to which you can add new repositories. For example:
+When you call @repositories.remote@, you get an array of URLs for the various
+remote repositories. Initially, it's an empty array, to which you can add new
+repositories. For example:
{{{!ruby
-repositories.remote << "http://www.ibiblio.org/maven2/"
+repositories.remote << 'http://www.ibiblio.org/maven2/'
}}}
-If you need to use a proxy server to access remote repositories, you can set the environment variable @HTTP_PROXY@ to the proxy server URL. You can also work without a proxy for certain hosts by specifying the @NO_PROXY@ environment variable. For example:
+If you need to use a proxy server to access remote repositories, you can set
+the environment variable @HTTP_PROXY@ to the proxy server URL. You can also
+work without a proxy for certain hosts by specifying the @NO_PROXY@ environment
+variable. For example:
{{{!sh
-$ export HTTP_PROXY = "http://myproxy:8080"
-$ export NO_PROXY = "*.mycompany.com,localhost,special:800"
+$ export HTTP_PROXY = 'http://myproxy:8080'
+$ export NO_PROXY = '*.mycompany.com,localhost,special:800'
}}}
Alternatively you acn use the Buildr options @proxy.http@ and @proxy.exclude@:
{{{!ruby
-options.proxy.http = "http://myproxy:8080"
-options.proxy.exclude << "*.mycompany.com"
-options.proxy.exclude << "localhost"
+options.proxy.http = 'http://myproxy:8080'
+options.proxy.exclude << '*.mycompany.com'
+options.proxy.exclude << 'localhost'
}}}
-All the artifacts download into the local repository. Since all your projects share the same local repository, you only need to download each artifact once. Buildr was designed to be used alongside Maven 2.0, for example, when migrating projects from Maven 2.0 over to Buildr. By default it will share the same local repository, expecting the repository to be the @.m2/repository@ directory inside your home directory.
+All the artifacts download into the local repository. Since all your projects
+share the same local repository, you only need to download each artifact once.
+Buildr was designed to be used alongside Maven 2.0, for example, when migrating
+projects from Maven 2.0 over to Buildr. By default it will share the same
+local repository, expecting the repository to be the @.m2/repository@ directory
+inside your home directory.
-You can choose to relocate the local repository by giving it a different path, for example:
+You can choose to relocate the local repository by giving it a different path,
+for example:
{{{!ruby
-repositories.local = "/usr/local/maven/repository"
+repositories.local = '/usr/local/maven/repository'
}}}
-That's one change you don't want to commit into the Buildfile, so the best place to do it is in your home directory's @buildr.rb@ file.
+That's one change you don't want to commit into the Buildfile, so the best
+place to do it is in your home directory's @buildr.rb@ file.
-Buildr downloads artifacts when it needs to use them, for example, to compile a project. You don't need to download artifacts directly. Except when you do, for example, if you want to download all the latest artifacts and then go off-line. It's as simple as:
+Buildr downloads artifacts when it needs to use them, for example, to compile a
+project. You don't need to download artifacts directly. Except when you do,
+for example, if you want to download all the latest artifacts and then go
+off-line. It's as simple as:
{{{!sh
$ buildr artifacts
@@ -130,67 +175,127 @@
h2. Downloading Artifacts
-Within your buildfile you can download artifacts directly by invoking them, for example:
+Within your buildfile you can download artifacts directly by invoking them, for
+example:
{{{!ruby
-artifact("org.apache.openjpa:openjpa-all:jar:0.9.7").invoke
+artifact('org.apache.openjpa:openjpa-all:jar:0.9.7').invoke
artifacts(OPENJPA).each(&:invoke)
}}}
-When you let Buildr download artifacts for you, or by invoking the artifact task yourself, it scans through the remote repositories assuming each repository follows the Maven 2 structure. Starting from the root repository URL, it will look for each artifact using the path @group/id/version/id-version.type@ (or ...@/id-version-classifier.type@). The group identifier becomes a path by turning periods (@.@) into slashes (@/@). So to find @"org.apache.axis2:axis2:jar:1.2"@, we're going to look for @org/apache/axis2/axis2/1.2/axis2-1.2.jar@.
-
-You'll find a lot of open source Java libraries in public repositories that support this structure (for example, the "Ibiblio Maven":http://www.ibiblio.org/maven2/ repository). And, of course, every remote repository you setup for your projects.
+When you let Buildr download artifacts for you, or by invoking the artifact
+task yourself, it scans through the remote repositories assuming each
+repository follows the Maven 2 structure. Starting from the root repository
+URL, it will look for each artifact using the path
+@group/id/version/id-version.type@ (or ...@/id-version-classifier.type@). The
+group identifier becomes a path by turning periods (@.@) into slashes (@/@).
+So to find @org.apache.axis2:axis2:jar:1.2@, we're going to look for
+@org/apache/axis2/axis2/1.2/axis2-1.2.jar@.
+
+You'll find a lot of open source Java libraries in public repositories that
+support this structure (for example, the "Ibiblio
+Maven":http://www.ibiblio.org/maven2/ repository). And, of course, every
+remote repository you setup for your projects.
+
+But there are exceptions to the rule. Say we want to download the Dojo widget
+library and use it in our project. It's available from the Dojo Web site, but
+that site doesn't follow the Maven repository conventions, so our feeble
+attempt to use existing remote repositories will fail.
-But there are exceptions to the rule. Say we want to download the Dojo widget library and use it in our project. It's available from the Dojo Web site, but that site doesn't follow the Maven repository conventions, so our feeble attempt to use existing remote repositories will fail.
-
-We can still treat Dojo as an artifact, by telling Buildr where to download it from:
+We can still treat Dojo as an artifact, by telling Buildr where to download it
+from:
{{{!ruby
-DOJO = "0.2.2"
+DOJO = '0.2.2'
url = "http://download.dojotoolkit.org/release-#{DOJO}/dojo-#{DOJO}-widget.zip"
download(artifact("dojo:dojo:zip:widget:#{DOJO}")=>url)
}}}
-Explaining how it works is tricky, skip if you don't care for the details. On the other hand, it will give you a better understanding of Buildr/Rake, so if not now, come back and read it later.
-
-We use the @artifact@ method to create an @Artifact@ task that references the Dojo widget in our local repository. The @Artifact@ task is a file task with some additional behavior added by Buildr. When you call @compile.with@, that's exactly what it does internally, turning each of your artifact specifications into an @Artifact@ task.
-
-But the @Artifact@ task doesn't know how to download the Dojo widget, only how to handle conventional repositories. So we're going to create a download task as well. We use the @download@ method to create a file task that downloads the file from a remote URL. (Of course, it will only download the file if it doesn't already exist.)
-
-But which task gets used when? We could have defined these tasks separately and used some glue code to make one use the other. Instead, we call @download@ with the results of @artifact@. Essentially, we're telling @download@ to use the same file path as @artifact@. So now we have two file tasks that point to the very same file. We wired them together.
-
-You can't have more than one task pointing to the same file. Rake's rule of the road. What Rake does is merge the tasks together, creating a single file task for @artifact@, and then enhancing it with another action from @download@. One task, two actions. Statistically, we've doubled the odds that at least one of these actions will manage to download the Dojo widget and install it in the local repository.
-
-Since we ordered the calls to @artifact@ first and @download@ second, we know the actions will execute in that order. But @artifact@ is slightly devilish: when its action runs, it adds another action to the end of the list. So the @artifact@ action runs first, adds an action at the end, the @download@ action runs second, and downloads the Dojo widget for us. The second @artifact@ action runs last, but checks that the file already exist and doesn't try to download it again.
+Explaining how it works is tricky, skip if you don't care for the details. On
+the other hand, it will give you a better understanding of Buildr/Rake, so if
+not now, come back and read it later.
+
+We use the @artifact@ method to create an @Artifact@ task that references the
+Dojo widget in our local repository. The @Artifact@ task is a file task with
+some additional behavior added by Buildr. When you call @compile.with@, that's
+exactly what it does internally, turning each of your artifact specifications
+into an @Artifact@ task.
+
+But the @Artifact@ task doesn't know how to download the Dojo widget, only how
+to handle conventional repositories. So we're going to create a download task
+as well. We use the @download@ method to create a file task that downloads the
+file from a remote URL. (Of course, it will only download the file if it
+doesn't already exist.)
+
+But which task gets used when? We could have defined these tasks separately
+and used some glue code to make one use the other. Instead, we call @download@
+with the results of @artifact@. Essentially, we're telling @download@ to use
+the same file path as @artifact@. So now we have two file tasks that point to
+the very same file. We wired them together.
+
+You can't have more than one task pointing to the same file. Rake's rule of
+the road. What Rake does is merge the tasks together, creating a single file
+task for @artifact@, and then enhancing it with another action from @download@.
+One task, two actions. Statistically, we've doubled the odds that at least one
+of these actions will manage to download the Dojo widget and install it in the
+local repository.
+
+Since we ordered the calls to @artifact@ first and @download@ second, we know
+the actions will execute in that order. But @artifact@ is slightly devilish:
+when its action runs, it adds another action to the end of the list. So the
+@artifact@ action runs first, adds an action at the end, the @download@ action
+runs second, and downloads the Dojo widget for us. The second @artifact@
+action runs last, but checks that the file already exist and doesn't try to
+download it again.
Magic.
h2. Install and Upload
-Generally you use artifacts that download from remote repositories into the local repository, or artifacts packaged by the project itself (see "Packaging":packaging.html), which are then installed into the local repository and uploaded to the release server.
+Generally you use artifacts that download from remote repositories into the
+local repository, or artifacts packaged by the project itself (see
+"Packaging":packaging.html), which are then installed into the local repository
+and uploaded to the release server.
-Some artifacts do not fall into either category. In this example we're going to download a ZIP file, extract a JAR file from it, and use that JAR file as an artifact. We would then expect to install this JAR in the local repository and upload it to the release server, where it can be shared with other projects.
+Some artifacts do not fall into either category. In this example we're going
+to download a ZIP file, extract a JAR file from it, and use that JAR file as an
+artifact. We would then expect to install this JAR in the local repository and
+upload it to the release server, where it can be shared with other projects.
-So let's start by creating a task that downloads the ZIP, and another one to extract it and create the JAR file:
+So let's start by creating a task that downloads the ZIP, and another one to
+extract it and create the JAR file:
{{{!ruby
-app_zip = download("target/app.zip"=>url)
-bean_jar = file("target/app/bean.jar"=>unzip("target/app"=>app_zip))
+app_zip = download('target/app.zip'=>url)
+bean_jar = file('target/app/bean.jar'=>unzip('target/app'=>app_zip))
}}}
-When you call @artifact@, it returns an @Artifact@ task that points to the artifact file in the local repository, downloading the file if it doesn't already exist. You can override this behavior by enhancing the task and creating the file yourself (you may also want to create a POM file). Or much simpler, call the @from@ method on the artifact and tell it where to find the source file.
+When you call @artifact@, it returns an @Artifact@ task that points to the
+artifact file in the local repository, downloading the file if it doesn't
+already exist. You can override this behavior by enhancing the task and
+creating the file yourself (you may also want to create a POM file). Or much
+simpler, call the @from@ method on the artifact and tell it where to find the
+source file.
-So the next step is to specify the artifact and tell it to use the extracted JAR file:
+So the next step is to specify the artifact and tell it to use the extracted
+JAR file:
{{{!ruby
-bean = artifact("example.com:beans:jar:1.0").from(bean_jar)
+bean = artifact('example.com:beans:jar:1.0').from(bean_jar)
}}}
-The artifact still points to the local repository, but when we invoke the task it copies the source file over to the local repository, instead of attempting a download.
+The artifact still points to the local repository, but when we invoke the task
+it copies the source file over to the local repository, instead of attempting a
+download.
-Use the @install@ method if you want the artifact and its POM installed in the local repository when you run the @install@ task. Likewise, use the @upload@ method if you want the artifact uploaded to the release server when you run the @upload@ task. You do not need to do this on artifacts downloaded from a remote server, or created with the @package@ method, the later are automatically added to the list of installed/uploaded artifacts.
+Use the @install@ method if you want the artifact and its POM installed in the
+local repository when you run the @install@ task. Likewise, use the @upload@
+method if you want the artifact uploaded to the release server when you run the
+@upload@ task. You do not need to do this on artifacts downloaded from a
+remote server, or created with the @package@ method, the later are
+automatically added to the list of installed/uploaded artifacts.
Our example ends by including the artifact in the @install@ and @upload@ tasks:
Modified: incubator/buildr/trunk/doc/pages/building.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/building.textile?rev=609910&r1=609909&r2=609910&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/building.textile (original)
+++ incubator/buildr/trunk/doc/pages/building.textile Tue Jan 8 01:01:03 2008
@@ -1,102 +1,180 @@
h1. Building
-To remove any confusion, Buildr's build task is actually called @build@. It's also the default task that executes when you run @buildr@ without any task name.
-
-The @build@ task runs two other tasks: @compile@ and its associated tasks (that would be, @resources@) and @test@ and its associated tasks (@test:compile@, @test:setup@ and friends). We'll talk about @compile@ more in this section, and @test@ later on. We'll also show you how to run @build@ without testing, not something we recommend, but a necessary feature.
-
-Why @build@ and not @compile@? Some projects do more than just compiling. Other projects don't compile at all, but perform other build tasks, for example, creating a database schema or command line scripts. So we want you to get in the practice of running the @build@ task, and help you by making it the default task.
+To remove any confusion, Buildr's build task is actually called @build@. It's
+also the default task that executes when you run @buildr@ without any task
+name.
+
+The @build@ task runs two other tasks: @compile@ and its associated tasks (that
+would be, @resources@) and @test@ and its associated tasks (@test:compile@,
+@test:setup@ and friends). We'll talk about @compile@ more in this section,
+and @test@ later on. We'll also show you how to run @build@ without testing,
+not something we recommend, but a necessary feature.
+
+Why @build@ and not @compile@? Some projects do more than just compiling.
+Other projects don't compile at all, but perform other build tasks, for
+example, creating a database schema or command line scripts. So we want you to
+get in the practice of running the @build@ task, and help you by making it the
+default task.
h2. Compiling
-Each project has its own @compile@ task you can invoke directly, by running @buildr compile@ or as part of another build task. (Yes, that @build@).
-
-The @compile@ task looks for source files in the @src/main/java@ directory and compiles them into @target/classes@. Of course, it
-won't do any of that unless your project has a @src/main/java@ directory, or give the task other source directories to work from.
-
-Most often, that's just good enough and the only change you need to make is setting the classpath dependencies. You can use @compile.classpath@ to get the array of classpath dependency file tasks. Each of these tasks points to a JAR of a directory containing Java classes, and the entire set is passed on the Java compiler.
+Each project has its own @compile@ task you can invoke directly, by running
+@buildr compile@ or as part of another build task. (Yes, that @build@).
-Buildr uses file tasks to handle dependencies, but here we're talking about the Rake dependency mechanism. It's a double entendre. It invokes these tasks before running the compiler. Some of these tasks will download JARs from remote repositories, others will create them by compiling and packaging from a different project. Using file task ensures all the dependencies exist before the compiler can use them.
-
-An easier way to specify classpath dependencies is by calling the @compile.with@ method. It takes a list of arguments and adds them to the classpath dependency list. The @compile.with@ method is easier to use, it accepts several type of dependencies. You can use file names, file tasks, projects, artifacts specifications and even pass arrays of dependencies.
-
-Most classpath dependencies fall into the last three categories. When you pass a project to @compile.with@, it picks up all the packages created by that project. In doing so, it establishes an order of dependency between the two projects (see "Defining the Project":projects.html#defining_the_project). For example, if you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect that change, recompile and package _teh-api_ before compiling _teh-impl_. You can also select a specific package using the @package@ or @packages@
-methods (see "Packaging":packaging.html).
-
-When you pass an artifact specification to @compile.with@, it creates an @Artifact@ task that will download that artifact from one of the remote repositories, install it in the local repository, and use it in your project. Rake's dependency mechanism is used here to make sure the artifact is downloaded once, when needed. Check the "Artifacts":artifacts.html section for more information about artifact specification and repositories.
+The @compile@ task looks for source files in well known directories, determines
+which compiler to use, and sets the target directory accordingly. For example,
+if it finds any Java source files in the @src/main/java@ directory, it selects
+the Javac compiler and generates bytecode in the @target/classes@ directories.
+If it finds Scala source files in the @src/main/scala@ directory it selects the
+Scalac compiler, and so forth.
+
+Most often, that's just good enough and the only change you need to make is
+adding compile dependencies. You can use @compile.dependencies@ to get the
+array of dependency file tasks. For Java, each of these tasks points to a JAR
+or a directory containing Java classes, and the entire set of dependencies is
+passed to Javac as the classpath.
+
+Buildr uses file tasks to handle dependencies, but here we're talking about the
+Rake dependency mechanism. It's a double entendre. It invokes these tasks
+before running the compiler. Some of these tasks will download JARs from
+remote repositories, others will create them by compiling and packaging from a
+different project. Using file task ensures all the dependencies exist before
+the compiler can use them.
+
+An easier way to specify dependencies is by calling the @compile.with@ method.
+It takes a list of arguments and adds them to the dependency list. The
+@compile.with@ method is easier to use, it accepts several type of
+dependencies. You can use file names, file tasks, projects, artifacts
+specifications and even pass arrays of dependencies.
+
+Most dependencies fall into the last three categories. When you pass a project
+to @compile.with@, it picks up all the packages created by that project. In
+doing so, it establishes an order of dependency between the two projects (see
+"Defining the Project":projects.html#defining_the_project). For example, if
+you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect
+that change, recompile and package _teh-api_ before compiling _teh-impl_. You
+can also select a specific package using the @package@ or @packages@ methods
+(see "Packaging":packaging.html).
+
+When you pass an artifact specification to @compile.with@, it creates an
+@Artifact@ task that will download that artifact from one of the remote
+repositories, install it in the local repository, and use it in your project.
+Rake's dependency mechanism is used here to make sure the artifact is
+downloaded once, when needed. Check the "Artifacts":artifacts.html section for
+more information about artifact specification and repositories.
For now let's just show a simple example:
{{{!ruby
-compile.with "org.apache.axis2:axis2:jar:1.2",
- "org.apache.derby:derby:jar:10.1.2.1", projects("teh-api", "teh-impl")
+compile.with 'org.apache.axis2:axis2:jar:1.2',
+ 'org.apache.derby:derby:jar:10.1.2.1', projects('teh-api', 'teh-impl')
}}}
-Passing arrays to @compile.with@ is just a convenient for handling multiple dependencies, we'll show more examples of that when
-we talk about "Artifacts":#artifacts.
+Passing arrays to @compile.with@ is just a convenient for handling multiple
+dependencies, we'll show more examples of that when we talk about
+"Artifacts":#artifacts.
-Likewise, the @compile@ task has an array of file tasks that point at the source directories you want to compile from. You can access that array by calling @compile.sources@. Initially, it will contain a single file task pointing to the @src/main/java@ directory. You can use @compile.from@ to add new source directories by passing a file name or a file task.
+Likewise, the @compile@ task has an array of file tasks that point at the
+source directories you want to compile from. You can access that array by
+calling @compile.sources@. You can use @compile.from@ to add new source
+directories by passing a file name or a file task.
-For example, let's run the APT tool on our annotated source code before compiling it:
+For example, let's run the APT tool on our annotated source code before
+compiling it:
{{{!ruby
compile.from apt
}}}
-When you call @apt@ on a project, it returns a file task that points to the @target/generated/apt@ directory. This file task executes by running APT, using the same list of source directories, classpath dependencies and compiler options. It then generates new source files in the target directory. Calling @compile.from@ with that file task includes those additional source files in the list of compiled sources.
+When you call @apt@ on a project, it returns a file task that points to the
+@target/generated/apt@ directory. This file task executes by running APT,
+using the same list of source directories, dependencies and compiler options.
+It then generates new source files in the target directory. Calling
+@compile.from@ with that file task includes those additional source files in
+the list of compiled sources.
Here's another example:
{{{!ruby
-jjtree = jjtree(_("src/main/jjtree"), :in_package=>"com.acme")
-compile.from javacc(jjtree, :in_package=>"com.acme"), jjtree
+jjtree = jjtree(_('src/main/jjtree'), :in_package=>'com.acme')
+compile.from javacc(jjtree, :in_package=>'com.acme'), jjtree
}}}
-This time, the variable @jjtree@ is a file task that reads a JJTree source file from the @src/main/jjtree@ directory, and generates additional source files in the @target/generated/jjtree@ directory. The second line creates another file task that takes those source files, runs JavaCC on them, and generates yet more source files in @target/generated/javacc@. Finally, we include both sets of source files in addition to those already in @src/main/java@, and compile the lot.
-
-The interesting thing about these two examples is how you're wiring file tasks together to create more complicated tasks, piping the output of one task into the inputs of another. Wiring tasks this way is the most common way to handle complex builds, and uses Rake's dependency mechanism to only run tasks when it detects a change to one of the source files.
-
-You can also control the target directory. Use @compile.target@ to get the target directory file task. Other tasks, like @resources@ and @test.compile@ do that to operate on the same target directory you set for the @compile@ task. If you need to change the target
-directory, call the @compile.into@ method with the new path.
-
-We use method pairs to give you find control over the compiler, but also a way to easily configure it. Methods like @classpath@ and
-@sources@ give you a live array you can manipulate, or iterate over. On the other hand, methods like @with@ and @from@ accept a wider set of arguments and clean them up for you. The also all return the same task you're calling, so you can chain methods together.
+This time, the variable @jjtree@ is a file task that reads a JJTree source file
+from the @src/main/jjtree@ directory, and generates additional source files in
+the @target/generated/jjtree@ directory. The second line creates another file
+task that takes those source files, runs JavaCC on them, and generates yet more
+source files in @target/generated/javacc@. Finally, we include both sets of
+source files in addition to those already in @src/main/java@, and compile the
+lot.
+
+The interesting thing about these two examples is how you're wiring file tasks
+together to create more complicated tasks, piping the output of one task into
+the inputs of another. Wiring tasks this way is the most common way to handle
+complex builds, and uses Rake's dependency mechanism to only run tasks when it
+detects a change to one of the source files.
+
+You can also control the target directory. Use @compile.target@ to get the
+target directory file task. If you need to change the target directory, call
+the @compile.into@ method with the new path.
+
+We use method pairs to give you finer control over the compiler, but also a way
+to easily configure it. Methods like @dependencies@ and @sources@ give you a
+live array you can manipulate, or iterate over. On the other hand, methods
+like @with@ and @from@ accept a wider set of arguments and clean them up for
+you. The also all return the same task you're calling, so you can chain
+methods together.
For example:
{{{!ruby
-compile.from("srcs").with("org.apache.axis2:axis2:jar:1.2").
- into("classes")
+compile.from('srcs').with('org.apache.axis2:axis2:jar:1.2').
+ into('classes').using(:target=>'1.4')
}}}
-Buildr uses the method pair and method chaining idiom elsewhere to make your life easier without sacrificing flexibility.
+Buildr uses the method pair and method chaining idiom in many places to make
+your life easier without sacrificing flexibility.
-Occasionally, you'll need to post-process the generated bytecode. Since you only want to do that after compiling, and let the compiler decide when to do that â only when changes require re-compiling â you'll want to extend the @compile@ task. You can do that by calling @compile@ with a block.
+Occasionally, you'll need to post-process the generated bytecode. Since you
+only want to do that after compiling, and let the compiler decide when to do
+that â only when changes require re-compiling â you'll want to extend the
+@compile@ task. You can do that by calling @compile@ with a block.
-For example, to run the OpenJPA bytecode enhancer after compiling the source files:
+For example, to run the OpenJPA bytecode enhancer after compiling the source
+files:
{{{!ruby
compile { open_jpa_enhance }
}}}
-You can change various compile options by calling, you guessed, @compile.options@. For example, to set the compiler to VM compatibility with Java 1.5 and turn on all Lint messages:
+You can change various compile options by calling, you guessed,
+@compile.options@. For example, to set the compiler to VM compatibility with
+Java 1.5 and turn on all Lint messages:
{{{!ruby
-compile.options.target = "1.5"
-compile.options.lint = "all"
+compile.options.target = '1.5'
+compile.options.lint = 'all'
}}}
Or, if you want to chain methods together:
{{{!ruby
-compile.using :target=>"1.5", :lint=>"all"
+compile.using :target=>'1.5', :lint=>'all'
}}}
-Sub-projects inherit the compile options from their parent project, so you only need to change these settings once in the top project. You can do so, even if the top project itself doesn't compile anything.
+Sub-projects inherit compile options from their parent project, so you only
+need to change these settings once in the top project. You can do so, even if
+the top project itself doesn't compile anything.
-Unless you set the @warning@ option, Buildr will set it for you, running the compiler with warnings on, but turning them off when you run @buildr@ with the @--silent@ option. It will also set the @debug@ option on, except when making a release. Since the debug option is something you may want to control when running Buildr, you can also do that by setting the environment variable @debug@ to @off@.
+The options available to you depend on which compiler you are using for this
+particular project, obviously the options are not the same for Java and Flash.
+Two options are designed to work consistently across compilers.
-For example:
+Buildr turns the @warning@ option on by default, but turns it off when you run
+@buildr --silent@. It also sets the @debug@ option on, but turns it off when
+making a release. You can also control the @debug@ option from the command
+line, for example:
{{{!ruby
# When calling buildr
@@ -110,114 +188,171 @@
h2. Resources
-The @compile@ task comes bundled with a @resources@ task. It copies files from the @src/main/resources@ directory into @target/classes@ (or wherever you point the compiler at). Best used for copying files that you want to included in the generated code, like configuration files and message bundles.
+The @compile@ task comes bundled with a @resources@ task. It copies files from
+the @src/main/resources@ directory into @target/resources@. Best used for
+copying files that you want to included in the generated code, like
+configuration files, i18n messages, images, etc.
-The @resources@ task uses a filter that can change files as it copies them from source to destination. The most common use is by mapping values using a hash. For example, to substitute "${version}" for the project's version number and "${copyright}" for "Acme Inc (C) 2007" :
+The @resources@ task uses a filter that can change files as it copies them from
+source to destination. The most common use is by mapping values using a hash.
+For example, to substitute "${version}" for the project's version number and
+"${copyright}" for "Acme Inc (C) 2007" :
{{{!ruby
-resources.filter.using "version"=>version,
- "copyright"=>"Acme Inc (C) 2007"
+resources.filter.using 'version'=>version,
+ 'copyright'=>'Acme Inc (C) 2007'
}}}
-You can specify a different format by passing it as the first argument. Supported formats include:
+You can specify a different format by passing it as the first argument.
+Supported formats include:
* @:ant@ -- Map from <code>@key@</code> to value.
* @:maven@ -- Map from @${key}@ to value (default).
* @:ruby@ -- Map from @#{key}@ to value.
-* @Regexp@ -- Map using the matched value of the regular expression (e.g. @/=(.*?)=/@).
+* @Regexp@ -- Map using the matched value of the regular expression (e.g.
+@/=(.*?)=/@).
For example, using the @:ruby@ format instead of the default @:maven@ format:
{{{!ruby
-resources.filter.using :ruby, "version"=>version,
- "copyright"=>"Acme Inc (C) 2007"
+resources.filter.using :ruby, 'version'=>version,
+ 'copyright'=>'Acme Inc (C) 2007'
}}}
-For more complicated mapping you can also pass a method or a proc. The filter will call it once for each file with the file name and content.
+For more complicated mapping you can also pass a method or a proc. The filter
+will call it once for each file with the file name and content.
-If you need to copy resource files from other directories, add these source directories by calling the @from@ method, for example:
+If you need to copy resource files from other directories, add these source
+directories by calling the @from@ method, for example:
{{{!ruby
-resources.from _("src/etc")
+resources.from _('src/etc')
}}}
-You can select to copy only specific files using common file matching patterns. For example, to include only HTML files:
+You can select to copy only specific files using common file matching patterns.
+For example, to include only HTML files:
{{{!ruby
-resources.include "*.html"
+resources.include '*.html'
}}}
To include all files, except for files in the @scratch@ directory:
{{{!ruby
-resources.exclude "scratch/*"
+resources.exclude 'scratch/*'
}}}
-The filter always excludes the @CVS@ and @.svn@ directories, and all files ending with @.bak@ or @~@, so no need to worry about these.
-
-A file pattern can match any file name or part of a file name using an asterisk (@*@). Double asterisk (@**@) matches directories recursively, for example, @"src/main/java/**/*.java"@. You can match any character using a question mark (@?@), or a set of characters using square brackets (@[]@), similar to regular expressions, for example, @"[Rr]eadme"@. You can also match from a set of names using curly braces (@{}@), for example, @"*.{html,css}"@.
+The filter always excludes the @CVS@ and @.svn@ directories, and all files
+ending with @.bak@ or @~@, so no need to worry about these.
-You can use filters elsewhere. The @filter@ method creates a filter, the @into@ method sets the target directory, and @using@ specifies the mapping. Last, you call @run@ on the filter to activate it.
+A file pattern can match any file name or part of a file name using an asterisk
+(@*@). Double asterisk (@**@) matches directories recursively, for example,
+@'src/main/java/**/*.java'@. You can match any character using a question mark
+(@?@), or a set of characters using square brackets (@[]@), similar to regular
+expressions, for example, @'[Rr]eadme'@. You can also match from a set of names
+using curly braces (@{}@), for example, @'*.{html,css}'@.
+
+You can use filters elsewhere. The @filter@ method creates a filter, the
+@into@ method sets the target directory, and @using@ specifies the mapping.
+Last, you call @run@ on the filter to activate it.
For example:
{{{!ruby
-filter("src/specs").into("target/specs").
- using("version"=>version, "created"=>Time.now).run
+filter('src/specs').into('target/specs').
+ using('version'=>version, 'created'=>Time.now).run
}}}
-The @resources@ task is, in fact, just a wrapper around such a filter that automatically adds the @src/main/resources@ directory as one of the source directories.
+The @resources@ task is, in fact, just a wrapper around such a filter that
+automatically adds the @src/main/resources@ directory as one of the source
+directories.
h2. More On Building
-The @build@ task runs the @compile@ (and @resources@) tasks as prerequisites, followed by any actions you add to it, and completes by running the @test@ task. The @build@ task itself is a prerequisite to other tasks, for example, @package@ and @upload@.
+The @build@ task runs the @compile@ (and @resources@) tasks as prerequisites,
+followed by any actions you add to it, and completes by running the @test@
+task. The @build@ task itself is a prerequisite to other tasks, for example,
+@package@ and @upload@.
+
+You can extend the @build@ task in two ways. You can add more prerequisites
+that will execute before the task itself, or you can add actions that will
+execute as part of the task. Which one you choose is up to you, we'll show you
+how they differ in a second. If you call @build@ with a list of tasks, it adds
+these tasks as prerequisites. Call @build@ with a block, and it adds that
+block as an action. Again, a common idiom you'll see elsewhere in Buildr and
+Rake.
-You can extend the @build@ task in two ways. You can add more prerequisites that will execute before the task itself, or you can add actions that will execute as part of the task. Which one you choose is up to you, we'll show you how they differ in a second. If you call @build@ with a list of tasks, it adds these tasks as prerequisites. Call @build@ with a block, and it adds that block as an action. Again, a common idiom you'll see elsewhere in Buildr and Rake.
-
-Let's look at a simple example. Say we want to generate a Derby database form an SQL file and include it in the ZIP package:
+Let's look at a simple example. Say we want to generate a Derby database form
+an SQL file and include it in the ZIP package:
{{{!ruby
-db = Derby.create(_("target/derby/db")=>_("src/main/sql/derby.sql"))
+db = Derby.create(_('target/derby/db')=>_('src/main/sql/derby.sql'))
package(:zip).include db
}}}
-There's nothing fundamentally wrong with this code, if that's what you intend to do. But in practice, you don't always run the @package@ task during development, so you won't notice if something is wrong with this task when you build. For example, if it fails to generate the SQL file. In addition, the @package@ task runs after @build@, so you can't use the database in your test cases.
-
-So let's refactor it. We're going to use the variable @db@ to reference the file task that creates the database, and make it a prerequisite of the @build@ task. And use that same variable again to include the database in the ZIP package:
+There's nothing fundamentally wrong with this code, if that's what you intend
+to do. But in practice, you don't always run the @package@ task during
+development, so you won't notice if something is wrong with this task when you
+build. For example, if it fails to generate the SQL file. In addition, the
+@package@ task runs after @build@, so you can't use the database in your test
+cases.
+
+So let's refactor it. We're going to use the variable @db@ to reference the
+file task that creates the database, and make it a prerequisite of the @build@
+task. And use that same variable again to include the database in the ZIP
+package:
{{{!ruby
-db = Derby.create(_("target/derby/db")=>_("src/main/sql/derby.sql"))
+db = Derby.create(_('target/derby/db')=>_('src/main/sql/derby.sql'))
build db
package(:zip).include db
}}}
-Much better. We're using the same task twice, but since we're using Rake here, it will only execute once. In fact, it will only execute if we don't already have a Derby database, or if it detects a change to the SQL file and needs to recreate the database. (Note: @Derby.create@ is not part of Buildr, you can get "derby.rake":http://svn.apache.org/repos/asf/incubator/ode/trunk/tasks/derby.rake here).
+Much better. We're using the same task twice, but since we're using Rake here,
+it will only execute once. In fact, it will only execute if we don't already
+have a Derby database, or if it detects a change to the SQL file and needs to
+recreate the database. (Note: @Derby.create@ is not part of Buildr, you can
+get
+"derby.rake":http://svn.apache.org/repos/asf/incubator/ode/trunk/tasks/derby.rake
+here).
-Here's another example. We want to copy some files over as part of the build, and apply a filter to them. This time, we're going to extend the @build@ task:
+Here's another example. We want to copy some files over as part of the build,
+and apply a filter to them. This time, we're going to extend the @build@ task:
{{{!ruby
build do
- filter("src/specs").into("target/specs").
- using("version"=>version, "created"=>Time.now).run
+ filter('src/specs').into('target/specs').
+ using('version'=>version, 'created'=>Time.now).run
end
}}}
-The @build@ task is recursive, so running @buildr build@ picks the current project and runs its @build@ task, which in turn runs the @build@ task on each of its sub-projects. One @build@ task to rule them all.
+The @build@ task is recursive, so running @buildr build@ picks the current
+project and runs its @build@ task, which in turn runs the @build@ task on each
+of its sub-projects. One @build@ task to rule them all.
h2. Cleaning
-The @build@ task has an evil twin, the @clean@ task. It's the task you use to remove all the files created during the build, especially when you mess things up and want to start all over.
-
-It basically erases the target directories, the one called @target@, and if you get creative and change the target directory for tasks like @compile@, it will also erase those. If you decide to generate files outside the target directory and want to cleanup after yourself, just extend the @clean@ task.
+The @build@ task has an evil twin, the @clean@ task. It's the task you use to
+remove all the files created during the build, especially when you mess things
+up and want to start all over.
+
+It basically erases the target directories, the one called @target@, and if you
+get creative and change the target directory for tasks like @compile@, it will
+also erase those. If you decide to generate files outside the target directory
+and want to cleanup after yourself, just extend the @clean@ task.
For example:
{{{!ruby
-clean { rm_rf _("staged") }
+clean { rm_rf _('staged') }
}}}
-The @rm_rf@ method deletes the directory and all files in it. It's named after UNIX's infamous @rm -rf@. Use it wisely. This is also a good time to introduce you to @FileUtils@, a standard Ruby library that contains convenient methods for creating and deleting directories, copying and moving files, even comparing two files. They're all free of charge when you use Buildr.
+The @rm_rf@ method deletes the directory and all files in it. It's named after
+UNIX's infamous @rm -rf@. Use it wisely. This is also a good time to
+introduce you to @FileUtils@, a standard Ruby library that contains convenient
+methods for creating and deleting directories, copying and moving files, even
+comparing two files. They're all free of charge when you use Buildr.
Now let's "talk about the artifacts":artifacts.html we mentioned before.
Modified: incubator/buildr/trunk/doc/pages/packaging.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/packaging.textile?rev=609910&r1=609909&r2=609910&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/packaging.textile (original)
+++ incubator/buildr/trunk/doc/pages/packaging.textile Tue Jan 8 01:01:03 2008
@@ -1,18 +1,22 @@
h1. Packaging
-For our next trick, we're going to try and create an artifact ourselves. We're going to start with:
+For our next trick, we're going to try and create an artifact ourselves. We're
+going to start with:
{{{!ruby
package :jar
}}}
-We just told the project to create a JAR file in the @target@ directory, including all the classes (and resources) that we previously complied into @target/classes@. Or we can create a WAR file:
+We just told the project to create a JAR file in the @target@ directory,
+including all the classes (and resources) that we previously complied into
+@target/classes@. Or we can create a WAR file:
{{{!ruby
package :war
}}}
-The easy case is always easy, but sometimes we have more complicated use cases which we'll address through the rest of this section.
+The easy case is always easy, but sometimes we have more complicated use cases
+which we'll address through the rest of this section.
Now let's run the build, test cases and create these packages:
@@ -20,61 +24,85 @@
$ buildr package
}}}
-The @package@ task runs the @build@ task (remember: @compile@ and @test@) and then runs each of the packaging tasks, creating packages in the projects' target directories[1].
+The @package@ task runs the @build@ task (remember: @compile@ and @test@) and
+then runs each of the packaging tasks, creating packages in the projects'
+target directories[1].
h2. Packaging JARs
-There are several ways you can configure the JAR package. We'll start with the MANIFEST.MF file. You can include a specific file:
+There are several ways you can configure the JAR package. We'll start with the
+MANIFEST.MF file. You can include a specific file:
{{{!ruby
-package(:jar).with :manifest=>_("src/main/MANIFEST.MF")
+package(:jar).with :manifest=>_('src/main/MANIFEST.MF')
}}}
Or generate a manifest from a hash:
{{{!ruby
-package(:jar).with :manifest=>{ "Copyright"=>"Acme Inc (C) 2007" }
+package(:jar).with :manifest=>{ 'Copyright'=>'Acme Inc (C) 2007' }
}}}
-You can also generate a JAR with no manifest with the value @false@, create a manifest with several sections using an array of hashes, or create it from a proc.
+You can also generate a JAR with no manifest with the value @false@, create a
+manifest with several sections using an array of hashes, or create it from a
+proc.
-In large projects, where all the packages use the same manifest, it's easier to set it once on the top project using the @manifest@ project property. Sub-projects inherit the property from their parents, and the @package@ method uses that property if you don't override it, as we do above.
+In large projects, where all the packages use the same manifest, it's easier to
+set it once on the top project using the @manifest@ project property.
+Sub-projects inherit the property from their parents, and the @package@ method
+uses that property if you don't override it, as we do above.
For example, we can get the same result by specifying this at the top project:
{{{!ruby
-manifest["Copyright"] = "Acme Inc (C) 2007"
+manifest['Copyright'] = 'Acme Inc (C) 2007'
}}}
-If you need to mix-in the project's manifest with values that only one package uses, you can do so easily:
+If you need to mix-in the project's manifest with values that only one package
+uses, you can do so easily:
{{{!ruby
-package(:jar).with :manifest=>manifest.merge("Main-Class"=>"com.acme.Main")
+package(:jar).with :manifest=>manifest.merge('Main-Class'=>'com.acme.Main')
}}}
-If you need to include more files in the @META-INF@ directory, you can use the @:meta_inf@ option. You can give it a file, or array of files. And yes, there is a @meta_inf@ project property you can set once to include the same set of file in all the JARs. It works like this:
+If you need to include more files in the @META-INF@ directory, you can use the
+@:meta_inf@ option. You can give it a file, or array of files. And yes, there
+is a @meta_inf@ project property you can set once to include the same set of
+file in all the JARs. It works like this:
{{{!ruby
-meta_inf << file("DISCLAIMER") << file("NOTICE")
+meta_inf << file('DISCLAIMER') << file('NOTICE')
}}}
-If you have a @LICENSE@ file, it's already included in the @meta_inf@ list of files.
+If you have a @LICENSE@ file, it's already included in the @meta_inf@ list of
+files.
-Other than that, @package :jar@ includes the contents of the compiler's target directory, which most often is exactly what you intend it to do. If you want to include other files in the JAR, instead or in addition, you can do so using the @include@ and @exclude@ methods. We'll tell you more about them when we talk about "Packaging Zips":#packaging_zips.
+Other than that, @package :jar@ includes the contents of the compiler's target
+directory and resources, which most often is exactly what you intend it to do.
+If you want to include other files in the JAR, instead or in addition, you can
+do so using the @include@ and @exclude@ methods. We'll tell you more about
+them when we talk about "Packaging Zips":#packaging_zips.
h2. Packaging WARs
-Pretty much everything you know about JARs works the same way for WARs, so let's just look at the differences.
+Pretty much everything you know about JARs works the same way for WARs, so
+let's just look at the differences.
-Without much prompting, @package :war@ picks the contents of the @src/main/webapp@ directory and places it at the root of the WAR, copies the compiler target directory into the @WEB-INF/classes@ path, and copies any compiled classpath dependencies into the @WEB-INF/libs@ paths.
+Without much prompting, @package :war@ picks the contents of the
+@src/main/webapp@ directory and places it at the root of the WAR, copies the
+compiler target directory into the @WEB-INF/classes@ path, and copies any
+compiled dependencies into the @WEB-INF/libs@ paths.
-Again, you can use the @include@ and @exclude@ methods to change the contents of the WAR. There are two convenience options you can use to make the more common changes. If you need to include a classes directory other than the default:
+Again, you can use the @include@ and @exclude@ methods to change the contents
+of the WAR. There are two convenience options you can use to make the more
+common changes. If you need to include a classes directory other than the
+default:
{{{!ruby
-package(:war).with :classes=>_("target/additional")
+package(:war).with :classes=>_('target/additional')
}}}
If you want to include a different set of libraries other than the default:
@@ -83,9 +111,15 @@
package(:war).with :libs=>MYSQL_JDBC
}}}
-Both options accept a single value or an array. The @:classes@ option accepts the name of a directory containing class files, initially set to @compiler.target@. The @:libs@ option accepts artifact specifications, file names and tasks, initially set to include everything in @compile.classpath@.
-
-As you can guess, the package task has two attributes called @classes@ and @libs@; the @with@ method merely sets their value. If you need more precise control over these arrays, you can always work with them directly, for example:
+Both options accept a single value or an array. The @:classes@ option accepts
+the name of a directory containing class files, initially set to
+@compile.target@ and @resources.target@. The @:libs@ option accepts artifact
+specifications, file names and tasks, initially set to include everything in
+@compile.dependencies@.
+
+As you can guess, the package task has two attributes called @classes@ and
+@libs@; the @with@ method merely sets their value. If you need more precise
+control over these arrays, you can always work with them directly, for example:
{{{!ruby
# Add an artifact to the existing set:
@@ -93,128 +127,182 @@
# Remove an artifact from the existing set:
package(:war).libs += artifacts(LOG4J)
# List all the artifacts:
-puts "Artifacts included in WAR package:"
+puts 'Artifacts included in WAR package:'
puts package(:war).libs.map(&:to_spec)
}}}
h2. Packaging ZIPs
-JARs and WARs are pretty much glorified ZIPs. The ZIP packaging is much simpler, it doesn't support the @:manifest@ and @:meta_inf@ options. Sounds simpler, and it is.
+JARs and WARs are pretty much glorified ZIPs. The ZIP packaging is much
+simpler, it doesn't support the @:manifest@ and @:meta_inf@ options. Sounds
+simpler, and it is.
-Which is why we're going to use this section to tell you a bit more about ZIP file packaging. But anything you read here, you can also use with @package :jar@ and @package :war@. They're all ZIP files, afterall.
+Which is why we're going to use this section to tell you a bit more about ZIP
+file packaging. But anything you read here, you can also use with @package
+:jar@ and @package :war@. They're all ZIP files, afterall.
-Let's start by including additional files in the ZIP package. We're going to include the @target/docs@ directory and @README@ file:
+Let's start by including additional files in the ZIP package. We're going to
+include the @target/docs@ directory and @README@ file:
{{{!ruby
-package(:zip).include _("target/docs"), "README"
+package(:zip).include _('target/docs'), 'README'
}}}
-The @include@ method accepts files, directories and file tasks. You can also use file pattern to match multiple files and directories. File patterns include asterisk (@*@) to match any file name or part of a file name, double asterisk (@**@) to match directories recursively, question mark (@?@) to match any character, square braces (@[]@) to match a set of characters, and curly braces (@{}@) to one of several names.
+The @include@ method accepts files, directories and file tasks. You can also
+use file pattern to match multiple files and directories. File patterns
+include asterisk (@*@) to match any file name or part of a file name, double
+asterisk (@**@) to match directories recursively, question mark (@?@) to match
+any character, square braces (@[]@) to match a set of characters, and curly
+braces (@{}@) to one of several names.
-And the same way you @include@, you can also @exclude@ specific files you don't want showing up in the ZIP. For example, to exclude @.draft@ and @.raw@ files:
+And the same way you @include@, you can also @exclude@ specific files you don't
+want showing up in the ZIP. For example, to exclude @.draft@ and @.raw@ files:
{{{!ruby
-package(:zip).include("target/docs").
- exclude("target/docs/**/*.{draft,raw}")
+package(:zip).include('target/docs').
+ exclude('target/docs/**/*.{draft,raw}')
}}}
-So far we've included files under the root of the ZIP. Let's include some files under a given path using the @:path@ option:
+So far we've included files under the root of the ZIP. Let's include some
+files under a given path using the @:path@ option:
{{{!ruby
-package(:zip).include "target/docs", :path=>"#{id}-#{version}"
+package(:zip).include 'target/docs', :path=>"#{id}-#{version}"
}}}
-If you need to use the @:path@ option repeatedly, consider using the @path@ method instead. For example[2]:
+If you need to use the @:path@ option repeatedly, consider using the @path@
+method instead. For example[2]:
{{{!ruby
package(:zip).path("#{id}-#{version}").tap do |path|
- path.include "target/docs"
- path.include "README"
+ path.include 'target/docs'
+ path.include 'README'
end
}}}
-*Note:* To allow you to spread files across different paths, the include/exclude patterns are specific to a path. So in the above example, if you want to exclude some files from the "target/docs" directory, make sure to call @exclude@ on the path, not on the ZIP task itself.
-
+*Note:* To allow you to spread files across different paths, the
+include/exclude patterns are specific to a path. So in the above example, if
+you want to exclude some files from the "target/docs" directory, make sure to
+call @exclude@ on the path, not on the ZIP task itself.
-If you need to include a file or directory under a different name, use the @:as@ option. For example:
+If you need to include a file or directory under a different name, use the
+@:as@ option. For example:
{{{!ruby
-package(:zip).include("corporate-logo-350x240.png", :as=>"logo.png")
+package(:zip).include('corporate-logo-350x240.png', :as=>'logo.png')
}}}
-You can also use @:as=>"."@ to include all files from the given directory. For example:
+You can also use @:as=>'.'@ to include all files from the given directory. For
+example:
{{{!ruby
-package(:zip).include "target/docs/*"
-package(:zip).include "target/docs", :as=>"."
+package(:zip).include 'target/docs/*'
+package(:zip).include 'target/docs', :as=>'.'
}}}
-These two are almost identical. They both include all the files from the @target/docs@ directory, but not the directory itself. But they operate differently. The first line expands to include all the files in @target/docs@. If you don't already have files in @target/docs@, well, then it won't do anything interesting. Your ZIP will come up empty. The second file includes the directory itself, but strips the path during inclusion. You can define it now, create these files later, and then ZIP them all up.
+These two are almost identical. They both include all the files from the
+@target/docs@ directory, but not the directory itself. But they operate
+differently. The first line expands to include all the files in @target/docs@.
+If you don't already have files in @target/docs@, well, then it won't do
+anything interesting. Your ZIP will come up empty. The second file includes
+the directory itself, but strips the path during inclusion. You can define it
+now, create these files later, and then ZIP them all up.
-For example, when @package :jar@ decides to include all the files form @target/classes@, it's still working on the project definition, and has yet to compile anything. Since @target/classes@ may be empty, may not even exist, it uses @:as=>"."@.
+For example, when @package :jar@ decides to include all the files form
+@target/classes@, it's still working on the project definition, and has yet to
+compile anything. Since @target/classes@ may be empty, may not even exist, it
+uses @:as=>'.'@.
-You can also merge two ZIP files together, expanding the content of one ZIP into the other. For example:
+You can also merge two ZIP files together, expanding the content of one ZIP
+into the other. For example:
{{{!ruby
-package(:zip).merge "part1.zip", "part2.zip"
+package(:zip).merge 'part1.zip', 'part2.zip'
}}}
-If you need to be more selective, you can apply the include/exclude pattern to the expanded ZIP. For example:
+If you need to be more selective, you can apply the include/exclude pattern to
+the expanded ZIP. For example:
{{{!ruby
# Everything but the libs
-package(:zip).merge("bigbad.war").exclude("libs/*")
+package(:zip).merge('bigbad.war').exclude('libs/*')
}}}
h2. Packaging AARs
-Axis2 service archives are similar to JAR's (compiled classes go into the root of the archive) but they can embed additional libraries under /lib and include @services.xml@ and WSDL files.
-
-{{{!ruby
-package(:aar).with(:libs=>"log4j:log4j:jar:1.1")
-package(:aar).with(:services_xml=>_("target/services.xml"), :wsdls=>_("target/*.wsdl"))
-}}}
-
-The @libs@ attribute is a list of .jar artifacts to be included in the archive under /lib. The default is no artifacts; artifacts from the compile classpath are not included by default.
-
-The @services_xml@ attribute points to an Axis2 services configuration file called @services.xml@ that will be placed in the @META-INF@ directory inside the archive. the default behavior is to point to the @services.xml@ file in the project's @src/main/axis2@ directory. In the second example above we set it explicitly,
-
-The @wsdls@ attribute is a collection of file names or glob patterns for WSDL files that get included in the @META-INF@ directory. In the second example we include WSDL files from the @target@ directory, presumably created by an earlier build task. In addition, AAR packaging will include all files ending with @.wsdl@ from the @src/main/axis2@ directory.
-
-If you already have WSDL files in the @src/main/axis2@ directory but would like to perform some filtering, for example, to set the HTTP port number, consider ignoring the originals and including only the filtered files, for example:
+Axis2 service archives are similar to JAR's (compiled classes go into the root
+of the archive) but they can embed additional libraries under /lib and include
+@services.xml@ and WSDL files.
+
+{{{!ruby
+package(:aar).with(:libs=>'log4j:log4j:jar:1.1')
+package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
+}}}
+
+The @libs@ attribute is a list of .jar artifacts to be included in the archive
+under /lib. The default is no artifacts; compile dependencies are not included
+by default.
+
+The @services_xml@ attribute points to an Axis2 services configuration file
+called @services.xml@ that will be placed in the @META-INF@ directory inside
+the archive. the default behavior is to point to the @services.xml@ file in
+the project's @src/main/axis2@ directory. In the second example above we set
+it explicitly,
+
+The @wsdls@ attribute is a collection of file names or glob patterns for WSDL
+files that get included in the @META-INF@ directory. In the second example we
+include WSDL files from the @target@ directory, presumably created by an
+earlier build task. In addition, AAR packaging will include all files ending
+with @.wsdl@ from the @src/main/axis2@ directory.
+
+If you already have WSDL files in the @src/main/axis2@ directory but would like
+to perform some filtering, for example, to set the HTTP port number, consider
+ignoring the originals and including only the filtered files, for example:
{{{!ruby
# Host name depends on environment.
host = ENV['ENV'] == 'test' ? 'test.host' : 'ws.example.com'
-filter.from("src/main/axis2").into("target").
- include("services.xml", "*.wsdl").using("http_port"=>"8080", "http_host"=>host)
+filter.from('src/main/axis2').into('target').
+ include('services.xml', '*.wsdl').using('http_port'=>'8080', 'http_host'=>host)
package(:aar).wsdls.clear
-package(:aar).with(:services_xml=>_("target/services.xml"), :wsdls=>_("target/*.wsdl"))
+package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
}}}
h2. Packaging Tars and GZipped Tars
-Everything you know about working with ZIP files translates to Tar files, the two tasks are identical in more respect, so here we'll just go over the differences.
-
-{{{!ruby
-package(:tar).include _("target/docs"), "README"
-package(:tgz).include _("target/docs"), "README"
-}}}
-
-The first line creates a Tar archive with the extension @.tar@, the second creates a GZipped Tar archive with the extension @.tgz@.
-The first creates a Tar archive with the extension @.tar@, the second creates a GZipped Tar archive with the extension @.tgz@.
-
-In addition to packaging that includes the archive in the list of installed/released files, you can use the method @tar@ to create a @TarTask@. This task is similar to @ZipTask@, and introduces the @gzip@ attribute, which you can use to tell it whether to create a regular file, or GZip it. By default the attribute it set to true (GZip) if the file name ends with either @.gz@ or @.tgz@.
+Everything you know about working with ZIP files translates to Tar files, the
+two tasks are identical in more respect, so here we'll just go over the
+differences.
+
+{{{!ruby
+package(:tar).include _('target/docs'), 'README'
+package(:tgz).include _('target/docs'), 'README'
+}}}
+
+The first line creates a Tar archive with the extension @.tar@, the second
+creates a GZipped Tar archive with the extension @.tgz@. The first creates a
+Tar archive with the extension @.tar@, the second creates a GZipped Tar archive
+with the extension @.tgz@.
+
+In addition to packaging that includes the archive in the list of
+installed/released files, you can use the method @tar@ to create a @TarTask@.
+This task is similar to @ZipTask@, and introduces the @gzip@ attribute, which
+you can use to tell it whether to create a regular file, or GZip it. By
+default the attribute it set to true (GZip) if the file name ends with either
+@.gz@ or @.tgz@.
h2. Installing and Uploading
-You can bring in the artifacts you need from remote repositories and install them in the local repositories. Other projects have the same expectation, that your packages be their artifacts.
+You can bring in the artifacts you need from remote repositories and install
+them in the local repositories. Other projects have the same expectation, that
+your packages be their artifacts.
-So let's create these packages and install them in the local repository where other projects can access them:
+So let's create these packages and install them in the local repository where
+other projects can access them:
{{{!sh
$ buildr install
@@ -226,7 +314,8 @@
$ buildr uninstall
}}}
-That works between projects you build on the same machine. Now let's share these artifacts with other developers through a remote repository:
+That works between projects you build on the same machine. Now let's share
+these artifacts with other developers through a remote repository:
{{{!sh
$ buildr upload
@@ -235,45 +324,65 @@
Of course, you'll need to tell Buildr about the release server:
{{{!ruby
-repositories.release_to = "sftp://john:secret@release/usr/share/repo"
+repositories.release_to = 'sftp://john:secret@release/usr/share/repo'
}}}
-We're using the SFTP protocol, currently the only protocol Buildr uses for uploads. The URL contains the release server ("release"), path to repository ("user/share/repo") and username/password for access. The way SFTP works, you specify the path on the release server, and give the user permissions to create directories and files inside the repository. The file system path is different from the path you use to download these artifacts through an HTTP server, and starts at the root, not the user's home directory.
-
-Of course, you'll want to specify the release server URL in the Buildfile, but leave the username/password settings private in your local @buildr.rb@ file. Let's break up the release server settings:
+We're using the SFTP protocol, currently the only protocol Buildr uses for
+uploads. The URL contains the release server ("release"), path to repository
+("user/share/repo") and username/password for access. The way SFTP works, you
+specify the path on the release server, and give the user permissions to create
+directories and files inside the repository. The file system path is different
+from the path you use to download these artifacts through an HTTP server, and
+starts at the root, not the user's home directory.
+
+Of course, you'll want to specify the release server URL in the Buildfile, but
+leave the username/password settings private in your local @buildr.rb@ file.
+Let's break up the release server settings:
{{{!ruby
# build.rb, loaded first
-repositories.release_to[:username] = "john"
-repositories.release_to[:password] = "secret"
+repositories.release_to[:username] = 'john'
+repositories.release_to[:password] = 'secret'
# Buildfile, loaded next
-repositories.release_to[:url] = "sftp://release/usr/share/repo"
+repositories.release_to[:url] = 'sftp://release/usr/share/repo'
}}}
-The @upload@ task takes care of uploading all the packages created by your project, along with their associated POM files and MD5/SHA1 signatures (Buildr creates these for you).
+The @upload@ task takes care of uploading all the packages created by your
+project, along with their associated POM files and MD5/SHA1 signatures (Buildr
+creates these for you).
-If you need to upload other files, you can always extend the @upload@ task and use @repositories.release_to@ in combination with @URI.upload@. You can also extend it to upload to different servers, for example, to publish the documentation and test coverage reports to your site:
+If you need to upload other files, you can always extend the @upload@ task and
+use @repositories.release_to@ in combination with @URI.upload@. You can also
+extend it to upload to different servers, for example, to publish the
+documentation and test coverage reports to your site:
{{{!ruby
-# We'll let some other task decide how to create "docs"
-task "deploy"=>"docs" do
+# We'll let some other task decide how to create 'docs'
+task 'deploy'=>'docs' do
uri = URI("sftp://#{username}:#{password}@var/www/docs")
- uri.upload file("docs")
+ uri.upload file('docs')
end
}}}
h2. Specifying And Referencing Packages
-If it's a package to us and an artifact to someone else, then it must have an artifact specification. Right? And to have an artifact specification, it must have a group identifier, artifact identifier, version number and optional classifier. Where do they come from?
-
-These are all options you can pass to the @package@ method. Or, you can let it pick them from the project definition. In this case it pays to be lazy, and easier to just specify the group identifier and version number as project properties. The artifact identifier is just the project (full) name, with colons (@:@) replaced by dashes (@-@).
+If it's a package to us and an artifact to someone else, then it must have an
+artifact specification. Right? And to have an artifact specification, it must
+have a group identifier, artifact identifier, version number and optional
+classifier. Where do they come from?
+
+These are all options you can pass to the @package@ method. Or, you can let it
+pick them from the project definition. In this case it pays to be lazy, and
+easier to just specify the group identifier and version number as project
+properties. The artifact identifier is just the project (full) name, with
+colons (@:@) replaced by dashes (@-@).
Let's run an example and find out:
{{{!ruby
-puts project("killer-app:teh-impl").packages.first.to_spec
+puts project('killer-app:teh-impl').packages.first.to_spec
=> acme:killer-app-teh-impl:1.0:jar
}}}
@@ -281,23 +390,25 @@
{{{!ruby
# Generates silly-1.0.jar
-package :jar, :id=>"silly"
+package :jar, :id=>'silly'
# Generates killer-app-la-web-1.x.war
-project "la-web" do
- package :war, :version=>"1.x"
+project 'la-web' do
+ package :war, :version=>'1.x'
end
# Generates killer-app-the-api-1.0-sources.zip
-project "teh-api" do
- package :zip, :classifier=>"sources"
+project 'teh-api' do
+ package :zip, :classifier=>'sources'
end
}}}
-You can get all the packages created by a project and filter them yourself. Let's illustrate that with an example that prints artifact specifications for all the packages we generate through our projects[3]:
+You can get all the packages created by a project and filter them yourself.
+Let's illustrate that with an example that prints artifact specifications for
+all the packages we generate through our projects[3]:
{{{!ruby
-puts projects.map(&:packages).flatten.map(&:to_spec).join(", ")
+puts projects.map(&:packages).flatten.map(&:to_spec).join(', ')
=> acme:killer-app:zip:sources:1.0, acme:killer-app-teh-api:jar:1.0,
acme:killer-app-teh-impl:jar:1.0, acme:killer-app-la-web:war:1.0
}}}
@@ -306,60 +417,85 @@
{{{!ruby
puts projects.map(&:packages).flatten.select { |pkg| pkg.type == :jar }.
- map(&:to_spec).join(", ")
+ map(&:to_spec).join(', ')
}}}
-But for a single package, we're just going to call @package@ with the right artifact specification. Each time you call @package@ on a project, it returns a file task for that package. It only creates the file task once, so call it twice, and you'll get the same file task. We can use that to our advantage:
+But for a single package, we're just going to call @package@ with the right
+artifact specification. Each time you call @package@ on a project, it returns
+a file task for that package. It only creates the file task once, so call it
+twice, and you'll get the same file task. We can use that to our advantage:
{{{!ruby
-compile.with project("teh-api").package(:jar)
+compile.with project('teh-api').package(:jar)
}}}
-But remember, @package@ decides which file task to return from the combination of file type, artifact and group identifiers, version number and classifier. So we need to pass the very same arguments to retrieve the very same package. For example:
+But remember, @package@ decides which file task to return from the combination
+of file type, artifact and group identifiers, version number and classifier.
+So we need to pass the very same arguments to retrieve the very same package.
+For example:
{{{!ruby
-projec("killer-app:teh-impl").package(:war)
-project("killer-app").package(:zip, :classifier=>"docs")
+projec(t'killer-app:teh-impl').package(:war)
+project('killer-app').package(:zip, :classifier=>'docs')
}}}
h2. Packaging Sources and JavaDocs
-IDEs can take advantage of source packages to help you debug and trace through compiled code. We'll start with a simple example:
+IDEs can take advantage of source packages to help you debug and trace through
+compiled code. We'll start with a simple example:
{{{!ruby
package :sources
}}}
-This one creates a ZIP package with the classifier "sources" that will contain all the source directories in that project, typically @src/main/java@, but also other sources generated from Apt, JavaCC, XMLBeans and friends.
-
-You can also generate a ZIP package with the classifier "javadoc" that contains the JavaDoc documentation for the project. It uses the same set of documentation files generated by the project's @javadoc@ task, so you can use it in combination with the @javadoc@ method. For example:
+This one creates a ZIP package with the classifier "sources" that will contain
+all the source directories in that project, typically @src/main/java@, but also
+other sources generated from Apt, JavaCC, XMLBeans and friends.
+
+You can also generate a ZIP package with the classifier "javadoc" that contains
+the JavaDoc documentation for the project. It uses the same set of
+documentation files generated by the project's @javadoc@ task, so you can use
+it in combination with the @javadoc@ method. For example:
{{{!ruby
package :javadoc
-javadoc :windowtitle=>"Buggy but Works"
+javadoc :windowtitle=>'Buggy but Works'
}}}
By default Buildr picks the project's description for the window title.
-You can also tell Buildr to automatically create sources and JavaDoc packages in all the sub-projects that have any source files to package or document. Just add either or both of these methods in the top-level project:
+You can also tell Buildr to automatically create sources and JavaDoc packages
+in all the sub-projects that have any source files to package or document.
+Just add either or both of these methods in the top-level project:
{{{!ruby
package_with_sources
package_with_javadoc
}}}
-You can also tell it to be selective using the @:only@ and @:except@ options. For example:
+You can also tell it to be selective using the @:only@ and @:except@ options.
+For example:
{{{!ruby
-package_with_javadoc :except=>"la-web"
+package_with_javadoc :except=>'la-web'
}}}
-We packaged the code, but will it actually work? Let's see "what the tests say":testing.html.
+We packaged the code, but will it actually work? Let's see "what the tests
+say":testing.html.
-fn1. The @package@ task and @package@ methods are related, but that relation is different from other task/method pairs. The @package@ method creates a file task that points to the package in the @target@ directory and knows how to create it. It then adds itself as a prerequisite to the @package@ task. Translation: you can create multiple packages from the same project.
+fn1. The @package@ task and @package@ methods are related, but that relation is
+different from other task/method pairs. The @package@ method creates a file
+task that points to the package in the @target@ directory and knows how to
+create it. It then adds itself as a prerequisite to the @package@ task.
+Translation: you can create multiple packages from the same project.
-fn2. The @tap@ method is not part of the core library, but a very useful extension. It takes an object, yields to the block with that object, and then returns that object.
+fn2. The @tap@ method is not part of the core library, but a very useful
+extension. It takes an object, yields to the block with that object, and then
+returns that object.
-fn3. The @map@ method takes an array, runs the block with each item, and returns a new array. The @&:@ shortcut is not a standard part of Ruby but a useful convenience that calls this method on each instance. So @map(&:packages)@ is just a shorter way of saying @map { |obj| obj.packages }@.
+fn3. The @map@ method takes an array, runs the block with each item, and
+returns a new array. The @&:@ shortcut is not a standard part of Ruby but a
+useful convenience that calls this method on each instance. So
+@map(&:packages)@ is just a shorter way of saying @map { |obj| obj.packages }@.