Overview

This article shows you how to install and use bftool, a Java™-based tool that uses the IBM® Rational® Build Forge® Java API to provide users with a command line interface to Build Forge. This can save you time in performing daily administration tasks or setting up new Build Forge projects and environments. The article gives an overview of the commands available. It also provides several examples of practical applications of the tool that have been used on customer engagements. This article presupposes familiarity with the core IBM Rational Build Forge product.

Installation

1. Download and install JDK 5. You can obtain it at the Java download site.
   
2. Download and extract the contents of the bftool.zip file from the Downloads section below.

Notes:

• The bftool directory includes a bftool.bat file for execution on Windows™ and a bftool file for UNIX® platforms. You can remove the one that is not needed for your platform.
• If you have a version of Build Forge other than IBM Rational Build Forge iFix2 for version 7.0.2, you will need to download your version’s rbf-services-client-java.jar file, as follows:
1. Bring up your Management Console in a Web browser, and append /clients to the URL of the server. For example: http://mybfconsole/clients.
2. From the clients page, download the Java Client Jar file. In some versions of the product it will download as a .zip file. In this case you should change the extension to .jar.
3. Copy the downloaded jar file into the /lib directory in your bftool installation directory.

Configuration

1. From your IBM Rational Build Forge Management Console, create the user and password that bftool will use to access Build Forge. Put the user in the necessary access groups.
2. Set the following variables in your system environment:
• BFTOOL_HOME – Set to the installation location of bftool. For example, C:\bftool or /usr/local/bftool.
• PATH – Append BFTOOL_HOME to your system path variable.
• BF_USER – Set to the name of the user created in step 1.
• BF_PASSWORD – Set to the password of the user created in step 1.
• BF_HOST – Set this to the IP address or server name of your Build Forge management console server.
3. Open a command prompt window and run the command: bftool lsgroup. You should see a list of all the access groups in your system.

Notes:

• The BF_USER you specify cannot be an LDAP user, but must exist only in the Build Forge database.
• If you begin running commands and you see 'Malformed database object' errors, you have the wrong version of the rbf-services-client-java.jar file. You must replace the rbf-services-client-java.jar file in the %BFTOOL_HOME%\lib directory with the one you download from your Management Console.

Back to top

Using bftool

There are several different categories of bftool commands, some examples are:

Informational commands: lscollector, lsenv, lsfilter, lsgroup, lsjob, lsperm, lsproject, lsresult, lsschedule, lsselector, lsserver, lsserverauth, lsstep, lstzone, lsuser

Addition commands: addcollectorproperty, addmember, addpattern, addselectorproperty, addstep, addsubgroup, addvar, grantperm, mkcollector, mkenv, mkfilter, mkgroup, mkproject, mkschedule, mkselector, mkserver, mkserverauth, mkuser

Removal commands: revokeperm, rmcollector, rmcollectorproperty, rmenv, rmfilter, rmgroup, rmmember, rmpattern, rmproject, rmselector, rmselectorproperty, rmserver, rmserverauth, rmstep, rmsubgroup, rmuser, rmvar

Execution commands: runproject

To see a complete list of available commands, simply type bftool at the command line with no arguments, and press Enter.

Back to top

Exercises

Here are some exercises to familiarize you with the commands. It may be helpful to keep a Web browser open to your Build Forge Management Console so you can see the objects you create in the console as you go along.

These exercises were executed on a new instance of Build Forge. Group numbers used reflect the groups initially present after a new install of Build Forge, and they may be modified for your environment. Also, for certain UNIX shells, escape characters may vary.

For any given command you can call the bftool <command> -h to see the command syntax and options.

1. Open a command window.
   
   
2. Run the following command to see the proper usage of command mkuser:
   
   > bftool mkuser -h
   
   
3. Create a user using the following commands (use bftool lstzone to see available timezone codes):
   
   > bftool lstzone
> bftool mkuser -name "Patrick Toma" -login "ptoma" -password "ptoma" -email "ptoma@noblestar.com" -level 6 -priority_login -tzone CST
   
   
4. Run the following command to view available groups:
   
   > bftool lsgroup -l
   
   
5. Add your user to the Build Engineer, System Manager and Security groups using the following commands:
   
   > bftool addmember -uname "ptoma" -gname "Build Engineer"
> bftool addmember -uname "ptoma" -gid 4
> bftool addmember -uname "ptoma" -gid 5
   
   
6. Create a Server Authentication profile. This should have valid login credentials for the server you plan to use:
   
   > bftool mkserverauth -name "MyAuth" -username "ptoma" -password "myserverpwd" -level 6
   
   
7. Create an environment for your server:
   
   > bftool mkenv -name "MyServer Env" -level 6
   
   
8. Add some variables to your server environment:
   
   > bftool addvar -name "ANT_HOME" -value "C:\ant1.6.5" -env_name "MyServer Env" -mode REQUIRED -action SET
> bftool addvar -name "JAVA_HOME" -value "C:\jdk1.5.0" -env_name "MyServer Env" -mode REQUIRED -action SET -index 1
> bftool addvar -name "PATH" -value "${ANT_HOME}\bin" -mode NORMAL -action APPEND -index 2 -env_name "MyServer Env"
   
   
9. Create a selector to be able to select your server:
   
   > bftool mkselector -name "MyServer Selector" -level 6
   
   
10. Add a selector property to your selector:
    
    > bftool addselectorproperty -id "MyServer Selector" -name "BF_NAME" –value "MyServer" -operator EQ -required
    
    
11. Create a collector:
    
    > bftool mkcollector -name "MyCollector"
    
    
12. Add some properties to your collector:
    
    > bftool addcollectorproperty -cname "MyCollector" -pname ".include" –pvalue "Example"
> bftool addcollectorproperty –cname "MyCollector" –pname "TEST_VAR" –pvalue "123"
> bftool addcollectorproperty –cname "MyCollector" –builtin CPU_LOAD
> bftool addcollectorproperty –cname "MyCollector" –pname "JDK_VERSION" –pvalue "java –version" –regex "^java version \"\d\.(\d)\.\d_\d+\" "
    
    
13. List available authentication profiles:
    
    > bftool lsserverauth -l
    
    
14. List available collectors:
    
    > bftool lscollector -l
    
    
15. List available environments:
    
    > bftool lsenv
    
    
16. Create your server:
    
    > bftool mkserver -name MyServer -host localhost -path "C:\builds" -level 6 -env_id 1 -collector_id MyCollector -auth_id MyAuth
    
    
17. Create the root directory of your server on the machine:
    
    > mkdir C:\builds
    
    
18. From the Web console, test the connection to your server and ensure the agent is up.
    
    
19. Create your project:
    
    > bftool mkproject -name MyProject -class Production -tag BUILD_$B -env_id 1 -selector_name "MyServer Selector" -access_id 6 -start_notify 6 -pass_notify 6 -fail_notify 6
    
    
20. Add some steps to your project:
    
    > bftool addstep -pname "MyProject" -name "hello" -cmd "echo hello\necho hi" –level 6
> bftool addstep -pname "MyProject" -name "sleeping" –cmd ".sleep 20" –level 6
> bftool addstep -pname "MyProject" -name "goodnight" -cmd "echo goodnight" -level 6
    
    
21. Run your project:
    
    > bftool runproject -pname MyProject
    
    
22. Check the status of the job as it progresses:
    
    > bftool lsjob -pname MyProject -l
    
    
23. Check the results of the build and its steps:
    
    > bftool lsresult -l -tag BUILD_1
    
    
24. Create a schedule to run the build every 1/2 hour:
    
    > bftool mkschedule -mins "*/30" -hrs "*" -mdays "*" -months "*" -wdays "1-5" -pid 1 -eid 1 -sid "MyServer Selector" -desc "CI Build"
    
    
25. Call 'bftool' without any arguments to see the list of available commands. Experiment with some of the other commands and options.
    
    

Back to top

Applications of bftool

Automating creation of a large number of environments

Creating a large number of environments, or environments with a large number of variables, can be very time-consuming using the GUI. It is easier to manage the information you need from a spreadsheet.

Using a simple Perl script and a sample .csv file provided, you will be able to create several environments and populate them with variables quickly. This example could easily be modified for creation of servers, selectors or any other entity in the system.

Note: To run this example you need to have Perl installed and in your path. Download the envs.csv file and the create_envs.pl from this article, and follow these steps:

1. Extract the contents of bf_envs.zip (see the Download section), open the envs.csv file and examine the data in it.
2. Open the create_envs.pl script and examine it. Notice the bftool commands being run to create the environments.
3. Run the script: ratlperl create_envs.pl envs.csv
4. Login to the console as root and examine the environments page. Examine the environments created and their variables.

Using bftool for integration with other tools

One potential application of the bftool is to call it within an IBM® Rational® ClearCase® check-in trigger. In a continuous integration environment, teams may want to trigger a smoke test build every time a developer checks in code. An example, bf_cc_trigger.pl, has been provided with this article (see Downloads). The trigger retrieves the VOB name, and executes a Build Forge project with the name ${VOB_NAME}_BUILD.

To run the sample trigger:

1. Select a VOB that you want to install the trigger into. For the purposes of this example, we will assume the VOB is named \JavaTools
   
   
2. Create a Build Forge project named ${VOB_NAME}_BUILD. For example, JavaTools_BUILD
   
   > bftool mkproject -name JavaTools_BUILD -class Production -tag BUILD_$B -env_id 1 -selector_name "MyServer Selector" -access_id 6
   
   
3. Add a step to the project:
   
   > bftool addstep -pid 2 -name "Sleep" -cmd ".sleep 20" -level 6
   
   
4. Install the trigger into your VOB. Modify this command with the appropriate paths for your ClearCase environment.
   
   > cleartool mktrtype -c "Trigger to fire builds" -element -all -postop checkin -execwin "ratlperl \\myservername\triggers\bf_cc_trigger.pl" -execunix "perl /net/triggers/bf_cc_trigger.pl" BF_CC_TRIGGER@\JavaTools
   
   
5. Ensure that bftool is correctly installed on the development machine where you will use the trigger.
6. Check a file into the VOB. You should see a prompt as shown in Figure 1.

7. Check the status of the job in the IBM Rational Build Forge Management Console (Figure 2).

This trigger is an example of how bftool can facilitate integration with other development tools. It could be modified to add environment variables or call different build projects depending on the types of files checked in. You could also easily call bftool commands from an IBM® Rational® ClearQuest® hook.

Acknowledgements

The author would like to thank the following people for their contribution to this project:

• David Bellagio, IBM Corporation
• Dale Newby, IBM Corporation
• Luis Carlos Quintela, IBM Corporation
• Steven Vaughan, IBM Corporation

Back to top

Downloads

Information about download methods

Notes

1. Note: bftool has been tested using an IBM Rational Build Forge iFix2 for version 7.0.2 Management Console. The bftool has been tested on the Microsoft Windows XP Pro SP2 and Ubuntu 8.04 LTS Desktop Edition platforms.
2. Use these files if you want to automate the creation of a large number of environments, or environments with a large number of variables.

Resources

Learn

• For more general information about IBM Rational Build Forge, check the Build Forge documentation.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Get products and technologies

• See the Build Forge examples page for a list of Build Forge example projects, APIs, adaptors, documentation and tools.
  
  
• Find more resources for build and release engineers and managers in the Build Forge area of the developerWorks Rational zone, including technical articles, downloads, demos and links to training courses, discussion forums, product documentation and support.
  
  
• Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Seeking answers or advice about good build and release management practices? Are you a Build Forge user looking to connect with others? Post in the Build and release management/Build Forge forum on developerWorks.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Overview
• Using bftool
• Exercises
• Applications of bftool
• Downloads
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers