1. Getting Started

1.1. Prior Required Tool Installations

The GNATbench plug-in for Wind River Workbench requires Workbench, version 3.2.3.x, 3.3.x or 4.x to be installed prior to installing GNATbench itself.

1.2. Installing GNATbench

The file gnatbench-<version>-<platform>-bin.zip is an archive to be installed through the regular Eclipse installation mechanism.

Open Workbench and select ‘Help -> Install New Software’. If this menu is not available, it can be added by selecting on Workbench ‘Window -> Open Perspective -> Advanced Device Development’.

Click on the ‘Add’ button to add a repository. Select ‘Archive’ and navigate to the zip file downloaded from AdaCore. The Location field will then reference that file. You can optionally enter a repository name for future reference, such as “GNATbench” (without the quotes). Click ‘OK’.

The Eclipse installer will then offer the choice of different versions of GNATbench for installation. For Workbench, select ‘AdaCore Plugins for WindRiver Workbench’ item matching your installed Workbench version (see Help > About Wind River Workbench menu to get the right version). Be certain to NOT select other version!

Click ‘Next’ and follow the installation wizard to completion. During the installation process, a dialog can be raised asking if you trust the AdaCore certificates. Check the mark next to the GNATbench certificate and press ‘OK’.

Note: the GNATbench Ada Development User Guide could be accessed after installation, along with all other User Guides, through “Help -> Help Contents” menu entry. Please read the “Before You Begin” section before beginning to use the plug-in.

1.3. GNATbench Installation into Workbench using administrator login

Users can use a Workbench installation managed by an administrator as long as the access rights allow them to read all files of the installation (same group as the user who installed Workbench).

By default, GNATbench and others Workbench extensions are installed in the user’s home directory. If you want to install them in a shared location or in any another location, you need to provide the new location to Workbench.

This is done changing osgi.configuration.area definition. It can be done editing config.ini file or adding a “-configuration <location>” startup option to the Workbench start command.

To check that the location was successfully changed, display osgi.configuration.area property in the configuration page of the Wind River Workbench installation details dialog. (see /Help menu)

See Eclipse Workbench User Guide: Running Eclipse in the Workbench online help for more information on startup options.

1.4. Verifying Correct GNATbench Installation

To verify that GNATbench has been installed into Workbench, use the Workbench Help menu. First, select Help and then “About Wind River Workbench” at the bottom of the selections. Then press the “Installation Details” button at the bottom of the resulting dialog box. Another pop-up dialog box will appear, with tabbed pages showing the installed software, installation history, features, plug-ins, and configuration. Click on the “Plug-ins” tab to show all the installed plug-ins. You should see a number of plug-ins with “AdaCore” shown in the Provider column. If so, installation is likely fine. If not, installation has not occurred or did not complete successfully.

The list of plug-ins will look something (but not exactly) like the figure below.

plug-ins list

Finally, verify that GNATbench is ready to use installed GNAT compilers.

At least one GNAT compiler should be installed to use GNATbench. Please note that no GNAT compiler is installed during GNATbench installation.

If a GNAT compiler was previously installed, check that any required changes to environment during GNAT installation have been done. As an example of such changes, the GNAT tools path should be added to the PATH environment variable. Otherwise, a GNAT compiler installation is requested and any required changes to environment variables must be performed. When a new compiler is installed, a workbench restart may be required to use the latest environment.

Successfully detected compilers are displayed in the /Ada/Toolchains preferences page accessible from the /Window/Preferences menu by selecting the Ada entry and then Toolchains.

toolchains window

If no toolchains are displayed, click on “Scan” button to start a toolchain scan.

1.5. Configuring the Project Build Type (Wind River Workbench 3.x only)

“Flexible” managed builds are used by default in Workbench; the older “Standard” managed builds are deprecated. Standard managed builds are still supported for existing GNATbench projects but, all new GNATbench projects will use Flexible managed builds. Therefore you should disable Standard managed builds so that you do not accidentally select them when creating new projects.

You should also ensure the option to “Create default build targets for new projects using flexible managed build” option remains enabled.

The build facility is controlled using the Wind River “Build” preference page. Set the options on the page as shown below. Note that you will only have to do this preference configuration once unless the preferences are somehow reverted.

enabling standard build pref page

1.6. Introduction

GNATbench supports sophisticated Ada-aware editing and browsing, code generation using GNAT Pro, and Ada-aware debugging.

1.7. Intended Audience

This User’s Guide is intended for Ada software developers using the GNAT Pro Ada tools to develop applications within Workbench.

1.8. Scope

This User’s Guide describes how to use the GNATbench Ada plug-in for Wind River’s Workbench IDE. Specific help is provided for configuring projects, building systems, and debugging under Workbench; please see the corresponding sections for details.

For help with the GNAT Pro compiler and associated tools themselves, see the GNAT Pro documentation corresponding to the specific compiler used. For example, if you are working with the version for Workbench and VxWorks 6 you should read “GNAT Pro for VxWorks 6: Getting Started”, located in the file “gnat_ugx-vx6.txt” shipped with the compiler.

1.9. For Additional Information and Help

Additional help and information is available online from AdaCore via the GNAT Tracker web interface.

1.10. Creating and Building a General Purpose Platform Project on Wind River Workbench 3.x

In this tutorial we will create and build a project for the Wind River General Purpose Platform (GPP) for VxWorks. We have arbitrarily chosen to create a Downloadable Kernel Module (DKM) project; the process is almost exactly the same for Real-Time Process (RTP) projects.

Building a GPP project for Ada development is easy with GNATbench. The wizard will create and configure the project for us and invoking the builder is simply a matter of selecting a command.

1.10.1. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.10.1.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “Advanced Device Development”. Of course you may skip that step if you are already using that perspective.

1.10.1.2. Disabling “Standard” Managed Builds

As of Wind River Workbench 3.0, “Flexible” managed builds are used by default and “Standard” managed builds are deprecated. New GNATbench projects must employ Flexible managed builds.

Therefore, set the options on the Wind River “Build” preference page as shown below to disable Standard managed builds. You must also ensure the option to “Create default build targets for new projects using flexible managed build” remains enabled.

enabling standard build pref page

1.10.2. Creating and Configuring the Project

The first step is to invoke the wizard. In the Application Development perspective, use the menu bar and select “File”, then “New”, and then the list of project types will be displayed in the menu, as shown in the following figure:

new project menu

We want the DKM project creation wizard so we click on the wizard named “VxWorks Downloadable Kernel Module Project” to select it.

The Workbench wizard will open so that you can configure the new DKM project (see figure below).

new DKM project wizard project name page

Enter the name of the new project (we used “test”, again arbitrarily) and choose to have the new project files reside in the default workspace location. Press Next.

Another wizard page will appear, allowing you to select the builder characteristics. You should choose the default “Flexible” build mechanism. Ordinarily the option to use “Standard” managed builds for a new project should be disabled.

Press Next.

new DKM project wizard build setup

The next page (below) allows you to configure the build command and how the result is processed. Take all the defaults and press Next.

new DKM project wizard build support

The next page (below) allows you to configure the build spec for the project. We first press “Deselect All” because we only want one build spec for this tutorial because we only have one type of board available. Then we selected “PPC604gnu” because we have a PPC board and GNAT is a GNU compiler. *Be sure to select the GNU version of any given build spec.*

new DKM project wizard build spec

The next page (below) allows you to configure a build target name and tool for the project. Take all the defaults and press Next.

new DKM project wizard build target

The next page (below) allows you to configure the source code indexer for the project. This is a C++ tool so it is not pertinent to GNATbench projects. You can either take all the defaults and press Next, or disable the indexer altogether. It will not cause difficulties later if you choose to take the defaults. In the figure below we show how to disable the indexer.

new DKM project wizard indexer

You can now press Finish. The new project will be created and you will see it in the Project Explorer, like so:

created project in Project Explorer

Next we convert the new project to support Ada via GNATbench. To do this, we invoke the contextual menu on the new project node and select “New”, then “Other”, as shown below:

tutorial\_file\_new\_other

We then select “Convert to an Ada Project” in the resulting dialog and press OK.

conversion wizard for extending project

The first page of the conversion wizard will appear (shown in the next figure). We enter the name of the new project and select the option to create a new GNAT project file.

tutorial\_conversion\_wizard\_page1.png

We then press Finish. Since we chose to create a new GNAT project file, another wizard is invoked.

The first page asks for the GNAT project unit name. This is not the gpr file name. Rather, it is the name of the unit (the project) within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, for example, by substituting underscores for dashes. If the Eclipse project name is already a legal Ada identifier that name is used unchanged, as in this case:

project conversion project unit name page

The next page asks for the name of the Ada main program, if any:

project conversion ada main subprogram page

Enter the name of the Ada main subprogram – not the file name – and press Next. In this case we have entered the name “test_main”. Note that a main program is not required. We have also chosen to have the wizard generate the source code for the procedure.

The next page allows selection of the directories that will hold sources and intermediate products. We take all the defaults.

tutorial\_project\_dirs\_dialog.png

The final page allows selection of one or more toolchains to be available to the project. The appropriate toolchain for the project’s selected build spec will be enabled by default, but can be changed. Multiple toolchains can be convenient for a number of reasons. For example, a project baseline compiler version can be used to build the actual release but a newer version of the same toolchain can also be used for the sake of improved error analysis. This page also allows selection of a “production” and “debug” scenario, in which different switches are applied (e.g., debugging versus optimization) depending on the current development mode. Other build options are also available on the page. We take the defaults and simply press Finish.

tutorial\_project\_build\_settings\_dialog.png

After conversion, note the presence of the new makefile in the Project Explorer. This is a makefile fragment that will automatically invoke the Ada compiler and other builder tools when the Workbench project builder is invoked. It must not be deleted.

Also note the “src” folder containing the main subprogram. This file will have the name we specified via the unit name, “test_main.adb”, and will contain a procedure with that unit name:

tutorial main subprogram in editor

In a real application we would alter the content of the main subprogram. It is a buildable subprogram, though, without any changes, so for the purpose of this tutorial we can leave it as it is.

1.10.3. Building the Project

In the Project Explorer, right-click to bring up the contextual menu. Select “Build Project”.

tutorial\_menu\_build\_project.png

A popup will appear. Just press “Continue”.

initial popup when building project

The build will then proceed and you can watch it in the Build Console. A sample successful build will look like the following:

content of Build Console after successful build

1.10.4. Congratulations

That’s it! You have created and built a DKM project with Ada sources.

1.11. Creating and Building a General Purpose Platform Project on Wind River Workbench 4.x

In this tutorial we will create and build a project for the Wind River General Purpose Platform (GPP) for VxWorks. We have arbitrarily chosen to create a Downloadable Kernel Module (DKM) project; the process is almost exactly the same for Real-Time Process (RTP) projects.

Building a GPP project for Ada development is easy with GNATbench. The wizard will create and configure the project for us and invoking the builder is simply a matter of selecting a command.

1.11.1. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.11.1.1. Perspective Selection

Use the “Window” menu entry and select “Perspective” then “”Open Perspective”, and finally select “Others..”. Select “System Development”. Of course you may skip that step if you are already using that perspective.

1.11.1.2. Preparing a source build or image project

Prior to be able to create a Downloadable Kernel Module (DKM) or a Real-Time Process (RTP) project, you need to have available a Kernel Image project or a pre-built VSB project.

To create them, see menu “File” > “New” > “Wind River Workbench Project...” and “Build type:” equal to Source Build and Kernel Image

1.11.2. Creating and Configuring the Project

The first step is to invoke the wizard. In the System Development perspective, use the menu bar and select “File”, then “New”, and finally “Wind River Workbench Project...”.

The Workbench wizard will open so that you can choose “Downloadable Kernel Module” build type. (see figure below).

new project wizard DKM build type page

Click “Next >” button.

Another wizard page will appear, allowing you to select the project name and location.

new project wizard DKM project name page

Enter the name of the new project (we used “test_dkm”, arbitrarily) and choose to have the new project files reside in the default workspace location. Press Next.

Another wizard page will appear, allowing you to configure the project context.

new project wizard DKM project context page

Select the project (image project or source build) to be used as base project.

You can now press Finish.

If the current Active Build Spec (see menu “Project” > “Build” > “Set Active Build Spec...”) of your new project is not a GNU spec and a GNU spec is available, change the active build spec to the GNU one.

You may be asked to rebuild the C/C++ index. (see below) Press “Yes” to rebuild. C/C++ Index can be rebuilt later running the menu “Project” > “C/C++ Index” > “Rebuild”.

rebuild C/C++ index

The new project is now ready to be converted to support Ada language, you should see it in the Project Explorer, like so:

The new project will be created and you will see it in the Project Explorer, like so:

created project in Project Explorer

Next convert the new project to support Ada via GNATbench. To do this, select the new project in “Project Explorer” view and invoke “File” > “New” > “Other...” menu.

Then select “Convert to an Ada Project” in the resulting dialog and press “Next >”.

conversion wizard for extending project

The first page of the conversion wizard will appear (shown in the next figure). We enter the name of the new project and select the option to create a new GNAT project file.

tutorial\_conversion\_wizard\_page1.png

We then press Finish. Since we chose to create a new GNAT project file, another wizard is invoked.

The first page asks for the GNAT project unit name. This is not the gpr file name. Rather, it is the name of the unit (the project) within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, for example, by substituting underscores for dashes. If the Eclipse project name is already a legal Ada identifier that name is used unchanged, as in this case:

project conversion project unit name page

The next page asks for the name of the Ada main program, if any:

project conversion ada main subprogram page

Enter the name of the Ada main subprogram – not the file name – and press Next. In this case we have entered the name “test_main”. Note that a main program is not required. We have also chosen to have the wizard generate the source code for the procedure.

The next page allows selection of the directories that will hold sources and intermediate products. We take all the defaults.

tutorial\_project\_dirs\_dialog.png

The final page allows selection of one or more toolchains to be available to the project. The appropriate toolchain for the project’s selected build spec will be enabled by default, but can be changed. Multiple toolchains can be convenient for a number of reasons. For example, a project baseline compiler version can be used to build the actual release but a newer version of the same toolchain can also be used for the sake of improved error analysis. This page also allows selection of a “production” and “debug” scenario, in which different switches are applied (e.g., debugging versus optimization) depending on the current development mode. Other build options are also available on the page. We take the defaults and simply press Finish.

tutorial\_project\_build\_settings\_dialog.png

After conversion, note the presence of the new makefile in the Project Explorer. This is a makefile fragment that will automatically invoke the Ada compiler and other builder tools when the Workbench project builder is invoked. It must not be deleted.

Also note the “src” folder containing the main subprogram. This file will have the name we specified via the unit name, “test_main.adb”, and will contain a procedure with that unit name:

tutorial main subprogram in editor

In a real application we would alter the content of the main subprogram. It is a buildable subprogram, though, without any changes, so for the purpose of this tutorial we can leave it as it is.

1.11.3. Building the Project

In the Project Explorer, right-click to bring up the contextual menu. Select “Build Project”.

tutorial\_menu\_build\_project.png

The following popup may appear. Just press “OK”.

initial popup when building project

The following popup may appear. Just press “Continue”.

set include search path

The build will then proceed and you can watch it in the Build Console. A sample successful build will look like the following:

content of Build Console after successful build

1.11.4. Congratulations

That’s it! You have created and built a DKM project with Ada sources.

1.12. Creating and Building a VxWorks 653 2.x Integration Project

In this tutorial we will create and build a project for Wind River VxWorks 653. We will create and build two application projects and one integration project that encapsulates the two application projects.

Creating a VxWorks 653 project for Ada development is easy with GNATbench and the Wind River wizards for creating 653 projects. The wizards will create and configure the projects for us, with only a little subsequent manual configuration required. Invoking the builder is simply a matter of selecting a command, as usual.

1.12.1. Prerequisites

To use GNAT Pro and GNATbench for VxWorks 653 you need to have the following:

  • Workbench for VxWorks 653
  • GNAT Pro High-Integrity Edition for VxWorks 653
  • GNATbench for Workbench

This tutorial shows how to build an example that is provided with the GNAT compiler. You can follow these steps, if you choose to do so, using the source files and XML files provided there.

Note that in this tutorial, all new projects created through the Workbench wizards must be created in the same workspace.

1.12.2. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.12.2.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “Advanced Device Development”. Of course you may skip that step if you are already using that perspective.

1.12.2.2. Disabling “Standard” Managed Builds

As of Wind River Workbench 3.0, “Flexible” managed builds are used by default and “Standard” managed builds are deprecated. New GNATbench projects must employ Flexible managed builds.

Therefore, set the options on the Wind River “Build” preference page as shown below to disable Standard managed builds. You must also ensure the option to “Create default build targets for new projects using flexible managed build” remains enabled.

enabling standard build pref page

1.12.3. Preliminary Project Setup

In order to ease the configuration process, we will put all the required xml configuration files from the example into a general Eclipse project within the workspace. The sole purpose of this project is to act as a container for these files and to make these files easily accessible.

First create a new project by selecting New and then Project to invoke the new-project wizard selection dialog, expanding the General category (if necessary) there, and then selecting Project under that, as shown below:

tutorial\_653\_general\_project\_wizard

Press Next to choose that specific wizard.

In the resulting dialog box, name this new project “config” and click Finish. The new project will be created.

Next, import the XML files from the directory containing the example into the new “config” project. To do so, right-click on the “config” project node and select “Import...” from the contextual menu. In the resulting dialog box, select File System under the General category:

tutorial\_653\_import\_file\_system

Press Next to invoke the File System wizard. You should then browse to the location of the example provided with your GNAT Pro installation. By default, this location would be “C:\GNATPRO\version#\share\examples\platform#\Workbench\apex_raven”, where “version#” is the GNAT Pro version you installed, such as “6.3.1”, for example; and “platform#” is “powerpc-wrs-vxworksae”, “e500v2-wrs-vxworksae” or “i586-wrs-vxworksae”. The figure below shows the browser window and the selection of the “config” directory there:

tutorial\_653\_import\_file\_system

Once you have selected the “config” directory press OK. Put a check-mark in the box next to “config” in the left-hand pane. The figure below shows the resulting wizard page:

tutorial\_653\_importing\_config\_files

Press Finish and the files will be imported into the “config” project in the workspace:

tutorial\_653\_config\_files\_imported

1.12.4. Updating imported module.xml file

Depending on your installed Wind River VxWorks 653 Platform, the Board Support Package (BSP) used in imported module.xml file may not be supported.

To get the BSP used by imported module.xml file, open the module.xml file and check what file is included in the “CoreOS” xml element.

To get supported BSPs, list subdirectories found in $(WIND_BASE)/target/config directory.

If required, change module.xml to use a supported platform. Only simpc, wrSbc750gx, wrSbcP4080 and wrSbc8548 have been tested with this example; other BSPs may require more substantial changes.

You will have to select the board support package used by module.xml file when configuring the board support package of the project base in “Project Setup” page during VxWorks 653 projects creation.

1.12.5. Creating and Building the Module OS Project

Use the menu bar and select File, then New, and then the list of project types will be displayed in the menu. Select “VxWorks 653 Module Operating System Project”, as shown in the following figure:

tutorial\_653\_new\_mos\_project\_menu

In the resulting dialog box, name the new project “coreOS” and click Next.

tutorial\_653\_new\_mos\_project\_page1

In the next page, select your board support package and build spec. Use the board support package of the imported module.xml file.

On that same page, click on the Advanced button.

Select “Use XML module file” and point it to the “module.xml” file located in the config project we just created.

Set the kernel name to “coreOS”. (It has to match the name given in the “module.xml” file.)

The wizard page will appear as follows:

tutorial\_653\_new\_mos\_project\_page2

Click Finish. The wizard will compute the necessary properties and create the new project. (This may take a little while.) It will appear as follows:

tutorial\_653\_new\_mos\_project\_in\_explorer

Using the “Kernel Configuration” node in the “coreOS” project, you could add any additional components required. No additional components are needed for this tutorial.

Note, however, that if you want to use a terminal server, you must use the Kernel Configuration interface to add the following components (for those not already present):

  • INCLUDE_DEBUG_CORE
  • INCLUDE_EXC_SHOW_INIT
  • INCLUDE_KERNEL_FULL
  • INCLUDE_KERNEL_UTIL
  • INCLUDE_KERNEL_SHOW
  • INCLUDE_LOADER
  • INCLUDE_LOADER_EXTRA
  • INCLUDE_NET_SYM_TBL
  • INCLUDE_BOOT_LINE_INIT
  • INCLUDE_SHELL
  • INCLUDE_SHELL_VI_MODE
  • INCLUDE_SYM_TBL_INIT
  • INCLUDE_USR_FS_UTILS

These components are equivalent to

%WIND_BASE%\target\config\comps\vxWorks\sysTemplates\vxKernel\targetTools.ddf

Next, build the “ADD_NEEDED” target by right-clicking on the target in the Project Explorer and selecting Build Target.

tutorial\_653\_build\_add\_needed

A dialog box may pop up, indicating that the C++ index needs to be rebuilt to reflect these changes. Select Yes.

Note

This C/C++ Index changed dialog may be displayed later.

tutorial\_653\_index\_changed\_dialog

Finally, build the “coreOS” project itself. To do so, right-click on the project node in the Project Explorer and select Build Project:

tutorial\_653\_build\_mos\_project

The build will appear in the Build Console view, as follows:

tutorial\_653\_build\_mos\_project\_console

1.12.6. Creating and Building the Partition OS Project

Use the menu bar and select File, then New, then Project... so that the list of project types will be presented. Expand the “VxWorks 653” category, if necessary, and select “VxWorks 653 Partition Operating System Project”, as shown in the following figure.

tutorial\_653\_new\_pos\_project\_menu

In the resulting dialog box, name the new project “vxSysLib” and click Next.

tutorial\_653\_new\_pos\_project\_page1

In the next page, select your board support package and build spec. Use the board support package of the imported module.xml file.

On that same page, click on Advanced.

Select “Use XML module file” and point it to the “module.xml” file located in the config project.

Ensure the Shared library name is “vxSysLib”. (It must match the name given in the “module.xml” file.)

The wizard page will appear as follows:

tutorial\_653\_new\_pos\_project\_page2

Click Finish. The wizard will compute the necessary properties and create the new project. It will appear as follows:

tutorial\_653\_new\_pos\_project\_in\_explorer

The Ada applications use an APEX library that is not included by default by the Workbench wizard. To include it, take the following steps:

In the Project Explorer, double-click on the “vxSysLib.xml” file located in the “vxSysLib” project to open the file in an editor. Then use the “Source” or “vxSysLib.xml” tab at the bottom of the editor to switch to the source view, and add the following line to the list of interfaces (you can copy and paste this text):

<xi:include href="$(WIND_BASE)/target/vThreads/config/comps/xml/apex.xml"/>

After inserting the line, the file will appear as illustrated below. Line 10 is the newly inserted line:

tutorial\_653\_edited\_newpos\_xml\_file

Save and close the file.

Next, double-click on the project’s “Makefile.vars” file to open an editor, then add the following line to the end of the file (you can copy and paste this text):

SSL_OBJS += apexComponent.o

After inserting the line, the file will appear as illustrated below. Line 13 is the newly inserted line:

tutorial\_653\_edited\_makefilevars\_file

Save and close the file.

You can then build the “vxSysLib” Partition OS project. Right-click on the project node in the Project Explorer and select Build Project:

tutorial\_653\_build\_pos\_menu

The build will appear in the Build Console view as usual.

tutorial\_653\_build\_pos\_project\_console

1.12.7. Creating and Building the Application Projects

There are two Ada applications in this example: “sender” and “receiver”. Each application is located within a separate, dedicated Workbench project.

The following steps are described for the “sender” application. After completing these steps, follow the same steps for the “receiver” application, replacing “sender” by “receiver” in each instance.

Use the menu bar and select File, then New, then Project... so that the list of project types will be presented. Expand the “VxWorks 653” category if necessary, then select “VxWorks 653 Application Project”, as shown in the following figure:

tutorial\_653\_new\_app\_project\_menu

In the resulting dialog box, name the new project “sender” and click Next.

tutorial\_653\_new\_app\_project\_page1

In the next page, select your board support package and build spec. Use the board support package of the imported module.xml file.

On that same page, click on Advanced.

Select “Use XML module file” and point it to the “module.xml” file located in the config project.

Set the Application name to “sender”. (It must match the name given in the “module.xml” file.)

The wizard page will appear as follows:

tutorial\_653\_new\_app\_project\_page2

Click Finish. The wizard will compute the necessary properties and create the new project. It will appear as shown below:

tutorial\_653\_new\_sender\_project\_in\_explorer

1.12.7.1. Import Ada Resources

Next, import the Ada sources from the sender application in the example to this new “sender” project. To do so, we use the file system import wizard just as we did when importing the XML files into the “config” project in the workspace.

Right-click on the “sender” project node and select “Import...” from the contextual menu. In the resulting dialog box, select File System under the General category:

tutorial\_653\_import\_file\_system

Press Next to invoke the specific wizard. The figure below shows the resulting wizard page after the “sender.gpr” file, the “src” sources folder, and the “obj” objects folder have been selected. (The location of the folder containing these files will also be part of the GNAT Pro installation on your system, as was the case earlier.)

tutorial\_653\_importing\_sender\_files

Press Finish and the folders and files will be imported into the project in the workspace:

tutorial\_653\_sender\_files\_imported

The “obj” folder must be manually created because the Import wizard will not import empty directories. To do so, right-click on the “sender” project node, select New, and then select Folder. In the resulting dialog box (see figure below), ensure “sender” is selected, enter the new folder name (“obj”), and press Finish.

tutorial\_653\_create\_obj\_folder

1.12.7.2. Configure for GNATbench Support

Next, the application project should be configured to support Ada specific activities. This support requires the project to be configured for GNATbench use.

Right-click on the “sender” project to invoke the contextual menu, select New, then Other, expand the “Ada” category if necessary, and then finally select “Convert to an Ada Project”.

tutorial\_653\_convert\_to\_gnatbench\_menu

Press Next.

In the resulting dialog, specify “sender” as the project to convert.

On the same page, select “Use a local GNAT project file” and specify “sender.gpr”.

The wizard page, when filled out, will appear as illustrated by the figure below:

tutorial\_653\_convert\_sender\_to\_gnatbench\_page1

Click the Finish button and the project will be enhanced for GNATbench use. The project will appear as follows:

tutorial\_653\_converted\_sender\_project

Note

The application procedure to be invoked from vxMain is automatically added to Workbench USER_APPL_INIT macro. It is provided to Workbench through ADDED_CFLAGS variable. (see below from generated gnat.makefile)

# Cause main generated by gprbuild to be invoked from vxMain
ADDED_CFLAGS = \"-DUSER_APPL_INIT=$(MAIN)()\"

1.12.7.3. Configure for Partition OS Interface Use

You will next indicate that the application project will use the interface provided by the Partition OS.

Right-click on the “sender” project node in the Project Explorer and select “Properties” from the contextual menu. In the resulting dialog, select the “Build Properties” category in the left-hand pane, then the “Build Macros” tab (for PSC 2.3.*) or “Variables” (for PSC 2.4.*) tab on the top. See the figure below.

tutorial\_653\_build\_macros

Click the New button located in the top right of the pane. A dialog will open, as shown in the following figure:

tutorial\_653\_new\_macro\_dialog

As shown, specify a new build macro named “SSL_NAME” and set its value to “vxSysLib”, the name of the Partition OS project. Press OK. The “Build Properties” page will then appear as follows:

tutorial\_653\_sender\_new\_build\_macro

Still in the Properties dialog, select the “Project References” category on the left-hand side of the dialog and insert a check-mark to enable a reference to “vxSysLib”.

tutorial\_653\_sender\_property\_newpos\_ref

Press the OK button to apply the changes and close the Properties dialog.

The projects will now appear differently in the Project Explorer as shown below. Note, in particular, how the “vxSysLib” project is now indicated as a referenced project for “sender”, instead of a stand-alone root project:

tutorial\_653\_sender\_after\_newpos\_ref

1.12.7.4. Select the Ada Runtime Library and APEX Binding

Next open the Scenario Variables view (if not already open). To do so, first invoke the “Window” menu, then the “Show View” submenu. The Scenario Variables view may be presented in the list of views for opening directly, as shown below. If the view is not one of those presented for selection, press “Others...” and “Ada” to get to the Ada-specific views.

tutorial\_653\_open\_scenariovar\_view

Select “Scenario Variables” and then press OK.

Once open, by default the view will appear in the same group as the Build Console, Problems, and Tasks views. See Scenario Variables View for how to set scenario variables in the view. Likewise, see Scenario Variables for the scenario variable concept itself.

Scenario variable can be set in two different modes: either “<set environment to use this value>” or “<set project specific value>”. In this tutorial, we will use the former.

Change the “BINDING” scenario variable from “apex” to “apex_zfp”. You will have to scroll down in the list of values to make that selection, as shown below:

tutorial\_653\_apex\_zfp\_pulldown

Similarly, select “ravenscar-cert” for the “RUNTIME” variable in the Scenario Variables view. (Note that you may need to scroll down, as before, in the list of values. Once set, the variables will look like the following in the view:

tutorial\_653\_sender\_scenariovars\_set

Also select your platform with the “PLATFORM” variable.

You can then build the “sender” project. Right-click on the project node and select “Build Project” as usual. If a dialog popup appears, asking whether to set the include path for the project, simply press “Continue”. This dialog will only appear once.

The project build will appear in the Build Console:

You may need to edit manually sender/receiver gnat.makefile if gprconfig fails detecting C & C++ compiler. Remove C & C++ lines from the gprconfig call.

tutorial\_653\_sender\_project\_build

For the sake of brevity assume we have performed the above steps for the “receiver” project. After doing so, the projects will appear in the Project Explorer as follows:

tutorial\_653\_both\_apps\_in\_explorer

The Scenario Variables view will also show both projects’ scenario variables:

tutorial\_653\_both\_apps\_scenario\_vars

1.12.8. Creating and Building the Integration Project

The final step is to create and build the integration project. To create this project we invoke the project creation wizard again. Use the File menu and select New as usual, and then select “VxWorks 653 Integration Project.”

tutorial\_653\_new\_int\_project\_menu

In the resulting dialog box, name the new project “Integration” and click Next.

tutorial\_653\_new\_int\_project\_page1

In the second wizard page, click on Advanced.

Enable “Create from CPU and XML module file(s)” and specify the “module.xml” file located in the “config” project created earlier. The easiest way is to use the Add button to browse to the file. When completed, the wizard page will appear as follows:

tutorial\_653\_new\_int\_project\_page2

Press Next.

The next wizard page (see below) is the Partition Setup dialog.

tutorial\_653\_new\_int\_project\_partition\_page

The VxWorks 653 2.3 and more recent versions, this dialog is the easiest way to set up the integration project. We will not do so in this tutorial, but if you decide to use it here, be sure to enable the option to include the sender, recever, and other projects as sub-project references. (This is the “Add a reference to the corresponding project” option in the Specify dialogs.)

Instead of using the Partition Setup dialog, you can perform the setup steps manually, and in older versions of VxWorks 653 you will have to do so. Therefore, we describe those steps here, as if you did not use the dialog. Instead, we assume you simply pressed Finish.

The wizard will then construct the new project. It will appear in the Project Explorer as follows:

tutorial\_653\_new\_int\_project\_in\_explorer

In the Project Explorer, invoke the contextual menu on the “Integration” project, select Properties to invoke the dialog, and then select the “Project References” page. Add the module OS, partition OS, and two application projects as references. The page will appear as shown in the next figure after these references are set:

tutorial\_653\_int\_project\_properties

Press OK. In the Project Explorer, the “Integration” project will now show the others as referenced projects nested underneath the Integration project node:

tutorial\_653\_int\_project\_refs

Next, double-click on the “Makefile.vars” file (see the figure above) to open it in an editor. Add the following lines to automatically copy the ”.sm” files to the “Integration” project during builds. You can copy and paste the following lines, but be sure to replace the leading blanks with a single *tab* on the four command lines! That change is absolutely essential: the build will fail otherwise.

coreOS.sm: ../coreOS/$(CPU)gnu.debug/coreOS.sm
        $(CP) $(subst /,$(DIRCHAR),$<) $@

vxSysLib.sm: ../vxSysLib/vxSysLib.sm
        $(CP) $(subst /,$(DIRCHAR),$<) $@

sender.sm: ../sender/$(CPU)gnu/sender/Debug/sender.sm
        $(CP) $(subst /,$(DIRCHAR),$<) $@

receiver.sm: ../receiver/$(CPU)gnu/receiver/Debug/receiver.sm
        $(CP) $(subst /,$(DIRCHAR),$<) $@

After the insertion, the file will appear as follows:

tutorial\_653\_int\_project\_makefilevars\_new

(Note that this marks the end of the manual alternatives to the integration Partition Setup dialog.)

You should also add the following lines to the “Makefile.vars” makefile if you want to build a ROM image (to use GNATemulator, for example). For VxWorks 653 version 2.3 and more recent, see the GNATemulator User Guide section on Workbench for a simpler method.

payloadObjs_rom.o: ../coreOS/$(CPU)gnu.debug_romPayload/payloadObjs_rom.o
        $(CP) $(subst /,$(DIRCHAR),$<) $@

As with the earlier fragment, you can copy and paste the lines above, but be sure to replace the leading blanks with a single *tab* on the command line.

(The file “payloadObjs_rom.o” is built via the “payloadObjs” target in the “coreOS” project.)

Finally, copy the “vxSysLib.xml”, “sender.xml”, and “receiver.xml” files located in the config project to the “Integration” project. To do so, open the “config” project in the Project Explorer, control-click on each of the three files, and then right-click on any one of them to invoke the contextual menu. In the menu, select “Copy”.

tutorial\_653\_copy\_xml\_files

Then go back to the “Integration” project and right-click on the project node. Select “Paste”.

tutorial\_653\_paste\_xml\_files

After copying the files, they will appear in the “Integration” project:

tutorial\_653\_final\_int\_project

You are now ready to build the integration project. Build either the “net” or “rom” targets to finalize compilation of the system. For example, right-click on the “net” target and select “Build Target”:

tutorial\_653\_build\_net

The last part of the build will appear in the Build Console as follows:

tutorial\_653\_build\_net\_console

After building the “net” target, the project will appear in the Project Explorer as shown below:

tutorial\_653\_int\_project\_after\_build\_net

1.12.9. Congratulations

That’s it! You have created and built a VxWorks 653 Integration project with Ada applications.

Note that to start the application, you select schedule 1 using the command “arincSchedSet 1” in the host shell.

1.13. Creating and Building a VxWorks 653-3.x Integration Project

In this tutorial we will create and build a project for Wind River VxWorks 653-3.x. We will create and build two partition operating system projects and one module integration project that encapsulates the two partition operating system projects.

Creating a VxWorks 653-3.x project for Ada development is easy with GNATbench and the Wind River wizards for creating 653-3.x projects. The wizards will create and configure the projects for us, with only a little subsequent manual configuration required. Invoking the builder is simply a matter of selecting a command, as usual.

1.13.1. Prerequisites

To use GNAT Pro and GNATbench for VxWorks 653-3.x you need to have the following:

  • Workbench for VxWorks 653-3.0.1 or later.
  • GNAT Pro High-Integrity Edition for PowerPC VxWorks6/Cert 7.4 or later
  • GNATbench for Workbench 2.10 or later.

This tutorial shows how to build the apex_raven example that is provided with the GNAT Pro High-Integrity Edition for PowerPC VxWorks6/Cert 7.4 or later compiler.

Note that in this tutorial, all new projects created through the Workbench wizards must be created in the same workspace.

1.13.2. Workspace Configuration

Start Workbench.

1.13.2.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “System Development”. Of course you may skip that step if you are already using that perspective.

1.13.3. Preliminary Project Setup

In order to ease the tutorial process, we will put all the required files from the apex_raven example into a general Eclipse project within the workspace. The sole purpose of this project is to act as a container for these files and to make these files easily accessible.

First create a new project by selecting New and then Project... to invoke the new-project wizard selection dialog, expanding the General category (if necessary) there, and then selecting Project under that, as shown below:

tutorial\_653\_general\_project\_wizard

Press Next to choose that specific wizard.

In the resulting dialog box, name this new project “apex_raven” and click Finish. The new project will be created.

Next, import the files from the directory containing the example into the new “apex_raven” project. To do so, right-click on the “apex_raven” project node and select “Import...” from the contextual menu. In the resulting dialog box, select File System under the General category:

tutorial\_653\_import\_file\_system

Press Next to invoke the File System wizard. You should then browse to the location of the example provided with your GNAT Pro High-Integrity Edition for PowerPC VxWorks6/Cert 7.4 or later installation. By default, this location would be “C:\GNATPRO\version#\share\examples\platform#\Workbench\apex_raven”, where “version#” is the GNAT Pro version you installed, such as “7.4.1”, for example; and “platform#” is “powerpc-wrs-vxworks”. The figure below shows the browser window and the selection of the “apex_raven” directory there:

tutorial\_653\_3\_import\_file\_system

Once you have selected the “apex_raven” directory press OK. Put a check-mark in the box next to “apex_raven” in the left-hand pane. The figure below shows the resulting wizard page:

tutorial\_653\_3\_importing\_config\_files

Press Finish and the files will be imported into the “apex_raven” project in the workspace:

tutorial\_653\_3\_files\_imported

If you have imported the apex_raven/config/hardware.xml file, delete it since this file is not compatible with recent vxworks653 versions. After a minor manual update, all hardware.xml files created by Workbench are compatible with this tutorial.

1.13.4. Creating and configuring the Module Integration Project

1.13.4.1. Create the Module Integration Project

Use the menu bar and select File, then New and then Wind River Workbench
Project...

In the resulting dialog box, set the target operating system to VxWorks 653 3.x operating system.

tutorial\_653\_3\_target\_operating\_system

Click Next.

In the next page, select the build type to “Module Integration Project”

tutorial\_653\_3\_module\_integration\_project

Click Next.

In the Project page, set the project name to “tutorial” and click Next.

On the Project Setup page

tutorial\_653\_3\_tutorial\_project\_setup

Set BSP to fsl_p3041_ds

Click Add...

Set the name of the partition to sender, and click OK.

tutorial\_653\_3\_add\_sender\_application

Click again to the Add... button to add the receiver partition.

tutorial\_653\_3\_applications\_added

Click on Finish button to create the tutorial Module Integration project and the sender/receiver Partition Operating System projects.

1.13.4.2. Import config files

If the config folder of apex_raven project contains the hardware.xml file, delete it before starting the import config files task.

Select the config folder of apex_raven project and then copy it to the clipboard.

Select the tutorial module integration project, and paste to the clipboard.

On the “Resource Exists” dialog, click to “Yes to All” to overwrite existing files.

If tutorial/config/hardware.xml file contains ‘uart0poll’ string, then apex_raven/config sender.xml & receiver.xml files should use a device named ‘uart0poll’.

<Device DeviceNameRef="uart0poll"/>

Otherwise, they should use a device named ‘uart0’.

<Device DeviceNameRef="uart0"/>

If it is required update the 2 xml files by changing DeviceNameRef attribute to the expected value.

Note: If sender.xml & receiver.xml are referencing ‘uart0poll’ device which is not part of hardware.xml devices, the tutorial build will fail with a “Device uart0poll does not exist” error. If sender.xml & receiver.xml are referencing ‘uart0’ device and ‘uart0poll’ is part of hardware.xml devices, the tutorial build will fail with an “Interrupt duart1 is assigned to multiple Partitions” error.

In apex_raven/config hardware.xml file, add MaxRefs attribute to the device used in sender.xml & receiver.xml files.

<Device Name="uart0" MaxRefs="unbounded">

or

<Device Name=”uart0poll” MaxRefs=”unbounded”>

Note: If the MaxRefs attribute is missing or invalid, the tutorial build will fail with a “Device uart0 or uart0poll is referenced more than 1 times” error.

Check that apex_raven/config init.xml, sender.xml & receiver.xml files contains “bootapp” strings for VxWorks 653 3.0.x target operating system or “bootapp_vt” for VxWorks 653 3.1.x target operating system. If it is required update the 3 xml files.

Note: If the wrong bootapp string is used, the tutorial build will fail with a “Cannot open bootapp or bootapp_vt file” error.

1.13.5. Configurating Partition Operating System Projects

There are two Ada applications in this apex_raven example: “sender” and “receiver”. Each application is located within a separate and dedicated Partition Operating System project.

The following steps are described for the “sender” application. Follow the same steps for the “receiver” application, replacing “sender” by “receiver” in each instance.

1.13.5.1. Configure sender/receiver kernel configuration

You should configure the kernel you have created to have it calling usrAppInit() (in your usrAppInit.c project file) after startup.

First open the sender kernel configuration editor. The menu to edit the kernel configuration is available in the sender project’s contextual menu.

tutorial\_653\_3\_edit\_kernel\_configuration

Expand the application components node and quick include INCLUDE_USER_APPL component if not already included.

tutorial\_653\_3\_add\_include\_user\_appl

Save (Ctrl+S) the sender kernel configuration.

Do the same for the receiver kernel configuration.

1.13.5.2. Import sender/receiver Ada Resources

Next, import the Ada sources from the sender application in the example to this new “sender” project.

Select all files/folder of sender folder of apex_raven project, and then copy them to the clipboard.

tutorial\_653\_3\_copy\_sender

Select the sender partition operating system project, and paste the clipboard.

tutorial\_653\_3\_paste\_sender

On the “Resource Exists” dialog, click to “Yes to All” to overwrite existing files.

Do the same copy/paste operation to import receiver Ada source files into receiver project.

1.13.5.3. Configure sender/receiver for GNATbench Support

Next, the application projects should be configured to support Ada specific activities. This support requires the project to be configured for GNATbench use.

Right-click on the “sender” project to invoke the contextual menu, select New, then Other, expand the “Ada” category if necessary, and then finally select “Convert to an Ada Project”.

tutorial\_653\_convert\_to\_gnatbench\_menu

Press Next.

In the resulting dialog, specify “sender” as the project to convert.

On the same page, select “Use a local GNAT project file” and specify “sender.gpr”.

The wizard page, when filled out, will appear as illustrated by the figure below:

tutorial\_653\_convert\_sender\_to\_gnatbench\_page1

Click the Finish button and the project will be enhanced for GNATbench use. The project will appear as follows:

tutorial\_653\_3\_converted\_sender\_project

Do the same conversion for the receiver project.

1.13.5.4. Checking sender/receiver projects

The projects should appear in the Project Explorer as follows:

tutorial\_653\_3\_both\_apps\_in\_explorer

Both projects should have the INCLUDE_USER_APPL component included in their kernel configuration.

1.13.5.5. Set BINDING, PLATFORM and RUNTIME scenario variables

Open the Scenario Variables view (if not already open). To do so, first invoke the “Window” menu, then the “Show View” submenu. The Scenario Variables view may be presented in the list of views for opening directly, as shown below. If the view is not one of those presented for selection, press “Others...” and “Ada” to get to the Ada-specific views.

tutorial\_653\_3\_open\_scenariovar\_view

Select “Scenario Variables” and then press OK.

Once open, by default the view will appear in the same group as the Build Console, Problems, and Tasks views. See Scenario Variables View for how to set scenario variables in the view. Likewise, see Scenario Variables for the scenario variable concept itself.

Scenario variable can be set in two different modes: either “<set environment to use this value>” or “<set project specific value>”. In this tutorial, we will use the former.

Change the “BINDING” scenario variable from “apex” to “apex_1.3_zfp”. You will have to scroll down in the list of values to make that selection, as shown below:

tutorial\_653\_3\_apex\_zfp\_pulldown

Similarly, select “ravenscar-cert” for the “RUNTIME” variable in the Scenario Variables view. (Note that you may need to scroll down, as before, in the list of values).

Select also “powerpc-wrs-vxworks” for the “PLATFORM” variable.

Once set, the variables will look like the following in the view:

tutorial\_653\_3\_both\_apps\_scenario\_vars

1.13.5.6. Build tutorial project

You are now ready to build the integration project. Right-click on the tutorial project node and select “Build Project” as usual.

You may be informed that the parallel builds have been enabled.

tutorial\_653\_3\_parallel\_build\_warningr

Click OK to continue the tutorial project build.

At the end of the build a “namespace warning : xmlns: URI ARINC653 is not absolute” error may be reported in tutorial project. Ignore it.

tutorial\_653\_3\_problems\_after\_build

If build failed on “Cannot open bootapp or bootapp_vt file”.

  • remove the tutorial, sender & receiver projects
  • replace in init.xml, sender.xml & receiver.xml files of apex_raven/config folder “bootapp*” strings occurences with bootapp (VxWorks 653 3.0.x) or bootapp_vt (VxWorks 653 3.1)
  • rerun the tutorial.

1.13.6. Congratulations

That’s it! You have created and built a VxWorks 653 3;x Integration project with Ada applications.

1.14. Creating and Building a VxWorks DO-178B Platform Project

In this tutorial we will create and build a “static kernel module” (SKM) project for the Wind River VxWorks DO-178B Platform. The process is very similar to creating a regular downloadable kernel module (DKM) project.

Building a Cert project for Ada development is easy with GNATbench. The wizard will create and configure the project for us and invoking the builder is simply a matter of selecting a command.

1.14.1. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.14.1.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “Advanced Device Development”. Of course you may skip that step if you are already using that perspective.

1.14.1.2. Disabling “Standard” Managed Builds

As of Wind River Workbench 3.0, “Flexible” managed builds are used by default and “Standard” managed builds are deprecated. New GNATbench projects must employ Flexible managed builds.

Therefore, set the options on the Wind River “Build” preference page as shown below to disable Standard managed builds. You must also ensure the option to “Create default build targets for new projects using flexible managed build” remains enabled.

enabling standard build pref page

1.14.2. Creating and Configuring the Project

The first step is to invoke the wizard. In the Application Development perspective, use the menu bar and select “File”, then “New”, and then the list of project types will be displayed in the menu, as shown in the following figure:

tutorial\_cert\_file\_new\_skm

We want the SKM project creation wizard so we click on the wizard named “VxWorks Cert Static Kernel Module Project [Cert kernel]” to select it.

The Workbench wizard will open so that you can configure the new SKM project (see figure below).

tutorial\_cert\_new\_skm\_project\_page1

Enter the name of the new project (we used “demo”, arbitrarily) and choose to have the new project files reside in the default workspace location. Press Next.

Another wizard page will appear, allowing you to select the build type. *You must use the default “Flexible” managed build type.* Ordinarily the option to use “Standard” managed builds for a new project should be disabled, as shown below. If “Standard” managed builds are enabled, do not choose that type of build for the new project.

Press Next.

tutorial\_cert\_new\_skm\_project\_page2

The next page (below) allows you to configure the build command and how the result is processed. Take all the defaults and press Next.

tutorial\_cert\_new\_skm\_project\_page3

The next page (below) allows you to configure the build spec for the project. We first press “Deselect All” because we only want one build spec for this tutorial because we only have one type of board available. Then we selected “PPC604gnu_CERT” because we have a PPC board and GNAT is a GNU compiler. (Note that older versions of VxWorks DO-178B will not offer the “_CERT” build specs.) *Be sure to select the GNU version of any given build spec.*

tutorial\_cert\_new\_skm\_project\_page4

The next page (below) allows you to configure a build target name and tool for the project. Take all the defaults and press Next.

tutorial\_cert\_new\_skm\_project\_page5

The next page (below) allows you to configure the source code indexer for the project. This is a C++ tool so it is not pertinent to GNATbench projects. You can either take all the defaults and press Next, or disable the indexer altogether. It will not cause difficulties later if you choose to take the defaults. In the figure below we show how to disable the indexer.

tutorial\_cert\_new\_skm\_project\_page6

You can now press Finish. The new project will be created and you will see it in the Project Explorer, like so:

tutorial\_cert\_created\_project

Next we convert the new project to support Ada via GNATbench. To do this, we invoke the contextual menu on the new project node and select “New”, then “Other”, as shown below:

tutorial\_cert\_convert\_invocation

We then select “Convert to an Ada Project” in the resulting dialog and press OK.

conversion wizard for extending project

The first page of the conversion wizard will appear (shown in the next figure). We enter the name of the new project and select the option to create a new GNAT project file.

tutorial\_cert\_conversion\_wizard\_page1.png

We then press Finish.

Since we chose to create a new GNAT project file, another wizard is invoked.

The new-project wizard first asks us to specify the unit name of the GNAT project (not the file name), that is, the name within the gpr file.

tutorial\_cert\_project\_unit\_name\_dialog

The next wizard page allows us to specify the name of the main program, if we choose to have one.

tutorial\_cert\_ada\_main\_name\_dialog

Enter the name of the Ada main subprogram – not the file name – in the text entry pane. In this case (above) we have entered the name “demo_main”.

On that same page we have chosen to have the wizard generate the source code for the procedure. You need not do so if you already have a main procedure that you will import later, or if you simply want to write it yourself. Note that we do *not* take the additional option to have the generated main procedure be a “Hello World” example because the code would use constructs outside the language subset supported by the ZFP runtime library. Without this option the generated procedure simply has a null body.

Press Next

The next page allows selection of the directories that will hold sources and intermediate products. We take all the defaults.

tutorial\_project\_dirs\_dialog.png

The final page allows selection of one or more toolchains to be available to the project. The appropriate toolchain for the project’s selected build spec will be enabled by default, but can be changed. Multiple toolchains can be convenient for a number of reasons. For example, a project baseline compiler version can be used to build the actual release but a newer version of the same toolchain can also be used for the sake of improved error analysis. This page also allows selection of a “production” and “debug” scenario, in which different switches are applied (e.g., debugging versus optimization) depending on the current development mode. Other build options are also available on the page. We take the defaults and simply press Finish.

tutorial\_cert\_project\_build\_settings\_dialog.png

After conversion, the project will appear as follows:

tutorial\_cert\_project\_after\_conversion.png

Note the presence of the file named “gnat.makefile” and the file named “scenario.makefile” in the Project Explorer. These are makefiles that will automatically invoke the Ada compiler and other builder tools when the Workbench project builder is invoked. *These files must not be deleted.*

Also note the “src” folder containing the main subprogram. This file will have the name we specified via the unit name, “demo_main.adb”, and will contain a procedure with that unit name:

tutorial\_cert\_main\_subprogram

In a real application we would alter the content of the main subprogram. It is a buildable subprogram, though, without any changes, so for the purpose of this tutorial we can leave it as it is.

1.14.3. Building the Project

In the Project Explorer, right-click to bring up the contextual menu. Select “Build Project”.

tutorial\_cert\_menu\_build\_project.png

A popup will appear. Just press “Continue”.

tutorial\_cert\_build\_popup

The build will then proceed and you can watch it in the Build Console. A sample successful build will look like the following:

tutorial\_cert\_build\_console\_result

1.14.4. Selecting the Run-Time Library

As generated, the “gnat.makefile” content will use the Zero Footprint (ZFP) run-time library, and the other option, the Ravenscar-Cert library, is commented out. This original state is illustrated below, on lines 16 and 17:

tutorial\_cert\_makefile\_original

You may edit the makefile to control the library selection each time you want to change it, or you may use a scenario variable. The latter approach is strongly recommended so we will illustrate it here.

First, modify the makefile (just once) so that lines 16 and 17 are now both commented out, and a new line, 18, is added:

tutorial\_cert\_makefile\_scenario

Save and close the makefile.

Next, edit the gpr file (named “demo.gpr”) to declare the new scenario variable referenced on line 18 of the makefile. In the figure below, we have added lines 3 and 4:

tutorial\_cert\_gprfile\_scenario

Save and close the gpr file.

With these changes in place, the SKM will be built with the ZFP run-time library by default. If you want to build with the ravenscar-cert library, simply change the value of the variable with the GUI via the Scenario Variable view. (See Scenario Variables View for how to set scenario variables in the view. Likewise, see Scenario Variables for the scenario variable concept itself.)

To do so, open the Scenario Variables view (if not already open) by invoking “Window”, then “Show View”, then “Other”:

tutorial\_cert\_open\_scenariovar\_view1

In the resulting dialog pop-up, select “Scenario Variables”:

tutorial\_cert\_open\_scenariovar\_view2

Press OK.

The Scenario variables view will appear, showing the current selection for CERT_RUNTIME to be “zfp”:

tutorial\_cert\_skm\_scenariovars\_before\_set

Click on the arrow to the right of the value to show the pull-down list of possible values for the “CERT_RUNTIME” variable. Select “ravenscar-cert” from the list. Once set, the variable will look like the following in the view:

tutorial\_cert\_skm\_scenariovars\_after\_set

Now, when we build the SKM demo project the ravenscar-Cert runtime library will be used. This change can be seen in the following figure:

tutorial\_cert\_skm\_ravenscar\_build

1.14.5. Integration Within A “Cert Kernel” Image Project

You may integrate an SKM project into a VxWorks Cert image project just as you would in other versions of VxWorks: you right-click on the SKM project and select “Project References”, then “Add as Project Reference...”, and then select the superproject name from the resulting dialog box. Building and cleaning the superproject will then also build and clean the enclosed subprojects. Note that the BSP for the subprojects must be compatible with the image superproject, otherwise those subprojects will be ignored when building.

In addition, however, you must also take the following steps:

  • Edit the “usrAppinit.c” file so that it calls the generated Ada entry point (the name of the Ada main procedure, with an appropriate pragma Export applied)
  • Add the “-nostdlib” switch to the default switches of package Linker in the SKM gpr file

1.14.6. Congratulations

That’s it! You have created and built an SKM project with Ada sources.

1.15. Creating and Building a VxWorks MILS Integration Project

In this tutorial we will create and build a project for Wind River VxWorks MILS. The system comprises two VxWorks Guest OS virtual boards running mixed language Ada/C applications, a virtual board providing multiplexed I/O using AMIO and ‘wrmonitor.exe’, and a High Assurance Environment virtual board running a simple Ada/C mixed language application.

Creating a VxWorks MILS project for Ada development is easy with GNATbench and the Wind River wizards for creating MILS projects. The wizards will create and configure the projects for us, with only a little subsequent manual configuration required. Invoking the builder is simply a matter of selecting a command, as usual.

1.15.1. Prerequisites

To use GNAT Pro and GNATbench for VxWorks MILS you need to have the following:

  • Workbench and VxWorks MILS
  • GNAT Pro High-Integrity Edition for VxWorks MILS
  • GNATbench for Workbench
  • QEMU, on your path and with its BSP installed under your VxWorks MILS installation, if targeting QEMU for MILS.

This tutorial shows how to build an example that is provided with the GNAT compiler. You can follow these steps, if you choose to do so, using the source files and XML files provided there.

Note that in this tutorial, all new projects created through the Workbench wizards must be created in the same workspace.

Steps specific to the use of QEMU for this exercise will appear as needed.

1.15.2. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.15.2.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “Advanced Device Development”. Of course you may skip that step if you are already using that perspective.

1.15.2.2. Disabling “Standard” Managed Builds

As of Wind River Workbench 3.0, “Flexible” managed builds are used by default and “Standard” managed builds are deprecated. New GNATbench projects must employ Flexible managed builds.

Therefore, set the options on the Wind River “Build” preference page as shown below to disable Standard managed builds. You must also ensure the option to “Create default build targets for new projects using flexible managed build” remains enabled.

enabling standard build pref page

1.15.3. Installation Preparation

These steps need only be performed once per board support package.

If your BSP is qemu, make sure it is installed according to the directions that come with its distribution package.

Create the virtual board boot application vbElfBoot.bin by opening the VxWorks MILS Development shell ($WIND_HOME/wrenv.sh -p vxworks-mils-2.1 or %WIND_HOME%\wrenvw.exe -p vxworks-mils-2.1, depending on your development host’s OS).

cd $WIND_HOME/vxworks-mils-vbbooter-1.0

or

cd %WIND_HOME%\vxworks-mils-vbbooter-1.0

make BSP=your BSP name

1.15.4. Integration Project

Use the menu bar and select File, then New, and the list of project types will be displayed in the menu. Select “VxWorks MILS Integration Project”, as shown in the following figure:

tutorial\_mils\_new\_integration\_project\_menu

In the resulting dialog box, name the new project “Integration” and click Next.

tutorial\_mils\_new\_int\_project\_page1

Select the appropriate BSP from the dropdown list. In this case we are targeting QEMU:

tutorial\_mils\_new\_int\_project\_page2

Click Finish. The wizard will compute the necessary properties and create the new project. It will appear as follows:

tutorial\_mils\_new\_int\_project\_in\_explorer

Note the “config” folder in the new project. It contains XML files describing the project configuration.

The example directories and files used in this tutorial (supplied with GNAT Pro) also include a “config” directory containing XML files. These files will be used to update those that are located in the “config” folder within the new project. To do so, we will next import them into the Workbench project.

Right-click on the “Integration” project node and select “Import...” from the contextual menu. In the resulting dialog box, select “File System” under the “General” category:

tutorial\_653\_import\_file\_system

Press Next to invoke the “File System” wizard.

Browse to the MILS example that comes with the compiler. Note that the location of the example will be different from that which is depicted in the figure below. Expand the “Integration” subdirectory and then select the “config” directory within, and, if targeting QEMU, the “qemu-boot” directory. (Make sure you do not select the entire “Integration” directory itself.) Note that the file “qemu-boot/start.s” has been customized for this example system. Do not use the version of the file that comes with the QEMU distribution example.

Also be sure to select “Makefile”. For an integration project, ordinarily you must modify the Makefile generated by Workbench to identify the directories containing the components of the system image (makefile variable PAYLOAD_PATH). The Makefile that comes with this example already takes care of this.

On that same page, enable the “Overwrite existing resources without warning” check-box in the “Options” panel.

The figure below shows the resulting wizard page for the QEMU usage case, after the directories and the Makefile file have been selected and the overwrite option enabled. (The location of the folder containing these files will be part of the GNAT Pro installation on your system.)

tutorial\_mils\_importing\_config\_files

Press Finish when ready.

The files and directories will be imported into the project. (Recall that this is the QEMU usage scenario. Your project will look slightly different if you are not targeting QEMU.)

tutorial\_mils\_config\_files\_imported

After importing, edit the “Makefile” file found in the “qemu-boot” folder. Specifically, change the definitions of the macro values for “CC” and “OBJCOPY” that appear on the first two lines, if they are not already as depicted below. In the following figure we have commented the original definitions and inserted the new, changed definitions:

tutorial\_mils\_qemuboot\_makefile\_after

Once changed, save and close the file.

If you are targeting QEMU, edit another “Makefile” file as well. This aditional file is the “Makefile” located in the root of the “Integration” project. Change it to enable variables and rules needed to build the QEMU boot image. Before the change, the Makefile will appear as follows:

tutorial\_mils\_makefile\_before

Uncomment all of the lines following “# rules for qemu boot image”

After making these changes, the file will appear as shown in the figure below (again, this is when targeting QEMU):

tutorial\_mils\_makefile\_after1

If you are targeting QEMU, right-click on the Integration project and select “Properties”. Select the “Build Properties” page and then the “Build Specs” tab. If your QEMU build spec does not exist, press the “New” button to the right to add it. Then select it as the active build spec and press “Apply” (not “OK”, since we are not finished yet). In our case we are using QEMU for a PPC, so the build spec is named “qemu-PPC604gnu”. The figure below shows the dialog to add that build spec.

tutorial\_mils\_new\_qemu\_buildspec

Once the QEMU build spec is defined, select it as the active build spec (and the default too).

Further, again only if you are targeting QEMU, in this same dialog box select the “Build Macros” tab, select the qemu build spec from the “Active build spec” pull-down list, and enter the following build macros’ values:

tutorial\_mils\_new\_qemu\_buildmacros

Press “OK”.

We will specify project references while creating the remaining projects for the system.

1.15.5. VxWorks MILS Kernel Image Project

If you do not already have a suitable kernel image in your workspace, follow these instructions to create one.

Create a new kernel image project using the “VxWorks MILS Kernel Image Project” new-project wizard:

tutorial\_mils\_new\_kernel\_project\_wiz

Name the new project “milsKernel” in the resulting first wizard page:

tutorial\_mils\_new\_kernel\_project\_page1

Press “Next”.

Select the BSP. If you are targeting QEMU, add it as a build spec (if necessary) and select it for the active build spec. In this case, the build spec will be the BSP name “qemu”. On the Build Macros page, set BSP to “qemu” and TOOL to “gnu”.

tutorial\_mils\_new\_kernel\_project\_page2

Press “Finish” and the new kernel image project will be created.

tutorial\_mils\_new\_kernel\_project\_in\_explorer

In the Project Explorer, select the milsKernel project and drag it into the Integration project to make it a subproject. Once that is done, the projects will appear as follows:

tutorial\_mils\_after\_kernel\_subproject

1.15.6. VxWorks Guest OS Virtual Boards

The following steps are to be performed for each of the “sender”, “receiver” and “amioServer” virtual boards, with one exception. The “amioServer” project should not be extended for use by GNATbench as it runs a pure C application providing multiplexed I/O to the other virtual boards.

First, right-click on the existing “Integration” project. *This approach to invoking the wizard is essential.* Then, in the contextual menu, select the “VxWorks MILS VxWorks Guest OS Application Project” new-project wizard:

tutorial\_mils\_new\_guest\_os\_project\_wiz

Name the new project “sender” in the resulting first wizard page:

tutorial\_mils\_new\_guest\_os\_project\_page1

Press “Next”.

Click the checkbox “Add reference to Integration”.

tutorial\_mils\_new\_guest\_os\_project\_page2

Press “Next” repeatedly until you get to the “Build Specs” page. Uncheck any build specs you don’t need and select the one you wish to use in the “Active build spec” pull-down:

tutorial\_mils\_new\_guest\_os\_buildspec\_page

Press “Next”.

Set the build target and binary output names to “sender” if not yet set. Make sure the builder is set to “Linker” in the drop-down text box.

tutorial\_mils\_new\_guest\_os\_buildtarget\_page

Press “Finish”.

The new VxWorks Guest OS project will be created and will appear nested within the “Integration” project. In the figure below, we have expanded it to show the contents:

tutorial\_mils\_sender\_in\_explorer

Next we import the project content from the example directories in the file system outside the workspace, much like we did for the XML files and Makefile for the “Integration” project.

Right-click on the “sender” project node and select “Import...” from the contextual menu.

tutorial\_mils\_sender\_import\_init.png

In the resulting dialog box, select “File System” under the “General” category:

tutorial\_653\_import\_file\_system

Press Next to invoke the “File System” wizard.

Browse to the “sender” folder under the same “mils_example” folder that you used to import the “Integration” directory contents earlier. The “sender” folder must be the only folder on the left panel in the dialog, as shown in the following figure. This is important because you do not want to import the “sender” folder itself, just the files within it and the “src” folder (and its contents) underneath it.

tutorial\_mils\_initial\_import\_sender.png

Click on the plus sign next to “sender” to display the expanded contents in the dialog box. The dialog will appear as follows:

tutorial\_mils\_import\_sender\_expanded.png

Put a check-mark next to the “src” folder in the left-hand pane. This will ensure the “src” folder and all its files will be imported. Next, in the right-hand pane, place check-marks in each of the files within the “sender” folder. The “sender” folder will have a green box rather than a check-mark, indicating that its contents are checked, but that the folder itself is not to be imported. This state is depicted in the following figure:

tutorial\_mils\_import\_sender.png

(Note that, when following these steps for the “amioServer” project, that project does not have a source directory to import so just import the files immediately within the “amioServer” directory.)

Ensure the option “Overwrite existing resources without warning” is enabled. If you forget, simply allow any files (such as the file named “usrAppInit.c”) to be overwritten when warned during the actual import processing.

Press “Finish”.

The sender project will now appear as depicted in the next figure. Note how the “src” folder appears immediately underneath the “sender” project itself, as do the imported files such as “sender.gpr” and the replacement “usrAppInit.c”, among others. In other words, we did not import the “sender” folder when we imported its contents.

tutorial\_mils\_import\_sender\_complete.png

Next, we create a folded named “obj” that is used to hold intermediate compilation products, such as object files. If you neglect this step, it’s harmless, but you will get a warning when converting the project to a GNATbench project. The directory will be created when building the project. (Note that the amioServer project does not need this folder added). Simply right-click on the “sender” project node and select “New”, then “Folder”:

tutorial\_mils\_sender\_file\_new\_folder.png

With the “sender” folder highlighted in the resulting dialog, name the new folder “obj” and press “Finish”.

tutorial\_mils\_sender\_file\_new\_folder2.png

We next extend the “sender” project for GNATbench Ada development.

Right-click on the “sender” project to invoke the contextual menu, select “New”, and then “Other”, as shown in this figure:

tutorial\_mils\_invoke\_sender\_conversion.png

Expand the “Ada” category if necessary, and then finally select “Convert to an Ada Project”.

tutorial\_653\_convert\_to\_gnatbench\_menu

Press Next.

In the resulting dialog, use the pull-down menu to specify “sender” as the project to convert, rather than “Integration”.

On the same page, select “Use a local GNAT project file” and ensure “sender.gpr” is specified.

The wizard page, when filled out, will appear as illustrated by the figure below:

tutorial\_mils\_convert\_sender\_to\_gnatbench\_page1

Press the “Finish” button and the project will be enhanced for GNATbench use.

For the sake of brevity, assume we have repeated the above steps for the “receiver” and “amioServer” virtual boards (but did not extend the “amioServer” project for GNATbench).

Once all these Guest OS projects are created, they will appear in the Project Explorer as illustrated in the figure below:

tutorial\_mils\_all\_guest\_projects\_explorer

1.15.7. High Assurance Environment Virtual Board

This section provides the steps for importing a mixed language application for execution in the High Assurance Environment (HAE).

First, right-click on the existing “Integration” project. *This approach to invoking the wizard is essential.* Then, in the contextual menu, select the “VxWorks MILS High Assurance Environment Application Project” new-project wizard:

tutorial\_mils\_new\_hae\_project\_wiz

Name the new project “baremetal” in the resulting first wizard page:

tutorial\_mils\_new\_hae\_project\_page1

Press “Next”.

Click the checkbox “Add reference to Integration”.

tutorial\_mils\_new\_hae\_project\_page2

Press “Next” repeatedly until you get to the “Build Specs” page. Uncheck any build specs you don’t need and select the one you wish to use in the “Active build spec” pull-down:

tutorial\_mils\_new\_hae\_buildspec\_page

Press “Next”.

Set the build target and binary output names to “baremetal”. Make sure the builder is set to “Linker” in the drop-down text box.

tutorial\_mils\_new\_hae\_buildtarget\_page

Press “Finish”.

The new HAE project will be created and will appear nested within the “Integration” project. In the figure below, we have expanded it to show the contents:

tutorial\_mils\_baremetal\_in\_explorer.png

Using the Project Explorer, delete the file “main.c” from the project.

Next we import the project content from the example directories in the file system outside the workspace, much like we did for the XML files and Makefile for the “Integration” project.

Right-click on the “baremetal” project node and select “Import...” from the contextual menu.

In the resulting dialog box, select “File System” under the “General” category, as usual.

Press Next to invoke the “File System” wizard. Browse to the “baremetal” directory below the “mils_example” directory in the supplied example. You will see this directory at the end of the selection for the “From directory:” panel in the figure below. As a result, the “baremetal” directory will be the root of the directories displayed at the left of the dialog box:

tutorial\_mils\_initial\_import\_baremetal.png

Click the box next to “baremetal” to place a check-mark in the box.

Click the plus-sign next to “baremetal” to expand the tree to verify that the “src” folder is also selected.

Once these steps have been taken, all the files immediately within the “baremetal” directory (on the right) will have check-marks next to them. Likewise, all the files immediately within “src” will have check-marks next to them. This state is depicted in the following figure:

tutorial\_mils\_import\_baremetal.png

Press “Finish”.

The “baremetal” project will now appear as depicted in the next figure:

tutorial\_mils\_import\_baremetal\_complete

Next, we create a folder named “obj” that is used to hold intermediate compilation products (such as object files). This step is not strictly necessary, but if you skip it you will get a harmless warning when converting to a GNATbench project. In that case, the folder will be created when first building the project.

Simply right-click on the “baremetal” project node and select “New”, then “Folder”. With the “baremetal” folder highlighted in the resulting dialog, name the new folder “obj” and press “Finish”.

tutorial\_mils\_baremetal\_file\_new\_folder

We next extend the “baremetal” project for GNATbench Ada development.

Right-click on the “baremetal” project to invoke the contextual menu, select “New”, and then “Other”, as shown in this figure:

tutorial\_mils\_invoke\_baremetal\_conversion

Expand the “Ada” category if necessary, and then finally select “Convert to an Ada Project”.

tutorial\_653\_convert\_to\_gnatbench\_menu

Press Next.

In the resulting dialog, specify “baremetal” as the project to convert.

On the same page, select “Use a local GNAT project file” and specify “baremetal.gpr”.

The wizard page, when filled out, will appear as illustrated by the figure below:

tutorial\_mils\_convert\_baremetal

Press the “Finish” button and the project will be enhanced for GNATbench use.

The Explorer now shows all projects in place:

tutorial\_mils\_all\_projects\_explorer

1.15.8. Building the Integration Project

Before building the first time, you must change some of the scenario variables from their default values. Use the Scenario Variables view to make the changes. (See Scenario Variables View for how to set scenario variables in the view. Likewise, see Scenario Variables for the scenario variable concept itself.)

Specifically, you must check the BINDING and RUNTIME scenario variables for all three projects for specific values. (Changing values invokes some automatic processing that make change the focus to another view. In that case simply put the focus back to the Scenario View to make any other changes.

Set the BINDING variables to “apex_mils” for the purpose of this tutorial. For the baremetal project, set the RUNTIME to “zfp”, the “zero-foorprint” run-time library. For the sender and receiver projects, check that RUNTIME is set to either “full” or “ravenscar-cert”. After you verify the values, the Scenario Variables view will appear as follows:

tutorial\_mils\_scenario\_vars\_after\_change

Note that you need not make these changes every time you build. Only the initial change is required.

You can now build the entire system by selecting the “Integration” project, right-clicking to invoke the contextual menu, and selecting “Build Project”. You can also build the projects individually using the same technique.

A pop-up dialog box will appear the first time a project is built. Press the “Continue” button; the build will then proceed.

The following figure illustrates what to expect in the Build Console as one of the individual projects (the “sender” project) is built:

tutorial\_mils\_sender\_built

Similary, the figure below illustrates what to expect in the Build Console as the “Integration” project is built (for QEMU in this case). We show only the last part of the build, for lack of space.

tutorial\_mils\_integration\_built

1.15.9. Congratulations

That’s it! You have created and built a VxWorks MILS Integration project with Ada applications.

1.16. Creating a Static Library Project in a User-Defined Project on Wind River Workbench 3.x

In this tutorial we will create and build a static library project for the Wind River General Purpose Platform (GPP) for VxWorks. We have arbitrarily chosen to create a static library for Downloadable Kernel Module (DKM) projects; the process is almost exactly the same for Real-Time Process (RTP) projects.

There are two general approaches to building static libraries with GNATbench. The difference is whether the project type is defined by Wind River Workbench or by the user.

The first approach uses a Workbench-defined type of project, for example a DKM project. As such it uses the Workbench builder, and all the facilities provided by the type of project are available. The second approach does not use a Workbench-defined project type. Instead, it uses a “User-Defined” project type. Building and cleaning are still supported for user-defined projects, among other capabilities, but the specific facilities provided by Workbench-defined (e.g. DKM) projects are not available. The first approach is somewhat simpler to use, however. We will examine the second approach in this tutorial.

1.16.1. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.16.1.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “Advanced Device Development”. Of course you may skip that step if you are already using that perspective.

1.16.1.2. Disabling “Standard” Managed Builds

As of Wind River Workbench 3.0, “Flexible” managed builds are used by default and “Standard” managed builds are deprecated. New GNATbench projects must employ Flexible managed builds.

Therefore, set the options on the Wind River “Build” preference page as shown below to disable Standard managed builds. You must also ensure the option to “Create default build targets for new projects using flexible managed build” remains enabled.

enabling standard build pref page

1.16.2. Creating and Configuring the Project

First, select the “User-Defined Project” wizard:

tutorial\_lib\_user\_defined\_proj\_wizard

In the resulting wizard, choose the “Wind River VxWorks” option in the pull-down menu:

tutorial\_lib\_user\_wiz\_page1

Press Next. In the next page, enter the name of the project. We name our project “staticDKMlib”:

tutorial\_lib\_user\_wiz\_page2

Press Next to configure build support.

tutorial\_lib\_user\_wiz\_page3

Ask to refresh current project after a build.

Press Finish. The new project will appear as shown below:

tutorial\_lib\_user\_proj\_init

Next we convert the new project to support Ada via GNATbench. To do this, we invoke the contextual menu on the new project node and select “New”, then “Other”, as shown below:

tutorial\_lib\_file\_new\_other

We then select “Convert to an Ada Project” in the resulting dialog and press OK.

conversion wizard for extending project

The first page of the conversion wizard will appear (shown in the next figure). We enter the name of the project to be converted and select the option to create a new GNAT project file.

tutorial\_lib\_user\_convert

Press Finish. A new wizard will activate to allow you to make the GNAT project file content choices.

The first page asks for the GNAT project unit name. This is not the gpr file name. Rather, it is the name of the unit (the project) within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, for example, by substituting underscores for dashes. If the Eclipse project name is already a legal Ada identifier that name is used unchanged, as in this case:

project conversion project unit name page

Select “Library Project” type and press Next.

The next page allows you to configure the ada library settings

tutorial\_lib\_ada\_library\_settings\_dialog

Click Next to take all the defaults. The next page allows you to configure the ada stand alone library settings

tutorial\_lib\_ada\_stand\_alone\_library\_settings\_dialog

Set interface to P and keep Generate the file(s) of the interface enabled to have a p.ads file automatically created. This code will be initially empty and we will edit it shortly.

Click Next.

The next page allows selection of the directories that will hold sources and intermediate products. We take all the defaults.

tutorial\_project\_dirs\_dialog.png

The final page allows selection of one or more toolchains to be available to the project.

Select the toolchain(s) to be used to build the static library.

Multiple toolchains can be convenient for a number of reasons. For example, a project baseline compiler version can be used to build the actual release but a newer version of the same toolchain can also be used for the sake of improved error analysis. This page also allows selection of a “production” and “debug” scenario, in which different switches are applied (e.g., debugging versus optimization) depending on the current development mode. Other build options are also available on the page. We take the defaults and simply press Finish.

tutorial\_lib\_project\_build\_settings\_dialog.png

Press Finish. The converted project will have new content:

tutorial\_lib\_user\_project\_converted

The GNATbench conversion wizard will generate the GNAT project file (“staticDKMlib.gpr”) with this content:

library project Staticdkmlib is

   for Languages use ("Ada");
   for Source_Dirs use ("src/**");
   for Object_Dir use "obj";
   for Library_Name use project'Name;
   for Library_Dir use "lib";
   for Library_Ali_Dir use project'Library_Dir;
   for Externally_Built use "False";
   for Library_Kind use "static";
   for Library_Standalone use "standard";
   for Library_Src_Dir use project'Library_Dir;
   for Library_Auto_Init use "False";
   for Library_Interface use ("P");

   package Compiler is
      for Default_Switches ("ada") use ("-g", "-gnato", "-gnatwa", "-gnatQ", "-gnat12");
   end Compiler;

   package Builder is
      for Default_Switches ("ada") use ("-g");
   end Builder;

   package Ide is
      for Gnat use "i586-wrs-vxworks-gnat";
      for Gnatlist use "i586-wrs-vxworks-gnatls";
      for Debugger_Command use "i586-wrs-vxworks6-gdb";
      for Compiler_Command ("ada") use "i586-wrs-vxworks-gnatls.exe";
      for Compiler_Command ("c") use "i586-wrs-vxworks-gcc.exe";
   end Ide;

end Staticdkmlib;

The Workbench wizard generated a file named “Makefile”. Originally it has the following content. The two targets (“all” and “clean”) are the hooks into the Workbench build infrastructure (the menus, in particular). In this original version the corresponding commands simply echo what the command would be doing.

all :
        @echo "make: built targets of `pwd`"

clean :
        @echo "make: removing targets and objects of `pwd`"

Modify the file to have the following content. Essentially you are replacing the entire content, although the two target names remain the same. Don’t forget to use tab characters to indent the commands under the targets – space characters will not work.

-include scenario.makefile

CONFIG_FILE = $(PLATFORM).cgpr

all :
        @echo "make: built targets of `pwd`"
        gprconfig --target=$(PLATFORM) \
                --config=ada,,$(RUNTIME), \
                --config=c,,$(RUNTIME), \
                --config=c++,,$(RUNTIME), \
                --config=asm,,, \
                --batch \
                -o $(CONFIG_FILE)
        gprbuild -p -P "$(GPRPATH)" \
                --config=$(CONFIG_FILE) \
                $(GNAT_SCENARIO_COMMAND)

clean :
        @echo "make: removing targets and objects of `pwd`"
        gprclean -r -P "$(GPRPATH)" \
                --config=$(CONFIG_FILE) \
                $(GNAT_SCENARIO_COMMAND);
        $(RM) $(CONFIG_FILE);

The new content will invoke “gprbuild”, a multi-language builder. In this case the GNAT project file directs gprbuild to create a static library. Note the various Makefile macros, such as “RUNTIME”.

Next we set the project build properties to define the “RUNTIME” macro. Right-click on the project node and select “Properties”, then select the “Build Properties” page.

We define a macro named “RUNTIME” to be associated with the project. “RUNTIME” stands for “run-time library”. We use “kernel-smp” to build a library for building a DKM client project on VxWorks 6 with SMP; make sure to use the proper value in your context. (The value will be passed by the Workbench builder invocation to the Makefile.)

Select the “$ Variables” tab. Then press the “New...” button and enter the new macro name and value, as shown below. Then press OK.

tutorial\_lib\_user\_new\_build\_macro

After doing so, the “Build Macros” tab will appear as follows:

tutorial\_lib\_user\_build\_props\_set

Press OK to close the Properties dialog.

Finally, we create some source files in the “src” folder:

Enter files content to get the following.

file p.ads

package P is
   procedure Q;
end P;

file p.adb

with GNAT.IO;
package body P is

  -------
   -- Q --
   -------

   procedure Q is
   begin
      GNAT.IO.Put_Line ("Hello from P.Q");
   end Q;

end P;

1.16.3. Building the Static Library Project

Select the “Build Project” menu entry.

Note the value passed to the Makefile for “RUNTIME” on the third line.

tutorial\_lib\_user\_proj\_build\_console

Click “No” to ignore index rebuild if a “C/C++ Index configuration potentially changed” dialog is displayed.

1.16.4. Client Projects Using the Library

Now that the library project is ready we can create and build a client project that uses the library. Strictly speaking you can build the client project first, making the necessary modifications to it after you build the static library project.

The client project is created via the new-project wizard just like any other DKM project. The project is also extended for GNATbench in the same manner. These construction and extension steps are described in great detail in the Creating and Building a General Purpose Platform Project on Wind River Workbench 3.x tutorial. Other than building it, follow those steps exactly. In this tutorial we have named the new client project “clientDKM”. The new main program is named “client_main” and we asked the wizard to generate the file for us.

The resulting new project will appear as follows:

tutorial\_lib\_both\_projects

The last required step is to associate the two GNAT project files so that the client project can make use of the static library when building the client’s Ada code. As always, this association is accomplished by placing a “with-clause” on the client’s GNAT project file (the “gpr file”) that references the static library’s GNAT project file. The fact that the static library gpr file is in a separate Workbench project does not matter.

with "../staticDKMlib/staticDKMlib.gpr";
project Clientdkm is

   for Languages use ("Ada");
   for Main use ("client_main.adb");
   for Source_Dirs use ("src/**");
   for Object_Dir use "obj";

   package Compiler is
      for Default_Switches ("ada") use ("-g", "-gnato", "-gnatwa", "-gnatQ", "-gnat12");
   end Compiler;

   package Builder is
      for Default_Switches ("ada") use ("-g");
   end Builder;

   package Linker is
      for Default_Switches ("ada") use ();
   end Linker;

   package Ide is
      for Gnat use "i586-wrs-vxworks-gnat";
      for Gnatlist use "i586-wrs-vxworks-gnatls";
      for Debugger_Command use "i586-wrs-vxworks6-gdb";
      for Compiler_Command ("ada") use "i586-wrs-vxworks-gnatls.exe";
      for Compiler_Command ("c") use "i586-wrs-vxworks-gcc.exe";
   end Ide;

end Clientdkm;

The “with-clause” on line one makes all the sources of the referenced GNAT project available, automatically, to the GNAT project file containing the clause. The clause must provide the path to the gpr file, but note that both absolute and relative paths are allowed. (This use of cross-project references is available generally, i.e., it is not limited to static library projects.)

The client main program can then reference the Ada package “P” provided by the static library:

with P;
procedure client_main is
begin
   P.Q;
end client_main;

1.16.5. Building the Client Project

Next we make the static library project a “sub-project” of the client project. We do this so that the Workbench builder will be separately invoked on the static library project, not just the GNAT builder as a result of the gpr file reference.

This step is accomplished by right-clicking on the static library project and selecting “Project References”, then “Add as Project Reference...”:

tutorial\_lib\_invoke\_project\_reference

In the resulting dialog box, enable the client project as a referencing “super-project”:

tutorial\_lib\_add\_proj\_ref\_dialog

Press OK and the Project Explorer will adjust to show the static library as a subproject of the client project:

tutorial\_lib\_nested\_lib\_project

Now, invoking the Workbench builder on the enclosing (client) super-project will also build, as necessary, the sub-projects. The other “build” oriented operations, such as project cleaning, will also now apply to the static library sub-project.

In the Project Explorer, select clientDKM project, right-click to bring up the contextual menu. Select “Build Project”.

A pop-up will appear the first time you build the project. Just press “Continue”.

Click “No” to ignore index rebuild if a “C/C++ Index configuration potentially changed” dialog is displayed.

tutorial\_lib\_user\_client\_build\_console

1.16.6. Congratulations!

You have created a static library in a user-defined project and used it with a client project.

1.17. Creating a Static Library Project in a Workbench-Defined Project on Wind River Workbench 3.x

In this tutorial we will create and build a static library project for the Wind River General Purpose Platform (GPP) for VxWorks.

There are two general approaches to building static libraries with GNATbench. The difference is whether the project type is defined by Wind River Workbench or by the user.

The first approach uses a Workbench-defined type of project, for example a DKM project. As such it uses the Workbench builder, and all the facilities provided by the type of project are available. The second approach does not use a Workbench-defined project type. Instead, it uses a “User-Defined” project type. Building and cleaning are still supported for user-defined projects, among other capabilities, but the specific facilities provided by Workbench-defined (e.g. DKM) projects are not available. The first approach is somewhat simpler to use. We will examine the first approach in this tutorial.

1.17.1. Workspace Configuration

These initial settings must be done for each new workspace used. You will only have to do this once per workspace unless the preferences are somehow reverted.

Start Workbench.

1.17.1.1. Perspective Selection

Use the Window menu entry and select “Open Perspective”, then select “Advanced Device Development”. Of course you may skip that step if you are already using that perspective.

1.17.1.2. Disabling “Standard” Managed Builds

As of Wind River Workbench 3.0, “Flexible” managed builds are used by default and “Standard” managed builds are deprecated. New GNATbench projects must employ Flexible managed builds.

Therefore, set the options on the Wind River “Build” preference page as shown below to disable Standard managed builds. You must also ensure the option to “Create default build targets for new projects using flexible managed build” remains enabled.

enabling standard build pref page

1.17.2. Creating and Configuring the Project

The first step is to invoke the wizard. In the Application Development perspective, use the menu bar and select “File”, then “New”, and then the list of project types will be displayed in the menu, as shown in the following figure:

new project menu

In this tutorial we are making a library compatible with a DKM project so we want the DKM project creation wizard. Click on the wizard named “VxWorks Downloadable Kernel Module Project” to select it.

The Workbench wizard will open so that you can configure the new project (see figure below).

tutorial\_lib\_dkm\_wizard\_projname

Enter the name of the new project (we used “staticDKMlib”, arbitrarily) and choose to have the new project files reside in the default workspace location. Press Next.

If a Project Structure Wizard page is displayed, ignore it and press Next.

Another wizard page will appear, allowing you to select the build type. Take the defaults and press Next.

new DKM project wizard build setup

The next page (below) allows you to configure the build command and how the result is processed. Take all the defaults and press Next.

new DKM project wizard build support

The next page (below) allows you to configure the build spec(s) for the project. We first press “Deselect All” because we only want one build spec for this tutorial (because we will use the simulator). Then we selected “SIMNTgnu”. *Be sure to select the GNU version of any given build spec.*

tutorial\_lib\_dkm\_wizard\_build\_specs

The next page (below) allows you to configure a build target name and build tool for the project. In this case we change the default tool (“Linker”) to “Librarian” by selecting it from the pull-down list. Then press Next.

tutorial\_lib\_dkm\_wizard\_build\_target

The next page (below) allows you to configure the source code indexer for the project. This is a C++ tool so it is not pertinent to GNATbench projects. You can either take all the defaults and press Next, or disable the indexer altogether. It will not cause difficulties later if you choose to take the defaults. In the figure below we show how to disable the indexer.

new DKM project wizard indexer

You can now press Finish. The new project will be created and you will see it in the Project Explorer, like so:

tutorial\_lib\_init\_created\_project

Next we convert the new project to support Ada via GNATbench. To do this, we invoke the contextual menu on the new project node and select “New”, then “Other”, as shown below:

tutorial\_lib\_file\_new\_other

We then select “Convert to an Ada Project” in the resulting dialog and press OK.

conversion wizard for extending project

The first page of the conversion wizard will appear (shown in the next figure). We enter the name of the project to be converted and select the option to create a new GNAT project file.

tutorial\_sharelib\_conversion\_wizard\_page1.png

Press Finish. A new wizard will activate to allow you to make the GNAT project file content choices.

The first page asks for the GNAT project unit name. This is not the gpr file name. Rather, it is the name of the unit (the project) within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, for example, by substituting underscores for dashes. If the Eclipse project name is already a legal Ada identifier that name is used unchanged, as in this case:

project conversion project unit name page

Press Next. The next page allows you to configure the ada library settings

tutorial\_lib\_ada\_library\_settings\_dialog

Click Next to take all the defaults. The next page allows you to configure the ada stand alone library settings

tutorial\_lib\_ada\_stand\_alone\_library\_settings\_dialog

Set interface to P and keep Generate the file(s) of the interface enabled to have a p.ads file automatically created. This code will be initially empty and we will edit it shortly.

Click Next.

The next page allows selection of the directories that will hold sources and intermediate products. We take all the defaults.

tutorial\_project\_dirs\_dialog.png

The final page allows selection of one or more toolchains to be available to the project. The appropriate toolchain for the project’s selected build spec will be enabled by default, but can be changed. Multiple toolchains can be convenient for a number of reasons. For example, a project baseline compiler version can be used to build the actual release but a newer version of the same toolchain can also be used for the sake of improved error analysis. This page also allows selection of a “production” and “debug” scenario, in which different switches are applied (e.g., debugging versus optimization) depending on the current development mode. Other build options are also available on the page. We take the defaults and simply press Finish.

tutorial\_lib\_project\_build\_settings\_dialog.png

After conversion, note the presence of the new gnat.makefile in the Project Explorer. This is a makefile fragment that will automatically invoke the Ada compiler and other builder tools when the Workbench project builder is invoked. It must not be deleted.

Also note the “src” folder containing the p.ads interface file.

Edit the p.ads file and add in it the procedure Q declaration.

package P is
   procedure Q;
end P;

Create the body of this package. Select p.ads file and then run Ada > Generate Body menu.

Modify p.adb content to get the following.

with GNAT.IO;
package body P is

  -------
   -- Q --
   -------

   procedure Q is
   begin
      GNAT.IO.Put_Line ("Hello from P.Q");
   end Q;

end P;

In a real application we would add a unit in Library_Interface declaration of GNAT project file “staticDKMlib.gpr” for each unit included in the library interface.

for Library_Interface use ("P", "Q", "R");

1.17.3. Building the Project

In the Project Explorer, right-click to bring up the contextual menu. Select “Build Project”.

A pop-up will appear the first time you build the project. Just press “Continue”.

The build will then proceed and you can watch it in the Build Console. A sample successful build will look like the following:

tutorial\_lib\_build\_console\_result

After the build complete the project will appear as shown below. Note the “lib” folder containing the new library file.

tutorial\_lib\_built\_library

1.17.4. Client Projects Using the Library

Now that the library project is ready we can create and build a client project that uses the library. Strictly speaking you can build the client project first, making the necessary modifications to it after you build the static library project.

The client project is created via the new-project wizard just like any other DKM project. The project is also extended for GNATbench in the same manner. These construction and extension steps are described in great detail in the Creating and Building a General Purpose Platform Project on Wind River Workbench 3.x tutorial. Other than building it, follow those steps exactly. In this tutorial we have named the new client project “clientDKM”. The new main program is named “client_main” and we asked the wizard to generate the file for us.

The resulting new project will appear as follows:

tutorial\_lib\_both\_projects

The last required step is to associate the two GNAT project files so that the client project can make use of the static library when building the client’s Ada code. As always, this association is accomplished by placing a “with-clause” on the client’s GNAT project file (the “gpr file”) that references the static library’s GNAT project file. The fact that the static library gpr file is in a separate Workbench project does not matter.

with "../staticDKMlib/staticdkmlib.gpr";

project Clientdkm is

   for Languages use ("Ada");
   for Main use ("client_main.adb");
   for Source_Dirs use ("src/**");
   for Object_Dir use "obj";

   package Compiler is
      for Default_Switches ("ada") use ("-g", "-gnato", "-gnatwa", "-gnatQ", "-gnat12");
   end Compiler;

   package Builder is
      for Default_Switches ("ada") use ("-g");
   end Builder;

   package Linker is
      for Default_Switches ("ada") use ();
   end Linker;

   package Ide is
      for Gnat use "i586-wrs-vxworks-gnat";
      for Gnatlist use "i586-wrs-vxworks-gnatls";
      for Debugger_Command use "i586-wrs-vxworks6-gdb";
   end Ide;

end Clientdkm;

The “with-clause” on line one makes all the sources of the referenced GNAT project available, automatically, to the GNAT project file containing the clause. The clause must provide the path to the gpr file, but note that both absolute and relative paths are allowed. (This use of cross-project references is available generally, i.e., it is not limited to static library projects.)

The client main program can then reference the Ada package “P” provided by the static library:

with P;
procedure client_main is
begin
   P.Q;
end client_main;

1.17.5. Building the Client Project

We can now build the full client project using the “Build Project” menu entry:

tutorial\_lib\_build\_client\_invocation

A pop-up will appear the first time you build the project. Just press “Continue”.

The resulting build appears in the Build Console:

tutorial\_lib\_client\_wb\_project\_built

1.17.6. Static Library As Subproject

As illustrated, this approach works, but there is a problem: the static library project must be built before building the client project. If the static library is not already built, the Ada compiler will simply compile the required source files from the static library project sources into the client project – the static library will not be built. This is because the Workbench builder for the static library project was never invoked.

You can address this problem by making the static library project a “sub-project” of the client project. Do this by right-clicking on the static library project and selecting “Project References”, then “Add as Project Reference...”:

tutorial\_lib\_invoke\_project\_reference

In the resulting dialog box, enable the client project:

tutorial\_lib\_add\_proj\_ref\_dialog

Press OK and the Project Explorer will adjust to show the static library as a subproject of the client project:

tutorial\_lib\_nested\_lib\_project

Now, invoking the Workbench builder on the enclosing (client) super-project will also build, as necessary, the sub-projects. The other “build” oriented operations, such as project cleaning, will also now apply to the static library sub-project.

Note that if there are multiple client sub-projects under an enclosing super-project, you may need to set the build order to ensure the static library is built first.

The image below shows a full build of both projects invoked on the client node:

tutorial\_lib\_nested\_project\_full\_build

1.17.7. Congratulations!

You created a static library in a Workbench-defined project and used it with a client project.