[Previous] [Contents] [Index] [Next]

Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Developing C/C++ Programs

You can select a topic from this diagram:

Utilities Used by the IDE Getting System Information Using Code Coverage Common Wizards Reference Preparing Your Target Developing Photon Applications Developing C/C++ Programs Where Files Are Stored Building OS and Flash Images Migrating to the 6.3 Release Tutorials IDE Concepts About This Guide Analyzing Your System With Kernel Tracing Profiling an Application Finding Memory Errors Debugging Programs Managing Source Code Launch Configurations Reference

Workflow diagram with C/C++ chapter highlighted


This chapter shows you how to create and manage your C or C++ projects.


In this chapter...

The C/C++ Development perspective

The C/C++ Development perspective is where you develop and build your projects. As mentioned in the Concepts chapter, a project is a container for organizing and storing your files.

Besides writing code and building your projects, you may also debug and analyze your programs from the C/C++ Development perspective.


Note: You'll find complete documentation on the C/C++ Development perspective, including several tutorials to help you get started, in the core Eclipse platform docset: Help-->Help Contents-->C/C++ Development User Guide.

The views in the C/C++ Development perspective are driven primarily by selections you make in the C/C++ editor and the C/C++ Projects view, which is a specialized version of the Navigator view.

Since the Navigator view is part of the core Eclipse platform, you'll find full documentation on the Navigator in the Workbench User Guide:

For information on the Navigator's: See these sections in the Workbench User Guide:
toolbar and icons Concepts-->Views-->Navigator view
right-click context menu Reference-->User interface information-->Views and editors-->Navigator View

Wizards and Launch Configurations

To create and run your first program, you'll use two major facilities within the IDE:

Once you've used these parts of the IDE for the first time, you'll be able to create, build, and run your programs very quickly. For details, see the Common Wizards Reference and Launch Configurations Reference chapters in this guide.

Controlling your projects

The C/C++ Development perspective's C/C++ Projects view is perhaps the most important view in the IDE because you can control your projects with it. The selections you make in the C/C++ Projects view greatly affect what information the other views display.

The C/C++ Projects view gives a "virtual" or filtered presentation of all the executables, source, and shared objects that comprise your project. You can set filters for the types of files you want shown in this view.

The C/C++ Projects view has many of the same features as the Navigator view, but is configured specifically for C and C++ development. At first glance, the two may seem identical, but the C/C++ Projects view:

Opening files

To open files and display them in the editor area:

=>> In the C/C++ Projects view, double-click the file to be opened.

The file opens in the editor area.

Opening projects

Since the C/C++ Projects view hides closed projects, you must use the Navigator view to open them.

=>> In the Navigator view, right-click your project, then select Open Project.

The project opens -- you can see it in the C/C++ Projects view.

Filtering files

To hide certain files from the C/C++ Projects view:

  1. In the C/C++ Projects view, click the menu dropdown button (Icon; menu dropdown).
  2. Select Filters.... The C Element Filters dialog appears:

    C/C++ Projects view; File Filter dialog

  3. In the filter pane, select the types of files you wish to hide. For example, if you select .*, then all files that start with a period (e.g. .cdtproject, .project, etc.) won't appear in the C/C++ Projects view.
  4. Click OK. The C/C++ Projects view automatically refreshes and shows only the files you haven't filtered.

Outlines of source and executable files

The C/C++ Projects view shows you an outline of the .c, .cc, and .h files in your project:

C/C++ Projects view; outline; source

Note that you can also use the Outline view to see the structure of your projects. (For more on the Outline view, see the "Code synopsis" section in this chapter.)

The C/C++ Projects view shows you the outlines of executables as well. You can examine the structure of executables to see the functions that you declared and used in the file, as well as the elements that were called indirectly, such as malloc(), _init(), and errno:

C/C++ Projects view; outline; executable

Creating projects

If you're creating an application from scratch, you'll probably want to create a QNX C Project or QNX C++ Project, which relies on the QNX recursive makefile hierarchy to support multiple CPU targets. For more on the QNX recursive makefile hierarchy, see the Conventions for Makefiles and Directories appendix in the Programmer's Guide.


Note: If you want to import an existing project, see the section "Importing existing source code into the IDE" in the Managing Source Code chapter in this guide.

You use the New Project wizard whenever you create a new project in the IDE. Here are the steps to create a simple "hello world" type of program:

  1. In the C/C++ Development perspective, click the New C/C++ Project button in the toolbar:

    New QNX C Project button

    The New Project wizard appears.


    Note: There are actually several ways to open the New Project wizard. See the Common Wizards Reference chapter in this guide for details.

  2. Name your project, then select the type:

    Even though it allows it, don't use any of the following characters in your project name (they'll cause problems later): | ! $ ( " ) & ` : ; \ ' * ? [ ] # ~ = % < > { }

  3. Click Next -- but don't press Enter! (Pressing Enter at this point amounts to clicking the Finish button, which will cause the IDE to create the project for all CPU variants, which you may not want.)
  4. In the Build Variants tab, check the build variant that matches your target type, such as X86 (Little Endian), PPC (Big Endian), etc.

    Also, check Build debug version and Build release version.

  5. Click Finish. The IDE creates your project and displays the source file in the editor.

Building projects

In this section...

Once you've created your project, you'll want to build it. Note that the IDE uses the same make utility and makefiles that are used on the command line.

The IDE can build projects automatically (i.e. whenever you change your source) or let you build them manually. When you do manual builds, you can also decide on the scope of the build.

You can watch a build's progress and see output from the build command in the Console view. If a build generates any errors or warnings, you can see them in the Problems view.

Build terminology

The IDE uses a number of terms to describe the scope of the build:

Build
Build only the components affected by modified files in that particular project (i.e. make all).
Clean
Delete all the built components (i.e. .o, .so, .exe, and so on) without building anything (i.e. make clean).
Rebuild
Delete all the built components, then build each one from scratch. A Rebuild is really a Clean followed by a Build (i.e. make clean; make all).

Turning off the autobuild feature

By default, the IDE automatically rebuilds your project every time you change a file or other resource in any way (e.g. delete, copy, save, etc.). This feature is handy if you have only a few open projects and if they're small. But for large projects, you might want to turn this feature off.

To turn off autobuilding:

  1. From the main menu, select Window-->Preferences.
  2. In the left pane, select Workbench.
  3. In the right pane, disable the Build automatically option.
  4. Click OK to save and apply your preferences.

    The IDE now builds your projects only when you ask it to.

Existing C/C++ projects (not QNX C/C++ projects) have their own autobuild setting. To turn this off:

  1. Right-click the C/C++ project, then choose Properties from the menu.
  2. Select C/C++ Make Project in the list on the left.
  3. Select the Make Builder tab.

    Make Builder tab

  4. Disable the Build on resource save (Auto Build) option in the Workbench Build Behavior section.
  5. Click OK to close the project properties dialog and return to the workbench.

Building everything

The IDE lets you manually choose to rebuild all your open projects. Depending on the number of projects, the size of the projects, and the number of target platforms, this could take a significant amount of time.

To rebuild all your open projects:

=>> From the main menu, select Project-->Build All.

Building selected projects

To rebuild a single project:

=>> In the C/C++ Projects view, right-click a project and select Rebuild Project.

Autosave before building

To have the IDE automatically save all your changed resources before you do a manual build:

  1. From the main menu, select Window-->Preferences.
  2. In the left pane, select Workbench.

    Workbench preferences

  3. In the right pane, check the Save automatically before build option.
  4. Click OK to save and apply your preferences.

The IDE will now save your resources before it builds your project.

Configuring project build order

You can tell the IDE to build certain projects before others. And if a given project refers to another project, the IDE builds that project first.


Note: Setting the build order doesn't necessarily cause the IDE to rebuild all projects that depend on a given project. You must rebuild all projects to ensure that all dependencies are resolved.

To manually configure the project build order:

  1. From the main menu, select Window-->Preferences.
  2. In the left pane, select Build Order.

    Build Order preferences

  3. Disable the Use default build order option.
  4. Select a project in the list, then use the Up or Down buttons to position the project where you want in the list.
  5. When you're done, click Apply, then OK.

Creating personal build options


Note: In this section, the term "targets" refers to operations that the make command executes during a build, not to target machines.

A make target is an action called by the make utility to perform a build-related task. For example, QNX makefiles support a target named clean, which gets called as make clean. The IDE lets you set up your own make targets (e.g. myMakeStuff). You can also use a make target to pass options such as CPULIST=x86, which causes the make utility to build only for x86. Of course, such an option would work only if it's already defined in the makefile.

To add your own custom make target to the C/C++ Project view's right-click menu:

  1. In the C/C++ Projects view, right-click a project and select Create Make Target....
  2. Type the name of your make target (e.g. myMakeStuff).
  3. Click Create.

You'll see your target option listed in the Build Targets dialog, which appears when you select the Build Make Target... item of the right-click menu of the C/C++ Projects view. Your targets also appear in the Make Targets view.

To build your project with a custom make target:

  1. In the C/C++ Projects view, right-click a project.
  2. In the context menu, select Build Make Target... item. The Build Targets dialog appears.
  3. Select your custom target, then click Build.

Note: To remove a make target:
  1. Open the Make Targets view (Window-->Show View-->Make Targets). Expand your project to see your make targets.
  2. Right-click the target you want to remove, then select Delete Make Target.

Adding a use message

Adding a helpful "use" message to your application lets people get an instant online reminder for command-line arguments and basic usage simply by typing use app_name.

Usage messages are plain text files, typically named app_name.use, located in the root of your application's project directory. For example, if you had the nodetime project open, its usage message might be in nodetime.use. This convention lets the recursive Makefile system automatically find your usage message data.

For information about writing usage messages, please refer to the usemsg documentation.

To add a usage message to your application when using a QNX C/C++ Project:

  1. In the C/C++ Projects or Navigator view, open your project's common.mk file. This file specifies common options used for building all of your active variants.
  2. Find the USEFILE entry in common.mk.
  3. If your usage message is in app_name.use, where app_name is your executable name, add a # character at the start of the USEFILE line. This lets the recursive Makefile system automatically pick up your usage message.

    If your usage message is in a file with a different name, or you want to explicitly specify your usage message's file name, change the USAGE line:

    USAGE=$(PROJECT_ROOT)/usage_message.use

    Where usage_message.use is the name of the file containing your usage message. This also assumes that your usage message file is in the root of the project directory. If the usage message file is located in another directory, include it instead of $(PROJECT_ROOT).

  4. Build your project as usual to include the usage message.

To add a usage message to your application when using a Standard C/C++ Project:

  1. In the C/C++ Projects or Navigator view, open your project's Makefile.
  2. Find the rule you use to link your application's various .o files into the final executable.
  3. Add the following to the rule after the link command:

    usemsg $@ usage_message.use

    Where usage_message.use is the name of the file containing your usage message.

  4. Build your project as usual to include the usage message.

Running projects


Note: Before running an application, you must prepare your target. If it isn't already prepared, you must do so now. See the previous chapter (Preparing Your Target) in this guide.

Once you've built your project, you're ready to run it. The IDE lets you run or debug your executables on either a local or a remote QNX Neutrino target machine. (For a description of local and remote targets, see the IDE Concepts chapter.)

To run or debug your program, you must create both of the following:


Note: For a complete description of how to create a QNX Target System Project, see the Common Wizards Reference chapter in this guide.

For a complete description of the Launch Configurations dialog and its available options, see the Launch Configurations Reference chapter in this guide.


To create a QNX Target System Project:

  1. From the menu, select File-->New-->Other....
  2. In the list, expand QNX.
  3. Select QNX Target System Project.
  4. Click Next.

    New QNX System Target project

  5. Name your target.
  6. Enter your target's Hostname or IP address.
  7. Click Finish.

You'll see your new QNX Target System Project in the Navigator view.

To create a launch configuration so you can run your "hello world" QNX C Application Project:


Note: Make sure you build your project first before you create a launch configuration for it. See "Building projects" above.

  1. In the C/C++ Projects view, select your project.
  2. From the Run workbench menu, click the Run... menu item.
  3. In the Launch Configurations dialog, select C/C++ QNX QConn (IP) in the left pane.
  4. Click New.

    New launch configuration

  5. In the Name field, give your launch configuration a name.
  6. Click the Search button beside the C/C++ Application field. The Program Selection dialog appears.
  7. Select a program to run; the _g indicates it was compiled for debugging.
  8. Click OK.
  9. In the Target Options pane, select your target.
  10. Click the Run button.

Your program runs -- you will see its output (if any) in the Console view.

Deleting projects

To delete a project:

  1. In the C/C++ Projects view, right-click a project and select Delete from the context menu. The IDE then prompts you to confirm, like this:

    Confirm delete dialog

  2. Decide whether you want to delete just the project framework, or its contents as well.

Note: When you delete a project in the IDE, any launch configurations for that project are not deleted. This feature lets you delete and recreate a project without also having to repeat that operation for any corresponding launch configurations you may have created.

For more on launch configurations, see the Launch Configurations Reference chapter in this guide.


Writing code

In this section...

The C/C++ editor is where you write and modify your code. As you work in the editor, the IDE dynamically updates many of the other views (even if you haven't saved your file).

C/C++ editor layout

The C/C++ editor has a gray border on each side. The border on the left margin might contain icons that indicate errors or other problems detected by the IDE, as well as icons for any bookmarks, breakpoints, or tasks (from the Tasks view). The icons in the left margin correspond to the line of code.

The border on the right margin displays red and yellow bars that correspond to the errors and warnings from the Problems view. Unlike the left margin, the right margin displays the icons for the entire length of the file.


C/C++ Editor layout


The C/C++ Editor



Note: If you use that cpptest.cc sample, you must add the math library to your project, or you will get link errors. For more information on adding libraries to your build, see the Linker tab section of the Common Wizards Reference appendix.

Finishing function names

The Content Assist feature can help you finish the names of functions if they're long or if you can't remember the exact spelling.

To use Content Assist:

  1. In the C/C++ editor, type one or two letters of a function's name.
  2. Press Ctrl-Space. (Or, right-click near the cursor and select Content Assist.) A menu with the available functions appears:

    C/C++ editor; Content Assist

  3. You may do one of the following:

Inserting code snippets

The IDE has another code-completion feature that can insert canned snippets of code such as an empty do-while structure. If you've already used the Content Assist feature, you may have already noticed the Code Templates feature; you access it the same way.

To use Code Templates:

  1. As with Content Assist, start typing, then press Ctrl-Space. (Or, right-click near the cursor and select Content Assist).
  2. Any code templates that match the letters you've typed will appear first in the list:

    C/C++ editor; Code Templates; using

The IDE lets you enable as many of these templates as you like, edit them as you see fit, create your own templates, and so on.

To edit a template or add one of your own:

  1. From the main menu, select Window-->Preferences.
  2. In the left pane, select C/C++-->Code Templates.

    C/C++ Code Templates

  3. To edit a template, select it, then click Edit.

    Editing a Code Template

  4. To add you own template, click New. A dialog for adding new templates appears:

    Adding a new Code Template

Adding #include directives

To insert the appropriate #include directive for any documented QNX Neutrino function:

  1. In the C/C++ editor, double-click the function name, but don't highlight the parentheses or any leading tabs or spaces.
  2. Right-click and select Add Include. The IDE automatically adds the #include statement to the top of the file, if it isn't already there.

Hover help

The IDE's hover help feature gives you the synopsis for a function while you're coding. To use hover help:

=>> In the C/C++ editor, pause your pointer over a function. You'll see a text box showing the function's summary and synopsis:

C/C++ editor; Hover help

Commenting-out code

You can easily add comments using either the C or C++ style, even to large sections of code. You can add // characters to the beginning of lines, letting you comment out large sections, even if they have /* */ comments.

When you uncomment lines, the editor removes the leading // characters from all lines that have them, so be careful not to accidentally uncomment sections. Also, the editor can comment or uncomment selected lines -- if you highlight a partial line, the editor comments out the entire line, not just the highlighted section.

To comment or uncomment a block of code:

  1. In the C/C++ editor, highlight a section of code to be commented or uncommented. For one line, place your cursor on that line.
  2. Right-click and select Comment or Uncomment.

Customizing the C/C++ editor

You can change the font, set the background color, show line numbers, and control many other visual aspects of the C/C++ editor. You can also configure context highlighting and change how the Code Assist feature works. You do all this in the C/C++ editor preferences dialog:

C/C++ editor; preferences

To access the C/C++ editor preferences dialog:

  1. Select Window-->Preferences.
  2. In the left pane, select C/C++-->Editor.

Using other editors

If you wish to use a different text editor than the one that's built into the IDE, you can do so, but you'll lose the integration of the various views and perspectives. For example, within the C/C++ editor, you can set breakpoints and then see them in the Breakpoints view, or put "to-do" markers on particular lines and see them in the Tasks view, or get hover help as you pause your cursor over a function name in your code, and so on.

If you want to use other editors, you can do so either outside or inside the IDE.

Outside the IDE

You can edit your code with an editor started outside of the IDE (e.g. from the command line). When you're done editing, you'll have to synchronize the IDE with the changes.

To synchronize the IDE with changes you've made using an editor outside of the IDE:

=>> In the C/C++ Projects view, right-click the tree pane and select Refresh. The IDE updates the display to reflect any changes you've made (such as creating new files).

Within the IDE

You can specify file associations that determine the editor you want to use for each file type. For example, you can tell the IDE to use an external program such as WordPad to edit all .h files. Once that preference is set, you can double-click a file in the C/C++ Projects view, and the IDE automatically opens the file in your selected program.

If the IDE doesn't have an association set for a certain file type, it uses the host OS defaults. For example, on a Windows host, if you double-click a .DOC file, Word or WordPad automatically launches and opens the file.


Note: For more information about file associations, follow these links in the Eclipse Workbench User Guide: Reference-->Preferences-->File Associations.

Creating files from scratch

By default, the IDE creates a simple "hello world" C/C++ source file for you, which you may or may not want to use as a template for your own code.

To create a new C/C++ file:

  1. Highlight the project that will contain the new file you're creating.
  2. Click the New C/C++ Source File button on the toolbar:

    Create file button

  3. Enter (or select) the name of the folder where the file will reside.
  4. Name your file, then click Finish.

You should now see an empty text editor window, ready for you to begin working on your new file. Notice your filename highlighted in blue in the title bar above the editor.

More development features

In this section...

Besides the features already described above, the IDE has several other helpful facilities worth exploring.

Tracking remaining work

The Problems view gives you a list of errors and warnings related to your projects. These are typically syntax errors, typos, and other programming errors found by the compiler:

Problems view

Error markers

The IDE also shows corresponding markers in several other locations:

Jumping to errors

To quickly go to the source of an error (if the IDE can determine where it is):

=>> In the Problems view, double-click the error marker (Icon: Error marker) or warning marker (Icon: Warning marker). The file opens in the editor area, with the cursor on the offending line.

To jump to errors sequentially:

=>> Click the Jump to next error marker button (Icon: Jump to next error marker button) or the Jump to previous error marker button (Icon: Jump to previous error marker button).

Filtering errors

Depending on the complexity and stage of your program, the IDE can generate an overwhelming number of errors. But you can customize the Problems view so you'll see only the errors you want to see.

To access the error-filtering dialog:

=>> In the Problems view, click the Filter icon (Icon: Filter button).

The Filters dialog lets you adjust the scope of the errors shown in the Problems view. The more boxes checked, the more errors you'll see.

Problems view; Filters dialog

Tracking Tasks

The Tasks view is part of the core Eclipse platform. For more information about this view, follow these links in the Workbench User Guide: Reference-->User interface information-->View and Editors-->Tasks view.


Tasks view


The Tasks view lets you track your tasks


Setting reminders

The Tasks view lets you create your own tasks for the unfinished function you're writing, the error-handling routine you want to check, or whatever.

You use the New Tasks dialog to add a personal task:

  1. In the Tasks view, right-click the tasks pane and select Add Task or click the Add Task button in the Tasks view.
  2. Complete the dialog for your task:

    Tasks view; New Tasks dialog


Note: To remove a personal task:
=>> In the Tasks view, right-click the task and select Delete.

Code synopsis

The Outline view gives you a structural view of your C/C++ source code:

Outline view

The view shows the elements in the source file in the order they occur, including functions, libraries, and variables. You may also sort the list alphabetically, or hide certain items (fields, static members, and nonpublic members).

If you click an entry in the Outline view, the editor's cursor moves to the start of the item selected.

Checking your build

The Console view displays the output from the make utility:

C-Build view

Customizing the Console view

You can choose to clear the Console view before each new build or let the output of each subsequent build grow in the display. You can also have the Console view appear on top of the other stacked views whenever you build.

To set the preferences for the Console view:

  1. From the main menu, select Window-->Preferences.
  2. In the left pane, select C/C++-->Build Console:

    C-Build view preferences

Accessing source files for functions

While editing source code in the editor, you can select a function name, press F3, and the editor immediately jumps to the source file for that function (if the file is also in your project).


Note: For more information on the C/C++ Development perspective, go to: Help-->Help Contents-->C/C++ Development User Guide.

Opening headers

You can select a header (such as stdio.h) in the C/C++ editor and press Ctrl-Shift-o to open the header file in the editor. You can also right-click the header file's name in the Outline view, then choose Open.

Many of the enhanced source navigation and code development accelerators available in the C/C++ editor are extracted from the source code. To provide the most accurate data representation, the project must be properly configured with the include paths and defines used to compile the source.

For QNX projects the standard include paths and defines are set automatically based on the compiler and architecture. Additional values can be set using the project's properties.

For Standard C/C++ Make projects, you must define the values yourself. These values can be set manually using the Paths and Symbols tab of the project's properties, or they can bet set automatically using the Set QNX Build Environment... item in the project's context menu.

Set the include paths and defines for a Standard C/C++ Make project:

  1. In the C/C++ Projects view, right-click your project and select Set QNX Build Environment....

    The Set QNX Build Environment wizard appears.

    Set QNX Build  Environment wizard

  2. Select one or more Standard C/C++ Make projects to update and click Next.

    The Compiler/Architecture Selection panel appears.

    Set QNX Build  Environment wizard - Compiler/Architecture Selection

  3. Select the appropriate Compiler, Language, and Architecture for your project, and click Finish.

[Previous] [Contents] [Index] [Next]