# Developing C/C++ Programs

The C/C++ Development perspective is probably the perspective where you'll spend most of your time. In it, you'll develop and build your programs. As you move further through your project, you'll likely use this perspective as the jump point for doing your debugging, program analysis, and target system integration.

Suggested prior reading:

- the IDE Concepts chapter

Related information:

- the Common Wizards chapter
- the Starting Your Programs chapter

In this chapter:

- Introduction
- Controlling the IDE (C/C++ Projects view)
- Creating projects (New Projects wizard)
- Building projects ( `make`)
- Running programs (launcher)
- Writing code (C/C++ Editor)
- More development features

# Introduction

Before you begin C/C++ development, you must create a project to contain your code; in the IDE, all your work must be contained in projects.

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, a specialized version of the Navigator view. Ensure you understand their functionality thoroughly.

## Wizards and the Launch Configurations dialog

In addition to perspectives and views, the IDE has two major "sections": wizards and the Launch Configurations dialog. To create and run your first program, you need both. The wizards let you quickly create a new project; the Launch Configurations dialog lets you set up how your program runs. Once you've used all these parts of the IDE for the first time, you'll be able to create, build, and run your programs very quickly. For more information, see the Common Wizards and Starting Your Programs chapters.

The C/C++ Development perspective also has many features that help you develop code quickly. Once you've learned the basics of creating programs and running them (in this chapter), take some time to browse through this chapter.

# Controlling the IDE (C/C++ Projects view)

The C/C++ Projects view is probably the most important view in the IDE because you 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 offers a filtered and slightly rearranged version of the Navigator view.

The Navigator view is part of the core Eclipse platform, so some of the features are documented there:

- For information about the Navigator view toolbar and icons, follow these links in the Workbench User Guide: Concepts-->Views-->Navigator view.
- For information about the right-click context menu in the Navigator view, follow these links in the Workbench User Guide: Reference-->User interface information-->Views and Editors-->Navigator 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:

- shows only open C/C++ projects
- pretends that the project's executables are stored in a virtual subdirectory called `bin`
- for a library project, pretends that the project's libraries are in a virtual subdirectory called `lib`
- hides certain files
- includes Build Project and related commands in its right-click menu
- gives an outline of `*.c`, `*.cc`, `*.cpp`, `*.h`, and binary files.

## 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 -- even if it's executable -- opens in the editor area.

## Opening projects

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

To open projects:

| In the Navigator view, right-click your project, and select Open Project. The project opens and appears in the C/C++ Projects view.

## Filtering files

To filter files in the C/C++ Projects view:

1. In the C/C++ Projects view, click the menu dropdown button .
2. Select Filter. The File Filter dialog appears:

3. In the filter pane, select the types of files you wish to hide. The .* selection hides files that start with a period, such as `.cdtproject` and `.project`.
4. Click OK. The C/C++ Projects view automatically refreshes and shows only the unfiltered file types.

## Outlines of source and executable files

The C/C++ Projects view shows you the outline of `.c`, `.cc`, and `.h` files:

This outline is similar to that found in the Outline view. To learn more about the Outline view, see the "Code synopsis (Outline view)" 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 not only the functions that you declared and used in the file, but the elements that were called indirectly, such as malloc(), _init(), and errno:

To view a file outline in the C/C++ Project view:

| In the C/C++ Projects view, click the "+" symbol to the left of any `.c`, `.cc`, or `.h`, or executable file. All the executables are grouped in the virtual `bin` directory. The tree expands to show the outline for that file. Click the "-" symbol to collapse the tree again.

# Creating projects (New Project wizard)

### @@@ NOTE I've left this in even though it is QNX specific, we would have to customize it to make it CDT generic

If you're creating an application from scratch, you'll probably want to create a QNX C Application Project or a QNX C ++ Application Project.

| For examples of creating specific types of projects, see the Tutorials book. We recommend that you create a few tutorial projects before you do too much reading. Having hands-on experience with the IDE gives you a better context for what you read in this guide. For a complete explanation of all the C/C++ project types and options, see the Common Wizards chapter.

To create a "Hello World!" QNX C Application Project:

1. In the C/C++ Development perspective, click the Create a new QNX C Application Project button . The New Project dialog appears:

2. In the Name field, type a name for your project (e.g. `myHelloWorldProject`).
3. Click Next. The dialog displays the appropriate with tabs.
4. In the Options tab, enable Build debug version and Build release version:

5. Click Finish. The IDE creates the project and displays the C file (e.g. `myHelloWorldProject.c` in the C Editor. It contains a working "Hello, World!" program:

# Building projects (`make`)

Once you've created your project, you can build it. The IDE uses the same `make` utility and makefiles used on the command line. The IDE can perform makes automatically or let you do them manually. When you do manual builds, you can also decide on the scope of the build.

You can watch the progress and see the build information in the C-Build view. If building your programs generates any errors or warnings, you can see them in the Tasks view.

This section includes:

- Build terminology
- Choosing autobuild or manual build
- Autobuilds
- Manual builds
- Configuring the project build order
- Creating personal build options (`make` targets)

## 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
  Build every component from scratch. A Rebuild is really a Clean followed by a Build (i.e. `make clean; make all`).

## Choosing autobuild or manual build

By default, the IDE automatically rebuilds every time you change a resource (e.g. file). This is handy if you have only a few open projects and if they're small. As the projects get larger, this feature can become a bit of a hindrance. You may find that you prefer to turn autobuilding off.

To turn off autobuilding:

1. From the main menu, select Window-->Preferences.
2. In the left pane, select Workbench. The dialog displays your workbench preferences:

3. In the right pane, disable the Perform build automatically on resource modification option. The IDE now builds only when you ask it to.

## Autobuilds

The IDE builds automatically every time you save a change. Thus, if you're using the default IDE configuration, you don't need to do anything. Even in this setting, you can build manually as well. Because the IDE always does incremental builds while in autobuild mode, you may wish to manually do a clean build to ensure you have fresh executables.

## Manual builds

Manual builds let you choose the scope of the build, as well as whether to do a Build, a Clean, or a Rebuild.

### 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 architectures, this can take a significant amount of time.

To rebuild all your open projects:

| From the main menu, select Project-->Rebuild All.

### Building selected projects

Because rebuilding all your open projects may be time-consuming, you may often wish to build only certain projects individually.

To rebuild a single project:

| In the C/C++ Projects view, right-click a project and select one of: Build Rebuild Clean. The IDE builds the selected project as you desired. For more information on the build methods, see the "Build terminology" section in this chapter.

### Manual build preferences

To have the IDE save your unsaved resources before manual builds:

1. From the main menu, select Window-->Preferences.
2. In the left pane, select Workbench.
3. In the right pane, enable the Save all modified resources automatically prior to manual build option. The IDE saves your resources before it builds.

## Configuring project build order

The IDE lets you determine the build order of your projects. If certain projects must be built before others, you can set that. If your project refers to another project, the IDE builds that project first.

| Setting the build order doesn't cause the IDE to rebuild projects that depend on the project; you must rebuild all projects to ensure all the changes are propagated.

To manually configure the project build order:

1. From the main menu, select Window-->Preferences.
2. In the left pane, select Build Order.
3. Disable the Use default build order option. You may now configure the build order as you desire. When you're done, click Apply, then OK.

## Creating personal build options (`make` targets)

| In this subsection, "targets" refer to actions in the makefiles, not target machines.

A `make` target is an action called by the `make` utility to perform a customized build-related task. For example, many makefiles support a target named `clean`, which gets called as `make clean`. The IDE lets you call your own target such as `myMakeAction` to be called as `make myMakeAction`. 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, these options work only if they're already defined in the makefile.

If you've added your own `make` targets, you can configure the IDE to call them specifically.

To add a customized `make` target to the C/C++ Project view right-click menu:

1. In the C/C++ Projects view, right-click a project and select Add Make Targets.
2. Type the name of the `make` target (e.g. `myMakeOption`):

3. Click OK. The target option appears in the right-click menu of the C/C++ Projects view.

To use a customized `make` target:

1. In the C/C++ Projects view, right-click a project. The right-click context menu appears. If there are any customized `make` targets for your project, the Make item is selectable.
2. Choose your make target from the Make menu:

# Running projects (launcher)

### @@@ Again the same thing applies here about stripping out the QNX specific information (ie regarding needing a target for launch) and replacing it with generic CDT information. I've much of it in for context.

Once you've built your project, you'll want 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 a QNX Target System Project that specifies how the IDE communicates with your target. You must also create a Launch Configuration that describes how the program runs on your target.

| For a complete description of the Launch Configurations dialog and the available options, see the Starting Your Programs chapter.

To run your "Hello World!" QNX C Application Project:

1. In the C/C++ Projects view, select your project (e.g. myHelloWorldProject).
2. In the C/C++ Development perspective, click the dropdown menu part of the run menu button set .
3. Select Run. The Launch Configurations dialog appears:

4. In the left pane, select C/C++ QNX QConn (IP).
5. Click New. The dialog displays the appropriate tabs:

6. In the Name field, type a meaningful name for your launch configuration (e.g. `myHelloProject IP launch`). The IDE automatically fills in the Project field.
7. Click the Search button beside the C/C++ Application field. The Program Selection dialog appears.

   | If the Program Selection dialog is blank, you must cancel and build your project. To learn how to build projects, see the "Building projects (`make`)" section.

8. Select a program to run. The `_g` indicates it's compiled with debug symbols. If you wish to run on an x86 target, select myHelloWorldProject [x86le]
9. Click OK.
10. In the Target Options pane, select your target.
11. Click Run. Your program runs. The IDE displays the output in the Console view. For example:

# Writing code (C/C++ Editor)

Within the C/C++ Development perspective, the C/C++ Editor is where you'll likely spend the great majority of your time -- you use it to write and modify your code:

The C/C++ Editor drives many of the other views. As you code, many of the other views update dynamically (even if you haven't saved).

This section includes:

- C/C++ Editor layout
- Finishing function names (Content Assist)
- Inserting code snippets (Code Templates)
- Adding `#include` directives (Add include)
- Hover help
- Commenting out code
- Customizing the C/C++ Editor appearance
- Using other editors

## 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 flag errors, warnings, or problems detected by the IDE. It also displays 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 Tasks view. Unlike the left margin, the right margin displays the icons for the entire length of the file.

## Finishing function names (Content Assist)

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

To use Content Assist:

1. In the C/C++ Editor, type at least the first letter of the function.
2. Press Ctrl-Space. (Or, right-click near the cursor and select Content Assist). A menu with the available functions appears:

3. You may do one of the following:
   - Continue typing. The list shortens. When there's only one function that matches, it's automatically inserted.
   - Scroll with the up and down arrows. Press Enter to select the function.
   - Scroll with the mouse. Double-click a function to select it.
   - Press Esc to close the Content Assist window.

## Inserting code snippets (Code Templates)

The IDE can help you by inserting snippets of code such as an empty `do-while` structure. If you've used the Content Assist feature, you may have already noticed this feature; you access it the same way.

To use Code Templates:

| Follow the procedure for using Content Assist, with the following exception: If any code templates start with the letter combination you've typed, they appear first in the list and have a different icon:

To add Code Templates:

1. From the main menu, select Window-->Preferences.
2. In the left pane, select C/C++-->Code Templates.
3. Click New. A dialog for adding new templates appears. You can view the format of existing templates by selecting them and clicking Edit:

## Adding `#include` directives (Add Include)

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

1. In the C/C++ Editor, highlight the entire function name by double-clicking it. 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 can give you information about functions while you're coding.

To use hover help:

| In the C/C++ Editor, place your pointer over a function. A tag appears, showing the function summary and synopsis:

## Commenting out code

The IDE makes it easy to comment out large sections of code. You can quickly add `//` characters to the beginning of lines, letting you comment out large sections, even if they have `/* */` comments. When you uncomment lines, the IDE removes the leading `//` characters from all lines that have them, so be careful not to accidentally uncomment sections. Also, the IDE comments or uncomments the selected lines -- if you select a partial line, the IDE comments out the entire line, not just the highlighted section of code.

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 appearance

You can change the font, set the background color, display 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.

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

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

## Using other editors

The IDE lets you use other editors, but you should consider the added functionality the C/C++ Editor offers before changing.

The C/C++ Editor is highly integrated with the IDE. The other views are designed to support the C/C++ Editor by updating dynamically. Since other editors aren't designed to interface with the IDE, you won't get the support from the views that the IDE provides.

You can use other editors 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 outside of the IDE:

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

### Within the IDE

The IDE lets you set file associations that determine the editor you 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 a set association for a certain file type, it uses the OS defaults. Thus, in Windows, double-clicking on a `.DOC` file automatically opens the file in MS Word or WordPad.

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

# More development features

The IDE has many features that help you work faster. Not all the features are things you'd necessarily think to look for; after you've used the IDE for a while, take some time to read this entire section.

This section includes:

- Tracking remaining work (Tasks view)
- Code synopsis (Outline view)
- Checking your build (C-Build view)

## Tracking remaining work (Tasks view)

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

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

The IDE also shows corresponding markers in several other locations:

- C/C++ Projects view: on both the file that contained compile errors and the project
- Outline view: in the method (e.g. main())
- C/C++ Editor: on the left side, beside the offending line of code.

### Jumping to errors

To quickly jump to the source of errors (if the IDE can determine where it is):

| In the Tasks view, double-click the error marker or warning marker . The file opens in the editor area, and the cursor jumps to the offending line.

To jump to errors sequentially:

| Click the Jump to next error marker button or 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. The IDE lets you customize the Tasks view so you see only the errors you want to see.

To access the error filtering dialog:

| In the Tasks view, click the Filter icon . The Filter Tasks dialog appears and lets you adjust the scope of the errors shown in the Tasks view. To see all errors and warnings, check all the boxes in Show items of type and enable On any resource:

### Setting reminders

The Tasks view lets you create your own tasks. In addition to having the Tasks view automatically list build errors, you can set personal reminders regarding the unfinished function you're writing, the error handling routine you want to check, or anything else.

To access the New Tasks dialog to add a personal task:

| In the Tasks view, right-click the tasks pane and select New Task. A New Tasks dialog appears:

To remove a personal task:

| In the Tasks view, right-click the task and select one of Delete or Mark Completed.

## Code synopsis (Outline view)

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

It shows the elements in the source file in the order they occur, including functions, libraries, and variables. You may also sort the list alphabetically. If you double-click an entry in the Outline view, the C/C++ Editor moves the cursor to the start of the item selected. (For example, to jump to the start of main() in the C/C++ Editor, double-click main() in the Outline view.)

## Checking your build (C-Build view)

The IDE displays the output from the `make` utility in the C-Build view:

### Customizing the C-Build view

You can choose to clear the C-Build view before each new build or let the results of each subsequent build to append to the display. You can have the C-Build view brought to the top when you build.

To access the C-Build view configurations:

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