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. The one tricky part is the use of scenario variables, which is optional but highly likely. We cover all three aspects in this tutorial.
The first step is to invoke the wizard. Use the menu bar and select "File", then "New", and then "Project..." as shown in the following figure:
Selecting "Project..." will bring up a dialog box showing all the new-project wizards, organized by category, so that you can choose which one to invoke.
If necessary, expand the "GNAT Pro Ada for VxWorks" category to show the two wizards offered there. As their names indicate, one wizard creates a new Downloadable Kernel Module project and the other creates a new Real Time Process project.
We want the DKM project creation wizard so we click on that wizard name to select it and then press Next.
The first page of the new-project wizard (shown in the next figure) will appear. Enter the name of the Ada main subprogram -- not the file name -- and have the wizard generate the file containing that unit. We arbitrarily name the unit "test_main".
After the main subprogram name is entered you can press Finish. This will end the first part of the wizard execution. Then, the Workbench wizard is automatically invoked so that you can configure the new DKM project (see figure below).
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 "standard" build mechanism. Press Next.
The next page (below) allows you to configure the build command and how the result is processed. Take all the defaults and press Next.
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.
Press Finish to take the remaining defaults. The new project will be created and you will see it in the Project Navigator, like so:
Note the presence of the file named "ada.makefile". This is a makefile fragment that will invoke the Ada compiler and other builder tools when the Workbench project builder is invoked. It must not be deleted.
Also note the file containing the main subprogram. This file will have the name we specified, "test_main.adb", and will contain a procedure with that unit name:
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.
In the Project Navigator, right-click to bring up the contextual menu. Select "Build Project".
A popup will appear. Just press "Continue".
The build will then proceed and you can watch it in the Build Console. A successful build will look like the following:
The wizard that created our new project also created the corresponding GNAT project file for us. It is shown below. Note the scenario variable named "Mode".
The scenario variable Mode has two possible values because of its type: "Production" and "Debug". (These values are case-sensitive because they are strings.) As you have guessed, these two values represent two different build scenarios. "Production" corresponds to the scenario in which you build for actual delivery. The "Debug" scenario is for development and testing. Therefore, these scenarios require different switches to be applied and this fact is reflected in the content of package Compiler and package Builder.
The value of the variable Mode, then, controls how the executable is built so we must control the value of the variable. Ordinarily this control is accomplished using the Scenario View (see the "Concepts" chapter for details of this view). However, in GNATbench 2.0 for Workbench, changes to scenario variables using this view are not recognized by the builder so we have to use a different approach.
The alternative to the Scenario View is to use environment variables defined at the operating system level outside of Workbench. In the GNAT project file above, the value of the variable Mode is set by the call to a function named "external". (See the GNAT Pro User's Guide for details of the function, as well as for project files in general.) The function will query an environment variable named "BUILD" and will return its value if found. Otherwise, if no such environment variable is found, the default value "Debug" is returned.
Therefore, the approach is to set the environment variable named "BUILD" to either "Production" or "Debug" and then invoke Workbench. You can change the value between Workbench invocations to change the switches applied during the build. (In this case we are running on Microsoft Windows so we used the Control Panel to bring up the System dialog box to set the environment variable. Use whatever facility is defined by your operating system.)
Note that the process that runs your Workbench environment will interpret all the environment variables when it starts but will not re-interpret them while it is running. It follows that you must set the environment variables' values between invocations of Workbench for changes to be effective.
If the environment variable "BUILD" did not exist when we stared Workbench, or if it had the value "Debug", the builder will apply those corresponding switches. We can see them in the Build Console below. Look for the use of switches "-g", "-gnato", and so forth under the blue subheading titled "building Ada project test.gpr".
If we change the value of "BUILD" to "Production" and then restart Workbench we will see the different switches applied:
That's it! You have created and built a DKM project and controlled the way it is built using scenario variables.