Managing Source Code

You can select a topic from this diagram:

Glossary What's New 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 CVS chapter highlighted


This chapter describes managing source code from within the IDE.

In this chapter:

CVS and the IDE

CVS is the default source-management system in the IDE. Other systems (e.g. ClearCase) are also supported.

The CVS Repository Exploring perspective lets you bring code from CVS into your workspace. If another developer changes the source in CVS while you're working on it, the IDE helps you synchronize with CVS and resolve any conflicts. You can also choose to automatically notify the CVS server whenever you start working on a file. The CVS server then notifies other developers who work on that file as well. Finally, the CVS Repository Exploring perspective lets you check your modified code back into CVS.


Note: The IDE connects to CVS repositories that reside only on remote servers -- you can't have a local CVS repository (i.e. one that resides on your host computer) unless it's set up to allow CVS pserver, ext, or extssh connections.

Local history feature

The IDE lets you "undo" changes with its local history. While you're working on your code, the IDE automatically keeps track of the changes you make to your file; it lets you roll back to an earlier version of a file that you saved but didn't commit to CVS.

For more information about the IDE's local history feature, see this link in the Workbench User Guide: Reference-->User interface information-->Development environment-->Local history.

Project files (.project and .cdtproject)

For each project, the IDE stores important information in these two files:

You must include both of these files with your project when you commit your changes into source control.

Core Eclipse documentation on using CVS in the IDE

Since the CVS Repository Exploring perspective is a core Eclipse feature, you'll find complete documentation in the Eclipse Workbench User Guide. Follow these links:

The following table may help you find information quickly in the Workbench User Guide:

If you want to: Go to:
Connect to a CVS repository Tasks-->Working in the team environment with CVS-->Working with a CVS repository-->Creating a CVS repository location
Check code out of CVS Tasks-->Working in the team environment with CVS-->Working with projects shared with CVS-->Checking out a project from a CVS repository
Synchronize with a CVS repository Tasks-->Working in the team environment with CVS-->Synchronizing with the repository, particularly the Updating section
See who's also working on a file Tasks-->Working in the team environment with CVS-->Finding out who's working on what: watch/edit
Resolve CVS conflicts Tasks-->Working in the team environment with CVS-->Synchronizing with the repository-->Resolving conflicts
Prevent certain files from being committed to CVS Tasks-->Working in the team environment with CVS-->Synchronizing with the repository-->Version control life cycle: adding and ignoring resources
Create and apply a patch Tasks-->Working in the team environment with CVS-->Working with patches
Track code changes that haven't been committed to CVS Tasks-->Working with local history, especially the Comparing resources with the local history section
View an online FAQ about the CVS Repository Exploring perspective Reference-->Team Support with CVS-->CVS

Importing existing source code into the IDE

As with many tasks within the IDE, there's more than one method to bring existing source files into your workspace:

Whatever method you use, you always need to set up an IDE project in your workspace in order to work with the resources you're importing.

If you're importing code that uses an existing build system, you may need to provide a Makefile with all: and clean: targets that call your existing build system.

For example, if you're using the jam tool to build your application, your IDE project Makefile might look like this:

all:
    jam -fbuild.jam

clean:
    jam -fbuild.jam clean

Projects within projects

If you have an existing source hierarchy that looks something like this:

Source tree example

To work efficiently with this source in the IDE, each component and subcomponent should be a "subproject" within the one main project. (You could keep an entire hierarchy as a single project if you wish, but you'd probably find it cumbersome to build and work with such a monolith.)

Unfortunately, the current version of the IDE doesn't support nesting projects as such. So how would you import such a source tree? You would use the following four step process:

  1. Step 1: Creating an initial project for your source code
  2. Step 2: Creating a new project for each existing project or component in your source code tree
  3. Step 3: Linking the projects to a directory in the source tree
  4. Step 4: Building the component project in the linked folder

For information about container projects, see "Using container projects" in this chapter.

Step 1

First, in your workspace create a single project that reflects all the components that reside in your existing source tree:

  1. Select File-->New-->Project....
  2. Select the type of project (e.g. Standard Make C project).
  3. Name your project (e.g. EntireSourceProjectA).
  4. To tell the IDE where the resources reside in the filesystem (since they don't reside in your workspace), disable the Use Default Location option.
  5. In the Location field, type the path to your source (or click Browse...).
  6. Click Finish. You should now have a project that looks something like this in the C/C++ Projects view:

    Entire source project example

Step 2

Now, you need to create an individual project (via File-->New-->Project...) for each of the existing projects (or components) in your source tree. In this example, you create a separate project for each of the following source components:

To create individual projects:

  1. Select File-->New-->Project....
  2. Select the type of project (e.g. Standard Make C project).
  3. In the Name type a descriptive name for your project (e.g. Project_ComponentA).
  4. Enable the Use default location option because you want the IDE to create a project in your workspace for this and all the other components that comprise your project EntireSourceProjectA. In the next step, you'll link each project to the actual location of the directories in your source tree.
  5. Click Finish, and you'll see Project_ComponentA in the C/C++ Projects view.

Step 3

Next, you'll link each individual project in the IDE to its corresponding directory in the source tree:

To link projects:

  1. Select File-->New-->Folder.
  2. Make sure your new project (Project_ComponentA) is selected as the parent folder.
  3. Type a name for the folder (e.g. ComponentA).
  4. Click Advanced>>.

    New Folder, Advanced options

  5. Enable the Link to folder in the file system option.
  6. Type the path to that folder in your source tree (or use Browse... to locate and select one).
  7. Click Finish. Now. your Project_ComponentA project should show a folder called ComponentA; the contents of which actually reside in your source tree.

Step 4

Now, you need to tell the IDE to build Project_ComponentA in the ComponentA linked folder that you just created in your workspace:

  1. In the C/C++ Projects view, right-click Project_ComponentA, then select Properties from the context menu.
  2. Select C/C++ Make Project.

    Make Builder properties

  3. In the Make Builder tab, set the Build Directory to ComponentA in your workspace.

Now, when you start to build Project_ComponentA, the IDE builds it in the ComponentA folder in your workspace (even though the source actually resides in a folder outside your workspace).


Caution: Linked resources let you overlap files in your workspace, so files from one project can appear in another project. If you change a file or other resource in one location, the duplicate resource is also affected. For example, if you delete a duplicate resource, its original is also deleted.

Special rules apply when working with linked resources. Since a linked resource must reside directly below a project, you can't copy or move a linked resource into other folders. If you delete a linked resource from your project, this does not cause the corresponding resource in the filesystem to also be deleted. But if you delete child resources of linked folders, this does delete those child resources from the filesystem!


Filesystem drag-and-drop

On Windows hosts, you can select files or folders and drop them into projects in the Navigator view:

  1. Create a new project. If your existing code has an existing build procedure, use a Standard Make C/C++ Project. If not, you can use a QNX C/C++ Project or a Standard Make C/C++ Project.
  2. Switch to the Navigator view.
  3. Select one or more source files or folders from Windows Explorer, then drag them into the project. The files are copied into your project workspace.

Note: From Windows Explorer, you can also use Cut, Copy, and Paste to move or copy files into a project.

CVS repository

Using the CVS Repository Exploring perspective, you can check out modules or directories into existing projects, or to create new projects.

Importing code into the IDE from CVS differs slightly depending on what you're importing:

Importing a C/C++ project from CVS

To check out an existing C/C++ project (either a QNX project or a Standard Make C/C++ project) from the CVS repository into your workspace:

  1. Right-click the project in the CVS Repositories view and choose Check Out from the menu.

    The IDE creates a project with the same name as the CVS module in your workspace. The project is automatically recognized as a Standard Make C/C++ or QNX C/C++ project (if the project has .project and .cdtproject files).

  2. If the project is a QNX project:
    1. Right-click the new project in the Navigator or C/C++ Projects view and choose Properties.
    2. Click the Build Variants tab, which displays a warning:

      At least one platform should be selected

    3. Select one or more of the build variants, then click OK.

Importing C/C++ code from CVS

To check out existing C/C++ code that isn't part of a project:

  1. Right-click the module or directory in the CVS Repositories view and choose Check Out As... from the menu.

    The IDE displays the Check Out As wizard.


    Check Out As


    The Check Out As wizard.

  2. Choose how to check out this project:
  3. Choose the workspace location for this project, then specify the CVS tag to check out. Click Finish to exit the Check Out As dialog.
  4. Click Next to continue.
  5. If you're creating or checking out a QNX project:
    1. Right-click the new project in the Navigator or C/C++ Projects view and choose Properties.
    2. Click the Build Variants tab, which displays a warning:

      At least one platform should be selected

    3. Select one or more of the build variants, then click OK.
  6. If you're creating a Standard Make C/C++ project, create a new Makefile with appropriate all: and clean: targets.

Importing C/C++ code into an existing project

To import a directory full of C/C++ code into an existing project:

  1. Right-click the module or directory in the CVS Repositories view and choose Check Out As... from the menu.

    The IDE displays the Check Out As dialog.

  2. Choose Check out into an existing project, and then click Next. The IDE displays the Check Out Into dialog:

    Check Out Into

  3. Select an existing project from the list, and then click Finish to add the code from CVS to the selected project.

Import wizard

Use the Import wizard to bring files or folders into an existing project from a variety of different sources, such as:

For details, see "Importing projects" in the Common Wizards Reference chapter.

Linked resources

As an alternative to dragging-and-dropping, you can link files and folders into a project. This method of linking resources lets you include files in your project, even if they need to reside in a specific place on your filesystem (because of a restrictive source control system, for example).

To add a linked resource to a project in the C/C++ Project or Navigator view:

  1. Right-click on a project, then select either New-->File or New-->Folder.

    The New File or New Folder dialog appears.

  2. In the Name field, type a new name for the file or folder.
  3. Click Advanced >>, and enable either the Link to file in the file system or Link to folder in the file system option.
  4. Type the full path to the file or folder, or click Browse... to select a specific file or folder.
  5. Click Variables... to define any path variables for use in the file or folder path:

    Setting path variables

  6. Click Finish to link the file or folder into your project.

See Concepts-->Workbench-->Linked resources in the Workbench User Guide for more information about linked resources.

Using container projects

A container is a project that creates a logical grouping of subprojects. Containers can ease the building of large multiproject systems. You can have containers practically anywhere you want on the filesystem, with one exception: containers can't appear in the parent folders of other projects. The IDE doesn't support the creation of projects in projects.

Containers let you specify just about any number of build configurations (which are analogous to build variants in C/C++ projects). Each build configuration contains a list of subprojects and specifies which variant to build for each of those projects.


Note: Each build configuration may contain a different list and combination of subprojects (e.g. QNX C/C++ projects, Standard Make C/C++ projects, or other container projects).

Creating a container project


Note: In order to create a container, you must have at least one subproject that you want to contain.

To create a container project:

  1. Select File-->New-->Project..., then QNX-->C/C++ Container Project.
  2. Click Next.
  3. Name the container.
  4. Click Next.
  5. In the New Project dialog, click Add Project....
  6. Now select all the projects (which could be other containers) that you want to include in this container:

    Container contents

    Each subproject has an entry for make targets under the Target field. You can click on an entry to get a menu that lets you change the selection. The "Default" entry means "don't pass any targets to the make command." QNX C/C++ projects interpret this as "rebuild." If a subproject is also a container project, this field represents the build configuration for that container.


    Note: You can set the default for QNX C/C++ projects by opening the Preferences dialog box (Window-->Preferences in the menu), then choosing QNX-->Container properties.

  7. If the project is a QNX C/C++ project, you can click in its Variant entry to select the build variant for each project you wish to build. You can choose All (for every variant that has already been created in the project's folder) or All Enabled (for just the variants you've selected). Note that the concept of variants makes sense only for QNX C/C++ projects.
  8. If you wish, click in the Stop on error column to control whether the build process for the container stops at the first subproject to have an error or continues to build all the remaining subprojects.
  9. If you want to reduce clutter in the C/C++ Projects view, then create a working set for your container. The working set contains all the projects initially added to the container. Note that the working set and the container have the same name.

    Note: If you later add elements to or remove elements from a container project, the working set isn't updated automatically.

  10. Click Finish. The IDE creates your container project.

To select a working set, click the down-arrow at the top of the C/C++ Projects view pane, and then select the working set you want.

Setting up a build configuration

Just as QNX C/C++ projects have build variants, container projects have build configurations. Each configuration can be entirely distinct from other configurations in the same container. For example, you could have two separate configurations, say Development and Released, in your top-level container. The Development configuration would build the Development configuration of any subcontainers, as well as the appropriate build variant for any subprojects. The Released configuration would be identical, except that it would build the Released variants of subprojects.


Note: Note that the default configuration is the first configuration that was created when the container project was created.

To create a build configuration for a container:

  1. In the C/C++ Projects view, right-click the container.
  2. Select Create Container Configuration....
  3. In the Container Build Configuration dialog, name the configuration.
  4. Click Add Project, then select all the projects to be included in this configuration.
  5. Change the Variant and Stop on error entries for each included project, as appropriate.

    Note: If you want to change the build order, use the Shift Up or Shift Down buttons.

  6. Click OK.

Editing existing configurations

There are two ways to change existing configurations for a container project, both of which appear in the right-click menu:


Note: Although you can use either method to edit a configuration, you might find changing the properties easier because it shows you a tree view of your entire container project.

Note also that you can edit only those configurations that are immediate children of the root container.


Editing via project properties

You can use the container project's properties to:

To edit a configuration:

  1. Right-click the container project and select Properties.
  2. In the left pane, select Container Build Configurations.
  3. Expand the project in the tree view on the right.
  4. Select the configuration you want to edit. Configurations are listed as children of the container.
  5. Click the Edit button at the right of the dialog. This opens the familiar Container Build Configuration dialog (from the New Container wizard), which you used when you created the container.
  6. Make any necessary changes -- add, delete, reorder projects, or change which make target or variant you want built for any given project.

    Note: While editing a configuration, you can include or exclude a component from the build just by checking or unchecking the component. Note that if you exclude a component from being built, it's not removed from your container.

  7. Click OK, then click OK again (to close the Properties dialog).

Editing via the Build Container Configuration... item

You can access the Container Build Configuration dialog from the container project's right-click menu.

Note that this method doesn't show you a tree view of your container.

To edit the configuration:

  1. Right-click the container project, then select Build Container Configuration....
  2. Select the configuration you want to edit from the list.
  3. Click the Edit button. This opens the familiar Container Build Configuration dialog (from the New Container wizard), which you used when you created the container.
  4. Make any necessary changes -- add, delete, reorder projects, or change which make target or variant you want built for any given project.
  5. Click OK to save your changes and close the dialog.
  6. Click Build or Cancel in the Build Container Configuration dialog.

Building a container project

Once you've finished setting up your container project and its configurations, it's very simple to build your container:

  1. In the C/C++ Projects view, right-click your container project.
  2. Select Build Container Configuration....
  3. Choose the appropriate configuration from the dialog.
  4. Click Build.

Note: A project's build variant selected in the container configuration is built, regardless of whether the variant is selected in the C/C++ project's properties. In other words, the container project overrides the individual project's build-variant setting during the build.

The one exception to this is the All Enabled variant in the container configuration. If the container configuration is set to build all enabled variants of a project, then only those variants that you've selected in the project's build-variant properties are built.


To build the default container configuration, you can also use the Build item in the right-click menu.

Importing a BSP or other QNX source packages

QNX BSPs and other source packages (e.g. DDKs) are distributed as .zip archives. The IDE lets you import these packages into the IDE:

When you import a: The IDE creates a:
QNX BSP source package System Builder project
QNX C/C++ source package C or C++ application or library project

Step 1: Use File-->Import...

You import a QNX source archive using the standard Eclipse import dialog:

Import BSP


Note: If you're importing a BSP, select QNX Board Support Package. If you're importing a DDK, select QNX Source Package.

As you can see, you can choose to import either a QNX BSP or a "source package." Although a BSP is, in fact, a package that contains source code, the two types are structured differently and generate different types of projects. If you try to import a BSP archive as a QNX Source Package, the IDE won't create a System Builder project.

Step 2: Select the package

After you choose the type of package you're importing, the wizard presents you with a list of the packages found in $QNX_TARGET/usr/src/archives on your host:

Select BSP

Notice that as you highlight a package in the list, a description for that package is displayed.

To add more packages to the list:

  1. Click the Select Package... button.
  2. Select the .zip source archive you want to add.

Step 3: Select the source projects

Each source package contains several components (or projects, in IDE terms). For the package you selected, the wizard gives you a list of each source project contained in the archive:

Select projects

You can decide to import only certain parts of the source package; simply uncheck the entries you don't want (they're all selected by default). Again, as you highlight a component, you'll see its description in the bottom pane.

Step 4: Select a working set

The last page of the import wizard lets you name your source projects. You can specify:

Select projects

If you plan to import a source BSP and a binary BSP into the IDE, remember to give each project a different name.


Note: If you import dual-endian BSPs, the wizard displays this informational message:

BSP import message

If you add build variants, you need to copy the CPU-specific files to the new variant's build directories.


Step 5: Build

When you finish with the wizard, it creates all the projects and brings in the source from the archive. The wizard then asks if you want to build all the projects you've just imported.


Note: If you answer Yes, the IDE begins the build process, which may take several minutes (depending on how much source you've imported).

If you decide not to build now, you can always do a Rebuild All from the main toolbar's Project menu at a later time.

If you didn't import all the components from a BSP package, you can bring in the rest of them by selecting the System Builder project and opening the import wizard (right-click the project, then select Import...). The IDE detects your selection and then extends the existing BSP (rather than making a new one).

QNX BSP perspective

When you import a QNX Board Support Package, the IDE opens the QNX BSP perspective. This perspective combines the minimum elements from both the C/C++ Development perspective and the System Builder perspective:

BSP perspective

Exporting projects

You can export projects to your filesystem or to an archive file by doing one of the following:

Using the Export... command

The Export wizard helps you export an entire project to your filesystem or an archive file.

To export one or more projects:

  1. Choose File-->Export... (or Export... from the Navigator context menu).

    The Export wizard appears:

    Export wizard

  2. To export your project to the filesystem, choose General-->File System. To export your project to an archive file, choose General-->Archive File. Click Next.

    The Export wizard's next panel appears:

    Export wizard

  3. Select the projects you want to export. You can also select or deselect specific files in each project.

    To select files based on their extensions, click the Select Types... button. The Select Types dialog box appears:

    Select Types dialog

    Click one or more extensions, then click OK to filter the selected files in the Export wizard.

  4. Type the name of the directory (if you're exporting to the filesystem) or file (if you're exporting to an archive file) in the input field.
  5. When you're done, click Finish.

Note: If you export more than one project, and you import from the resulting filesystem or archive file, you'll get one project containing all of the projects you exported.