Vxworks: Command-Line Tools User'S Guide

VxWorks Command-Line Tools User's Guide, 6.
VxWorks
®
COMMAND-LINE TOOLS USER'S GUIDE
6.7
Copyright © 2008 Wind River Systems, Inc.
All rights reserved. No part of this publication may be reproduced or transmitted in any
form or by any means without the prior written permission of Wind River Systems, Inc.
Wind River, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc.
The Wind River logo is a trademark of Wind River Systems, Inc. Any third-party
trademarks referenced are the property of their respective owners. For further information
regarding Wind River trademarks, please see:
http://www.windriver.com/company/terms/trademark.html
This product may include software licensed to Wind River by third parties. Relevant
notices (if any) are provided in your product installation at the following location:
installDir/product_name/3rd_party_licensor_notice.pdf.
Wind River may refer to third-party documentation by listing publications or providing
links to third-party Web sites for informational purposes. Wind River accepts no
responsibility for the information provided in such third-party documentation.
Corporate Headquarters
Wind River Systems, Inc.
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.
toll free (U.S.): (800) 545-WIND

telephone: (510) 748-4100
facsimile: (510) 749-2010
For additional contact information, please visit the Wind River URL:
http://www.windriver.com
For information on how to contact Customer Support, please visit the following URL:
http://www.windriver.com/support
VxWorks Command-Line Tools User's Guide, 6.7
2 Dec 08
Part #: DOC-16305-ND-00
Contents
1 Overview ............................................................................................... 1
1.1 Introduction ............................................................................................................. 1
1.2 Related Documentation ....................................................................................... 2
2 Setting Environment Variables ........................................................... 5
2.1 Introduction ............................................................................................................. 5
2.2 Setting Environment Variables With wrenv ................................................... 6

Solaris and Linux ...................................................................................... 6
Windows .................................................................................................... 6
Setting Environment Variables Without Spawning a Shell ................ 6
2.3 How wrenv Works ................................................................................................. 7
2.4 wrenv Command Options .................................................................................... 8
3 Configuring and Building VxWorks .................................................... 11
3.1 Introduction ............................................................................................................ 11
3.2 Working With VxWorks Image Projects: VIPs ................................................ 12

3.2.1 Setting Environment Variables ............................................................... 12
iii
VxWorks
Command-Line Tools User's Guide, 6.7
3.2.2 Creating VxWorks Image Projects ........................................................ 12

Checking the Toolchain ........................................................................... 14
Copying VIPs ............................................................................................ 14
Using Profiles ............................................................................................ 15
3.2.3 Deleting VIPs ........................................................................................... 15
3.2.4 Modifying VIPs ........................................................................................ 16
Adding Components ............................................................................... 16
Removing Components ........................................................................... 17
Setting Configuration Parameter Values .............................................. 17
Changing the Project Makefile Name ................................................... 18
Adding and Removing Individual Application Files ......................... 18
3.2.5 Getting Information About VIPs ........................................................... 18
Listing Components ................................................................................. 18
Listing Bundles ......................................................................................... 19
Listing Profiles .......................................................................................... 19
Comparing Projects .................................................................................. 20
Checking a Component ........................................................................... 20
Checking Component Dependencies .................................................... 20
Listing Configuration Parameters and Values ..................................... 20
Listing the Source Files in a Project ....................................................... 21
3.2.6 Building VIPs ........................................................................................... 22
Build Specifications, Build Rules, and Image Types ........................ 22
Examining Build Specifications and Rules ........................................... 24
Changing Build Specifications ............................................................... 24
Adding and Changing Build Rules ....................................................... 25
Building VxWorks .................................................................................... 25
3.2.7 Example vxprj Session ............................................................................. 26
3.3 Working With VxWorks Source Build Projects: VSBs ................................... 26

3.3.1 Using VSB Projects: Basic Steps ............................................................. 27
3.3.3 Displaying BSP and CPU Options for VSB Projects ........................... 28
3.3.4 Creating VSB Projects ............................................................................. 28
3.3.5 Selecting VSB Options ............................................................................ 30
3.3.6 Reconfiguring a VSB Project ................................................................... 31
iv
Contents
3.3.7 Changing the CPU for a VSB Project .................................................... 32

3.3.8 Changing the BSP for a VSB Project ..................................................... 33
3.3.9 Building a VSB Project ............................................................................ 34
3.3.10 Deleting a VSB Project ............................................................................ 35
3.3.11 Using a VSB Project With a VxWorks Image Project .......................... 35
3.3.12 Identifying a VIP-VSB Association ....................................................... 35
3.3.13 Validating a VIP-VSB Association ........................................................ 36
3.4 Building Customized VxWorks Source Code .................................................. 36

3.4.1 Limitations and Restrictions ................................................................... 37
3.4.2 Third-Party Binary Files .......................................................................... 37
3.4.3 VxWorks Library Source Code and Archive Locations ...................... 37
3.4.5 Building Customized Kernel Source Code with VSB Projects .......... 38
3.4.6 Building With Make Directly .................................................................. 38
UP and SMP Kernel Build Commands ................................................. 39
User (RTP) Build Command ................................................................... 39
Building Compiler Intrinsics Libraries ................................................. 39
4 Building Kernel Applications and Libraries ...................................... 41
4.1 Introduction ........................................................................................................... 42
4.2 About Building Kernel Applications and Libraries ....................................... 42
4.3 Setting Environment Variables ............................................................................ 42
4.4 Using the VxWorks Build Environment ........................................................... 43
4.5 Example Makefile for a Kernel Application .................................................... 43
4.6 Setting CPU and TOOL Make Variables .......................................................... 44
4.7 Building Kernel Applications for UP, SMP, and VSB Variants .................... 45
4.7.1 Building Applications With Default VxWorks UP Libraries ............ 45
v
VxWorks
4.7.2 Building Applications With Default VxWorks SMP Libraries .......... 46

4.7.3 Building Applications With User-Configured Variant Libraries ...... 46
4.8 Linking Kernel Application Modules ............................................................... 47
4.9 Linking Kernel Application Modules With VxWorks ................................... 47
4.10 make Variables for Kernel Applications and Libraries ................................. 48
4.11 Running Kernel Applications ............................................................................. 49
5 Building RTP Applications and Libraries ........................................... 51
5.1 Introduction ............................................................................................................ 52
5.2 About Building RTP Applications and Libraries ............................................ 52
5.3 Setting Environment Variables ............................................................................ 53
5.4 Using the VxWorks Build Environment ........................................................... 53
5.5 Make Rules for RTP Applications and Libraries ............................................ 54
5.6 Setting CPU and TOOL Make Variables .......................................................... 54
5.7 Top-Level Makefile for Applications and Libraries ....................................... 54
5.8 Building RTP Libraries ......................................................................................... 55

5.8.1 Basic Library Makefile ............................................................................ 55
5.8.2 More Complex Library Makefile ........................................................... 56
5.8.3 Library Build Output ............................................................................... 57
5.8.4 Library Build Commands ....................................................................... 58
5.9 Building RTP Applications ................................................................................. 58

5.9.1 Basic Application Makefile for a Dynamic Executable ...................... 58
5.9.2 More Complex Application Makefile ................................................... 59
5.9.3 RTP Application Build Output ............................................................... 60
5.9.4 RTP Application Build Commands ....................................................... 60
vi
Contents
5.10 Using a Custom Build Environment .................................................................. 61

5.10.1 Generating PIC Object Modules ............................................................ 62
5.10.2 Generating the Shared Library ............................................................... 62
5.10.3 Generating the Application’s Object Modules ..................................... 63
5.10.4 Generating the Application Executable ................................................ 63
5.11 Compiler Options for Shared Objects and Dynamic RTP Applications .... 64
5.11.1 Options for Shared Objects ..................................................................... 64
5.11.2 Options for Dynamic RTP Application Executables ........................... 65
Identifying the Run-time Paths of Shared Libraries ........................... 65
5.12 Make Variables for RTP Applications and Libraries ..................................... 66
5.13 Running RTP Applications ................................................................................. 69
6 Configuring and Building VxWorks Using config.h .......................... 71
6.1 Introduction ............................................................................................................ 71
6.2 Using config.h to Configure VxWorks ............................................................... 72
6.3 Configuration Examples ....................................................................................... 73

6.3.1 Removing Network Support .................................................................. 73
6.3.2 Adding RTP Support ............................................................................... 73
6.4 Using make .............................................................................................................. 74

6.4.1 Makefile Details ........................................................................................ 74
Customizing the VxWorks Makefile ...................................................... 75
Commonly Used Makefile Macros ........................................................ 76
6.4.2 Building Custom Boot Loaders .............................................................. 79
Index .............................................................................................................. 81
vii
VxWorks
viii
1
Overview
1.1 Introduction 1
1.2 Related Documentation 2
1.1 Introduction
This guide describes how to use the command-line build environment provided
with VxWorks. It complements the Wind River Workbench by Example guide for
programmers who prefer to do development tasks outside of the Workbench
graphical interface or who need to create scripted build environments.
The Workbench IDE includes many features, such as code browsing, host-target
communication, and multicore debugging, that are not available from the
command line. For a complete description of the Workbench environment, see the
Wind River Workbench by Example guide, which also provides information about
setting up the host-target development environment.
For information about the VxWorks operating system and developing applications
that run under it, see the VxWorks Kernel Programmer’s Guide and VxWorks
Application Programmer’s Guide.
VxWorks ships with two compilers and associated toolchains: the Wind River
Compiler (sometimes called the Diab compiler) and GCC (part of the GNU
project). Both toolchains use the GNU make utility for VxWorks application
development. To the largest extent possible, these toolchains have been designed
1
VxWorks
for interoperability, but it is not always safe to assume that code written for one set
of tools will work perfectly with the other. While examples in this guide may use
either or both compilers, it is best to select one compiler and toolchain before
starting a project.
The Wind River Compiler and tools are documented in a separate user’s guide for
each supported target architecture. For example, information about the PowerPC
compiler is in the Wind River Compiler for PowerPC User’s Guide. GCC and the other
GNU tools are documented in a series of manuals from the Free Software
Foundation, which are provided with this release.
NOTE: Throughout this guide, UNIX refers to both Solaris and Linux host
development environments. Windows refers to all supported versions of Microsoft
Windows. Examples in this guide include both UNIX and Windows command
lines. It is assumed that the reader can make appropriate modifications—such as
changing forward slashes (/) to backward slashes (\)—depending on the
environment.
NOTE: For information about building the VxWorks networking and middleware
products that are delivered only in source code format, see the Wind River VxWorks
Platforms User’s Guide.
1.2 Related Documentation

The following guides provide information closely related to the topics covered in
this one:
■
Wind River Compiler guides
■
Wind River GNU guides
■
Wind River Workbench by Example guide
■
Wind River Project Configuration Command-Line Reference
■
VxWorks Kernel Programmer’s Guide
■
VxWorks Application Programmer’s Guide
■
VxWorks BSP Developer’s Guide
2
1 Overview
1.2 Related Documentation
■
VxWorks Device Driver Developer’s Guide
1
3
VxWorks
4
2
Setting Environment Variables
2.1 Introduction 5
2.2 Setting Environment Variables With wrenv 6
2.3 How wrenv Works 7
2.4 wrenv Command Options 8
2.1 Introduction
To use the command-line development environment for VxWorks, you need to
configure environment variables and other settings. The best way to do this is with
the Wind River environment utility, wrenv. The utility guarantees a consistent,
portable execution environment for tools (such as make) that are launched from
Wind River Workbench or from a command-line automation environment such as
the VxWorks Development Shell. The wrenv utility also provides services that
other tools can use to query environment settings that are set by wrenv.
Throughout this guide, whenever host operating system commands are shown or
described, it is assumed that you are working from a properly configured shell
created with wrenv.
5
VxWorks
2.2 Setting Environment Variables With wrenv

Assuming a standard product installation, you can invoke wrenv as described
below for Solaris, Linux, and Windows.
Solaris and Linux
On Solaris and Linux, you must set the environment variables whether you use
Workbench or the command line. In your installation directory, run the following
command in a shell:
% ./wrenv.sh -p vxworks-6.x
NOTE: If your shell configuration file (.profile, .cshrc, .tcshrc, and so forth)
overwrites the environment each time a new shell is created, the above command
may not work. To test whether the environment variables have been set
successfully, start Workbench. If you find that you cannot start the Workbench
tools after running the above command, use the following command:
% eval `installDir/wrenv.sh -p platform -o print_env -f shell`
where shell is sh or csh, depending on the current shell program. For example:
% eval `./wrenv.sh -p vxworks-6.x -o print_env -f sh`
Windows
If you use the VxWorks Development Shell, environment variables are set
automatically. To start the shell, select
Start > All Programs > Wind River > VxWorks 6.x and
General Purpose Technologies > VxWorks Development Shell.
You can also invoke wrenv from the command prompt, as follows:
C:\> installDir\wrenv.exe -p vxworks-6.x
Setting Environment Variables Without Spawning a Shell
In some cases, it is not desirable to start a shell—for example, when you are using
scripting to set the environment on a host, or when you cannot start a shell because
your .cshrc or .profile file overrides PATH or other variables whenever a shell is
started.
6
2 Setting Environment Variables
2.3 How wrenv Works
In these cases, the following command can be used to output the environment
variables to standard out:
2
On Linux and Solaris hosts:
% wrenv.sh –p vxworks-6.x –o print_env –f format
On Windows hosts:
C:\> wrenv.exe -p vxworks-6.x print_env -f format
In this example, format specifies the output format or shell type, which can be set
to plain, sh, csh, bat, or tcl.
For example, to set the environment in csh on a Linux or Solaris host without
starting a sub-shell, use the following command:
% eval 'wrenv.sh –p vxworks-6.x –o print_env –f csh'
Or, to set the environment in tcl on a Windows host without starting a sub-shell,
use the following command:
For example, to set the environment in tcl without starting a sub-shell, use the
following command:
C:\> eval 'wrenv.exe –p vxworks-6.x –o print_env –f tcl'
2.3 How wrenv Works

The wrenv utility uses the installation properties file install.properties, which
consolidates information about installed package components in a single location,
including the information needed for environment settings. A package component
is an independent software entity (package) that interacts with the other package
components that have bee installed. Examples include large packages such as
Workbench, to a small Platform facility.
The install.properties file is dynamically created at product installation time by a
script that aggregates the package property files (package.properties) that
accompany each installed package. The install.properties file is independent of
host platform and provides information to help enforce correct environment
setting dependencies across multiple installed component packages (such as
Wind River Workbench, Wind River VxWorks Platforms, documentation, and test
packages).
7
VxWorks
! CAUTION: Do not edit the install.properties installation properties file.
2.4 wrenv Command Options

The wrenv utility provides several options, summarized in Table 2-1, that can be
useful in complex build environments. For most purposes, -p is the only option
you need. The syntax for a wrenv command is as follows:
On Linux and Solaris hosts:
% wrenv options env=value command [args]
On Windows hosts:
C:\> wrenv.exe options env=value command [args]
Table 2-1 Options for wrenv
Option Meaning Example
-e Do not redefine existing environment variables. % wrenv.sh -p vxworks-6.x -e

(Variables identified with addpath in
install.properties are still modified.)
-f format Select format for print_env or print_vars (see -o): C:\> wrenv -p vxworks-6.x -o
print_vars -f sh
plain (the default)
sh
csh
bat
tcl
-i path Specify the location of install.properties. % wrenv.sh -p vxworks-6.x -i

directoryPath/install.properties
(Overrides the default method of finding
install.properties.)
8
2 Setting Environment Variables
2.4 wrenv Command Options
Table 2-1 Options for wrenv (cont’d)
Option Meaning Example 2

-o operation Select operation:
run C:\> wrenv -p vxworks-6.x -o

run
The default operation. Configures the
environment and creates a command shell % wrenv.sh -p vxworks-6.x -o
in which subsequent commands are run
executed. Checks the value of SHELL
(usually defined under UNIX) to
determine which shell program to invoke;
if SHELL is not defined, it checks ComSpec
(Windows).
print_varsa C:\> wrenv -o print_vars

Show environment settings that would be
made if wrenv were invoked with -o run.
print_enva % wrenv.sh -o print_env

Like print_vars, but shows only variables
that are exported to the system
environment. (Such variables are identified
with export or addpath, rather than
define, in install.properties.)
print_packagesa C:\> wrenv -o print_packages

List the packages defined in
install.properties and their attributes. (The
displayed name of a package can later be
specified with the -p option.)
print_compatiblea % wrenv.sh -p vxworks-6.x -o

print_compatible
Use with -p. Show the list of packages
defined in install.properties as compatible
with the specified package. Helpful for
determining which IDE version works
with a given target OS platform.
print_package_namea C:\> wrenv -r directory -o

Use with -r. Show the name of the package print_package_name
in the specified root directory.
9
VxWorks
Table 2-1 Options for wrenv (cont’d)
Option Meaning Example
-p package Specify a package (a set of Workbench components) % wrenv.sh -p vxworks-6.x

for environment initialization. The package must
be defined in install.properties.
-r root Specify the root path for a package. (Overrides the C:\> wrenv -p vxworks-6.x -r
default method of finding packages.) Usually, the directory
root path is a directory under installDir that has the
same name as the package.
-v Verbose mode. Show all altered environment % wrenv.sh -p vxworks-6.x -v

settings.
env=value Set the specified variable in addition to other C:\> wrenv -p vxworks-6.x
PATH=directory
environment settings. Overrides
install.properties.b env=value must be the last item
on the command line, except for command [args] (see
below).
command Execute the specified command in the new shell % wrenv.sh -p vxworks-6.x ls
[args] environment. (Does not open a new shell.) Must be *.sh
the last item on the command line.
a. These operations are primarily for internal use and may change in later releases.
b. Once a setting has been overridden with this option, wrenv maintains the override on subsequent
executions—even if the option is omitted from the command line—as long as the new shell is running. A
list of overridden settings is stored in a temporary variable called WIND_PROTECTED_ENV that
disappears when the shell terminates.
10
3
Configuring and Building
VxWorks
3.1 Introduction 11
3.2 Working With VxWorks Image Projects: VIPs 12
3.3 Working With VxWorks Source Build Projects: VSBs 26
3.4 Building Customized VxWorks Source Code 36
3.1 Introduction
VxWorks is a highly scalable operating system that can be configured and
customized in a variety of ways. VxWorks image projects (VIPs) allow for
configuring a system with selected standard components that provide default
libraries. VIPs also provide configuration parameters for modifying the behavior
of individual components. VxWorks Source Build projects (VSBs) provide options
that allow for creating systems based on variants of standard libraries and other
optimizations. In addition, VxWorks source code itself can be directly customized
(edited), and the libraries rebuilt. The vxprj tool and the VxWorks build
environment provide the means for most of the configuration and build activities
involved with these approaches to configuring and customizing operating system.
NOTE: For information about building the VxWorks networking and middleware
products that are delivered only in source code format, see the Wind River VxWorks
Platforms User’s Guide.
11
VxWorks
3.2 Working With VxWorks Image Projects: VIPs

A VxWorks image project (VIP) is used to create a version of VxWorks based on
components (which are defined by component description files, or CDFs). By
default a VIP makes use of the standard VxWorks libraries that are delivered in
binary format in the VxWorks installation. A VIP can also be based on a VxWorks
source build (VSB) project, which produces custom library binaries based on the
selection of source-based feature options (see 3.3 Working With VxWorks Source
Build Projects: VSBs, p.26).
NOTE: This section provides an overview of the vxprj functionality that you use to
create and work with VIPs.
For a complete description of vxprj and all of its options, see the vxprj reference
entry in the Wind River Project Configuration Command-Line API Reference. In
addition you may use the help provided by the tool itself, with the following
syntax:
vxprj help
vxprj featureName help
where help for featureName is available for certain elements, such as build,
buildmacro, component, and so on.
3.2.1 Setting Environment Variables
Environment variables are set automatically if you are using the VxWorks
Development Shell on Windows. Otherwise you must use the wrenv utility to set
them. For more information, see 2.2 Setting Environment Variables With wrenv, p.6.
3.2.2 Creating VxWorks Image Projects
The command-line vxprj utility creates a project based on an existing board support
package (BSP).1 The syntax for creating a VIP is as follows:
vxprj create [-smp] [-profile profile] [-vsb vsbdir] BSP tool [projectFile|projectDirectory]
For example:
C:\>vxprj create -profile PROFILE_DEVELOPMENT mv5100 diab c:\mv5100VIP
1. For information about BSPs, see the VxWorks BSP Developer’s Guide.
12
3 Configuring and Building VxWorks
The options listed above are as follows:

-smp
An optional argument that specifies an SMP configuration of VxWorks (that is,
3
one that uses SMP-specific libraries). The vxprj tool verifies that the specified
BSP supports an SMP configuration, and generates an error if not. For
example,
C:\>vxprj create -smp mv5100 diab c:\scratch\mv5100VIP
Exception while creating project : "option SMP not installed"
Note that if the VIP is based on an SMP VxWorks source build (VSB) project
(see -vsb vsbdir, p.13), and -smp is not specified when the VIP is created, the
VIP inherits the SMP specification from the VSB project anyway. For
information about VSB projects, see 3.3 Working With VxWorks Source Build
Projects: VSBs, p.26 and the VxWorks Kernel Programmer’s Guide: Kernel Facilities
and Kernel Configuration.
-profile profile
An optional argument to specify the kernel profile type to be built. If you do
not specify a profile, the project is built according to the default profile that is
defined for your BSP. For information on profiles, see Using Profiles, p.15, and
the VxWorks Kernel Programmer’s Guide.
-vsb vsbdir
An optional argument that specifies a VxWorks source build (VSB) project on
which to base the VIP. Essentially, it points to a variant set of libraries instead
of the default VxWorks libraries provided in the VxWorks installation. For
detailed information about VSBs, see 3.3 Working With VxWorks Source Build
Projects: VSBs, p.26 and the VxWorks Kernel Programmer’s Guide: Kernel Facilities
and Kernel Configuration.
BSP
The name or location of a BSP.
tool
A supported compiler (usually diab or gnu). See Checking the Toolchain, p.14
for information about determining valid compilers for a given BSP.
projectFile|projectDirectory
An optional argument to specify the name of the project file to create, or the
name of its parent directory. If no filename or directory is specified, vxprj
generates a name based on the other input arguments and stores the resulting
project in a new directory under installDir/vxworks-6.x/target/proj.
13
VxWorks
If you do not have a target board for your application, the easiest way to
experiment with vxprj is to create projects for the VxWorks Simulator. For
example:
C:\> vxprj create simpc diab C:\myProj\myproj.wpj
This command creates a kernel configuration project to be built with the Wind
River compiler (diab) and run on the VxWorks Simulator for Windows (simpc).
The project file (myproj.wpj), source files, and makefile are stored in C:\myProj.
To generate a similar project for Solaris or Linux hosts, specify solaris or linux as
the BSP, type the following:
% vxprj create solaris diab /myProj/myproj.wpj
$ vxprj create linux diab /myProj/myproj.wpj
(For more information about the VxWorks Simulator, see the Wind River VxWorks
Simulator User’s Guide.)
The following command creates a project in the default location using the
wrSbcPowerQuiccII (PowerPC) board support package:
% vxprj create wrSbcPowerQuiccII diab
When you execute this command, vxprj creates a subdirectory for the new project
and reports the location of directory.
Checking the Toolchain
You can use vxprj to check the valid toolchains for a BSP using the following
syntax:
vxprj tccheck list bspName
For example:
% C:\WindRiver>vxprj tccheck list mv5100
diab gnu
Copying VIPs
To copy an existing project to a new location, type the following:

vxprj copy [sourceFile] destinationFile|destinationDirectory
If no source file is specified, vxprj looks for a .wpj file in the current directory. If a
destination directory—but no destination filename—is specified, vxprj creates a
project file with the same name as the directory it resides in. For example:
14
% vxprj copy myproj.wpj /New
This command copies myproj.wpj and associated files to /New/New.wpj.
3
Using Profiles
A profile is a defined set of components that provides a kernel configuration

designed for a specific purpose. For example, PROFILE_DEVELOPMENT includes
a variety of standard development and debugging tools. The following command
creates a PROFILE_DEVELOPMENT-based project in the default location using the
wrSbcPowerQuiccII BSP:
% vxprj create -profile PROFILE_DEVELOPMENT wrSbcPowerQuiccII diab
The profile affects only the components used to create the project: after creation,
the project does not retain any information about the profile used to create it.
For a description of profiles, see the VxWorks Kernel Programmer’s Guide.
3.2.3 Deleting VIPs
To delete a project, type the following:

vxprj delete projectFile
where projectFile is the .wpj file associated with the project. The delete command
permanently deletes the directory in which projectFile resides and all of its contents
and subdirectories. (Do not run the command from the project directory you are
trying to remove.) For example:
% vxprj delete /myProj/myproj.wpj
This command deletes the entire myProj directory.
! CAUTION: vxprj delete removes any file passed to it, regardless of the file’s name
or extension, along with the entire directory in which the file resides. It does not
verify that the specified file is a Workbench project file, nor does it attempt to save
user-generated files.
15
VxWorks
3.2.4 Modifying VIPs
Adding Components
To add components to a kernel configuration project, type the following:

vxprj component add [projectFile] component [component ... ]
If no project file is specified, vxprj looks for a .wpj file in the current directory and
adds the specified components to that file. Components are identified by the
names used in .wpj and .cdf files, which have the form INCLUDE_xxx. For
example:
% cd MyProject
% vxprj component add INCLUDE_MMU_BASIC INCLUDE_ROMFS
This command adds support for a memory management unit and the ROMFS
target file system to MyProject.wpj.
For information about listing components, see Listing Components, p.18.
Adding Bundles
Some components are grouped into bundles that provide related or complementary
functionality. Adding components in bundles is convenient and avoids unresolved
dependencies.
To add a bundle to a project, type the following:
vxprj bundle add [projectFile] bundle [bundle ... ]
For example:
% cd MyProject
% vxprj bundle add BUNDLE_RTP_DEVELOP
This command adds process (RTP) support to the VIP in the current working
directory.
% vxprj bundle add MyProject.wpj BUNDLE_RTP_DEVELOP
BUNDLE_STANDALONE_SHELL BUNDLE_POSIX BUNDLE_EDR
This command adds support for processes, the kernel shell, POSIX, and error
detection and reporting to MyProject.wpj.
For information about listing bundles, see Listing Bundles, p.19.
16
Removing Components
To remove components from a VIP, type the following:

vxprj component remove [projectFile] component [component ... ] 3
If no project file is specified, vxprj looks for a .wpj file in the current directory. For
example:
% cd MyProject
% vxprj component remove INCLUDE_MMU_BASIC INCLUDE_DEBUG
This command removes the specified components as well as any components that are
dependent on them.
Removing Bundles
To remove a bundle, use the following syntax:

vxprj bundle remove [projectFile] bundle [bundle ... ]
Setting Configuration Parameter Values
To set the value of a configuration parameter, type the following:

vxprj parameter set [projectFile] parameter value
example:
% vxprj parameter set MyProject.wpj VM_PAGE_SIZE 0x10000
This command sets VM_PAGE_SIZE to 0x10000. (To list a project’s configuration

parameters, see Listing Configuration Parameters and Values, p.20.)
Parameter values that contain spaces should be enclosed in quotation marks. If a
parameter value itself contains quotation marks, they can be escaped with \
(Windows) or the entire value surrounded with ’...’ (UNIX). An easier way to set
parameter values that contain quotation marks is to use setstring, which tells vxprj
to treat everything from the space after the parameter argument to the end of the
command line as a single string. For example:
% vxprj parameter setstring SHELL_DEFAULT_CONFIG "LINE_LENGTH=128"
This command sets SHELL_DEFAULT_CONFIG to the following (including the

quotation marks):
"LINE_LENGTH=128"
To reset a parameter to its default value, type the following:
17
VxWorks
vxprj parameter reset [projectFile] parameter [parameter ... ]
Changing the Project Makefile Name
To change the name of a project’s makefile, type the following:

vxprj makefile [projectFile] newMakefileName
example:
% vxprj makefile make.rules
This command changes the name of the makefile (for the project in the current
working directory) from the default Makefile to make.rules.
Adding and Removing Individual Application Files
To link a kernel application with the VxWorks kernel image, the source file must
be added to the project. To add a specific source code file to a VIP, type the
following:
vxprj file add [projectFile] sourceFile
If no project file is specified, vxprj looks for a .wpj file in the current directory.
When the project is built, the specified source file is compiled and linked into the
resulting kernel image.
To remove a file from a project, type the following:
vxprj file remove [projectFile] sourceFile
For information about configuring VxWorks to start kernel applications at boot

time, see the VxWorks Kernel Programmer’s Guide.
For information about linking kernel applications with VxWorks using a make
command directly, see 4.9 Linking Kernel Application Modules With VxWorks, p.47.
3.2.5 Getting Information About VIPs
Listing Components
To see a list of components, type the following:

vxprj component list [projectFile] [type] [pattern]
18
If no project file is specified, vxprj looks for a .wpj file in the current directory. If
pattern is specified, vxprj lists only components whose names contain pattern as a
substring; if pattern is omitted, all components are listed.
The type argument can be all, included, excluded, or unavailable. The default is 3
included, which lists components included in the project. Specify excluded to list
installed components that are not included in the project; all to list all installed
components; or unavailable to list components that are installed but not available
for the project. (An available component is one that is installed, with all its
dependent components, under the VxWorks directory.)
For example:
% vxprj component list MyProject.wpj SHELL
This command returns all components in MyProject.wpj whose names

contain “SHELL”, such as INCLUDE_SHELL_BANNER and
INCLUDE_RTP_SHELL_C.
% vxprj component list MyProject.wpj excluded VM
This command returns all available components with names containing “VM”
that are not included in MyProject.wpj.
Listing Bundles
To see a list of bundles, type the following:

vxprj bundle list [projectFile] [type] [pattern]
For type and pattern, see Listing Components, p.18.

To see the components and other properties of a bundle, type the following:
vxprj bundle get [projectFile] bundle
Listing Profiles
To see a list of profiles, type the following:

vxprj profile list [projectFile] [pattern]
For pattern, see Listing Components, p.18.

To see the components and other properties of a profile, type the following:
vxprj profile get [projectFile] profile
19
VxWorks
Comparing Projects
To compare the components in two projects, type the following:

vxprj component diff [projectFile] projectFile|directory
If only one project file or directory is specified, vxprj looks for a .wpj file in the
current directory and compares it to the specified project. For example:
% vxprj component diff /Apps/SomeProject.wpj
This command compares the components included in /Apps/SomeProject.wpj to

those included in the project in the current working directory. It returns a list of the
unique components in each project.
Checking a Component
To verify that components are correctly defined, type the following:

vxprj component check [projectFile] [component ... ]
no component is specified, vxprj checks every component in the project. For
example:
% vxprj component check MyProject.wpj
This command invokes the cmpTest routine, which tests for syntactical and
semantic errors.
Checking Component Dependencies
To generate a list of component dependencies, type the following:

vxprj component dependencies [projectFile] component [component ... ]
example:
% vxprj component dependencies INCLUDE_OBJ_LIB
This command displays a list of components required by INCLUDE_OBJ_LIB.
Listing Configuration Parameters and Values
To list a project’s configuration parameters, type the following:
20
vxprj parameter list [projectFile] [pattern]
pattern is specified, vxprj lists only parameters whose names contain pattern as a
substring; if pattern is omitted, all parameters are listed. For example: 3
% vxprj parameter list MyProject.wpj TCP
This command lists all parameters defined in MyProject.wpj whose names

contain “TCP”, such as TCP_MSL_CFG.
To list a project’s parameters and their values, type the following:
vxprj parameter value [projectFile] [Namepattern [valuePattern]]
namePattern is specified, vxprj lists only parameters whose names contain
namePattern as a substring; if valuePattern is specified, vxprj lists only parameters
whose values contain valuePattern as a substring. For example:
% vxprj parameter value
% vxprj parameter value USER TRUE
The first command lists all parameters and values for the project in the current
directory. The second lists only parameters whose names contain “USER” and
whose values contain “TRUE”.
Comparing Parameters in Different Projects
To compare the configuration parameters of two projects, type the following:

vxprj parameter diff [projectFile] projectFile|directory
If only one project file or directory is specified, vxprj looks for a .wpj file in the
current directory and compares it to the specified project. For example:
% vxprj parameter diff /MyProject/MyProject.wpj /Apps/SomeProject.wpj
This command compares the parameters in MyProject.wpj to those in

SomeProject.wpj and returns a list of unique parameter-value pairs for each
project.
Listing the Source Files in a Project
To list a project’s source code files, type the following:

vxprj file list [projectFile] [pattern]
21
VxWorks
pattern is specified, vxprj lists only files whose names contain pattern as a substring;
otherwise, all files are listed.
To see build information for a source code file, type the following:
vxprj file get [projectFile] sourceFile
3.2.6 Building VIPs
A VxWorks image project includes build rules based on the format used in
makefiles. Projects also include build specifications, which organize and configure
build rules.
A build specification defines variables passed to make and flags passed to the
compiler. Each project has a current build specification, initially defined as default.
The build specifications that are available for a given project depend on the type of
project and BSP, but a typical project might have four build specifications: default,
default_rom, default_romCompress, and default_romResident.
Build Specifications, Build Rules, and Image Types
You must use an appropriately paired build specification and build rule to create
a specific VxWorks image type (the names of the build rules and images are the
same).
! CAUTION: The build specification and build rule must match. If they do not match,
in most cases the build will simply fail; in other cases, linkage occurs but the build
output will be inconsistent.
The common build specifications, build rules, image types, and their association
are described in Table 3-1.
Table 3-1 VxWorks Build Specifications, Build Rules, and Image Types
Build Specifications Build Rules and Image Types
default vxWorks[.bin | .hex]
default_rom vxWorks_rom[.bin | .hex]
22
Table 3-1 VxWorks Build Specifications, Build Rules, and Image Types (cont’d)
Build Specifications Build Rules and Image Types
default_romCompress vxWorks_romCompress[.bin | .hex] 3

default_romResident vxWorks_romResident[.bin | .hex]
For more information about VxWorks image types, see the VxWorks Kernel
Programmer’s Guide.
Displaying Build Specification Options
To display the available build specifications, use the build list option for vxprj in the
project directory. For example:
C:\workspace\myVip>vxprj build list
default
default_rom
default_romCompress
default_romResident
To determine what build rules are available for your BSP, use the buildrule list
option for vxprj in the project directory. For example:
C:\workspace\myVip>vxprj buildrule list
vxWorks
linkSyms.o
prjConfig.o
romInit.o
romStart.o
sysALib.o
sysLib.o
vxWorks_rom
vxWorks_rom.bin
vxWorks_rom.hex
vxWorks_romCompress
vxWorks_romCompress.bin
vxWorks_romCompress.hex
vxWorks_romResident
vxWorks_romResident.bin
vxWorks_romResident.hex
For more on getting information about build specifications, see Examining Build
Specifications and Rules, p.24.
23
VxWorks
Setting a Build Specification
Before you build VxWorks, you must first use the following command to set the
build specification if you are not going to use the default:
vxprj build set buildSpecification
For example:
vxprj build set default_rom
For more information about changing build settings, see Changing Build
Specifications, p.24.
Examining Build Specifications and Rules
To see the name of the current build specification, type the following:
vxprj build get [projectFile]
If no project file is specified, vxprj looks for a .wpj file in the current directory. To
see all available build specifications for a project, type the following:
vxprj build list [projectFile]
To see all the build rules in a project’s current build specification, type the
following:
vxprj buildrule list [projectFile]
To examine a build rule in a project’s current build specification, type the

following:
vxprj buildrule get [projectFile] buildRule
For example:
% vxprj buildrule get prjConfig.o
This command displays the prjConfig.o build rule.
Changing Build Specifications
To change a project’s current build specification, type the following:

vxprj build set [projectFile] buildSpecification
example, the following command changes the current build specification of
myproj.wpj to default_romCompress:
24
% vxprj build set myproj.wpj default_romCompress
To reset a project’s current build specification to its default, type the following:
vxprj build reset [projectFile]
3
The set and reset commands update a project’s makefile as well as its .wpj file.
Adding and Changing Build Rules
The commands documented below edit project makefiles and .wpj files.
To add a build rule to a project’s current build specification, type the following:
vxprj buildrule add [projectFile] buildRule value
example:
% vxprj buildrule add default_new "$(CC) $(CFLAGS) ./prjConfig.c -o $@"
This command creates a build rule (if it doesn’t already exist) called default_new,
adds it to the current build specification, and sets its value to
$(CC) $(CFLAGS) ./prjConfig.c -o $@.
To create or edit a build rule without including it in the project’s current build
specification, type the following:
vxprj buildrule set [projectFile] buildRule value
Rules created with set are added to the list of available build rules for the current
build specification.
To remove a build rule from a project, type the following:
vxprj buildrule remove [projectFile] buildRule
To set the default build rule for the current build specification, type the following:
vxprj buildrule [projectFile] buildRule
For example:
% vxprj buildrule default_new
Building VxWorks
Then to build VxWorks, use the following command:

vxprj build [projectFile] [buildSpecification|buildRule]
25
VxWorks
the second argument is omitted, vxprj uses the project’s current build
specification. Output from the compiler is saved in a subdirectory—with the same
name as the build specification—under the project’s source directory. Two
examples are as follows:
% vxprj build
% vxprj build myproj.wpj default_rom
The first command builds the project found in the current directory using the
project’s current build specification. The second command builds the project
defined in myproj.wpj using the default_rom build specification.
3.2.7 Example vxprj Session
The following sample vxprj session creates an SMP kernel for the pcPentium4 BSP
using the diab compiler in the directory pcPentium4_diab (relative to the current
directory). In addition to the basic operations of creating and building the project,
this example demonstrates the addition of bundles, components, and build
macros.
% vxprj create -smp pcPentium4 diab pcPentium4_diab
% cd pcPentium4_diab
% vxprj bundle add pcPentium4_diab.wpj BUNDLE_STANDALONE_SHELL
% vxprj bundle add pcPentium4_diab.wpj BUNDLE_RTP_DEVELOP
% vxprj bundle add pcPentium4_diab.wpj BUNDLE_POSIX
% vxprj component add pcPentium4_diab.wpj INCLUDE_HRFS
% vxprj component add pcPentium4_diab.wpj INCLUDE_HRFS_FORMAT
% vxprj component add pcPentium4_diab.wpj INCLUDE_RAM_DISK
% vxprj parameter setstring RAM_DISK_DEV_NAME /hrfs0
% vxprj buildmacro add ROMFS_DIR
% vxprj buildmacro set ROMFS_DIR ./romfs
% vxprj build pcPentium4_diab.wpj
3.3 Working With VxWorks Source Build Projects: VSBs

You can use a VxWorks source build (VSB) project to create specialized (and
frequently smaller) variants of VxWorks libraries, and to employ optimizations.
The libraries are conditionally compiled based on user selection of various options.
In some cases, the libraries produced with a VSB project provide a subset of the
26
APIs provided with standard VxWorks components. In order to make use of the
variant libraries and optimizations in a VxWorks system, you must create a
VxWorks image project (VIP) and associate it with the VSB project. Then use the
VIP to configure the system itself.
3
For a general discussion of VSB projects, as well as the core OS VSB options, see the
VxWorks Kernel Programmer’s Guide. For information about other VSB options, see
the relevant programmer’s guides for the technology in question and the Platform
user’s guide. You can also use Workbench or vxprj to list the VSB options available
with your installation.
For basic tool commands, see the vxprj entry in the Wind River Project Configuration
Command-Line API Reference; and from the command-line, use the vxprj vsb help
command.
NOTE: VSB projects can only be used to create variants of kernel libraries. They
cannot be used to create variants of user (RTP) libraries.
NOTE: The standard VxWorks libraries are built using a VSB project with the
default options.
! CAUTION: Kernel applications that are intended for use with systems based on
VSB projects must be built specifically for those configurations of VxWorks. For
information in this regard, see 4.7 Building Kernel Applications for UP, SMP, and VSB
Variants, p.45.
3.3.1 Using VSB Projects: Basic Steps
Using VSB projects to configure and build VxWorks involves the following basic
steps:
1. Create a VSB project, select the desired VSB options, and then build the project
to create specialized variants of VxWorks libraries and utilize other
optimizations.
2. Create a VxWorks image project (VIP) based on the VSB project.
3. Using the VIP, configure VxWorks in the standard way with the desired
components, and then build the project to create a system image based on the
specialized library variants.
27
VxWorks
The following sections describe how to perform the first two steps of this process.
For information about the third, see 3.2 Working With VxWorks Image Projects: VIPs,
p.12.
3.3.3 Displaying BSP and CPU Options for VSB Projects
VSB projects can be based on a BSP or CPU type. The advantage of basing a VSB
on a BSP is that the build is optimized for that BSP, providing better performance
and smaller code size. The advantage of basing a VSB on a CPU type is that the
project can be used for all BSPs that support that CPU.
To get a list of the CPU classes available for your project, use the following
command:
vxprj vsb listCpus
To get a list of available BSPs, use one of the following commands:

vxprj vsb listBsps
vxprj vsb listBsps cpuName
The first lists all available BSPs and the second lists only those that support the
specified CPU.
To get a list of BSPs that are supported by an existing project, use the following
command in the VSB project directory:
vxprj vsb listSupportedBsps
3.3.4 Creating VSB Projects
The syntax for creating a VSB project is as follows:

vxprj vsb create [-force] {[-bsp bsp|bspdir]|[-cpu cpuName]} [vsbfile|vsbdir][-D defFile|-S]
The options listed above are as follows:
28
-force
Deletes the VSB project directory first, if it already exists. If you do not use this
option, and the project file exists, then a new project directory is created
automatically using the original project directory name with _2 appended (for
3
example, myVsb_2). Additional directories are created and the number
incremented if this process is repeated.
-bsp bsp|bspdir
The name or location of the BSP on which to base the project. Use either -bsp
or -cpu, not both. For example, pcPentium or
installDir/vxworks-6.x/target/config/pcPentium. See 3.3.3 Displaying BSP and
CPU Options for VSB Projects, p.28.
-cpu cpuName
The name of the CPU class on which to base the VSB. Use either -bsp or -cpu,
not both. See 3.3.3 Displaying BSP and CPU Options for VSB Projects, p.28.
vsbfile
A VSB project file name (for example, /home/xeno/myVsb/myVsb.wpj). If this
option is used without -force, and the project file exists, then a new project
directory is created using the original project directory name with _2
appended; for example, myVsb_2. Additional directories are created and the
number incremented if this process is repeated.
vsbdir
The directory path for the VSB project. If you do not specify a project directory
at creation time, the project directory is automatically created below the one in
which the command is executed. The name in this case is based on a prefix
vsb_ plus the BSP or CPU name, depending on which was used for project
creation (for example, vsb_PPC32). If you use this option with -force to remove
an existing project before creating one of the same name, use vsbdir to specify
a directory containing the VSB project file. For example, /home/xeno/myVsb/,
which would hold myVsb.wpj.
-D defFile
Create a VSB project based an existing VSB project configuration file (for
example, using /home/xeno/myVsb/vsb.config). (This option can also be used
to modify an existing project.)
-S
Sets all options to the defaults. The configuration tool runs silently. (This
option can also be used to set an existing project to the defaults.)
29
VxWorks
Command Example
For example, the following command creates a VSB project based on the PowerPC
architecture:
% vxprj vsb create -bsp mv5100 /home/xeno/myVsb
3.3.5 Selecting VSB Options
After creating the project directory and files, vxprj automatically presents a series
of options that can be selected to create custom VxWorks libraries, to select
optimization features, and so on.
The following example illustrates a creation command and the first few VSB
options that are presented. The location of the VSB project is announced in the first
lines of output, which is useful to note if you did not specify the location with the
creation command.
C:\>vxprj vsb create -bsp mv5100 c:\workspace\myVsb
Creating VSB Project ...
{saving the VSB project...}
VSB Project created in : c:/workspace/myVsb
starting VSB configuration...
*
* VxWorks Source Build (VSB) Configuration
*
*
* BSP mv5100 Configuration Options
*
Set advanced options (ADVANCED_OPT) [N/y] (NEW) n
*
* mv5100_CPU = PPC32
*
*
* mv5100_FP = hard
*
*
* mv5100_TOOL = diab
*
*
* mv5100_TOOL2 = gnu
*
Applications TOOL [diab gnu ?] (mv5100_APP_TOOL) [diab] (NEW)
*
* VxWorks Kernel Configuration Options
*
Low-level arch code need not support inconsistent cache modes (PPC_CACHE_MODE_IS_CONSISTENT)
[N/y/?] (NEW)
Enable System Viewer Instrumentation Support (SV_INSTRUMENTATION) [Y/n/?] (NEW) n
Enable Real-Time Process (RTP) Support (RTP) [Y/n/?] (NEW) n
Enable WIND Object Management Support (OBJECT_MANAGEMENT) [Y/n/?] (NEW) n
30
Enable ED&R Message Logging (FULL_EDR_STUBS) [Y/n/?] (NEW))
Additional VSB options are presented after these; some depending on what
technologies have been installed and licensed.
3
VSB Option Selection Syntax
Note the following about the conventions used to present options:

■ Option selections are presented either as yes/no alternatives or as a set of
multiple choices from which you select one.
■ At project creation, system default selections are presented as a capitalized
letter (in the case of yes/no alternatives), or listed the option near the end of
the line in brackets (in the case of multiple choices). For example:
FLOATING POINT [hard soft e500v2] (_WRS_CONFIG_PPC32_FP) [hard] (NEW)
■ If you reconfigure the project (see 3.3.6 Reconfiguring a VSB Project, p.31), the
default selections are those recorded the last time you worked with the project
(when you created it, or the last time you reconfigured it).
■ The NEW designation in parentheses means that the option is new to this project.
This would be the case when projects are first created, but also when new
options are introduced by the installation of additional features (for example,
another networking protocol) after a project has been created. For information
about how to configure new options without having to run through all
possible options, see 3.3.6 Reconfiguring a VSB Project, p.31.
3.3.6 Reconfiguring a VSB Project
To reconfigure a VSB project, use the following syntax:

vxprj vsb config [vsbfile|vsbdir] [-d|-D defFile |-o |-s|-S]
The options have the same meaning as when used to create a project (see
3. Configuring and Building VxWorks), with the additions and differences described
below.
Note that the reference to new VSB options below refers to VSB options that become
available to a project when additional features are installed after a project has been
created.
-d
Reconfigure a project based on a VSB configuration file called
default.vxconfig. The file must be located in the directory of the project that is
to be modified.
31
VxWorks
-D defFile
Reconfigure a project based on another VSB project configuration file (for
example, using /home/xeno/myVsb/vsb.config). Any new VSB options are
added with the default settings.
-o
Run the configuration tool, but prompt only for any new VSB options that
have become available (through installation of other features) since the project
was created. This option provides the means for adding them to a project.
-s
Reconfigure a project based on an existing VSB project. The configuration tool
runs silently. A defFile is created in each VSB project directory (for example,
/home/xeno/myVsb/vsb.config). The user is, however, prompted for any new
VSB options that have become available (through installation of other features)
since the project was created.
-S
Reset a VSB project to the default options. The configuration tool runs silently.
3.3.7 Changing the CPU for a VSB Project
To change the CPU on which a VSB project is based, use the following command
syntax:
vxprj vsb setCpu cpuName [vsbfile|vsbdir] [-d|-D defFile |-o |-s|-S]
Options in addition to CPU are available because changing the CPU causes the
interactive VSB option selection process to be restarted, and the vxprj vsb
command options provide various ways to manage selection.
created.
3. Configuring and Building VxWorks), with the following additions and differences:
-d
to be modified.
32
-D defFile
3
-o
Run the configuration tool, but prompt only for any new VSB options that
have become available (through installation of other features) since the project
was created. This option provides the means for adding them to a project.
-s
runs silently. A defFile is created in each VSB project directory (for example,
/home/xeno/myVsb/vsb.config). The user is, however, prompted for any new
VSB options that have become available (through installation of other features)
since the project was created.
-S
3.3.8 Changing the BSP for a VSB Project
To change (or set) the BSP on which a VSB project is based, use the following
command syntax:
vxprj vsb setBsp bsp|bspdir [vsbfile|vsbdir] [-d|-D defFile|-o |-s|-S]
Options in addition to BSP are available because changing the BSP causes the
interactive VSB option selection process to be restarted, and the vxprj vsb options
provide various ways to manage selection (for example, to only deal with new
items).
created.
3. Configuring and Building VxWorks), with the following additions and differences:
-d
to be modified.
33
VxWorks
-D defFile
-o
Run the configuration tool, but prompt only for new options. New options
may be available to a project if additional features are installed after a project
has been created, and this option provides the means for adding them to a
project.
-s
runs silently. A defFile is created in each VSB project directory; for example,
/home/xeno/myVsb/vsb.config.
-S
3.3.9 Building a VSB Project
To build a VSB project, simply execute make in the project directory.

The Wind River Compiler (diab) is used to build VxWorks source for all
architectures except IA. The GNU compiler is used to build source for IA. The
compiler intrinsics libraries are built with the opposite (“secondary”) compiler;
that is the one not used for the primary build (for information about compiler
intrinsics, see the VxWorks Kernel Programmer’s Guide: Target Tools).
Note that the “secondary” compiler can also be used for building certain VxWorks
networking and middleware facilities that are delivered only in source code
format. For information in this regard, see the Wind River VxWorks Platforms User’s
Guide.
The build takes VxWorks source code in installDir/vxworks-6.x/target/src as input
and writes output to subdirectories of the VSB project directory. For example, for a
PPC32 VSB project, the libraries would be created in directories below
vsbdir/ppc/PPC32/.
Note that if a VSB configuration is changed, the libraries are cleaned before the
next build takes place.
34
3.3.10 Deleting a VSB Project
To delete a VSB project, use the following syntax:

vxprj vsb delete path/vsbFile 3
This command removes the entire VSB project directory, and must therefore be
executed outside of that directory.
3.3.11 Using a VSB Project With a VxWorks Image Project
In order to use the customized libraries that you have created with a VSB project—
instead of the default libraries provided with the product installation—you must
associate a VxWorks image project (VIP) with the VSB project. You can make this
association when you create the VIP or afterwards.
To associate a VIP with a VSB when the VIP is created, use the -vsb option with
vxprj create. For example:
% vxprj create wrSbc8560 diab -vsb /home/xeno/myVsb /home/xeno/myVip
To associate a VIP with a VSB after the VIP is created, use the following command
syntax:
vxprj vsb set [prjfile|prjdir] [vsbfile|vsbdir|-default]
The -default option sets the VIP to use default libraries (in target/lib or
target/lib_smp) instead of VSB libraries. The selection of UP or SMP default
libraries is made automatically based on the selection for the VIP itself (that is,
without or with the -smp option).
For detailed information about VxWorks image projects, see 3.2 Working With
VxWorks Image Projects: VIPs, p.12.
3.3.12 Identifying a VIP-VSB Association
To identify which VSB (if any) a VIP is associated with, use the following command
syntax:
vxprj vsb info [prjfile|prjdir]
For example:
C:\workspace\mv5100VIP>vxprj vsb info
VSB directory is set to ./../myPpc32Vsb
35
VxWorks
If the VIP is not associated with a VSB, the output of the command indicates that
it is associated with the default installed libraries, as follows:
C:\workspace\mv5100VIP_3>vxprj vsb info
VSB directory is set to C:/WindRiver/vxworks-6.7/target/lib
3.3.13 Validating a VIP-VSB Association
To check that the association of a VSB and a VIP is valid, use the following
command syntax:
vxprj check
3.4 Building Customized VxWorks Source Code

If you choose to customize (edit) VxWorks kernel source code, you have the
following options for rebuilding it:
■ Create a VSB project and rebuild from the project.
■ Rebuild using the make command directly in the appropriate source directory.
In the case of VSB projects, the new libraries do not overwrite the default libraries
in the VxWorks installation—the output is written to the VSB project directory. VSB
projects can be used only for kernel libraries, and not user (RTP) libraries.
In the case of using make directly, the new libraries do overwrite the default
libraries in the VxWorks installation. Using make directly is simpler in the sense
that you do not have to create a VSB project yourself; but you do need to back up
the libraries you are rebuilding if you want to preserve the defaults provided with
the distribution.
If you choose to customize (edit) user mode (RTP) code, you must use make
directly.
NOTE: You can rebuild kernel libraries (whether UP or SMP) with either the VSB
or direct make method. You must rebuild user-mode (RTP) libraries with the make
method—they cannot be rebuilt with VSB projects.
36
3.4.1 Limitations and Restrictions
There are some limitations and restrictions you must be aware of when
recompiling the VxWorks source:
3
■
You must build the source code in the vxworks-6.x installation tree with the
host tools and makefiles provided with the VxWorks installation.
■ There may be certain portions of VxWorks object code for which source code
has not been provided. See 3.4.2 Third-Party Binary Files, p.37.
■ Modifications to the source code may not be covered by Wind River Customer
Support.
3.4.2 Third-Party Binary Files
Due to licensing restrictions, the VxWorks source code does not include source files
licensed by Wind River from third parties. This code is instead distributed in the
form of binary (.o) files.
When you build the VxWorks source code, the third-party binaries are copied
automatically into the source build directory.
Third party binaries are located in installDir/vxworks-6.x/target/precomp. For a
complete list of the affected files and architectures, search this directory for files
with a .o extension.
! CAUTION: Do not delete the precompiled files in

installDir/vxworks-6.x/target/precomp. Doing so may prevent you from creating
projects that rely on these files.
3.4.3 VxWorks Library Source Code and Archive Locations
The VxWorks library source code and archives are installed in the following
locations:
UP Kernel
installDir/vxworks-6.x/target/src
installDir/vxworks-6.x/target/lib
37
VxWorks
SMP Kernel
installDir/vxworks-6.x/target/lib_smp
User (RTP)
installDir/vxworks-6.x/target/usr/src
installDir/vxworks-6.x/target/usr/lib
! CAUTION: Remember to back up your VxWorks source and binaries before

modifying and rebuilding them.
3.4.5 Building Customized Kernel Source Code with VSB Projects
For information about using VSB projects, see 3.3 Working With VxWorks Source
Build Projects: VSBs, p.26.
3.4.6 Building With Make Directly
To build VxWorks from source using the make command directly, execute the
make command with the appropriate CPU and TOOL variable assignments in the
appropriate source directory.
For information about the CPU and TOOL variables, see the VxWorks Architecture
Supplement.
38
NOTE: You can build a debug version of the source by providing a -g flag with
ADDED_CFLAGS and ADDED_C++FLAGS in the following file:
installDir/vxworks-6.x/target/src/Makefile
3
Or use the variables from the command-line as follows:
% make CPU=cpuVal TOOL=toolChain ADDED_CFLAGS+=-g ADDED_C++FLAGS+=-g
UP and SMP Kernel Build Commands
To build UP or SMP kernel-mode libraries, first change directory to:

For UP libraries, execute the make command using the following syntax:
make CPU=cpuName TOOL= toolchain
For SMP libraries, execute the make command using the following syntax:
make CPU=cpuName TOOL= toolchain VXBUILD=SMP
User (RTP) Build Command
To build user-mode (RTP) libraries, change directory to:

installDir/vxworks-6.x/target/usr/src
Then execute the make command using the following syntax:
make CPU=cpuName TOOL= toolchain
Building Compiler Intrinsics Libraries
VxWorks can be configured with compiler intrinsics components to provide

support for dynamically loading kernel modules, including those built with a
different compiler than was used for the VxWorks kernel itself.
The compiler intrinsics libraries are built automatically when VxWorks source
code is built using a VSB project. If you use make directly, however, you must build
VxWorks a second time, using the other (“secondary”) compiler. That is, if your first
build is performed with the Wind River Compiler (Diab), then you must perform
a second build with the GNU compiler.
39
VxWorks
For more information about compiler intrinsics and downloadable kernel

modules, see the VxWorks Kernel Programmer’s Guide: Target Tools. For information
about compiler options, see the VxWorks Architecture Supplement.
40
4
Building Kernel Applications
and Libraries
4.1 Introduction 42
4.2 About Building Kernel Applications and Libraries 42
4.3 Setting Environment Variables 42
4.4 Using the VxWorks Build Environment 43
4.5 Example Makefile for a Kernel Application 43
4.6 Setting CPU and TOOL Make Variables 44
4.7 Building Kernel Applications for UP, SMP, and VSB Variants 45
4.8 Linking Kernel Application Modules 47
4.9 Linking Kernel Application Modules With VxWorks 47
4.10 make Variables for Kernel Applications and Libraries 48
4.11 Running Kernel Applications 49
41
VxWorks
4.1 Introduction
This chapter explains how to build VxWorks kernel applications and associated
libraries using command-line build facilities. You can build applications and
libraries using a default set of makefile rules and make.
You can use kernel applications as downloadable modules or linked with the
VxWorks kernel itself. You can also create custom static libraries for use with
kernel applications.
For detailed information about writing code for kernel applications and libraries,
see the VxWorks Kernel Programmer’s Guide. For information about how to use
Wind River Workbench to build applications and libraries, see the Wind River
Workbench by Example guide.
4.2 About Building Kernel Applications and Libraries

To build a kernel-mode application or library from the command line, you can use
the default makefile system and invoke the make utility directly. Wind River
supplies a general build model implemented by a series of make rules, with
standard make variables that control aspects of the build process such as target
CPU and toolchain.
For information about writing code for kernel applications and libraries (including
use of kernel facilities and APIs, C and C++ libraries, header files, and so on), see
the VxWorks Kernel Programmer’s Guide.
4.3 Setting Environment Variables

42
4 Building Kernel Applications and Libraries
4.4 Using the VxWorks Build Environment

Using the command-line interface (CLI) build environment provided with the
VxWorks installation allows you to take advantage of a set of default makefile
rules to build kernel applications and libraries.
4
4.5 Example Makefile for a Kernel Application

# basic build file for a kernel application
# for Windows hosts, fix slashes

WIND_HOME := $(subst \,/,$(WIND_HOME))
WIND_BASE := $(subst \,/,$(WIND_BASE))
WIND_USR := $(subst \,/,$(WIND_USR))
include $(WIND_BASE)/target/h/make/defs.vsbvars.mk
# project-specific macros
EXE = hello.out
OBJ = hello.o
SRC = hello.c
# libraries, includes
LIBS =
INCLUDES = -I$(WIND_BASE)/target/h \
-I$(WIND_BASE)/target/h/wrn/coreip
# define CPU and tools

CPU = SIMPENTIUM
TOOL_FAMILY = diab
TOOL = diab
# compiler, linker (dcc, dld)

CC = dcc
LL = dld
# See Wind River compiler guide for complete details on linker options
# -r retains relocation entries, so the file can be re-input to the linker
LFLAGS = $(TARGET_SPEC) -r
# See Wind River compiler guide for information on target selection.

TARGET_SPEC = -tX86LH:vxworks66
##############################
# generic build targets, rules
43
VxWorks
# executable constructed using linker from object files

$(EXE) : $(OBJ)
$(LL) $(LFLAGS) -o $@ $(OBJ) $(LIBS)
# objects compiled from source

$(OBJ) : $(SRC)
$(CC) $(TARGET_SPEC) $(INCLUDES) \
-DCPU=$(CPU) \
-DTOOL=$(TOOL) \
-DTOOL_FAMILY=$(TOOL_FAMILY) \
$(ALLFLAGS_VSBDEFS)
-o $@ -c $<
# clean up
clean :
rm $(EXE) $(OBJ)
# See the Wind River compiler documentation for more details on

# compiler and linker options.
The inclusion of defs.vsbvars.mk allows you to build an application using

VxWorks source build (VSB) variant libraries or SMP libraries as well as the default
uniprocessor (UP) libraries. For information about the make commands used to
build applications for different types of systems, see 4. Building Kernel Applications
and Libraries.
4.6 Setting CPU and TOOL Make Variables

The makefile defaults for processor architecture and compiler are PowerPC
architecture and the Wind River Compiler (Diab). Variable assignments can be
used at the command line or in a makefile to identify other architectures and
compilers. For example, the command used to build an application with the GNU
compiler for Pentium2 would be as follows:
make CPU=PENTIUM2 TOOL=gnu
Supplement.
44
4.7 Building Kernel Applications for UP, SMP, and VSB Variants
4.7 Building Kernel Applications for UP, SMP, and VSB Variants
The VxWorks CLI build system provides make variables that you can use to build
kernel applications for the following types of VxWorks systems:
■
Uniprocessor (UP) or Symmetric multiprocessor (SMP) systems using the 4
default libraries provided with the VxWorks distribution. These systems are
configured simply using a VxWorks image project (VIP).
■ UP or SMP systems using variant (that is, non-default) libraries. These systems
use libraries you create with a VxWorks source build (VSB) project. In order to
make use of the variant libraries, you associate the VIP project for the system
with the VSB project when you configure the system is configured.
For information about configuring VxWorks with a VIP (using the default
libraries), see 3.2 Working With VxWorks Image Projects: VIPs, p.12. For information
about creating variant libraries using a VSB project, and associating a VIP project
with a VSB project, see 3.3 Working With VxWorks Source Build Projects: VSBs, p.26.
The build options described below ensure that the application is linked against the
libraries that are appropriate for the system on which the application will run. That
is, they specify whether an application is linked against UP libraries, SMP libraries,
or variant libraries of either a UP or an SMP variety.
! CAUTION: VxWorks kernel applications must be built specifically for the type of
system on which they will run. Applications built for uniprocessor (UP) VxWorks,
for symmetric multiprocessor (SMP) VxWorks, or for VxWorks systems based on
variant libraries created with a VxWorks source build (VSB) project (either UP or
SMP), are not binary compatible. Note that the loader does not generate an error if
a kernel module is incompatible with the system onto which it is loaded.
4.7.1 Building Applications With Default VxWorks UP Libraries
To generate a kernel application for use with a VxWorks UP kernel using default
libraries, use the following command syntax or add the variable assignments to the
application’s makefile:
make CPU=cpuType TOOL= toolchain
Supplement.
45
VxWorks
4.7.2 Building Applications With Default VxWorks SMP Libraries
To build a kernel application for use with a VxWorks SMP kernel using default
libraries, use the following command syntax or add the variable assignments to the
make CPU=cpuType TOOL= toolchain VXBUILD=SMP
The VXBUILD=SMP ensures that the application will be linked against the default
SMP libraries.
Supplement.
4.7.3 Building Applications With User-Configured Variant Libraries
To build a kernel application for a VxWorks kernel (UP or SMP) using variant
libraries that you have created with a VSB project, the makefile must include
rules.dkm.mk.
Use the following command syntax or add the variable assignments to the
make CPU=cpuType TOOL= toolchain VSB_DIR=pathToVsbProjectDir
The VSB_DIR assignment ensures that the application will be linked against the
specified set of variant libraries. Whether these libraries are UP or SMP was
determined when the VSB project was created.
Supplement.
NOTE: No specific designation of UP or SMP is required for an application linked

against VSB variant libraries. The variant libraries themselves were defined as UP
or SMP in the source build project (VSB) with which they were created. In fact the
use of the VSB_DIR variable with VXBUILD=SMP is not supported. For
information about VSB projects, see 3.3 Working With VxWorks Source Build Projects:
VSBs, p.26.
46
4.8 Linking Kernel Application Modules
4.8 Linking Kernel Application Modules

In general, if you are going to download kernel object modules to a VxWorks target
you do not need to link them prior to download. However, if modules cross
reference each other, you should link them to form a single module. With C++
4
code, this linking should be done before the munch step. (For information about
munching, see the VxWorks Kernel Programmer’s Guide.)
For example, the following command links several modules, using the Wind River
linker for the PowerPC family of processors:
c:\> dld -o applic.o -r applic1.o applic2.o applic3.o
Similarly, this example uses the GNU linker:

c:\> ldppc -o applic.o -r applic1.o applic2.o applic3.o
In either case, the command creates the object module applic.o from the object
modules applic1.o, applic2.o, and applic3.o. The -r option is required, because the
object-module output must be left in relocatable form so that it can be downloaded
and linked to the target VxWorks image.
Any VxWorks facilities called by the kernel application modules are reported by
the linker as unresolved externals. These are resolved by the loader when the
module is loaded into VxWorks memory.
! WARNING: Do not link each kernel application module with the VxWorks libraries.
Doing this defeats the load-time linking feature of the loader, and wastes space by
adding multiple copies of VxWorks system modules to the target.
4.9 Linking Kernel Application Modules With VxWorks

In order to produce complete systems that include kernel application object
modules, the modules must be statically linked with the VxWorks image. The
makefile EXTRA_MODULES variable can be used to do so.
It can be used from the command line as follows:
c:\workspace\myVIP> make EXTRA_MODULES="foo.o"
Note that the command must be issued in the VxWorks image project (VIP)
directory.
47
VxWorks
To include your kernel application modules in the system image using a makefile,
identify the names of the application object modules with EXTRA_MODULES. For
example, to link the module myMod.o with the operating system, add a line like
the following:
EXTRA_MODULES = myMod.o
Building the system image with the module linked in is the final part of this step.
In the project directory, execute the following command:
c:\workspace\myVIP> make vxWorks
For information about how to have kernel applications start automatically at boot
time, see the VxWorks Kernel Programmer’s Guide.
For information about using vxprj to add link kernel applications with VxWorks
with a VxWorks image project (VIP), see Adding and Removing Individual Application
Files, p.18. The vxprj method has the advantage of making the application an
integral part of the VxWorks project (and it remains so even when the project is
cleaned).
4.10 make Variables for Kernel Applications and Libraries

You can specify values for the following variables either from the make command
line, or from your own makefiles (when you take advantage of the predefined
VxWorks make include files).
ADDED_CFLAGS
Application-specific compiler options for C programs.
ADDED_C++FLAGS
Application-specific compiler options for C++ programs.
You can use additional variables to link kernel application modules with the
VxWorks image; see 4.9 Linking Kernel Application Modules With VxWorks, p.47.
! CAUTION: Specific make variables are required if you are building an application
for a symmetrical multiprocessing SMP configuration of VxWorks or for a system
based on variant libraries (created with a VxWorks source build project). For more
information, see 4.7 Building Kernel Applications for UP, SMP, and VSB Variants, p.45.
48
4.11 Running Kernel Applications
4.11 Running Kernel Applications

You can statically link kernel applications to a VxWorks image or download them
from the host system, and start them automatically or interactively. For
information on these topics, see the VxWorks Kernel Programmer’s Guide: Kernel
4
Applications, the VxWorks Kernel Programmer’s Guide: Target Tools, the Wind River
Workbench Host Shell User’s Guide, and the Wind River Workbench by Example guide.
49
VxWorks
50
5
Building RTP Applications
and Libraries
5.1 Introduction 52
5.2 About Building RTP Applications and Libraries 52
5.3 Setting Environment Variables 53
5.4 Using the VxWorks Build Environment 53
5.5 Make Rules for RTP Applications and Libraries 54
5.6 Setting CPU and TOOL Make Variables 54
5.7 Top-Level Makefile for Applications and Libraries 54
5.8 Building RTP Libraries 55
5.9 Building RTP Applications 58
5.10 Using a Custom Build Environment 61
5.11 Compiler Options for Shared Objects and Dynamic RTP
Applications 64
5.12 Make Variables for RTP Applications and Libraries 66
5.13 Running RTP Applications 69
51
VxWorks
5.1 Introduction
This chapter explains how to build VxWorks user-mode applications and libraries,
using command-line build facilities. You can build applications and libraries using
a default set of makefile rules and make, or with a custom build environment.
VxWorks user-mode applications are standalone executables. They are referred to
as real-time process (RTP) applications. You can use the default (or a custom) build
environment to build static libraries, shared libraries, and plug-ins for use with
RTP applications.
For detailed information writing code for applications and libraries, see the
VxWorks Application Programmer’s Guide. For information about how to use
Wind River Workbench to build applications and libraries, see the Wind River
Workbench by Example guide.
5.2 About Building RTP Applications and Libraries

To build a user-mode, real-time process (RTP) application or library (either static
or shared), or plug-in from the command line, you can make use of the default
makefile system and invoke the make utility directly. Wind River supplies a
general build model implemented by a series of make rules, with standard make
variables that control aspects of the build process such as target CPU and
toolchain. You can also use a custom build environment.
RTP application and library projects can be created by following the models in
target/usr/apps/samples/ and target/usr/src/usr/ under the VxWorks installation
directory.
For information writing code for RTP applications, libraries, and plug-ins
(including use of kernel facilities and system calls, C and C++ libraries, header
files, and so on), see the VxWorks Application Programmer’s Guide.
NOTE: Relocatable RTP application executables (the default) can be run on a

system that has been configured for the overlapped virtual memory model.
However, to take advantage of this model, RTP applications must be built as
absolutely-linked executables. For more information, see the VxWorks Application
Programmer’s Guide: Real-Time Processes.
52
5 Building RTP Applications and Libraries


It can be useful to set up a project with a top-level directory with subdirectories for
the application and for each shared library. The makefiles would be as follows:
■ A top-level makefile that identifies the application and library subdirectories
to build.
■ A makefile for each shared library.
■ A makefile for each application.
The directory structure might look like the one in Figure 5-1. The grey boxes
indicate directories created automatically by the default build rules.
Figure 5-1 Example of CLI Build Directory Structure
Top-level directory
Executables Library A Library B
PPC32diab PPC32diab PPC32diab
... ... ...
If you do not use a top-level makefile for the whole project, and you build libraries
and applications separately, you must build libraries first.
53
VxWorks
5.5 Make Rules for RTP Applications and Libraries

The rules.rtp, rules.library, and other make rule files (some of them host-specific)
are found in target/usr/make/ under the VxWorks installation directory. Except for
the LOCAL_CLEAN and LOCAL_RCLEAN variables (see 5.12 Make Variables for RTP
Applications and Libraries, p.66), rules.rtp or rules.library should usually be
included as the last line of the makefile; user-defined build rules must precede
rules.rtp or rules.library.
5.6 Setting CPU and TOOL Make Variables

The makefile defaults for processor architecture and compiler are PowerPC
architecture and the Wind River Compiler (Diab). Variable assignments can be
used at the command line or in a makefile to identify other architectures and
compilers. For example, the command used to build an application with the GNU
compiler for Pentium2 would be as follows:
make CPU=PENTIUM2 TOOL=gnu
For information about the CPU and TOOL make variables, see the VxWorks
Architecture Supplement.
5.7 Top-Level Makefile for Applications and Libraries

The top-level makefile requires only two elements. For example:
SUBDIRS = libA libB app
include $(WIND_USR)/make/rules.rtp
SUBDIRS
Indicates what subdirectories to build. In this case, there are two library
subdirectories (libA and libB) and an application subdirectory (app)
identified.
54
5.8 Building RTP Libraries
rules.rtp
The make fragment holding build rules for application (.vxe) files.
$(WIND_USR)
An environment variable pointing to the user-side of the target tree:
installDir/vxworks-6.x/target/usr.

This section provides information about the elements of a makefile for statruc abd
shared libraries (and plug-ins), the output of builds, and build commands.
5.8.1 Basic Library Makefile
Only four elements are required for a shared library (or plug-in) makefile. For
example:
LIB_BASE_NAME = MyFoo
OBJS = foo1.o foo2.o foo3.o
EXTRA_INCLUDE += -I/home/xeno/proj/h
include $(WIND_USR)/make/rules.library
LIB_BASE_NAME
Specifies the library’s basename. It takes a stripped version of the library name;
that is, without the lib prefix and without the filename extension. The
LIB_BASE_NAME variable is required for generating the shared object name
(soname) information, which is necessary for identifying the run-time location
of the shared library. For detailed information about shared object names, see
the VxWorks Application Programmer’s Guide.
OBJS
Identifies the object files that make up the library.
EXTRA_INCLUDE
Appends additional search paths for the include files (using the += operator).
rules.library
The make fragment holding build rules for libraries.
55
VxWorks
$(WIND_USR)
An environment variable pointing to the user-side of the target tree:
installDir/vxworks-6.x/target/usr.
5.8.2 More Complex Library Makefile
Additional makefile variables and conditional statements can be used to build

either shared or static libraries, to specify a location other than the default in which
to create the library, and so on. A more useful makefile would look like this:
SL_INSTALL_DIR = /home/xeno/proj/ppc32/lib
ifeq ($(EXE_FORMAT),dynamic)
LIB_FORMAT = shared
endif
ifeq ($(LIB_FORMAT),shared)
LOCAL_CLEAN += $(OBJ_DIR)/*.sho $(OBJ_DIR)/libMyFoo.so
else
LOCAL_CLEAN += $(OBJ_DIR)/*.o $(OBJ_DIR)/libMyFoo.a
endif
LIB_BASE_NAME = MyFoo
LIBNAME = lib$(LIB_BASE_NAME)
SL_VERSION = 2
OBJS = module1.o module2.o
OBJ_DIR = $(CPU)$(TOOL)
EXTRA_INCLUDE += -I/home/xeno/proj/h
include $(WIND_USR)/make/rules.library
LIBDIR = $(OBJ_DIR)
SL_INSTALL_DIR
Specifies a non-default location for the library file. It is often useful to keep
project work outside of the installation directory. Note that if you are
generating code for different processor architectures, you could use the $(CPU)
variable to define the architecture-specific subdirectory (which would then use
the Wind River naming conventions—PPC32 instead of ppc32, as in this case).
LIB_FORMAT
Specifies whether the library must be generated as a static library (the default
if not specified) or a shared library. It can be set to static, shared, or both. See
5.8.4 Library Build Commands, p.58.
LOCAL_CLEAN
Specifies what must be deleted when non-default directories are used.
OBJ_DIR
Specifies a non-default directory in which the object modules are generated.
LIBNAME
Specifies a non-default directory for the static library.
56
SL_VERSION
Creates a version number for a shared library. By default, the shared library
version number is 1 (libName.so.1), so the variable is not needed unless you
want to build an alternate version of the shared library. For detailed
information about shared object names and versions, see the VxWorks
Application Programmer’s Guide.
LIBDIR 5
Prevents the creation of an unused directory in
installDir/vxworks-6.x/target/usr/lib when set to $(OBJ_DIR), as it is in this
example. This variable must be the last one used; that is, it must be listed after
the inclusion of rules.library in order to take precedence.
5.8.3 Library Build Output
By default, a library is created as a static archive file (libName.a) in

installDir/target/usr/lib/arch/cpu/common. For example,
installDir/target/usr/lib/ppc/PPC32/common.
When a library is built as a shared library:
■ The reference file (libName.so) is created by default in the same default
directory as a static library file. The reference file is used by the linker when a
dynamic application is built.
■ The run-time version of the shared library (libName.so.n) is created by default
in the same default directory as the application executable.
That is, all the run-time executables are created in the same binary directory by
default: installDir/target/usr/root/cpuTool/bin. For example,
installDir/target/usr/root/PPC32diab/bin.
As noted in 5.8.1 Basic Library Makefile, p.55, the SL_INSTALL_DIR makefile
variable can be used to specify a non-default location for the library file.
NOTE: The rather cumbersome usage of LIBNAME, OBJ_DIR and LIBDIR is

required by the library rules. The three must be specified to avoid cluttering the
distribution’s installDir/vxworks-6.x/target/usr/lib/arch/cpu/common directory
with unnecessary directories and user application-specific files.
57
VxWorks
5.8.4 Library Build Commands
The first conditional statement in the example above allows for building both a
shared library and dynamic application using the top-level makefile. For example:
make EXE_FORMAT=dynamic
builds the dynamic executable and related shared libraries for the PPC32
architecture with the Wind River Compiler (the default architecture and compiler).
The following command is similar, but uses the GNU compiler to build for the
Pentium architecture:
make CPU=PPC32 TOOL=gnu EXE_FORMAT=dynamic
Static libraries are created by default, so the EXE_FORMAT variable need not be
used to create them. For information about the CPU and TOOL variables see
5.6 Setting CPU and TOOL Make Variables, p.54.
You can also build libraries by executing make in the directory containing the
library makefile. The LIB_FORMAT variable allows you to create static, shared, or
both sets of libraries. For example:
make LIB_FORMAT=static
make LIB_FORMAT=shared
make LIB_FORMAT=both
Static libraries are created by default, so that option is superfluous in this context.
5.9 Building RTP Applications

This section provides information about the elements of a makefile for an RTP
applications, the output of builds, and build commands.
5.9.1 Basic Application Makefile for a Dynamic Executable
Only four elements are required for an RTP application makefile when the
application is a dynamic executable that uses a shared library. For example:
EXE = myVxApp.vxe
OBJS = myVxApp.o
ADDED_LIBS += -L../lib/$(CPU)$(TOOL) –lMyFoo
58
5.9 Building RTP Applications
EXE
Defines the name of the application executable.
OBJS
Identifies the constituent object modules. If more than one is used, they are
listed in a space-separated string. For example:
OBJS = bar1.o bar2.0 bar3.0
5
ADDED_LIBS
Appends the search paths and stripped names of any custom libraries that the
application requires (with the += operator). This option can be used for
creating either static or dynamic applications. See 5.11 Compiler Options for
Shared Objects and Dynamic RTP Applications, p.64 for a discussion of the -l
option.
The include statement and $(WIND_USR) element are described in 5.7 Top-Level
Makefile for Applications and Libraries, p.54.
5.9.2 More Complex Application Makefile
Additional makefile variables can (and often should) be used to specify a different
location for the application executable, the run-time location of the shared libraries
upon which it depends, conditional compilation of either a dynamic or static
application, and so on. A more useful makefile would look like the following:
EXE = myVxApp.vxe
OBJS = myVxApp.o
VXE_DIR = $(CPU)$(TOOL)/bin
LIB_DIR = ../lib/$(CPU)$(TOOL)
ADDED_LIBS += -L $(LIB_DIR) –lMyFoo
ifeq ($(EXE_FORMAT),dynamic)
ADDED_DYN_EXE_FLAGS += -Wl,-rpath /romfs/lib
else
ADDED_LIB_DEPS += $(LIB_DIR)/libMyFoo.a
endif
VXE_DIR
Identifies an alternative to the default directory in which the application
executable is created. It is often useful to keep project work outside of the
installation tree.
LIB_DIR
Is a local make variable that can be used conveniently to identify where a
library is located (if it is not in the default location) in the ADDED_LIBS and
ADDED_LIB_DEPS lines without repeating the literal path information.
59
VxWorks
ADDED_DYN_EXE_FLAGS
Is used to pass additional compiler options specific to the generation of
dynamic executables. It is used here with the -Wl,-rpath option to specify the
run-time location of any shared libraries upon which the application depends
NOTE: The the usage for -rpath is different for the Wind River Compiler and the
Wind River GNU compiler. For the latter, an equal sign (=) must be used between
-rpath and the path name.
In this example, the location is in a lib subdirectory of the ROMFS file system
on the VxWorks target:
ADDED_DYN_EXE_FLAGS += -Wl,-rpath /romfs/lib
In this next example, the location is on the host system:

# ADDED_DYN_EXE_FLAGS += -Wl,-rpath c:/myProj/lib/SIMPENTIUMdiab
For information about the -Wl,-rpath option, see 5.11 Compiler Options for
Shared Objects and Dynamic RTP Applications, p.64.
Note that some types of connections between the target and host require
modifiers to the path name. NFS is transparent; FTP requires hostname: before
the path if it is not on the same system from which VxWorks was booted; the
VxWorks simulator requires a host: prefix; and so on.
ADDED_LIB_DEPS
Specifies the dependencies between the application and the application’s static
libraries (with the += operator). For static linkage, this variable forces a rebuild
of the application if the static library has been changed since the last build.
5.9.3 RTP Application Build Output
By default, the executable is created in installDir/target/usr/root/cpuTool/bin, as are

the run-time shared object files (libraries and plug-ins). For example,
installDir/target/usr/root/PPC32diab/bin.
As noted in 5.9.2 More Complex Application Makefile, p.59, the VXE_DIR variable can
be used to identify an alternative output directory.
5.9.4 RTP Application Build Commands
In the example provided in 5.9.2 More Complex Application Makefile, p.59, the
conditional ifeq/else/endif statement allows for generating either a static
60
5.10 Using a Custom Build Environment
executable or a dynamic executable, depending on the value given the

EXE_FORMAT variable when make is executed at the command line. The
EXE_FORMAT variable can take one of two values, dynamic or static. For example:
make EXE_FORMAT=dynamic
As a static build is the default, setting EXE_FORMAT to static is not necessary.

For information about using the CPU and TOOL make variables to set the processor 5
architecture and compiler to something other than the defaults, see 5.6 Setting CPU
and TOOL Make Variables, p.54.

If you do not use Wind River Workbench or the VxWorks command-line build
environment provided with the installation to create shared libraries and dynamic
executables, follow the guidelines provided in this section (including the compiler
options listed in 5.11 Compiler Options for Shared Objects and Dynamic RTP
Applications, p.64).
To create a dynamically linked program or shared object, you must run the static
linker (dld or ld) with specific options. These options cause the linker to mark the
output as dynamically linked, and to include various data structures for later
dynamic linking.
Shared objects are compiled as position-independent code (PIC). Note that all code
that you compile for a shared object must be PIC. Do not use PIC options to
compile modules that will be statically linked into an executable program.
You must build a shared library before any dynamic application that makes use of
it, in two steps:
1. Generate the PIC object modules that are to be assembled into a shared object
file. The modules are created with the .sho filename extension.
2. Generate the shared object (with the .so filename extension) based on the PIC
object modules.
You can then build the dynamic application in two more steps:
1. Generate the object modules that will be assembled into an executable file. The
application’s object modules are created with a .o filename extension.
61
VxWorks
2. Generate the executable file based on the object modules. By convention, the
application is created with the .vxe filename extension.
5.10.1 Generating PIC Object Modules
The following examples illustrate compiler commands used to generate a library’s

PIC modules. The compiler options are the same as those used by the default
makefile system.
Using the Wind River Compiler:
dcc -tPPCEH:rtp -Xansi -XO -I$(WIND_BASE)/target/usr/h -I/home/xeno/proj/h
-DCPU=PPC32 -DTOOL_FAMILY=diab -DTOOL=diab -Xpic -Xswitch-table-off -c foo1.c
-o PPC32diab/foo1.sho
Using the GNU Compiler:

ccppc -mhard-float -mstrict-align -mregnames -ansi -mrtp -O2
-fstrength-reduce -fno-builtin -I$(WIND_BASE)target/usr/h -I/home/xeno/proj/h
-DCPU=PPC32 -DTOOL_FAMILY=gnu -DTOOL=gnu -fpic -c foo1.c -o PPC32gnu/foo1.sho
! CAUTION: Combining PIC modules generated by the Wind River Compiler and
the GNU compiler is not supported and is not expected to work. Doing so may
lead to unpredictable results.
5.10.2 Generating the Shared Library
The following examples illustrate compiler commands used to generate a library

from PIC modules. The compiler options are the same as those used by the default
makefile system.
dplus -tPPCEH:rtp -Xansi -XO -DCPU=PPC32 -DTOOL_FAMILY=diab -DTOOL=diab -Xpic
-Xswitch-table-off -Wl, -Xshared -Wl, -Xdynamic -soname=libMyFoo.so.1
-L$(WIND_BASE)/target/usr/lib/ppc/PPC32/common/PIC -lstlstd
PPC32diab/foo1.sho PPC32diab/foo2.sho -o libMyFoo.so

c++ppc -mhard-float -mstrict-align -mregnames -ansi -mrtp -O2
-fstrength-reduce -fno-builtin -DCPU=PPC32 -DTOOL_FAMILY=gnu -DTOOL=gnu -fpic
-shared -Wl,-soname,libMyFoo.so.1
-L$(WIND_BASE)/target/usr/lib/ppc/PPC32/common/PIC -lstdc++ PPC32gnu/foo1.sho
PPC32gnu/foo2.sho -o libMyFoo.so
62
5.10.3 Generating the Application’s Object Modules
The following examples illustrate compiler commands used to generate an

application’s object modules. The compiler options are the same as those used by
the default makefile system.
5
dcc -tPPCEH:rtp -Xansi -XO -I$(WIND_BASE)/target/usr/h -I/home/xeno/proj/h
-DCPU=PPC32 -DTOOL_FAMILY=diab -DTOOL=diab -c main.c -o PPC32diab/main.o

ccppc -mhard-float -mstrict-align -mregnames -ansi -mrtp -O2
-fstrength-reduce -fno-builtin -I$(WIND_BASE)/target/usr/h
-I/home/xeno/proj/h -DCPU=PPC32 -DTOOL_FAMILY=gnu -DTOOL=gnu -c main.c -o
PPC32gnu/main.o
5.10.4 Generating the Application Executable
The following examples illustrate compiler commands used to generate the

application executable. The compiler options are the same as those used by the
default makefile system.
dplus -tPPCEH:rtp -Xansi -XO -DCPU=PPC32 -DTOOL_FAMILY=diab -DTOOL=diab
PPC32diab/main.o PPC32diab/secondary.o -Xdynamic -L
$(WIND_BASE)/target/usr/lib/ppc/PPC32/common/ -L../lib/PPC32diab -lMyFoo
-lstlstd -Wl,-rpath /romfs/lib -o myVxApp.vxe

c++ppc -mhard-float -mstrict-align -mregnames -ansi -mrtp -O2
-fstrength-reduce -fno-builtin -DCPU=PPC32 -DTOOL_FAMILY=gnu -DTOOL=gnu -mrtp
PPC32gnu/main.o PPC32gnu/secondary.o -non-static -L
$(WIND_BASE)/target/usr/lib/ppc/PPC32/common -Wl,--start-group
-L../lib/PPC32gnu -lMyFoo -lstdc++ -Wl,--end-group -Wl,-rpath=/romfs/lib -o
tmPthreadLib.vxe
NOTE: The the usage for -rpath is different for the Wind River Compiler and the
Wind River GNU compiler. For the latter, an equal sign (=) must be used between
-rpath and the path name.
63
VxWorks
5.11 Compiler Options for Shared Objects and Dynamic RTP

Applications
The most important compiler options used in generating shared objects (shared
libraries and plug-ins) and dynamic RTP applications are described below. Note
that no specific options are required for generating the application modules (the .o
files), but that special options are required for generating an application executable
(the .vxe file).
5.11.1 Options for Shared Objects
To generate PIC suitable for use in a shared library or plug-in, use the following
options:
■
-Xpic with the Wind River Compiler
■
-fpic with the GNU Compiler
To link shared library PIC modules, use:
■
-Xshared with the Wind River Compiler
■
-shared with the GNU Compiler
To name a shared object (and optionally provide a version number), use:
■
-soname= sharedLibraryName with the Wind River Compiler
■
-Wl,-soname,sharedLibraryName with the GNU Compiler
Note that gcc does not recognize -soname so it must be passed to ld with -Wl.
The -soname option specifies a shared object name for a shared library. This
information is used both for locating shared libraries at run-time, as well as for
creating different versions of shared libraries. For detailed information about
shared object names, see the VxWorks Application Programmer’s Guide.
To force the object to use its own definitions for global functions and data even if
some other shared object, or the dynamic executable, would otherwise override
those definitions, use:
■
-Bsymbolic with either compiler
Note that the compilers do not recognize -Bsymbolic, so it must be passed to
their linker with -Wl.
64
5.11 Compiler Options for Shared Objects and Dynamic RTP Applications
Normally when the dynamic linker looks for a definition for a function or some
data, it chooses the first one that it sees, even if some later module has its own
definition.
5.11.2 Options for Dynamic RTP Application Executables

5
To allow an RTP application to dynamically link with a shared library, use:
■ -Xdynamic with the Wind River Compiler
■ -non-static with the GNU Compiler
Identifying the Run-time Paths of Shared Libraries
To identify the run-time path to shared libraries, use the following when building
the application’s dynamic executable:
■ -Wl,-rpath sharedLibDirPath (with either compiler)
Provide a semicolon-separated list of directory names (the run path), which the
dynamic linker uses as one of the means to locate shared libraries at run time.
! CAUTION: The dynamic linker assumes that library files with the same name are
different if the path defined with -rpath is different. Care should therefore be taken
to ensure that multiple copies of identical libraries are not loaded.
For more information about run-time paths, as well as additional methods for
identifying them, see the VxWorks Application Programmer’s Guide.
The paths provided with the -Wl,-rpath linker option must, of course, be accessible
to the VxWorks target system. If the paths reference files on the host’s file system,
make sure that they are identified in a way that is appropriate for the host-target
connection. NFS is transparent; FTP requires hostname: before the path if it is not
on the same system from which VxWorks was booted; the VxWorks simulator
requires a host: prefix; and so on.
For example, the following example identifies a lib subdirectory in the ROMFS file
system in VxWorks, the c:\proj\lib on a Windows host system, and
/home/xeno/proj on an NFS file system as the locations for shared libraries:
-Wl,-rpath /romfs/lib;c:/proj/lib;/home/xeno/proj
65
VxWorks
When using Wind River Workbench to create a dynamic executable, the linker
option for a dynamic executable must be selected. The -Wl,-rpath option can be
used to identify shared library locations, if necessary.
To indicate which shared libraries will be used by the dynamic application, use:
■
-l with either compiler
The -l option takes a stripped version of the library name. By convention,
libraries referred to by the -l option are named libname.so or libname.a. Both
the lib part of the name and the filename extension (.so or .a) are omitted when
specified with -l. For example, both libMyFoo.so and libMyFoo.a could be
identified with -l MyFoo. This facility is particularly useful for conditional
compilation of either static or dynamic applications (see 5.9.2 More Complex
Application Makefile, p.59).
5.12 Make Variables for RTP Applications and Libraries

The VxWorks build system utilizes a number of make variables (also called
macros), some of which are described below. The files in target/usr/make/ include
additional variables, but only the ones documented here are intended for
redefinition by the user.
ADDED_C++FLAGS
Additional C++ compiler options.
ADDED_CFLAGS
Additional C compiler options.
ADDED_CLEAN_LIBS
A list of libraries (static and dynamic) deleted when make clean is executed in
the application directory. See LOCAL_CLEAN and LOCAL_RCLEAN below.
ADDED_DYN_EXE_FLAGS
Additional compiler options specific to the generation of dynamic executables.
ADDED_LIBS
A list of static libraries (in addition to the standard VxWorks RTP libraries)
linked into the application. This macro must be defined before the inclusion of
rules.library file.
66
5.12 Make Variables for RTP Applications and Libraries
ADDED_LIB_DEPS
Dependencies between the application and the application’s static libraries
(with the += operator). For static linkage, this variable forces a rebuild of the
application if the static library has been changed since the last build.
ADDED_SHARED_LIBS
A list of shared libraries dynamically linked to the application. Items in the list
are prefixed with lib and have the.so file extension added. For example, 5
ADDED_SHARED_LIBS="foo bar" causes the build system to try to link
libfoo.so and libbar.so.
CPU
The target instruction-set architecture to compile for. This is not necessarily the
exact microprocessor model.
DOC_FILES
A list of C and C++ source files that are specially parsed during the build to
generate online API documentation. Should be an empty list if there are no
files to generate documentation from.
-DTOOL_FAMILY
The compiler tool family (diab or gnu) for kernel applications.
-D_VX_TOOL_FAMILY
The compiler tool family (diab or gnu) for user applications. This macro is
analogous to the -DTOOL_FAMILY macro used for kernel applications.
EXCLUDE_SUBDIRS
A list of subdirectories excluded from the build. Generally, when make is
executed, the system tries to build the default target for every subdirectory of
the current directory that has a makefile in it. Use EXCLUDE_SUBDIRS to
override this behavior. See also SUBDIRS.
EXE
The output executable filename. Specify only one executable per makefile. Do
not include a directory path. See VXE_DIR.
EXE_FORMAT
The format of the output executable (static or dynamic). The default is static.
EXTRA_INCLUDE
Additional search paths for the include files. Uses the += operator.
LIBNAME
A non-default directory for the static library.
67
VxWorks
LIB_BASE_NAME
The name of the archive that objects built in the directory are collected into. For
example, LIB_BASE_NAME=foo causes the build system to create a static
library called libfoo.a or a dynamic library called libfoo.so. See LIB_FORMAT.
(Library builds only.)
LIB_DIR
A local make variable that can be used conveniently to identify where a library
is located (if it is not in the default location) in the ADDED_LIBS and
ADDED_LIB_DEPS lines without repeating the literal path information.
LIB_FORMAT
The type of library to build. Can be static, shared (dynamic), or both; defaults
to both. (Library builds only.)
LOCAL_CLEAN
Additional files deleted when make clean is executed. By default, the clean
target deletes files listed in OBJS. Use LOCAL_CLEAN to specify additional files
to be deleted. Must be defined after rules.rtp or rules.library.
LOCAL_RCLEAN
Additional files deleted when make rclean is executed. The rclean target
recursively descends the directory tree starting from the current directory,
executing make clean in every subdirectory; if SUBDIRS is defined, only
directories listed in SUBDIRS are affected; directories listed in
EXCLUDE_SUBDIRS are not affected. Use LOCAL_RCLEAN to specify
additional files in the current directory to be deleted. Must be defined after
rules.rtp or rules.library.
OBJ_DIR
The output subdirectory for object files.
OBJS
A list of object files built; should include object files to be linked into the final
executable. Each item must end with the .o extension. If you specify an object
file that does not have a corresponding source file (.c for C, .cpp for C++, or .s
for assembly), there must be a build rule that determines how the object file is
generated. Do not include a directory path. See OBJ_DIR and LIBDIRBASE.
SL_INSTALL_DIR
A non-default location for the library file. It is often useful to keep project work
outside of the installation directory.
68
5.13 Running RTP Applications
SL_VERSION
A version number for a shared library. By default, the shared library version
number is one (libName.so.1), so this variable is not needed unless you want to
build an alternate version of the shared library.
SUBDIRS
A list of subdirectories of the current directory in which the build system looks
for a makefile and tries to build the default target. If SUBDIRS is not defined, 5
the system tries to build the default target for every subdirectory of the current
directory that has a makefile in it. EXCLUDE_SUBDIRS overrides SUBDIRS.
TOOL
The compiler and toolchain used. The Wind River (Diab) and GCC (GNU)
compilers are supported. TOOL can also specify compilation options for
endianness or floating-point support.
VXE_DIR
The output subdirectory for executable files and shared libraries. Defaults to
target/usr/root/CPUtool/bin/ (executables) or target/usr/root/CPUtool/lib/
(shared libraries); for example, target/usr/root/PPC32diab/bin/.
For further information on these make variables, see the VxWorks Application
Programmer’s Guide.
For information on the supported values for the CPU and TOOL make variables,
see the VxWorks Architecture Supplement: Building Applications.
5.13 Running RTP Applications

You can download RTP applications from the host system or store them in a target
file system, and start them automatically or interactively. For information on these
topics, see the VxWorks Application Programmer’s Guide: RTP Applications, the
VxWorks Kernel Programmer’s Guide: Target Tools, the Wind River Workbench Host
Shell User’s Guide, the Wind River Workbench by Example guide, and the VxWorks
Kernel Shell Command Reference.
69
VxWorks
70
6
Configuring and Building
VxWorks Using config.h
6.1 Introduction 71
6.2 Using config.h to Configure VxWorks 72
6.3 Configuration Examples 73
6.4 Using make 74
6.1 Introduction
Wind River recommends using either Workbench or the vxprj command-line
facility to configure and build VxWorks. The legacy method using bspDir/config.h
to configure VxWorks and bspDir/make to build it has been deprecated for most
purposes, and you cannot use it for multiprocessor (SMP and AMP) development.
Note that the config.h/make method is often referred to simply as a BSP build.
However, you must still use the config.h method for the following:
■
Some middleware products (see the Platform release notes for further
information).
■
Boot loaders, when the BSP does not support the PROFILE_BOOTAPP
configuration profile.
71
VxWorks
You can also use the config.h method for uniprocessor BSP development prior to
the CDF (configuration description file) development, which is required for
configuration with vxprj and Workbench.
! CAUTION: The config.h/make (BSP build) method does not work for SMP and
AMP systems, and does not work for most Platform products.
6.2 Using config.h to Configure VxWorks

In the absence of CDFs (configuration description files), you can configure a boot
loader or VxWorks image using the config.h file. For example, you can select a
different network driver, or networking components can be removed if the system
does not require networking to boot or to operate.
In general, you should only configure a build manually if it is not already set up to
use vxprj or Workbench.
To add or remove components from a boot loader or VxWorks image, you must use
two BSP configuration files: configAll.h (for reference purposes only) and
config.h:
installDir/vxworks-6.x/target/config/all/configAll.h
installDir/vxworks-6.x/target/config/bspName/config.h
The configAll.h file provides the default VxWorks configuration for all BSPs. The
INCLUDED SOFTWARE FACILITIES section of this header file lists all components
that are included in the default configuration. The EXCLUDED FACILITIES section
lists those that are not. To add or remove components from a kernel configuration,
examine the configAll.h file to determine the default, then change the default for
a specific BSP by editing the config.h file for that BSP, defining or undefining the
appropriate components.
The config.h header file includes definitions for the following parameters:
■
Default boot parameter string for boot ROMs.
■
Interrupt vectors for system clock and parity errors.
■
Device controller I/O addresses, interrupt vectors, and interrupt levels.
■
Shared memory network parameters.
72
6 Configuring and Building VxWorks Using config.h
6.3 Configuration Examples
■
Miscellaneous memory addresses and constants.
The config.h file overrides any setting in the configAll.h file. You should never
edit the configAll.h file.
! CAUTION: Do not edit the configAll.h file. Any changes that you make will affect
all BSPs. You should only edit the config.h files in the individual BSP directories.
6.3 Configuration Examples

The following examples draw from configAll.h and from specific BSPs.
6.3.1 Removing Network Support
The INCLUDED SOFTWARE FACILITIES section of configAll.h has the following

entry for the core networking component:
#define INCLUDE_NETWORK /* network subsystem code *
If you are creating a boot loader for a wrSbc8560 board that does not require
networking, you would add the following line to the config.h file in
installDir/vxworks-6.x/target/config/wrSbc8560:
#undef INCLUDE_NETWORK
6.3.2 Adding RTP Support
RTP (real-time process) support is not included by default in BSP builds. Even
though the line
#define INCLUDE_RTP
appears in configAll.h, it is in the EXCLUDED FACILITIES section (wrapped in an

#if FALSE block).
If you want to include RTP support, you need to define the appropriate macros in
config.h. For example (from the simpc BSP):
#define INCLUDE_RTP /* Real Time Process */
#define INCLUDE_RTP_APPL_INIT_BOOTLINE /* RTP bootline Facility */
73
VxWorks
#ifdef INCLUDE_RTP
#define INCLUDE_SC_POSIX /* POSIX system calls */
#endif /* INCLUDE_RTP */
6.4 Using make

The recommended way of building kernel configuration projects is to use vxprj or
the Wind River Workbench. You can build VxWorks projects of other types from
the IDE. If you decide to build a project by invoking the make utility directly, and
especially if you edit the makefile, you should discard any generated project (.wpj
or .wrproject) files and no longer use the Workbench project management tools.
The wrenv environment utility automatically configures the correct version of
make, and Workbench-generated makefiles contain information about build tools,
target CPUs, and compiler options. Hence you should be able to build a project
created by vxprj, cmpScriptLib, or Wind River Workbench simply by moving to
the project’s parent directory and entering make from the command prompt. If the
project is set up to support multiple compilers or target CPUs, you may need to
specify values for make variables on the command line; for example:
% make TOOL=diab
On Windows, the make utility, as configured by wrenv, executes the Z shell (zsh,
installed with the Workbench tools as sh.exe). On UNIX, the make utility executes
whatever shell program is invoked by the command sh.
NOTE: Your compiler installation may include a copy of dmake, an alternative

open-source make utility. This make utility is used only for building libraries
shipped with the standalone Wind River Compiler toolchain. VxWorks projects,
whether compiled with GCC or the Wind River Compiler, should be managed
with make.
For complete information about make, see the GNU Make manual.
6.4.1 Makefile Details
Each BSP has a makefile for building VxWorks. This makefile, called Makefile, is
abbreviated to declare only the basic information needed to build VxWorks with
74
6.4 Using make
the BSP. The makefile includes other files to provide target and VxWorks specific
rules and dependencies. In particular, a file of the form depend.bspName is
included. The first time that make is run in the BSP directory, it creates the
depend.bspName file.
The Makefile in the BSP directory is used only when building from the traditional
command line. It is not used when building projects with vxprj or Wind River
Workbench. Each build option for a project has its own makefile that the tool uses
to build the project modules.
6
There are a number of different VxWorks image targets that can be created using
the Makefile, including vxWorks (a downloadable image that executes from
RAM), and vxWorks.st (a standalone image that includes a symbol table). In
addition, you can build VxWorks images that can be stored in ROM as well as
images that can be executed from ROM. In addition to VxWorks images, you can
build boot loader images that are VxWorks images configured with a boot loader
as the application. For details on VxWorks image types, see the Boot Sequence
section of the Wind River VxWorks BSP Developer’s Guide: Overview of a BSP.
When projects are created from a BSP, the BSP makefile is scanned once and the
make parameters are captured into the project. Any changes made to the BSP
makefile after a project has been created do not affect that project. Only projects
built from the BSP after the change is made are affected.
Customizing the VxWorks Makefile
The BSP makefile provides several mechanisms for configuring the VxWorks
build. Although VxWorks configuration is more commonly controlled at
compile-time by macros in configAll.h and bspName/config.h.
Most of the makefile macros fall into two categories: macros intended for use by
the BSP developer, and macros intended for use by the end user. The needs of these
two audiences differ considerably. Maintaining two separate compile-time macro
sets lets the make separate the BSP-specific requirements from user-specific
requirements.
Macros containing EXTRA in their name are intended for use by the BSP developer
to specify additional object modules that must be compiled and linked with all
VxWorks images.
Macros containing ADDED in their name are intended for use by the end-user on
the make command line. This allows for easy compile time options to be specified
by the user, without having to repeat any BSP-specific options in the same macro
declaration.
75
VxWorks
Commonly Used Makefile Macros
Of the many makefile macros, this document discusses only the most commonly
used.
MACH_EXTRA
You can add an object module to VxWorks by adding its name to the skeletal
makefile. To include fooLib.o, for example, add it to the MACH_EXTRA definition
in Makefile. This macro causes the linker to link it into the output object.
Finally, regenerate VxWorks with make. The module will now be included in all
future VxWorks builds. If necessary, the module will be made from fooLib.c or
fooLib.s using the .c.o or .s.o makefile rule.
MACH_EXTRA can be used for drivers that are not included in the VxWorks driver
library. BSPs do not usually include source code for device drivers; thus, when
preparing your system for distribution, omit the driver source file and change the
object file’s name from .o to .obj (update the makefiles, too). Now the end user can
build VxWorks without the driver source, and rm *.o will not remove the driver’s
object file.
LIB_EXTRA
The LIB_EXTRA makefile variable makes it possible to include library archives in

the VxWorks build without altering the standard VxWorks archive or the driver
library archive. Define LIB_EXTRA in Makefile to indicate the location of the extra
libraries.
The libraries specified by LIB_EXTRA are provided to the link editor when building
any VxWorks or boot ROM images. This is useful for third-party developers who
want to supply end users with network or SCSI drivers, or other modules in object
form, and find that the MACH_EXTRA mechanism described earlier in this chapter
does not suit their needs.
The extra libraries are searched first, before Wind River libraries, and any
references to VxWorks symbols are resolved properly.
EXTRA_INCLUDE
The makefile variable EXTRA_INCLUDE is available for specifying additional

header directory locations. This is useful when the user or BSP provider has a
separate directory of header files to be used in addition to the normal directory
locations.
EXTRA_INCLUDE = -I../myHdrs
76
6.4 Using make
The normal order of directory searching for #include directives is:

$(INCLUDE_CC) (reserved for compiler specific uses)
$(EXTRA_INCLUDE)
.
$(CONFIG_ALL)
$(TGT_DIR)/h
$(TGT_DIR)/src/config
$(TGT_DIR)/src/drv
EXTRA_DEFINE 6
The makefile variable EXTRA_DEFINE is available for specifying compile time
macros required for building a specific BSP. In the following example the macro
BRD_TYPE is given the value MB934. This macro is defined on the command line
for all compiler operations.
EXTRA_DEFINE = -DBRD_TYPE=MB934
By default a minimum set of macro names are defined on the compiler command
line. This is primarily used to pass the same memory addresses used in both the
compiling and linking operations.
These default macro definitions include:
-DCPU=$(CPU)
ADDED_CFLAGS
Sometimes it is inconvenient to modify config.h to control VxWorks configuration.

ADDED_CFLAGS is useful for defining macros without modifying any source
code.
Consider the hypothetical Acme XYZ-75 BSP that supports two hardware
configurations. The XYZ-75 has a daughter board interface, and in this interface
either a Galaxy-A or a Galaxy-B module is installed. The drivers for the modules
are found in the directory src/drv/multi.
The macro GALAXY_C_FILE determines which driver to include at compile-time.
The file named by GALAXY_C_FILE is #included by sysLib.c.
The default configuration (Galaxy-A module installed) is established in config.h:
#ifndef GALAXY_C_FILE
#define GALAXY_C_FILE "multi/acmeGalaxyA.c"
#endif /* GALAXY_C_FILE */
When make is called normally, VxWorks supports the XYZ-75 with the Galaxy-A
module installed. To override the default and build VxWorks for the
XYZ-75/Galaxy-B configuration, do the following:
77
VxWorks
% make ADDED_CFLAGS=’-DGALAXY_C_FILE=\"multi\/acmeGalaxy02.c\"’ vxWorks
For ease of use, you can encapsulate the lengthy command line within a shell script
or independent makefile.
To ensure that a module is incorporated in vxWorks, remove the module’s object
file and vxWorks before running make.
ADDED_MODULES
The ADDED_MODULES makefile variable makes it possible to add modules to

VxWorks without modifying any source code.
While MACH_EXTRA requires the makefile to be modified, ADDED_MODULES
allows one or more extra modules to be specified on the make command line. For
example, to build VxWorks with the BSP VTS support library included, copy
pkLib.c to the target directory and enter the following:
% make ADDED_MODULES=pkLib.o vxWorks
One disadvantage of using ADDED_MODULES is that makefile dependencies are

not generated for the module(s). In the above example, if pkLib.c, pkLib.o, and
VxWorks already exist, you must remove pkLib.o and vxWorks before running
make to force the latest pkLib.c to be incorporated into VxWorks.
CONFIG_ALL
Under extreme circumstances, the files in the config/all directory might not be
flexible enough to support a complex BSP. In this case, copy all the config/all files
to the BSP directory (config/bspName) and edit the files as necessary. Then redefine
the CONFIG_ALL makefile variable in Makefile to direct the build to the altered
files. To do this, define CONFIG_ALL to equal the absolute path to the BSP’s
config/bspName directory as shown in the following example:
CONFIG_ALL = $(TGT_DIR)/config/bspName/
The procedure described above works well if you must modify all or nearly all the
files in config/all. However, if you know that only one or two files from config/all
need modification, you can copy just those files to the BSP’s config/bspName
directory. Then, instead of changing the CONFIG_ALL makefile macro, change one
or more of the following (which ever are appropriate).
USRCONFIG
The path to an alternate config/all/usrConfig.c file.
BOOTCONFIG
The path to an alternate config/all/bootConfig.c file.
78
6.4 Using make
BOOTINIT
The path to an alternate config/all/bootInit.c file.
DATASEGPAD
The path to an alternate config/all/dataSegPad.s file.
CONFIG_ALL_H
The path to an alternate config/all/configAll.h file.
TGT_DIR
The path to the target directory tree, normally $(WIND_BASE)/target. 6
COMPRESS
The path to the host’s compression program. This is the program that
compresses an executable image. The binary image is input through stdin,
and the output is placed on the stdout device. This macro can contain
command-line options for the program if necessary.
BINHEX
The path to the host’s object-format-to-hex program. This program is
called using HEX_FLAGS as command line options. See
target/h/make/rules.bsp for actual calling sequence.
HEX_FLAGS
Command line options for the $(BINHEX) program.
BOOT_EXTRA
Additional modules to be linked with compressed ROM images. These
modules are not linked with uncompressed or ROM-resident images, just
compressed images.
EXTRA_DOC_FLAGS
Additional preprocessor options for making man pages. The default
documentation options are -DDOC -DINCLUDE_SCSI. If
EXTRA_DOC_FLAGS is defined, these options are passed to the man page
generation routines in addition to the default options.
6.4.2 Building Custom Boot Loaders
Once a boot loader is configured, you can build the custom boot loader by running
make bootrom in the BSP directory. There are a variety of boot loader image types,
including the compressed bootrom that executes from RAM, the uncompressed
bootrom_uncmp (which also executes from RAM), and the bootrom_res (which
executes from ROM). For more information, see the VxWorks Kernel Programmer’s
Guide.
79
VxWorks
80
Index
Symbols B
symbols - see assignment operators, asterisk, at, backslashes 2
backslashes, quotation marks, slashes, BSP
spaces build method (deprecated) 71
defined 12
documentation 12
make variables 48
A build environment
custom, for RTP applications 61
ADDED_C++FLAGS 48, 66
kernel applications 43
ADDED_CFLAGS 66
RTP applications 53
ADDED_CFLAGS
build rules
modifying run-time 48
changing 25
ADDED_CLEAN_LIBS 66
defined 22
ADDED_DYN_EXE_FLAGS 66
examining 24
ADDED_LIB_DEPS 67
VxWorks 22
ADDED_LIBS 66
build specifications
ADDED_SHARED_LIBS 67
defined 22
application modules
examining 24
make variables 48
setting 24
makefiles 43
VxWorks 22
applications
building
kernel-mode, see kernel applications
customized VxWorks source code 36
user mode, see RTP applications
RTP applications 58
81
VxWorks
bundles default build specifications 22

adding to projects 16 delete (vxprj) 15
defined 16 dependencies, components 20
listing and examining 19 development shell - see wrenv
removing from projects 17 diab
see also Wind River Compiler
specifying compiler with vxprj 14
diff
C vxprj component 20
vxprj parameter 21
.cdf files
DOC_FILES 67
components 16
documentation
check (vxprj component) 20
BSPs 12
cmpTest 20
compiler 2
compiler
generating 67
documentation 2
vxprj 12
GNU 1
VxWorks 1
option flags (C) 66
VxWorks Simulator 14
option flags (C++) 66
Workbench 1
options for dynamic RTP applications 64
-DTOOL_FAMILY 67
options for shared objects 64
selecting
TOOL make variable 69
vxprj 13 E
Wind River (Diab) 1
components -e 8
adding to projects 16 environment variables
checking syntax 20 displaying with wrenv 9
dependencies 20 setting with wrenv 6
listing (projects) 18 error detection 16
removing from projects 17 EXCLUDE_SUBDIRS 67
config.h EXE (make variable) 67
configuration and build method EXE_FORMAT 67
(deprecated) 71 EXTRA_INCLUDE 67
configuration parameters
listing and examining 20
setting 17
CPU make variable 44, 54, 67 F
custom build environment
-f 8
RTP applications and libraries 61
files
adding and removing in projects 18
examining source 21
D
-D_VX_TOOL_FAMILY 67
82
Index
G L
GCC (GNU Compiler) 1 LIB_BASE_NAME 68
documentation 2 LIB_DIR 68
gnu LIB_FORMAT 68
specifying compiler with vxprj 13 LIBNAME 67
libraries
kernel-mode, building 42
linking to RTP applications 66
I user-mode (RTP), building 52
linking Index
-i 8
kernel application modules 47
image types, VxWorks 22
kernel application modules with VxWorks 47
include files, using 43
linux (simulator BSP) 14
LOCAL_CLEAN 68
LOCAL_RCLEAN 68
K
kernel applications
about building 42
M
build environment 43
make rules
building for default SMP system 46
RTP applications and libraries 54
building for default UP system 45
make utility 1
building for library variants 45
make variables 66
building for VSB-based system 46
for kernel applications and libraries 48
example makefile 43
for RTP applications and libraries 66
linking modules 47
setting CPU and TOOL 44, 54
linking modules with VxWorks 47
makefile
make variables for 48
running 49
RTP applications 54, 58, 59
kernel configuration projects
RTP libraries 54, 55, 56
building
makefiles
vxprj 22
changing name 18
creating
include files
vxprj 12
application modules, and 43
kernel libraries
variables, include file
about building 42
customizing run-time, for 47, 48
make variables for 48
vxprj-generated 14
kernel shell 16
make-rule files 54
kernel-mode applications, see kernel applications
O
-o 9
83
VxWorks
OBJ_DIR 68 RTP applications

object files about building 52
specifying build output 68 build environment 53
OBJS 68 building 58
dynamic, compiler options 64
make rules 54
make variables 66
P makefile 54, 58, 59
RTP libraries
packages
about building 52
displaying with wrenv 9
building 55
parameter (vxprj) 17
make rules 54
POSIX 16
make variables 66
print_compatible (wrenv -o) 9
makefile 54, 55, 56
print_env (wrenv -o) 9
rules.library 54
print_package_name (wrenv -o) 9
and LOCAL_CLEAN 68
print_packages (wrenv -o) 9
and LOCAL_RCLEAN 68
print_vars (wrenv -o) 9
rules.rtp 54
-profile 15
and LOCAL_CLEAN 68
PROFILE_DEVELOPMENT 15
and LOCAL_RCLEAN 68
profiles
run (wrenv -o) 9
creating projects 15
running
defined 15
listing and examining 19
projects
building 42, 52
vxprj 22 S
comparing
components 20 shared libraries
parameters 21 compiler options for 64
copying 14 linking to RTP applications 67
deleting 15 shell
vxprj 12 development 5
simpc 14
simulator (VxWorks)
BSPs 14
Q documentation 14
kernel configuration projects 14
quotation marks
SL_INSTALL_DIR 68
on command line 17
SL_VERSION 69
slashes
UNIX and Windows 2
R .so files 67
solaris (simulator BSP) 14
-r linker option 47 source code, building VxWorks 36
remove (vxprj) 17
84
Index
spaces changing CPU 32

on command line 17 creating 28
SUBDIRS 69 deleting 35
symbols - see assignment operators, asterisk, at, reconfiguring 31
backslashes, quotation marks, slashes, selecting options 30
spaces using with VIPs 35
VIP association identification 35
VIP-VSB validation 36
VxWorks image types 22
T VxWorks
build environment 53 Index
TOOL make variable 44, 54, 69
build environment, kernel applications 43
configuration and build 11
documentation 1
U image types 22
linking kernel application modules with 47
UNIX linking kernel applications with 47
conventions 2 VxWorks image projects
user mode applications, see RTP applications build rules 22
build specifications 22
building 22
creating 12
V deleting 15
getting information 18
variables image types 22
displaying with wrenv 9 modifying 16
environment 6, 9 working with 12
VIPs,see VxWorks image projects VxWorks Simulator
VSBs, see VxWorks source build projects see simulator
VXE_DIR 69 VxWorks source build projects
vxprj basic steps 27
documentation 12 BSP and CPU options 28
VIPs building 34
build rules 22 building kernel applications for 46
build specification 22 changing BSP 33
building projects 22 changing CPU 32
creating 12 creating 28
deleting 15 deleting 35
information about 18 reconfiguring 31
managing 12 selecting options 30
modifying 16 using with VIPs 35
VSBs 26 VIP association identification 35
basic steps 27 VIP-VSB validation 36
BSP and CPU options 28 working with 26
building 34
changing BSP 33
85
VxWorks
VxWorks source code

building 36
W
Wind River Compiler 1
Windows
conventions 2
Workbench
documentation 1
.wpj files
components 16
wrenv
how it works 7
options 8
overview 5
setting environment variables 6
86

Vxworks: Command-Line Tools User'S Guide

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Vxworks: Command-Line Tools User'S Guide

Caricato da

Copyright:

Formati disponibili

VxWorks Command-Line Tools User's Guide, 6.

COMMAND-LINE TOOLS USER'S GUIDE

toll free (U.S.): (800) 545-WIND

VxWorks Command-Line Tools User's Guide, 6.7

1.1 Introduction ............................................................................................................. 1

1.2 Related Documentation ....................................................................................... 2

2 Setting Environment Variables ........................................................... 5

2.1 Introduction ............................................................................................................. 5

2.2 Setting Environment Variables With wrenv ................................................... 6

2.3 How wrenv Works ................................................................................................. 7

2.4 wrenv Command Options .................................................................................... 8

3 Configuring and Building VxWorks .................................................... 11

3.1 Introduction ............................................................................................................ 11

3.2 Working With VxWorks Image Projects: VIPs ................................................ 12

3.2.2 Creating VxWorks Image Projects ........................................................ 12

3.3 Working With VxWorks Source Build Projects: VSBs ................................... 26

3.3.7 Changing the CPU for a VSB Project .................................................... 32

3.4 Building Customized VxWorks Source Code .................................................. 36

4 Building Kernel Applications and Libraries ...................................... 41

4.1 Introduction ........................................................................................................... 42

4.2 About Building Kernel Applications and Libraries ....................................... 42

4.3 Setting Environment Variables ............................................................................ 42

4.4 Using the VxWorks Build Environment ........................................................... 43

4.5 Example Makefile for a Kernel Application .................................................... 43

4.6 Setting CPU and TOOL Make Variables .......................................................... 44

4.7.2 Building Applications With Default VxWorks SMP Libraries .......... 46

4.8 Linking Kernel Application Modules ............................................................... 47

4.9 Linking Kernel Application Modules With VxWorks ................................... 47

4.10 make Variables for Kernel Applications and Libraries ................................. 48

4.11 Running Kernel Applications ............................................................................. 49

5 Building RTP Applications and Libraries ........................................... 51

5.1 Introduction ............................................................................................................ 52

5.2 About Building RTP Applications and Libraries ............................................ 52

5.3 Setting Environment Variables ............................................................................ 53

5.4 Using the VxWorks Build Environment ........................................................... 53

5.5 Make Rules for RTP Applications and Libraries ............................................ 54

5.6 Setting CPU and TOOL Make Variables .......................................................... 54

5.7 Top-Level Makefile for Applications and Libraries ....................................... 54

5.8 Building RTP Libraries ......................................................................................... 55

5.9 Building RTP Applications ................................................................................. 58

5.10 Using a Custom Build Environment .................................................................. 61

5.12 Make Variables for RTP Applications and Libraries ..................................... 66

5.13 Running RTP Applications ................................................................................. 69

6 Configuring and Building VxWorks Using config.h .......................... 71

6.1 Introduction ............................................................................................................ 71

6.2 Using config.h to Configure VxWorks ............................................................... 72

6.3 Configuration Examples ....................................................................................... 73

6.4 Using make .............................................................................................................. 74

1.2 Related Documentation

2.2 Setting Environment Variables With wrenv

Solaris and Linux

Setting Environment Variables Without Spawning a Shell

2.3 How wrenv Works

! CAUTION: Do not edit the install.properties installation properties file.

2.4 wrenv Command Options

Table 2-1 Options for wrenv

Option Meaning Example

-e Do not redefine existing environment variables. % wrenv.sh -p vxworks-6.x -e

-i path Specify the location of install.properties. % wrenv.sh -p vxworks-6.x -i

Table 2-1 Options for wrenv (cont’d)

Option Meaning Example 2

run C:\> wrenv -p vxworks-6.x -o

print_varsa C:\> wrenv -o print_vars