Building Applications with Ant Build Files

If you perform the build process from the command line, Workshop will export an Ant script that duplicates the standard, IDE-based application build. You can then do command line builds using the Ant script. Note that modifying the generated Ant script does not alter the build process within Workshop.

Ant Build Script Functionality

The exported Ant script contains a set of standard targets for building, assembling, staging and generating module archives. You can view the targets supported for a specific script with the command ant -projecthelp. The functionality of these targets is detailed in the following table.

Supported Ant Targets

Target	Dependencies	Details
build		Compiles the source files; does not package the results. The target in an EAR project's Ant script builds all child module projects in dependency order. This target requires that the target project is associated with a particular runtime.
assemble	build(a formal dependency does not exist on "build" but that target must be called prior to assemble)	Assembles the project for iterative dev deployment; requires that the "ear.root" property is specified. The target in an EAR project's Ant script assembles all child module projects.
stage	build(a formal dependency does not exist on "build" but that target must be called prior to stage)	Copies all of project's resources and build artifacts into a form that's ready for archive creation; staging directory can be overridden via the "staging.dir" property. The target in an EAR project's Ant script stages all child module projects.
archive	stage	Creates an archive containing all projects's resources and build artifacts; archive name and location can be overridden via the "archive.path" property. Note that the archive target builds an EAR file if run from an EAR script; if run from an Ant script generated from a web project, it generates a WAR file.
clean		Removes the files and directories generated by the build target

Workspace Metadata File

If you want to run your Ant scripts on a remote machine that does not have access to the workspace, you must first generate a workspace metadata file

This file lets you relativize absolute paths in the workspace's .metadata directory, including:

the WebLogic home directory
the workspace directory
the Java home directory

Variables defined in the workspace metadata file need to be passed to the ant script at runtime using the -D syntax.

Generating Ant Build Scripts

To Export Ant Build Scripts and (Optionally) a Workspace Metadata File

Select File > Export > Workshop Build Scripts > Workshop Ant Scripts. Click Next.
In the Export Ant Scripts pane, select the projects to generate Ant scripts for and decide whether to create a workspace metadata file.

For non-Workshop project types (i.e. WTP EJB, Connector, Application Client, Java), only the Java Project Build Script is available. This build script provides minimal functionality (just basic build and clean targets) and cannot be used directly within the context of a full EAR build. For these projects, you may find it useful to instead customize the build script created for a utility project.
The Export workspace metadata checkbox controls whether a workspace metadata file is created. This file allows you to run the Ant scripts on a remote machine that does not have access to the workspace, by relativizing absolute paths in the workspace's .metadata directory. For more details see Workspace Metadata File above.
- The Destination field controls where the workspace metadata file will be written.
The Export Libraries checkbox controls whether libraries will be copied to an new location. (Alternatively, you can export libraries by selecting File > Export > General > Workshop Libraries.)
- The Destination field controls where the libraries will be copied to.

Click Finish to generate the scripts.
Click Next to define variables to relativize absolute paths in the workspace's .metadata directory

On the Paths screen, The wl.home and workspace.dir will be automatically populated. The purpose of that screen is to define variables to relativize absolute paths written to the exported workspace.xml file. The user can see the remaining absolute paths in the lower box. When a new variable is defined that covers a portion of one of the absolute paths, those absolute paths will be removed from that box. Every variable that’s defined at this point will need to be passed to the ant script at runtime using the -D syntax.

Click Finish to generate the scripts.

To Export a Workspace Metadata File

Choose File > Export > Workshop Build Scripts > Workspace Metadata for Workshop Ant Script.

This wizard does not export ant scripts. It is only used for exporting workspace metadata. It is typically used to update the workspace metadata after build scripts have already been exported and changes have been made to the workspace.

Troubleshooting

Projects must be open (Project > Open Project) before exporting an Ant script. You cannot export an Ant script for a closed project.
The Ant script for a project should be regenerated if any changes are made to the project's enabled facets.
The workspace metadata file must be regenerated if changes are made to project metadata (e.g. Java build path) or workspace structure (e.g. new/removed projects, changes in inter-project dependencies).
The machine used to run the ant scripts must have the exported Workshop libraries from the same release of Workshop that was used to generate the Ant scripts. In addition it must have an installation of whichever version of WebLogic Server that the projects in question are targeting. To export libraries, you can either click the Export Libraries checkbox in the Ant export wizard or select File > Export > General > Workshop Libraries. These libraries must be referenced when calling Ant script targets: see the libraryDirPath parameter below.
The Beehive Controls and WebLogic Control Extensions facets depend on one another. If either is enabled for a given project, the other must also be enabled in order to generate a valid Ant script. Projects with one facet enabled but not the other my show the following error when running the archive target in the generated Ant script:
```
    Could not create task or type of type: assemble.
```

Executing Ant Build Scripts

To Build a Project by Running the Ant Script:

Generate the Ant script for the project.
Configure the execution environment of your shell by executing wl.home/common/bin/commEnv.cmd (or wl.home/common/bin/commEnv.sh for Linux).

Use of the Ant scripts without prior execution of commEnv.cmd (commEnv.sh for Linux) is not currently supported.
Change to the Eclipse project directory.
Execute the desired Ant targets as follows (example illustrates the creation of the project archive):

ant build archive -Dworkspace=workspacepath -Dworkshop.lib.dir=libraryDirPath

where the parameters are:

workspacepath is the full path for the workspace folder (e.g., on Windows you might specify the path as C:/MyWork/Workspaces/MyApp) OR the full path and file name of the workspace metadata file.

libraryDirPath is the full path to a directory containing Workshop libraries that are used by the Ant scripts. Workshop libraries can be exported by either checking the Export Libraries checkbox in the Ant export wizard or using the Export Workshop Libraries wizard (File > Export > General > Workshop Libraries).

If your path names have embedded spaces, you must use quote marks to delimit the path name, e.g.,

ant build -Dworkspace="C:\Documents and Settings\MyWorkspace"

To Build an EAR File Using the Ant Script:

Generate the Ant script for each project in the EAR.
Generate the Ant script for the EAR project.
Configure the execution environment of your shell by executing wl.home/common/bin/commEnv.*
Change to the Eclipse directory for the EAR project.
Execute the desired target in the EAR project's Ant script as follows:

ant build archive -Dworkspace=workspacepath

To Execute Ant Scripts on a Remote Machine:

Generate the workspace metadata file as discussed above.
Generate the necessary project Ant build scripts.
Copy the following files to the remote machine:
- the Ant script(s)
- the workspace metadata file
- everything else in the project and/or ear file, minus the contents of the build directories
Following the project or EAR build instructions above but specify the location of the workspace metadata file as the value of -Dworkspace= argument instead of the workspace directory location.

Caveats and Implementation Notes:

Workspace metadata is imported by the Workshop Ant scripts during every execution. Unless an exported workspace metadata file is being used, this behavior ensures that changes to the workspace metadata (e.g. modifications to a project's classpath) will be reflected without necessitating a regeneration of the script. The state of the imported workspace metadata can be viewed by specifying -Decho.metadata=true on the commandline when executing Ant.
Generated Ant scripts are for use in command line builds, not to run within Workshop. Concurrent use of Workshop and the Ant scripts is not supported and can lead to build errors. The output from the Ant script build should be cleaned prior to launching Workshop to ensure there are no conflicts.

Handling Different Target Runtimes in the Same Workspace

Suppose you have a workspace where the projects target different runtime versions, for example, where one project targets WebLogic Server version 9.2 and another project targets version 10.0.

When building such workspaces, you may encounter a build error like the following:

    BUILD FAILED
    C:\bea\workshop10\user_projects\workspaces\myWorkspace\webEAR\build.xml:72: Property wl.home2 is not defined!

To avoid the error, all path variables created in the script export process must be specified at script launch time using the -D syntax. The list of path variables to specify is available on the second page of the script generation dialog File > Export > Workshop Build Scripts > Workshop Ant Scripts. Note that you do not need to specify wl.home because the scripts will automatically read WL_HOME environmental variables, but you must specify wl.home2 for the second runtime location, as shown below.

    ant clean build archive
        -Dworkspace=C:\bea\workshop10\user_projects\workspaces\myWorkspace
        -Dworkshop.lib.dir=C:\bea\workshop10\user_projects\workspaces\myWorkspace\workshop-lib
        -Dwl.home2=C:/bea/workshop92/wlserver_92

EJB project properties not visible from generated Ant build scripts

The "Jar settings" properties and EJBC flags that can be set on EJB projects via Project > Properties > WebLogic EJB are only used when the IDE build executes; these settings are not visible when exported Workshop Ant build scripts are executed.

Prior to building the project with the exported Ant script, specify all desired "Jar settings" properties using weblogic.ejbgen.JarSettings annotations in your EJB Java source files and add desired EJBC flags directly to the build script where "weblogic.ejbc" is executed.