VxWorks Command-Line Tools User's Guide, 6.7

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.2 Setting Environment Variables ...... 28 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.4 Setting Environment Variables ...... 38 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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

! 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 /install.properties (Overrides the default method of finding directoryPath 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 print_package_name Use with -r. Show the name of the package in the specified root directory.

9 VxWorks Command-Line Tools User's Guide, 6.7

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= environment settings. Overrides directory 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 *.sh [args] environment. (Does not open a new shell.) Must be 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 Command-Line Tools User's Guide, 6.7

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 3.2 Working With VxWorks Image Projects: VIPs

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 Command-Line Tools User's Guide, 6.7

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 3 Configuring and Building VxWorks 3.2 Working With VxWorks Image Projects: VIPs

% 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 Command-Line Tools User's Guide, 6.7

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 3 Configuring and Building VxWorks 3.2 Working With VxWorks Image Projects: VIPs

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 If no project file is specified, vxprj looks for a .wpj file in the current directory. For 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 Command-Line Tools User's Guide, 6.7

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 If no project file is specified, vxprj looks for a .wpj file in the current directory. For 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 3 Configuring and Building VxWorks 3.2 Working With VxWorks Image Projects: VIPs

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 Command-Line Tools User's Guide, 6.7

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 ... ] If no project file is specified, vxprj looks for a .wpj file in the current directory. If 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 ... ] If no project file is specified, vxprj looks for a .wpj file in the current directory. For 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 3 Configuring and Building VxWorks 3.2 Working With VxWorks Image Projects: VIPs

vxprj parameter list [projectFile] [pattern] If no project file is specified, vxprj looks for a .wpj file in the current directory. If 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]] If no project file is specified, vxprj looks for a .wpj file in the current directory. If 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 Command-Line Tools User's Guide, 6.7

If no project file is specified, vxprj looks for a .wpj file in the current directory. If 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 3 Configuring and Building VxWorks 3.2 Working With VxWorks Image Projects: VIPs

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 Command-Line Tools User's Guide, 6.7

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 If no project file is specified, vxprj looks for a .wpj file in the current directory. For example, the following command changes the current build specification of myproj.wpj to default_romCompress:

24 3 Configuring and Building VxWorks 3.2 Working With VxWorks Image Projects: VIPs

% 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 If no project file is specified, vxprj looks for a .wpj file in the current directory. For 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 Command-Line Tools User's Guide, 6.7

If no project file is specified, vxprj looks for a .wpj file in the current directory. If 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 3 Configuring and Building VxWorks 3.3 Working With VxWorks Source Build Projects: VSBs

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 Command-Line Tools User's Guide, 6.7

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.2 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.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 3 Configuring and Building VxWorks 3.3 Working With VxWorks Source Build Projects: VSBs

-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 _2 automatically using the original project directory name with 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-Line Tools User's Guide, 6.7

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 3 Configuring and Building VxWorks 3.3 Working With VxWorks Source Build Projects: VSBs

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 Command-Line Tools User's Guide, 6.7

-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. 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. The options have the same meaning as when used to create a project (see 3. Configuring and Building VxWorks), with the following additions and differences: -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.

32 3 Configuring and Building VxWorks 3.3 Working With VxWorks Source Build Projects: VSBs

-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. 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 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.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). 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. The options have the same meaning as when used to create a project (see 3. Configuring and Building VxWorks), with the following additions and differences: -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.

33 VxWorks Command-Line Tools User's Guide, 6.7

-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 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 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. -S Reset a VSB project to the default options. The configuration tool runs silently.

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 Configuring and Building VxWorks 3.3 Working With VxWorks Source Build Projects: VSBs

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 Command-Line Tools User's Guide, 6.7

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 Configuring and Building VxWorks 3.4 Building Customized VxWorks Source Code

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 Command-Line Tools User's Guide, 6.7

SMP Kernel installDir/vxworks-6.x/target/src 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.4 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.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 3 Configuring and Building VxWorks 3.4 Building Customized VxWorks Source Code

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: installDir/vxworks-6.x/target/src 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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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

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.

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

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 Command-Line Tools User's Guide, 6.7

# 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 For information about the CPU and TOOL variables, see the VxWorks Architecture Supplement.

44 4 Building Kernel Applications and Libraries 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 For information about the CPU and TOOL variables, see the VxWorks Architecture Supplement.

45 VxWorks Command-Line Tools User's Guide, 6.7

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 application’s makefile:

make CPU=cpuType TOOL= toolchain VXBUILD=SMP The VXBUILD=SMP ensures that the application will be linked against the default SMP libraries. For information about the CPU and TOOL variables, see the VxWorks Architecture 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 application’s makefile:

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. For information about the CPU and TOOL variables, see the VxWorks Architecture 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 Building Kernel Applications and Libraries 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 Command-Line Tools User's Guide, 6.7

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 Building Kernel Applications and Libraries 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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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 5.3 Setting Environment Variables

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

5

5.4 Using the VxWorks Build Environment

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 Command-Line Tools User's Guide, 6.7

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 Building RTP Applications and Libraries 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.

5

5.8 Building RTP Libraries

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 Command-Line Tools User's Guide, 6.7

$(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 5 Building RTP Applications and Libraries 5.8 Building RTP Libraries

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 Command-Line Tools User's Guide, 6.7

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 include $(WIND_USR)/make/rules.rtp

58 5 Building RTP Applications and Libraries 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 include $(WIND_USR)/make/rules.rtp 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 Command-Line Tools User's Guide, 6.7

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 Building RTP Applications and Libraries 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.

5.10 Using a Custom Build Environment

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 Command-Line Tools User's Guide, 6.7

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. Using the Wind River Compiler: 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 Using the GNU Compiler: 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 Building RTP Applications and Libraries 5.10 Using a Custom Build Environment

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. Using the Wind River Compiler: 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 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 -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. Using the Wind River Compiler: 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 Using the GNU Compiler: 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 Command-Line Tools User's Guide, 6.7

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 Building RTP Applications and Libraries 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 Command-Line Tools User's Guide, 6.7

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 Building RTP Applications and Libraries 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 Command-Line Tools User's Guide, 6.7

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 Building RTP Applications and Libraries 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 Command-Line Tools User's Guide, 6.7

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 Command-Line Tools User's Guide, 6.7

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

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 Command-Line Tools User's Guide, 6.7

#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 Configuring and Building VxWorks Using config.h 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 Command-Line Tools User's Guide, 6.7

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 Configuring and Building VxWorks Using config.h 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 Command-Line Tools User's Guide, 6.7

% 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 Configuring and Building VxWorks Using config.h 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 Command-Line Tools User's Guide, 6.7

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 kernel applications 45 RTP applications 58

81 VxWorks Command-Line Tools User's Guide, 6.7

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 M about building 42 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 kernel applications 43 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 Command-Line Tools User's Guide, 6.7

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 kernel applications 49 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 TOOL make variable 44, 54, 69 Index 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 Command-Line Tools User's Guide, 6.7

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