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.

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.

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%.

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

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

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

1. Start Microsoft Visual C++ 5.0.

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

1. 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.

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

1. 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.

1. 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.

1. 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.

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

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

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

% wtxapp targetServer

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

1. Select the Customize option under the Tools menu.

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

1. 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

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

1. Now click OK.

1. Select wtxApp from the Tools menu to run your application.

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.