This page defines the build architecture being deployed in Pentaho development. This document covers all the tools used with the build architecture and how Pentaho is using them to create a better build process.

Tool Overview

There are a number of open source 3rd party tools being used in the build process. The following list outlines the tools and how they are being used:

Tool Name	Version	Description
Apache Ant	1.7.0	The tool that runs the build script. These scripts will perform all the tasks necessary to take the source code and create jar files.
Apache Ivy	2.0 beta 2	A dependency manager that works well with Apache Ant. It allows for a list of dependencies in each project that get resolved at build time and removes the need to check in jar files for each project.
Artifactory	1.2.5	A Maven2 repository implementation that allows for the storage of build artifacts (like jar files) and information about their dependencies.

User Home

<HOME>/.ivy2

.ivy2/
|-- cache
`-- local

<HOME>/.pentaho_build_cache

.pentaho_build_cache/
|-- ant-contrib
|-- cobertura
|-- ivy
`-- tmp

IVY is the dependency resolver tool of choice for Pentaho projects.

.ivy2/cache - IVY will cache downloaded artifacts on your disk here in order to minimize downloads.
.ivy2/local - Developers have the option of publishing to their local repository during a build, e.g. ant publish-local. The directory .ivy2/local is that hierarchical, file-based repository.

The common_build.xml Ant script requires custom and third-party Ant libraries in order to run all targets, however it does not require that the user have these pre-installed. Common build is able to bootstrap itself by intelligently fetching libraries as needed. When common build fetches such a library, it will store it in a well-known directory, .pentaho_build_cache, and not attempt to retrieve it again as long so it is available there.

.pentaho_build_cache - root directory where all common build dependencies are maintained
.pentaho_build_cache/tmp - temporary sandbox used by common build

Your Workspace

<WORKSPACE>/my-pentaho-proj

my-pentaho-proj/
|-- eclipse-bin
|-- bin
|   |-- classes
|   |-- javadoc
|   |-- reports
|   |   |-- cobertura
|   |   |   |-- html
|   |   |   `-- xml
|   |   `-- test
|   |       |-- html
|   |       `-- xml
|   `-- test
|       |-- classes
|       |-- cobertura-bin
|       `-- instrumented-classes
|-- dev-lib
|-- dist
|-- lib
|-- src
|-- test-src
`-- test-lib

Sources

src - Application source code
test-src - Test source code

Libs

lib - Directory where IVY will deposit "default" (compile-time) dependencies, when it is asked to retrieve them (ant resolve-default).
test-lib - Directory where IVY will deposit "test" dependencies, e.g. junit4.jar, when it is asked to retrieve them (ant resolve-test).
dev-lib - non-IVY directory where developer can temporarily link jars into the project. Common build will look for jars in dev-lib and include them in the build.
dev-lib should never be committed to SVN!

When developing with the IVY Eclipse plugin, ivyDE, IVY-populated lib directories are ignored. Your Eclipse project will reference jars outside of the project space, in .ivy2/cache.

Notable Files

build.xml - Ant build file for the Pentaho project. This build file includes the common_build.xml and defines any project specific build functionality.
common_build.xml - Standardized Ant build file for all Pentaho projects
ivy.xml - Defines all the dependencies for the Pentaho project.

Distributable Archives

dist - Archive files produced by the build are placed in dist, this would include .jar, .zip, .tar.gz, .war, .ear, etc.

All Other Build Output

Build output has typically been placed in mix of hierarchical and flat directories from the project root. In an effort to tidy up the project workspace, bin has been reorganized to become the root of the hierarchy of all (non-archive) build output.

bin/classes - Classes compiled from project application source code are placed here. Compiled classes used to be placed directly in bin, keep that in mind if you run into strange behavior such as incorrect jar content from your custom build scripts.
bin/test - Root directory for any resources that may be needed to run unit tests, such as compiled test code and instrumented application source code (for code coverage tools)
bin/reports - Root directory for all kinds of reports the build might generate about the project, e.g. JUnit test reports, Cobertura or Clover coverage reports, FindBugs static analysis reports.
bin/javadoc - Javadoc html is placed here for browsing (javadoc may also be archived as a zip or targz in which case the archive would be placed in dist).

eclipse-bin - Eclipse will place compiled java classes here as opposed to bin which is reserved for the Ant-based build. The two are kept separate so Eclipse will not compete with Ant.

Artifact Repositories

An artifact repository allows for the storage and retrieval of build artifacts. These artifacts are mainly jar files with information about their dependencies. In addition, multiple versions of jar files may be retained for later retrieval.

Pentaho is using Ibiblio and their own Maven2 repository (running in Artifactory) to store and retrieve build artifacts:

Repository Name	Browse URL	Browse Login	Description
Ibiblio	http://mirrors.ibiblio.org/pub/mirrors/maven2/	none required	Public repository maintained by Ibiblio. Contains most of the 3rd party dependencies used by Pentaho.
third-party	http://repo.pentaho.org/artifactory	guest / guest	Repository which contains 3rd party libraries that can not be found (or are not correct) in the Ibiblio repository.
pentaho	http://repo.pentaho.org/artifactory	guest / guest	Repository which contains build artifacts generated by Pentaho.

Artifact Resolution

During the build process for each project, the build script will use the ivysettings.xml file to define the repository search order for resolving dependencies. The default setup of this file set the search order as:

The developer's IVY2 local repository
The developer's IVY2 cache repository (for dependencies marked as "changing" in the ivy.xml, the cache will check the next repository before returning the cached version)
The pentaho and third-party repositories
The ibiblio reposotory

If the artifact can not be found after check all the above, then the build will fail.

**** INSERT INFO HERE ABOUT RUNNING THE BUILD OFFLINE ****

Browser not supported