Getting started with Rational Application Developer for WebSphere Software build utility

This topic provides instructions on how to get started using the build utility.

Getting started

To get started with the build utility:
  1. The build utility stores your projects and metadata in a folder. You need to define a workspace environment variable to use for each command prompt session. Set the workspace directory to an existing and empty directory:
    This graphic is a Windows icon. On Windows:
    set workspace=<workspace root>
    Example: set workspace=c:\workspace
    This graphic is a Linux icon. On Linux:
    export workspace=<workspace root>
    Example: export workspace=/opt/workspace
    Remember: Using /opt/workspace assumes you have root authority. If you are not a root user create or use an empty directory in a location where you do have write access.
    This graphic is a z/OS icon. On z/OS:
    export workspace=<workspace root>
    Example: export workspace=/opt/workspace
    Remember: Using /opt/workspace assumes you have root authority. If you are not a root user create or use an empty directory in a location where you do have write access.
  2. To list all your environment variables and their values, run the following command:
    • This graphic is a Windows icon. On Windows:set
    • This graphic is a Linux icon. On Linux:export
    • This graphic is a z/OS icon. On z/OS:export
  3. Issue the runAnt command to start the build utility and run your build script. The runAnt command is located in <Build_Utility_installation_directory>\eclipse\bin directory. For example in a command prompt issue the following command:
    This graphic is a Windows icon. On Windows:
    c:\BuildUtility\eclipse\bin>runAnt -buildfile myScript.xml
    This graphic is a Linux icon. On Linux:
    /opt/BuildUtility/eclipse/bin>runAnt.sh -buildfile myScript.xml
    This graphic is a z/OS icon. On z/OS:
    /opt/BuildUtility/eclipse/bin>runAnt_zos.sh -buildfile myScript.xml

Running the AutoBuild sample

Packaged in the build utility core installation files is an AutoBuild sample. This section provides instructions on how to run this AutoBuild sample.

Prerequisites

To run the AutoBuild sample:
  1. Create a backup copy of the original AutoBuild sample by archiving the files under the BuildUtility\eclipse\samples\AutoBuild directory. Otherwise, you will modify the sample by running it and no longer has access to the original sample.
  2. Open a command prompt and set the workspace environment variable. For details on setting the workspace environment variable, see the Getting Started section.
  3. If you have already run the AutoBuild sample and want to run it again, you need to reset the environment:
    1. Verify that the directory defined for the workspace environment variable is existing and empty. In other words, remove all files and directories under the workspace that are from a previous run of the AutoBuild sample.
    2. Replace the BuildUtility\eclipse\samples\AutoBuild directory with a backup copy of the original packaged AutoBuild sample.
  4. Modify the following line in the AdderBuild.preferences file available in the BuildUtility\eclipse\samples\AutoBuild directory:
    targetRuntime.targetLocation=D:/WAS61
    Replace D:/WAS61 with the local WebSphere Application Server v6.1 installation directory. In the file path to the local WebSphere Application Server v6.1 installation directory, you must use forward slashes. Here is an example:
    Correct usage of the forward slashes:
    targetRuntime.targetLocation=C:/Program Files/IBM/WebSphere/AppServer
    Incorrect, the slashes are backward slashes:
    targetRuntime.targetLocation=C:\Program Files\IBM\WebSphere\AppServer
  5. To study what the AutoBuild sample does, open the AdderBuild.xml build script in a text editor. You can find it in the BuildUtility\eclipse\samples\AutoBuild directory. This script file implements the following Ant tasks:
    init
    • Prints out information about the build including some of the variables that are defined.
    • Loads the preferences from the AdderBuild.preferences file.
      • This sets up the AdderRuntime in the workspace
    • Builds the workspace
    importAndBuildEverything
    • Imports and builds all projects listed in the AdderBuildImport.psf file by calling projectSetImportAndBuild Ant task
    • Builds the workspace
    • Builds the AdderEJBClient_UtilJar.jar file
    • Imports and builds the AdderErrorWeb project to demonstrate a build failure
    projectSetImportAndBuild
    • Imports all the projects listed in the AdderBuildImport.psf file by calling projectSetImport
    • Builds all the projects listed in the AdderBuildImport.psf by calling projectSetBuild
    projectImportAndBuild
    • Imports the project projectName
    • Builds the project projectName
    DebugTraceHighlight
    • Prints out a debug message
  6. To study how to run the AutoBuild sample, open the buildAdderExample file in a text editor. You can find it in the BuildUtility\eclipse\samples\AutoBuild directory. Look for the following command in the script:
    "%RUNANT_DIR%\..\..\bin\runant" -buildfile  "%RUNANT_DIR%\AdderBuild.xml" %*  importAndBuildEverything
    This command issues the runAnt command to start the build utility with the build script file AdderBuild.xml, and requests to start the importAndBuildEverything Ant task.
  7. Switch back to the command prompt and run the buildAdderExample command. For example on the Windows operating system:
    c:\BuildUtility\eclipse\samples\AutoBuild>buildAdderExample.bat
  8. In the AutoBuild sample there is a test for failure for the AdderErrorWeb project. If you receive a similar BUILD FAILED message for this AdderErrorWeb project, due to the test for failure you can safely ignore this message:
    buildECLIPSE:
     [echo] buildMASTER for AdderErrorWeb
[projectBuild] Building: AdderErrorWeb (Begin)
[projectBuild]  (Begin)
[projectBuild]  (Done)
[projectBuild]  (Begin)
[projectBuild]  (Done)
[projectBuild] The user operation is waiting for background work to complete. (Begin)
[projectBuild] The user operation is waiting for background work to complete. (Done)
[projectBuild] The user operation is waiting for background work to complete. (Begin)
[projectBuild] The user operation is waiting for background work to complete. (Done)
[projectGetErrors] ----------
[projectGetErrors] 1. ERROR in \AdderErrorWeb\src\AdderJavaErrors.java
[projectGetErrors] (at line 2)    org.eclipse.jdt.core.problem
[projectGetErrors] The import xyz cannot be resolved
[projectGetErrors] ----------
[projectGetErrors] 2. ERROR in \AdderErrorWeb\src\AdderJavaErrors.java
[projectGetErrors] (at line 5)    org.eclipse.jdt.core.problem
[projectGetErrors] Syntax error on token "x", delete this token
[projectGetErrors] ----------
[projectGetErrors] 3. ERROR in \AdderErrorWeb\WebContent\AdderJspErrors.jsp
[projectGetErrors] (at line 23)    org.eclipse.jst.jsp.core.validationMarker
[projectGetErrors] badVariable cannot be resolved

BUILD FAILED
C:\IBM\SDP\7552\20100721_2133\samples\AutoBuild\AdderBuild.xml:110: The following error occurred while executing this line:
C:\IBM\SDP\7552\20100721_2133\samples\AutoBuild\AdderBuild.xml:153: The following error occurred while executing this line:
C:\IBM\SDP\7552\20100721_2133\samples\AutoBuild\AdderBuild.xml:163: The following error occurred while executing this line:
C:\IBM\SDP\7552\20100721_2133\samples\AutoBuild\AdderErrorWeb\build.xml:18: The following error occurred while executing this line:
C:\IBM\SDP\7552\20100721_2133\samples\AutoBuild\AdderBuild\buildMASTER.xml:173: The following error occurred while executing this line:
C:\IBM\SDP\7552\20100721_2133\samples\AutoBuild\AdderBuild\buildMASTER.xml:43: FAIL-ON-ERROR.  projectName=AdderErrorWeb  errorCount=3  errorMessage[1]=The import xyz cannot be resolved

Total time: 26 seconds
HeadlessWorkspaceSettings: RESTORED autoBuild=true maxFile=1048576
runAnt BUILD FAILED.
  9. The output for the AutoBuild sample is project archive files, such as the EAR, WAR, and JAR files. The output is in the directory defined for your java.io.tmpdir property, which typically corresponds to the TMP environment variable for your computer. For example, you can find the following project archive files in the C:\Documents and Settings\Administrator\Local Settings\Temp directory for Windows operating system; and /tmp or /var/tmp for Linux operating system:
    • Adder.ear
    • AdderClient.jar
    • AdderEJB.jar
    • AdderEJBClient_UtilJar.jar
    • AdderStaticWeb.war
    • AdderWeb.war
    Alternatively, in the command prompt you can determine the directory location of the output from the system output of running the AutoBuild sample. For example, look for the following system output:
    [ejbExport] EJBExport completed to /tmp/AdderEJB.jar
...
[appClientExport] AppClientExport completed to /tmp/AdderClient.jar
...
[warExport] WARExport completed to /tmp/AdderWeb.war
...
    In this example, the AdderEJB.jar, AdderClient.jar, and AdderWeb.war are in the /tmp directory for a Linux operating system.
Related concepts:
Installing Rational Application Developer for WebSphere Software build utility for Windows, Linux, and Solaris
Installing Rational Application Developer for WebSphere Software build utility for z/OS
Related tasks:
Installing Rational Application Developer for WebSphere Software build utility
Related information:
Automate the builds of applications
Feedback