--------------- Getting Started --------------- .. toctree:: 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. Installing GNATbench ==================== The file gnatbench---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. 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 " 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. 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. .. image:: images/installed_plugins_dialog_box.png :align: center :alt: 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. .. image:: images/toolchains_wr.png :align: center :alt: toolchains window If no toolchains are displayed, click on "Scan" button to start a toolchain scan. Introduction ============ GNATbench supports sophisticated Ada-aware editing and browsing, code generation using GNAT Pro, and Ada-aware debugging. Intended Audience ================= This User's Guide is intended for Ada software developers using the GNAT Pro Ada tools to develop applications within Workbench. 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. For Additional Information and Help =================================== Additional help and information is available online from `AdaCore `_ via the GNAT Tracker web interface. .. _getting-started-building-gpp-wrwb4-tutorial: 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. 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. 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. 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 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). .. image:: ../project_setup/images/wrs_dkm_wrwb4_wizard_build_type.png :align: center :alt: new project wizard DKM build type page Click "Next >" button. Another wizard page will appear, allowing you to select the project name and location. .. image:: ../project_setup/images/wrs_dkm_wrwb4_wizard_project_name.png :align: center :alt: 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. .. image:: ../project_setup/images/wrs_dkm_wrwb4_wizard_project_context.png :align: center :alt: 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". .. image:: ../project_setup/images/rebuild_c_cpp_index.png :align: center :alt: 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: .. image:: ../project_setup/images/new_dkm_wrwb4_project_before_conversion.png :align: center :alt: 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 >". .. image:: images/tutorial_extend_for_gnatbench_use.png :align: center :alt: 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. .. image:: images/tutorial_conversion_wizard_page1.png :align: center :alt: 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: .. image:: images/tutorial_new_project_unit_name_page.png :align: center :alt: project conversion project unit name page The next page asks for the name of the Ada main program, if any: .. image:: images/tutorial_ada_main_name_dialog.png :align: center :alt: 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. .. image:: images/tutorial_project_dirs_dialog.png :align: center :alt: 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. .. image:: images/tutorial_project_build_settings_dialog.png :align: center :alt: 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: .. image:: images/tutorial_main_subprogram.png :align: center :alt: 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. Building the Project -------------------- In the Project Explorer, right-click to bring up the contextual menu. Select "Build Project". .. image:: images/tutorial_menu_build_project.png :align: center :alt: tutorial\_menu\_build\_project.png The following popup may appear. Just press "OK". .. image:: images/tutorial_655_3_parallel_build_warning.png :align: center :alt: initial popup when building project The following popup may appear. Just press "Continue". .. image:: ../project_setup/images/set_include_search_path.png :align: center :alt: 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: .. image:: images/tutorial_build_console_result.png :align: center :alt: content of Build Console after successful build Congratulations --------------- That's it! You have created and built a DKM project with Ada sources. 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. 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. Workspace Configuration ----------------------- Start Workbench. 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. 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: .. image:: images/tutorial_653_general_project_wizard.png :align: center :alt: 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: .. image:: images/tutorial_653_import_file_system.png :align: center :alt: 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\: .. image:: images/tutorial_653_3_example_location.png :align: center :alt: 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: .. image:: images/tutorial_653_3_importing_config_files.png :align: center :alt: tutorial\_653\_3\_importing\_config\_files Press Finish and the files will be imported into the "apex_raven" project in the workspace: .. image:: images/tutorial_653_3_files_imported.png :align: center :alt: 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. Creating and configuring the Module Integration Project ------------------------------------------------------- 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. .. image:: images/tutorial_653_3_target_operating_system.png :align: center :alt: tutorial\_653\_3\_target\_operating\_system Click Next. In the next page, select the build type to "Module Integration Project" .. image:: images/tutorial_653_3_module_integration_project.png :align: center :alt: 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 .. image:: images/tutorial_653_3_tutorial_project_setup.png :align: center :alt: 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. .. image:: images/tutorial_653_3_add_sender_application.png :align: center :alt: tutorial\_653\_3\_add\_sender\_application Click again to the Add... button to add the receiver partition. .. image:: images/tutorial_653_3_applications_added.png :align: center :alt: tutorial\_653\_3\_applications\_added Click on Finish button to create the tutorial Module Integration project and the sender/receiver Partition Operating System projects. 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'. :: .. Otherwise, they should use a device named '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. :: or :: .. 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. 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. 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. .. image:: images/tutorial_653_3_edit_kernel_configuration.png :align: center :alt: tutorial\_653\_3\_edit\_kernel\_configuration Expand the application components node and quick include INCLUDE_USER_APPL component if not already included. .. image:: images/tutorial_653_3_add_include_user_appl.png :align: center :alt: tutorial\_653\_3\_add\_include\_user\_appl Save (Ctrl+S) the sender kernel configuration. Do the same for the receiver kernel configuration. 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. .. image:: images/tutorial_653_3_copy_sender.png :align: center :alt: tutorial\_653\_3\_copy\_sender Select the sender partition operating system project, and paste the clipboard. .. image:: images/tutorial_653_3_paste_sender.png :align: center :alt: 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. 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". .. image:: images/tutorial_653_convert_to_gnatbench_menu.png :align: center :alt: 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: .. image:: images/tutorial_653_convert_sender_to_gnatbench_page1.png :align: center :alt: 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: .. image:: images/tutorial_653_3_converted_sender_project.png :align: center :alt: tutorial\_653\_3\_converted\_sender\_project Do the same conversion for the receiver project. Checking sender/receiver projects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The projects should appear in the Project Explorer as follows\: .. image:: images/tutorial_653_3_both_apps_in_explorer.png :align: center :alt: tutorial\_653\_3\_both\_apps\_in\_explorer Both projects should have the INCLUDE_USER_APPL component included in their kernel configuration. 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. .. image:: images/tutorial_653_3_open_scenariovar_view.png :align: center :alt: 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 :ref:`concepts-scenario-view` for how to set scenario variables in the view. Likewise, see :ref:`concepts-scenario-vars` for the scenario variable concept itself. Scenario variable can be set in two different modes: either "" or "". 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: .. image:: images/tutorial_653_3_apex_zfp_pulldown.png :align: center :alt: 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: .. image:: images/tutorial_653_3_both_apps_scenario_vars.png :align: center :alt: tutorial\_653\_3\_both\_apps\_scenario\_vars 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. .. image:: images/tutorial_655_3_parallel_build_warning.png :align: center :alt: 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. .. image:: images/tutorial_653_3_problems_after_build.png :align: center :alt: 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. Congratulations --------------- That's it! You have created and built a VxWorks 653 3;x Integration project with Ada applications. Creating a Static Library Project in a Workbench-Defined Project on Wind River Workbench 4.x ============================================================================================ In this tutorial we will create and build a static kernel library project in Wind River Workbench 4.x. The process is almost exactly the same for static user library projects used by Real Time Process (RTP) applications. 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 then Wind River Workbench Project... In the "New Wind River Workbench Project" dialog select "Static Kernel Library" as shown in the following figure: .. image:: images/tutorial_wrwb4_new_static_kernel_library_project.png :align: center :alt: new static kernel library project Click Next> The Workbench wizard will open so that you can configure the new project (see figure below). .. image:: images/tutorial_wrwb4_configure_static_kernel_library_project.png :align: center :alt: 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. Another wizard page will appear, allowing you to configure the project context. .. image:: ../project_setup/images/wrs_dkm_wrwb4_wizard_project_context.png :align: center :alt: 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. The new project will be created and you will see it in the 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: .. image:: images/tutorial_lib_file_new_other.png :align: center :alt: tutorial\_lib\_file\_new\_other We then select "Convert to an Ada Project" in the resulting dialog and press OK. .. image:: images/tutorial_extend_for_gnatbench_use.png :align: center :alt: 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. .. image:: images/tutorial_lib_conversion_wizard_page1.png :align: center :alt: tutorial\_sharelib\_conversion\_wizard\_page1.png Press Finish. A new wizard will appear 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: .. image:: images/tutorial_lib_new_project_unit_name_page.png :align: center :alt: project conversion project unit name page Press Next. The next page allows you to configure the Ada library settings .. image:: images/tutorial_lib_ada_library_settings_dialog.png :align: center :alt: 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 .. image:: images/tutorial_lib_ada_stand_alone_library_settings_dialog.png :align: center :alt: 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. .. image:: images/tutorial_project_dirs_dialog.png :align: center :alt: 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. .. image:: images/tutorial_lib_project_build_settings_dialog.png :align: center :alt: 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 declaration of the procedure Q. :: 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"); 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 see the progress in the Build Console. A sample successful build will look like the following: .. image:: images/tutorial_lib_build_console_result.png :align: center :alt: tutorial\_lib\_build\_console\_result After the build completes, the project will appear as shown below. Note the "lib" folder containing the new library file. .. image:: images/tutorial_lib_built_library.png :align: center :alt: tutorial\_lib\_built\_library 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 in it, after you have built 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 :ref:`getting-started-building-gpp-wrwb4-tutorial` 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: .. image:: images/tutorial_lib_both_projects.png :align: center :alt: 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" makes all the sources of the referenced GNAT project available, automatically, in the GNAT project file containing this clause. The clause must provide the path to the gpr file, both absolute and relative paths are allowed. (This use of cross-project references is available generally, i.e., it is not limited only 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; Building the Client Project --------------------------- We can now build the full client project using the "Build Project" menu entry: .. image:: images/tutorial_lib_build_client_invocation.png :align: center :alt: tutorial\_lib\_build\_client\_invocation A pop-up will appear the first time the project is built. Just press "Continue" to go further. The resulting build appears in the Build Console: .. image:: images/tutorial_lib_client_wb_project_built.png :align: center :alt: tutorial\_lib\_client\_wb\_project\_built 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...": .. image:: images/tutorial_lib_invoke_project_reference.png :align: center :alt: tutorial\_lib\_invoke\_project\_reference In the resulting dialog box, enable the client project: .. image:: images/tutorial_lib_add_proj_ref_dialog.png :align: center :alt: 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: .. image:: images/tutorial_lib_nested_lib_project.png :align: center :alt: 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: .. image:: images/tutorial_lib_nested_project_full_build.png :align: center :alt: tutorial\_lib\_nested\_project\_full\_build Congratulations! ---------------- You created a static library in a Workbench-defined project and used it with a client project. .. _getting-started-using-gnatcov-tutorial: Using GNATCoverage on Wind River Workbench 4.x ============================================== In this tutorial we will show you how to use GNATcoverage from GNATbench in order to instrument your source code for coverage analysis. GNATcoverage is supported for both Downloadable Kernel Modules (DKM) and Real-Time Process (RTP) projects running on top of Wind River General Purpose Platform (GPP) for VxWorks. This tutorial assumes that you have completed the procedure in section :ref:`getting-started-building-gpp-wrwb4-tutorial` GPR Configuration ----------------- In order to configure GNATcoverage from the Scenario Variable view, add the following definition: .. code-block:: gpr type Gnatcov_Level_Type is ("none", "stmt", "stmt+decision", "stmt+mcdc", "stmt+uc_mcdc"); Gnatcov_Level : Gnatcov_Level_Type := external ("GNATCOV_LEVEL", "none"); This setting will allow you to select the coverage level from the Scenario Variable View. For more advanced configuration, you may also add definitions for ``GNATCOV_DUMP_TRIGGER`` and ``GNATCOV_DUMP_CHANNEL``; these would allow you to specify the corresponding options of gnatcovage. Refer to "GNATDAS Manuals" for more information about these options. .. code-block:: gpr type Gnatcov_Dump_Trigger_Type is ("default", "manual", "atexit", "main-end", "ravenscar-task-termination"); Gnatcov_Dump_Trigger : Gnatcov_Dump_Trigger_Type := external ("GNATCOV_DUMP_TRIGGER", "default"); type Gnatcov_Dump_Channel_Type is ("default", "bin-file", "base64-stdout"); Gnatcov_Dump_Channel : Gnatcov_Dump_Channel_Type := external ("GNATCOV_DUMP_CHANNEL", "default"); Instrumenting for coverage -------------------------- The next step will be to select a coverage criterion. 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. .. image:: images/tutorial_653_3_open_scenariovar_view.png :align: center :alt: 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 :ref:`concepts-scenario-view` for how to set scenario variables in the view. Likewise, see :ref:`concepts-scenario-vars` for the scenario variable concept itself. On this panel, expand your project, then click on the value of ``GNATCOV_LEVEL`` to change it to ``stmt - ``. You can now build your project by doing "Project", then "Build...", and finally "Rebuild project". This will instrument your source code in a sub-directory suffixed by ``-gnatcov-instr``; then this instrumented source code will be used to build your application. Generating coverage traces -------------------------- In order to generate coverage traces, just run the application that has been built. By default, a file ``.srctrace`` will be generated in the working directory from which the application was executed. If your kernel is configured to include the debug agent, Workbench provides a way to mount your project directory on target; so on your development host you would find the trace file in the same directory as your application. If the host mount is not usable in your context, consider setting ``GNATCOV_DUMP_CHANNEL`` to ``base64-stdout``. Generating a report ------------------- The makefile provides a target ``gnatcov_report`` to generate a coverage report for coverage traces. Go to the "Terminal" panel and cd to your project, then to your build dir. For instance, for DKM project named aarch64-dkm, targetting aarch64: :: Active Workspace is 'C:\WindRiver\workspace' Wind River Workbench Enhanced Command Prompt (cmd), version 1.0 Type 'wt help' for WrTool automation, or 'we filename' to edit a file. C:\WindRiver\workspace>cd aarch64-dkm C:\WindRiver\workspace\aarch64-dkm>cd vsb_ARMARCH8Allvm_LP64_LARGE_SMP Then call ``make gnatcov_report``, specifying coverage traces in variable ``GNATCOV_SRCTRACE``: :: C:\WindRiver\workspace\aarch64-dkm\vsb_ARMARCH8Allvm_LP64_LARGE_SMP>make GNATCOV_SRCTRACE=/WindRiver/workspace/aarch64-dkm/vsb_ARMARCH8Allvm_LP64_LARGE_SMP/aarch64-dkm/Debug/aarch64-dkm.out.srctrace gnatcov_report info: creating output path C:/WindRiver/workspace/aarch64-dkm/vsb_ARMARCH8Allvm_LP64_LARGE_SMP/aarch64-dkm_partialImage/Debug/Objects/aarch64-dkm/report You may then go to this output path and open index.html to see the result of your coverage analysis.