A downloadable application is a collection of relocateable object modules that can be downloaded and dynamically linked to VxWorks, and started from the shell or debugger. A downloadable application can consist of a single "hello world" routine or a complex application.

To create a downloadable application, you must:

1. Create a project for a downloadable application.

1. Write your application, or use an existing one.

1. Add the application files to the project.

1. Build the project.

You can then download the object module(s) to the target system and run the application.

All work that you do with the project facility, whether a downloadable application, a customized version of VxWorks, or a bootable application, takes place in the context of a project.

Open a project workspace by clicking the Project button in the Tornado Launch window. If the Create Project or Open Workspace window is open (the default when you first open the Tornado Project window¹ ), click the New tab. Then choose the selection for a downloadable application, and click OK (Figure 4-3)

Figure 4-3:  Create Downloadable Application

.

The application wizard appears (Figure 4-4). This wizard is a tool that guides you through the steps of creating a new project.

First, enter the full directory path and name of the directory you want to use for the project (only one project is allowed in a directory), and enter the project name. It is usually most convenient to use the same name for the directory and project, but it is not required.

	NOTE: You may create your projects anywhere on your file system. However, it is preferable to create them outside of the Tornado directory tree to simplify the process of future Tornado upgrades.

You may also enter a description of the project, which will later appear in the property sheet for the project. Finally, identify the workspace in which the project should be created. Click Next to continue.

Figure 4-4:  Application Wizard: Step One for Downloadable Application

Then you identify the toolchain with which the downloadable application will be built. You can do so by referencing an existing project, or by identifying a toolchain.

Basing a project on an existing one means that the new project will reference the same source files and build specifications as the one on which it was based. Once the new project has been created, its build specifications can be modified without affecting the original project, but changes to any shared source files will be reflected in both.

For example, to create a project that will run on the target simulator, select A toolchain and select the default option for the target simulator from the drop-down list (Figure 4-5).² Click Next.

Figure 4-5:  Application Wizard: Step Two for Downloadable Application

The wizard confirms your selections (Figure 4-6) Click Finish.

Figure 4-6:  Application Wizard: Step Three for Downloadable Application

The Workspace window appears, containing a folder for the project. Note that the window title includes the name of the workspace (Figure 4-7).

Figure 4-7:  Initial Workspace Window for a Downloadable Application

	NOTE: Context menus provide access to all commands that can be used with the objects displayed in, and the pages that make up, the Workspace window (use the right mouse button).

The project facility generates a set of files whose contents are based on your selection of project type, toolchain, build options, and build configurations. During typical use of the project facility you need not be concerned with these files, except to avoid accidental deletion, to check them in or out of a source management system, or to share your projects or workspaces with others. The files are created in the directories you identify for the workspace and project. The files initially created are:

projectName.wpj

Contains information about the project used for generating the project makefile.

workspaceName.wsp

Contains information about the workspace, including which projects belong to it.

Both of these files contain information that changes as you modify your project, and add projects to, or delete projects from, the workspace.

When you build your application, a makefile is dynamically generated in the main project directory, and a subdirectory is created containing the objects produced by the build. The subdirectory is named after the selected build specification. If other build specifications are created and used for other builds, parallel directories are created for their objects.

The Files view of the Workspace window displays information about projects, and the directories and files that make up each project (Figure 4-8).

Figure 4-8:  Workspace Files View

The first level of folders in the Files view are projects. Each project folder contains:

• Project source code files, which are added to the project by the user.

• An Object Modules folder, which contains a list of objects that the project's build will produce. The list is automatically generated by the project facility.

• An External Dependencies folder, which contains a list of make dependencies. The list is automatically generated by the project facility.

Initially, there are only the default folders for Object Modules and External Dependencies, and the projectName.out file. The file projectName.out is created as a single, partially-linked module when the project is built. It comprises all of the individual object modules in a project for a downloadable application, and provides for downloading them to the target simultaneously.

	WARNING: Use of the projectName.out file is essential for downloading C++ modules, which require munching for proper static constructor initialization. You should also use the projectName.out file for downloading C modules to avoid any potential link order issues related to dynamic loading and linking.

To create a new file, click File>New. Select the file type from the New dialog box. Then select the project to which the file should be added. Finally, enter the file name and directory, and click OK (Figure 4-9). The editor window opens, and you can write your code and save the file.

Figure 4-9:  New File Dialog Box

Add existing files to a project by right-clicking in the Workspace window, selecting Add Files or Add FIles from project from the context menu, and then using the associated dialog box to locate and select the file(s).

To link object files with your project, use the Linker page of the build specification property sheet (see Linker Options). To link library (archive) files with your project, add the libraries to the list defined by the LIBS macro in the Macros page of the build specification property sheet (see Makefile Macros).

Remove files from the project by right-clicking on the file name and selecting Remove from the context menu, or by selecting the file name and pressing DELETE.

	CAUTION: Adding a file to a project or removing a file from a project does not affect its existence in the file system. The project facility does not copy, move, or delete user source files; merely the project facility's references to them. Removing a file from one workspace context does not affect references to it in any others, nor its existence on disk. However, if a file is included in more than one project or workspace, an edit made in one context will be reflected in all (if this behavior is not desired, copy source files to another directory before adding them to a project).

To display information about the properties of a file, right-click on the file name in the Workspace window, and select Properties from the context menu. The extent of information displayed depends on the type of file and whether or not make dependencies have been generated. In the case of source code, a Properties sheet for the file appears, displaying information about make dependencies; general file attributes such as modification date; and the associated make target, custom dependencies, and commands used for the build process (Figure 4-10).

Figure 4-10:  Source File Property Sheet

See Calculating Makefile Dependencies, for information about how and when to calculate makefile dependencies. See Compiler Options for information about overriding default compiler options for individual files.

The File menu and context menu provides options for opening, saving, and closing files. You can also use standard Windows shortcuts (such as double clicking on a file name to open the file in the editor).

The project facility uses the GNU make utility to automate compiling and linking an application.³ It creates a makefile automatically prior to building the project. But before it can create a makefile, the makefile dependencies must be calculated. The calculation process, which is based on the project files' preprocessor #include statements, is also an automated feature of the project facility.

Binaries produced by a given build are created in a project subdirectory with the same name as the name of the build specification (projectName/buildName).

	NOTE: All source files in a project are built using a single build specification (which includes a specific set of makefile, compiler, and linker options) at a time. If some of your source requires a different build specification from the rest, you can create a project for it in the same workspace, and customize the build specification for those files. One project's build specification can then be modified to link in the output from the other project. See Linker Options.

	NOTE: The project facility allows you to create specifications for different types of builds, to modify the options for any one build, and to easily select the build specification you want to use at any given time. See 4.5 Working With Build Specifications.

To calculate makefile dependencies select Dependencies from the workspace context menu. The Dependencies dialog box appears (Figure 4-11). Click OK.

Figure 4-11:  Dependencies Dialog Box

After dependencies have been calculated, the files are listed in the External Dependencies folder (Figure 4-12).

Figure 4-12:  External Dependencies

 

If you do not calculate dependencies before you start a build, Tornado prompts you to do so for any project files for which dependencies were not previously calculated.

The Advanced option allows you to speed up the build process by specifying paths in which none of the dependencies could have changed since the last build. The timestamps for the files in the specified paths are not checked (Figure 4-13).

Figure 4-13:  Dependency Calculation Option

Each build for a downloadable application consists of a set of options for makefile rules and macros, as well as for the compiler, assembler, and linker. A default build specification is defined when you create your project. To display information about it, double-click on the build name in the Builds view of the workspace to display the property sheet for the build. The Rules page (Figure 4-14) allows you to select from the following build target options:

Figure 4-14:  Build Property Sheet

objects

Objects for all source files in the project.

archive

An archive (library) file.

projectName.out

A single, partially-linked and munched object that comprises all of the individual object modules in a project.

You can use the project facility to change the options for a given build, create and save new build specifications, and select the specification to use for a build. You can, for example, create one build specification for your project that includes debug information, and another that does not. For more information, see 4.5 Working With Build Specifications.

	NOTE: It is sometimes useful to build an application for the target simulator, and then to create a new build specification to build it for a real target.

To build a project with the default options, select the name of the project (or any subordinate object in its folder) and then select Build 'projectName.out' from the context menu. If you have created build specifications in addition to the default, you can select the build specification you want to use from the Build Spec drop-down list at the top of the workspace window before you start the build.

	WARNING: Tornado only calculates dependencies upon the first use of a file in a build. Once an initial set of dependencies has been calculated, Tornado does not attempt to detect changes in dependencies that may have resulted from modification of the file. If you have changed dependencies by adding or deleting #include preprocessor directives, you should regenerate dependencies.

The Build Output window displays build messages, including errors and warnings (Figure 4-15). Any compiler errors or warnings include the name of the file, the line number, and the text of the error or warning text.

Figure 4-15:  Build Output

	WARNING: The default compiler options include -g for debugging information. Using -g with the optimization option -O set to anything but zero may produce unexpected results. See 4.5 Working With Build Specifications for information about modifying builds and creating new build configurations.

To force a rebuild of all project objects, select Rebuild All from the context menu (which performs a make clean before the build).

Build Toolbar

The Build toolbar provides quick access to build commands. Display of the toolbar is controlled with the View>Build Toolbar menu option (Figure 4-16).

Figure 4-16:  Build Toolbar

The Build toolbar commands (Table 4-1) are also available from the main menus and the Workspace context menu.

Table 4-1:  Build Toolbar Buttons

Button		Menu		Description
		Build>Build		Build project.
		Build>Rebuild All		Rebuild project (performing a make clean first).
		Build>Compile		Compile selected source file.
		Build>Dependencies		Update dependencies.
		Project>Download		Download object file (or boot image for target simulator).

Before you can download and run an application, you must boot VxWorks on the target system, have access to a Tornado registry, and configure and start a target server. See 2. Setup and Startup and 3. Launcher for more information.

You can download an entire project from the project workspace by selecting Download 'projectName.out' from the context menu for the Files view, or by using the download button on the Build toolbar. You can download individual object modules by selecting the file name and then and the Download 'filename.o' option from the context menu. However, you may inadvertently introduce errors by downloading individual object modules out of sequence. We strongly recommend that you always download the partially-linked projectName.out file.

C++ projects should be downloaded as projectName.out because this file is produced from application files and munched for proper static constructor initialization.

To unload a project from the target, use the Unload 'projectName.out' option on the context menu.

New projects can be added to a workspace by selecting the menu options File>New Project and creating a new project when the workspace is open.

Existing projects can be added to a workspace by selecting File>Add Project to Workspace, and using the file browser to select a project file (projectName.wpj).

Projects can be removed from a workspace by selecting the project name in the Files view, and then selecting the Remove option from the context menu, or by selecting the project name and pressing DELETE.

	NOTE: When you remove a project, you only remove it from the workspace. The project directory and its associated files are not removed from disk.

1:  You can modify the default behavior by un-checking the Show this window on startup box at the bottom of the window.

2:  The default toolchain names for target simulators take the form SIMHOST_OSgnu (for example, SIMSPARCSOLARISgnu and SIMHPPAgnu).

3:  See the GNU Make User's Guide for more information about make.