6 Adding Tools to Tornado

6.1 Introduction

Wind River Systems encourages users and third parties to customize the Tornado environment and to add features to it. This chapter describes how to create a new Tornado tool and add it to the Tornado launcher (in the UNIX environment) or to the Tornado launch toolbar (in the Windows environment). It also provides information about sharing Tornado development such as enhancements of existing tools or useful utilities with other users.

The Tornado environment is structured to make adding tools easy. For information on coding conventions and the Tornado tree, see the Tornado User's Guide: Coding Conventions.

6.2 Creating a Tornado Application

This section describes how to build and install a simple Tornado application based on the WTX protocol. It also describes how to generate HTML documentation for the new tool.

6.2.1 Example Specifications

The Tornado tool we build and install in this example was presented in 4. The WTX Protocol as an example of using the WTX C API. It allocates memory from the target memory pool managed by the target server until no more memory is available. It then frees the allocated memory and repeats this sequence until the user issues a CTRL+C. The tool is called wtxapp. When the tool is used with the Tornado browser in auto-update mode, it displays a changing memory-in-use chart.

The tool main program is made up of two files, wtxapp.h and wtxapp.c. It makes use of the WTX C API requests wtxMemAlloc( ) and wtxMemFree( ). The code for the application is located in 4.5.6 Application Example.

Note that the wtxapp tool installs a signal handler that not only stops the program on CTRL+C but also terminates the communication session with the target server properly. All Tornado tools should implement this type of signal handling.

6.2.2 Directories and File Naming

Wind River Systems recommends creating a dedicated directory for each Tornado tool in installDir/host/src. This directory contains all source and header files that constitute the tool plus a makefile. For wtxapp the files are:

installDir/host/src/wtxapp/Makefile

installDir/host/src/wtxapp/wtxapp.c

installDir/host/src/wtxapp/wtxapp.h

NOTE: For UNIX hosts, installDir is $WIND_BASE. For Windows users who use the command line, installDir is %WIND_BASE%.

6.2.3 Building the Application

Use a makefile that incorporates the Tornado generic makefile rules and macros found in the directory installDir/host/include/make to build Tornado applications. This type of makefile automatically generates a secondary makefile called Makefile.gen that contains the dependencies list. It installs the wtxapp executable in the bin directory for the host (for example, in installDir/host/sun4-solaris2/bin). The makefile for wtxapp appears in Example 6-1.

The Tornado include files are located in the installDir/host/include directory. This path is available in the makefile through the INCLUDES macro.

wtxapp uses routines from libwtxapi shared library. This library is included by the $UTIL_LIB macro in the makefile. wtxapp is also linked with extra libraries required by a particular tool chain on a given host. These extra libraries are defined by EXTRA_LIBS in the makefile.

For more information about the available makefile macros defined with Tornado, see installDir/host/include/make/generic.mh.

Example 6-1: wtxapp Makefile

# Makefile - for simple Tornado Application 
# 
# modification history 
# -------------------- 
# 01c,28jan99,wcc  add $(CFLAGS) to $(WTXAPP) rule  
# 01b,13jan97,bcc  port to Windows 
# 01a,25jul95,p_m  written 
# 
# DESCRIPTION 
# This file contains the makefile rules for building a simple 
# Tornado application 
# 
# SUBSTITUTION 
# 
# INCLUDES 
#       $(WIND_BASE)/host/include/make/generic.mh 
#       $(WIND_BASE)/host/include/make/$(HOST).mh 
#       $(WIND_BASE)/host/include/make/generic2.mh 
# 
 
include $(WIND_BASE)/host/include/make/generic.mh 
include $(WIND_BASE)/host/include/make/$(HOST).mh 
 
INCLUDES                = $(WIND_INC) 
 
WTXAPP                  = $(WIND_BIN)/wtxapp 
 
# documentation related variables 
 
DOC_FILES               = wtxapp.c 
DOC_DIR                 = $(DOCS_ROOT)/tornado-app/wtxapp 
 
VERSION_DEFINE          = $(CFLAGS) 
 
LIBRARIES               = 
PROGRAMS                = $(WTXAPP) 
TESTS                   = 
DOCS                    = doc 
 
## Add special build targets and default here. 
 
default:                prog 
 
$(WTXAPP): wtxapp.c $(SH_UTIL_LIB) 
        $(CC) $(CFLAGS) -DHOST=$(HOST) $(INCLUDES) wtxapp.c -o $@ \ 
                $(UTIL_LIB) $(EXTRA_LIBS) 
 
doc: $(DOC_FILES) 
        $(WIND_BIN)/refgen $(REFGEN_OPT) -book Tornado_Applications \ 
                -chapter WTX_Applications -out $(DOC_DIR) $(DOC_FILES) 
        $(WIND_BIN)/htmlLink $(DOC_DIR) 
 
include $(WIND_BASE)/host/include/make/generic2.mh

6.2.4 Compiling the Application

UNIX Hosts

The specific commands for compiling wtxapp depend on your host. For example, to compile on a Sun4 workstation running Solaris 2.5.1., issue the following commands from a UNIX shell (this example assume the c-shell; issue the appropriate commands for your shell):

% setenv WIND_BASE installdir 
% setenv WIND_HOST_TYPE sun4-solaris2 
% set path=(installDir/host/$WIND_HOST_TYPE/bin $path) 
% cd installDir/host/src/wtxapp 
% make HOST=$WIND_HOST_TYPE

Windows Hosts

Compiling on a Windows host requires creating a Visual C++ project.

Start Microsoft Visual C++ 5.0.

Select the Project tab under the New item on the File menu.

Select Win32 Console Application and fill in wtxapp in the Project name field. Be sure that the correct path is displayed in the Location field.

Select wtxapp.c in the Insert Files into Project dialog box under the Add to Project>Files item on the Project menu.

Select Settings on the Project menu. First select the Win32 Debug build target in the Settings for combo box. After debugging, you can change to the Win32 Release target.

For your debug build, select the following settings:

Click on the C/C++ tab and:

Select Code Generation in the Category combo box. Then select Debug Multithreaded DLL under the Use Run-time library option.

Select Preprocessor in the Category combo box. Add ,HOST to Preprocessor definitions and ..\..\include to Additional Include Directories.

Click on the Link tab and leave General selected in the Category combo box:

Enter ..\..\x86-win32\bin\wtxapp-d.exe under the Output file name option.

Enter ..\..\x86-win32\lib\wtxapidll-d.lib at the end of the list of Object/library modules.

For your release build, select the following settings:

Click on the C/C++ tab and:

Select Code Generation in the Category combo box. Then select Multithreaded DLL under the Use Run-time library option.

Select Preprocessor in the Category combo box. Add ,HOST to Preprocessor definitions and ..\..\include to Additional Include Directories.

Click on the Link tab and leave General selected in the Category combo box:

Enter ..\..\x86-win32\bin\wtxapp.exe under the Output file name option.

Add ..\..\x86-win32\lib\wtxapidll.lib at the end of the list of Object/library modules.

Click OK and go to the Build>Set Active Configuration. Select either the Debug or Release version.

You are now ready to start a target server and run your new application.

6.2.5 Testing the Application

UNIX Hosts

To test the application, call it from the Unix shell:

% wtxapp targetServer

Windows Hosts

To test the application, create a custom tool as follows:

Select the Customize option under the Tools menu.

Click Add and enter wtxApp under the Menu Text: option.

Enter one of the following lines under the Tool Command option, depending on whether you want to run the debug version or the release version:

wtxapp-d.exe targetServer@host 
wtxapp.exe targetServer@host

Fill in your working directory under the Working Directory option and select Redirect to Child Window.

Now click OK.

Select wtxApp from the Tools menu to run your application.

6.2.6 Creating Documentation

The man makefile rule permits the HTML documentation generation for the specified files.The wtxapp application code located in 4.5.6 Application Example can generate an example of documentation.

The DOC_FILES macro specifies which files are to be documented. The following excerpt from a makefile generates HTML documentation for the given files:

DOC_FILES               = wtxapp.c 
DOC_DIR                 = $(DOCS_ROOT)/tornado-app/wtxapp 
... 
DOCS                    = doc 
...

doc: $(DOC_FILES) 
$(WIND_BIN)/refgen $(REFGEN_OPT) -book Tornado_Applications \ 
    -chapter WTX_Applications -out $(DOC_DIR) $(DOC_FILES) 
$(WIND_BIN)/htmlLink $(DOC_DIR)

For the make man command to generate the documentation, the DOCS macro of the makefile must be set to the target doc.

CAUTION: The DOCS macro must appear in all the makefiles, or a make man (or rman) would build the application instead of building the doc.

In the makefile, the documentation is generated for the wtxapp.c file, and will belong to the book Tornado Applications, in the chapter WTX Applications. The directory where it is located is specified by the -out option of refgen.

6.3 Installing a New Application in Tornado

Tornado applications can be launched from the host command shell, as you did when testing this application. However, it is more convenient to launch them from the launcher (on UNIX hosts) or from the launch toolbar (on Windows hosts). The next sections explain how to install a new application.

6.3.1 The Tornado Launcher (UNIX Hosts)

Once the new Tornado application is working, you can add it to the Tornado launcher. To do this, install a Tcl resource file containing the command that adds a button to the launcher in the Launch directory. The name of this file is related to the application you are starting and is prefixed with "01" so that it will be sourced with other applications early in the initialization process. The complete path to the new resource file is:

installDir/host/resource/tcl/app-config/Launch/01Wtxapp.tcl.

The Tcl program shown in Example 6-2 uses the objectCreate command to create a new button in the Tornado launcher. This button is associated with the Tcl routine launchWtxapp that gets the name of the target server currently selected in the launcher target window and passes it as a parameter to wtxapp.

The second parameter of objectCreate is the name of a bitmap file to be displayed as an icon at the bottom of the launcher. Add the bitmap file to the resource bitmap directory for the launcher. In this example the complete path to the bitmap is installDir/host/resource/bitmap/Launch/objects/wtxapp. This file can be created with an icon editor like bitmap from the X11 distribution. For more information about objectCreate, see the online material under Tornado API Reference>GUI Tcl Library (UNIX).

Example 6-2: Install wtxapp in Launcher

# Wtxapp.tcl - simple wtx application support for launch 
# 
# modification history 
# -------------------- 
# 01a,25jul95,p_m  written 
#*/ 
 
# Add a wtxapp activation button to bottom of the launcher 
# The associated icon is the default icon (WRS logo) if there is not a 
# bitmap file called "wtxapp" in  
# installDir/host/resource/bitmaps/Launch/objects.  
 
objectCreate app wtxapp    wtxapp       {launchWtxapp}

######################################################################## 
# 
# wtxapp launch on selected target server 
#

proc launchWtxapp {} { 
    global env 
    global tgtsvr_selected 
    global tgtsvr_user 
    global tgtsvr_lock

    # check for a selected target server

    if {$tgtsvr_selected == ""} { 
        noticePost error "Select a target first." 
        return 
    }

    # check if target server is locked

    if {$tgtsvr_lock == "locked"} { 
        noticePost error "Target server locked by $tgtsvr_user." 
        return 
    }

    # check if we have access authorization on the selected target server 
 
    if {$tgtsvr_lock == "unauthorized"} { 
        noticePost error "Access not authorized." 
        return 
    } 
 
    exec wtxapp $tgtsvr_selected & 
}

6.3.2 The Launch Toolbar (Windows Hosts)

Once the new Tornado application is working, you can add it to the Tornado launch toolbar. To do this, install a Tcl resource file containing a command to add a button to the toolbar in the Tornado directory. The name of this file is related to the application you are starting and is prefixed with "01"so that it will be sourced with other applications early in the initialization process. The complete path to the new resource file is:

installDir\host\resource\tcl\app-config\Tornado\01Wtxapp.win32.tcl

The Tcl program shown in Example 6-3 uses the controlCreate command to create a new button in the Tornado launcher. This button is associated with the launchWtxapp Tcl routine that gets the name of the target server currently selected in the launcher target window and passes it as a parameter to wtxapp.

The -bitmap parameter of controlCreate is the name of a bitmap file to be displayed as an icon on the button. Add the bitmap file to the resource bitmap directory for the toolbar. In this example the complete path to the bitmap is installDir\host\resource\bitmaps\Launch\controls\wtxapp.bmp. This file can be created with an icon editor such as Microsoft Paintbrush. For more information about controlCreate see the online material under Tornado API Reference>GUI Tcl Library (Windows).

Example 6-3: Install wtxapp on Launch Toolbar

# Wtxapp.win32.tcl - simple wtx application support for launcher 
# 
# modification history 
# -------------------- 
# 01a, 05may96, j_k written 
#*/ 
 
# Add a wtxapp activation button to the launch toolbar 
# The associated bitmap will be the default bitmap (WRS logo) if 
# there is no bitmap file called "wtxapp" in 
# installDir/host/resource/bitmaps/Tornado, no bitmap appears 
 
set wtxappBitmap [wtxPath host resource bitmaps Tornado]Wtxapp.bmp 
controlCreate launch [list toolbarbutton -name wtxapp \ 
                    -callback launchWtxapp \ 
                    -tooltip "Launch Wtxapp" \ 
                    -bitmap $wtxappBitmap]

############################################################################ 
# wtxapp launch on selected target server 
# 
 
proc launchWtxapp {} { 
    global env 
 
    # first get the name of the selected target 
 
    set tgtsvr_selected [selectedTargetGet] 
        if {$tgtsvr_selected == ""} { 
            messageBox -stopicon "Select a target first." 
            return 
        } 
 
    # Then try to attach to the tool without any errors. 
    # If any, return the error to be displayed for the user. 
 
        if {[catch {wtxToolAttach $tgtsvr_selected wtxapp} attachRetVal]} { 
            messageBox -stopicon "Tool attach failed. $attachRetVal" 
            return 
        } 
 
    # Next try to get the target server information. 
    # If any errors, report to the user 
 
        if [catch "wtxTsInfoGet" info] { 
            if {[lindex $info 3] == "(SVR_TARGET_NOT_ATTACHED)"} { 
                wtxToolDetach 
                messageBox -stopicon "Target not attached" 
                return 
            } 
            messageBox -stopicon "Couldn't obtain target server infomation" 
            return 
        } 
 
    # If we get here, looks pretty good 
 
    set tgtsvr_user         [lindex $info 8] 
    set tgtsvr_lock         [lindex $info 11] 
 
    # Now check if target server is locked 
 
    if {$tgtsvr_lock == "locked"} { 
        messageBox -stopicon "Target server locked by $tgtsvr_user." 
        return 
    } 
 
    # Now check if we have access authorization on the selected target server 
 
    if {$tgtsvr_lock == "locked"} { 
        messageBox -stopicon "Access not authorized." 
        return 
    }

    # Finally since everything looks good lets launch the target server 
 
    if {[catch {toolLaunch "Wtxapp" "wtxapp $tgtsvr_selected" \ 
        $env(WIND_BASE)/host/x86-win32/bin 0 0 0 0 0 0} result]} { 
            puts "\nError: wtxapp launch failed: '$result'\n" 
        }

6.4 Distributing and Publishing New Applications

Users wishing to exchange applications and information with other users can find sources on the World Wide Web. The WRS Web page provides links to a range of subjects, including the Wind River Users Group. Browse the Web page for information on the public software archive, instructions for joining the mailing list "exploder," and information about users' group annual meetings. If you do not have access to the Internet, contact your sales representative.

Third parties developing Tornado-compatible products should contact their local Wind River Systems sales office directly or through e-mail (inquiries@wrs.com).