Projects, Build and IDE#

This article talks about how to set up projects in the QNX Momentics IDE, what types of projects to pick, and how to organize projects to perform effective builds from the IDE and command line. This article based on IDE 4.5.1 and some IDE 4.6 features.

What do you need to know about the IDE project model?#

The QNX Momentics IDE is based on the open source Eclipse platform and the open source CDT project, which give the essential part of the functionality of projects and builds. The IDE uses the concept of a workspace, which is a user-specific writable directory on the local host. This directory itself should never be part of a version-control system shared between users, nor should it be located on shared drive (unless you're sure only one user is using it). The IDE (Eclipse) also uses the concept of a project , which is a container for source and binaries together with some configuration files, which usually is located in your workspace, and which can be shared between users using a version-control system.

Projects are flat; they cannot contain one another. However there is a concept of a Working Set , which allows you to filter and group projects if you have too many of them in a workspace. There is also a special QNX Container project that allows you to control/build sets of projects at the same time.

When you pick the location of your workspace and the names of the projects, be aware that these names can be used in the build, and make does not like directory and file names with spaces and funky characters in them, even it is fine with the IDE -- the build won't work with such paths.

If you used Visual Studio before, you may think that a project is a virtual container that contains arbitrary files and directories, but this isn't the case with Eclipse. You can stretch an Eclipse project to use "Eclipse Links", but they have limited functionality. In general you have to have a directory in the file system that contains the project root (source and build output), and the same directory would contain the Eclipse project metadata. If you want to separate the project metadata from the source directories, you have to use folder links. You have an option to put a project inside or outside your workspace. You can use your imagination about how a project directory is created: you can check out the top level from one place, and subdirectories from another, you can use OS soft links, or some other means to create it.

The QNX Momentics IDE supports 3 project types: Makefile projects, QNX projects, and Managed projects.

Makefile projects#

A Makefile project would work for any project that has a Makefile (by default). Technically it can launch anything as an external builder in any folder. The IDE starts make ; after make exits, the IDE refreshes the workspace to show what you have created. You can change the make command and/or run specific make targets, but the IDE has no control over what make is doing.

Because the IDE doesn't know what is building, it would have problems parsing source files (which it does internally to allow Navigation, Code Completion, Syntax Highlighting, Code Generation and Refactoring). So if you use a Makefile project, you have to tune the "Indexer" (the internal parser) to point it to where to find any missing Includes and what Defines your parser uses for conditional compilation. The process of figuring this out called "Discovery" and can be controlled using "Discovery Options". If you know what includes and defines you are using, it is probably easier just to enter them directly (Project->Properties->C/C++ General -> Path and Settings).

QNX projects#

A QNX project is special a flavor of a Makefile project with additional control over the make. To use a QNX project, you also have to use QNX recursive makefiles. QNX recursive makefiles follow certain conventions for creating makefiles that use specific variables and use a specific layout. This allows the IDE to parse the makefile and provide UI control over makefile options and build variants. You typically can use a single QNX project to build one binary/library for several variants, such as x86 and PPC in debug, release, and profiling modes.

Managed projects#

A Managed project is a CDT-specific project that doesn't use makefiles, and all build settings are controlled by the UI. The inconvenience of it is its inability to perform a build of the project from the command line (although it is possible in simple cases with some extra setup files, or you can use a makefile generator). Also there are restrictions on what you can build and how, especially if you use special steps in the the build that involve other tools.

Original project creation#

Let's consider some scenarios where you'll create a project for the first time (in comparison to checking out a pre-made project, which will be discussed below).

When you create a new IDE project, you have to pick from one of the following options:

1. This is new project; I will create all source in the IDE.
2. The source/structure exists already in the file system, and I want to "attach" an IDE project to it.
3. The project source/structure exists in a version-control system.

New Project (#1) - pick one of the project types described above. Use the File->New... menu and pick the C or C++ project wizard:

• For a QNX project, pick "QNX C Project" (or "QNX C++ project" for C++). On the first page, pick the build variants (for example, x86 Debug & Release).
• For a Makefile project, pick "C Project" (or "C++ Project" for C++). Select Makefile on the left. Pick QNX Toolchain on the right. Click Finish.
• For Managed project, pick "C Project" (or "C++ Project" for C++). Select one of the projects types or templates on the left, other than Makefile. Pick QNX Toolchain on the right. Click Finish.

Attaching to an existing folder(#2) - pick one of the project types described above for your project. Open the corresponding wizard as described in #1, but don't proceed any further. The first wizard page asks you to choose between using the default location and picking one. Uncheck "Use default location". Select the location of your existing project using the "Browse" button. Follow the wizard as in #1. Alternatively, you can create the project in the default location and later attach other directories using link folders. See Example 4, below.

Checking out from source control(#3) - pick one of the project types described above for your project. If the whole project is in one directory in the version-control system, you can use Check Out As... action of the SVN or CVS plugin to check it out. Use "Check out as a project configured using New Project Wizard" and pick the wizard of your choice. For a QNX project, make sure you uncheck Generate default file and Generate Makefiles (? - not in 4.5 - you need to revert to the base to restore makefiles after checking out). If you want a partial checkout, see the next section.

Checking out a partial source tree#

Here's how to create a project by checking out from several folders from version-control system (this example uses SVN).

Let's say you have a folder in svn called big_project, and it has 100 subfolders, each of them representing different binaries, but big_project has a Makefile and some other common folders, such as "public_includes" that you need to compile your subfolder "my_binary".

• Follow the instructions for checking out a folder as a new project (big_project) but unselect "Checkout recursively" (SVN cannot check out one file; it has to be the whole folder).
• Now find the "my_binary" subfolder in SVN, right click->Find/Check Out As..., and then select "Check out as folder into existing project". Click Next.
• Select the previously created project. Click Finish.
• If you need any other subfolders, repeat the process.
• Switch to the C/C++ Perspective.

If you checked out more than one project that shares an SVN folder as its project root, you can't commit the .project file back to SVN. You would need to add it to svn's list of files to ignore to prevent it from showing up as changed resource.

Sharing projects#

When you have created a project, you may want to "share" the settings so the next person can just check it out as an Eclipse project. If the given project root matches with exactly one folder in the source control system, you may commit project metadata files back (.project and .cproject). If your project is attached to version control, but you don't want them to be committed, you have to add those files to the "ignore" list.

QNX projects share most of the options in makefiles, however some options such as the current build variants are user-specific (i.e. not in the project metadata). You can make them "shared" by enabling "Share project properties" in the Main tab of the QNX project properties.

Checking out existing Eclipse projects#

Source control IDE integrations (CVS and SVN) can detect the presence of the Eclipse project metadata in the repository and check out pre-made projects. You can search recursively and check out all existing projects from the selected folder or choose a specific project. You can also create a special file called a "Team Project Set" (.psf) that contains a set of projects that you want everybody to check out. Team sets can be located in the source control repository as well, and the IDE will recognize them and should be able to check out all specified projects automatically.

Quick and Dirty project creation#

If you don't want to build using the IDE, but you suddenly want to use the debugger or profiler, or find memory corruption, you can create a simple project in the IDE for these tools to use. To do this:

• Create an empty Makefile project.
• Copy or Link the source files into the project.
  • To create a link, create a new directory in the project. In the new directory dialog, select Advanced, and the pick Link to folder.
• Copy or Link binaries and libraries into the project.
• Create a launch configuration for the selected tool.
• If you want source navigation, and the source files aren't in the same location where they were compiled, you need to enable Source Path Lookup; edit the Source tab of the launch configuration to provide a lookup.

See more details in Example 4, below.

Build Properties#

QNX projects#

You can adjust the build properties for a QNX project using Project Properties or by modifying the makefile. Be aware that if you modify the makefile manually, you can make it unrecognizable by the IDE, and it won't be able to properly update it in future.

Example of things you can do in Project Properties:

• Add extra libraries and library paths (Linker tab -> Pick Extra Libraries from drop down)
• Add extra includes (Compiler tab -> Pick Extra Include from drop down)
• Define macro variables for the whole project
• Define macros and includes for one file (Click Advanced and pick file on the left)
• Select more than one platform to build for (Build Variants tab)
• Create another build variant (such as Profiling)
• Change a make variable (from Make Builder tab - override Build Command such as make DEBUG=1)
• Add custom compiler and linker options
• Change name of the output binary/library

Managed projects#

You can adjust the build properties for Managed projects using the Project Properties.

Example of things you can do in Project Properties:

• Add extra libraries and library paths (C/C++ Build->Settings->QCC Linker->Libraries)
• Change output options, such as add Debug, Optimize, or Instrumentation options (C/C++ Build->Settings->QCC Compiler->Output Control). Some options require changes in both the compiler and linker.
• Add custom linker or compiler options
• Add another build variant (build configuration) (Manage Configuration... button in any page of C/C++ Build)
• To set individual file's options, use the same properties, but on the file/folder.

Other things:

• To exclude a file from a build, select the file and select Exclude from build from the context menu.
• To include a folder in the build, it has to be a "source folder". Or you click on the folder, select Properties, and then uncheck "Exclude from build" in C/C++ Build page.
• You can choose Internal Build or External Make build with make generation. This is controlled from (C/C++ Build->Tool Chain Editor->Current Builder).

Makefile projects#

For a Makefile project, you can change the location where build starts from, and the make arguments (and even the command to launch make itself). Also you can change environment variables for the make invocation in Environment subcategory of C/C++ Build options. Same variable can be changed automatically from the Settings tab, if you're using QNX naming conventions for the make variables. If the variables are defined in make itself, environment variables can't override them, unless you use make -e.

All other options you set in your makefile.

Building from IDE#

To do simple build for active configuration select one or more project and select Build Project from context menu or from Project main menu. To clean project(s) select Clean Project.

For qnx and makefile project you can create and build specific make targets. Use context menu for that.

For managed project you can switch default active configuration and build using Build Configurations menu. You can also set global preference of whether to build one configuration or all when you do a Build on managed project (>= IDE 4.6).

Container project is a specific complex quasi-hierarchical project that lets to combine set of projects in order to quickly switch between different build configuration. Root of container project is always a container. Container's children are configurations. Configuration is a set of projects of various types (including other containers). Each member of configuration has two important attributes specific for container environment: target and variant. These are very generic attributes, their interpretation completely defined by particular configuration member. For example, for QNX C project target is a build target, such as build, clean, and variant can be something like x86/release, x86/debug. To build any desirable configuration user just select container configuration from pull down menu. For managed project you can use Working Sets to build them together.

Setting up automated builds#

In IDE 4.5 to set up automated build you have to use make. If you are using managed project you have to use Gnu Make Build which would generate makefiles for you. If projects does not depend on anything you just run make in a root (or appropriate directory). If you want to build several project you have to create external makefile which references all subprojects. See details in IDEBuildFAQ.

In IDE 4.6 you can use mkbuild command (comes with 6.4.1) which launches eclipse in headless more (no UI) and allow to build project in workspace as you would have done from UI. More info in IDE User Guide.

Examples#

Example 1

You local source (c++) files have the following structure:

 -source
    -a
      +inc
      -b
         -mydir
           +src
           +out     
            Makefile
 

You work in directory "mydir" yourself and just run make. Make picks up libraries from other pars of the file-system and picks includes from inc (and local ones inside mydir), To create project:

• Select "New->C++ Project" (from context menu in Project Navigator)
• Name "mydir" (or any name your like)
• Uncheck "Use default project location"
• Browse to pick directory "mydir" from file system
• Select Makefile->Empty Project
• Select QNX Toolchain
• Click finish
• Select new project and select Properties... from context menu (right click)
• In Properties select C/C++ General->Paths and Symbols
• Select GNU C++ and add Directory /source/a/inc as your include path (This required for internal parser - for code navigation, refactoring, syntax highlighting, etc)
• Also if you know default macro that make used to build source add them here (For example if you compile as qcc -DDEBUG foo.c, add DEBUG macro)
• Run Build Project

Example 2 (Makefile is not in the root)

Same as Example 1 but Makefile in the out directory, and this is build directory

• Create project as above
• Open Project Properties, click on C/C++ Build
• As Build directory specify ${workspace_loc:/mydir/out}

Example 3 (Link for output directory)

Same as Example 1 but out directory is outside of mydir (Makefile in there still)

• Create project as above
• Select the project and select New->Folder from context menu
• In folder dialog, click Advanced
• Select Link the folder in the file system
• Select output folder outside of project "mydir"
• Click Finish

Example 4 (Links for everything)

Source code in directory A. Output binaries in directory B. Extra includes in directory C. All of them have common root D (for example D/x/y/z/A, D/x/C, D/w/C)

You want project itself with metadata somewhere else. You also want to share it if possible.

Procedure

• Create C++ Empty makefile project
• In the project dialog use default project location (in workspace). Lets call it Project4. Click Finish.
• Now we going to create link folders for A,B,C
  • In the project select New->Folder from context menu
    • Click Advanced, Check "Link the folder in the file system"
    • Select "Variables..." (If you don't have button, because of earlier version of IDE just select path from file system)
    • Add new variable called ROOT_DIR and select its path in file system pointing to directory D
    • In the dialog click Extend... and select subdirectory A
  • You should see path something like ROOT_DIR/x/y/z/A in the path. Click Finish
  • Repeat procedure for output directory B (you don't need to create ROOT_DIR again, just click Extend...)
  • Repeat procedure for extra include directory C (this is required so project setting can keep relative path, if you not going to share this project this step can be ommited)
• Now you add extra include folder
  • In Properties select C/C++ General->Paths and Symbols. Select GNU C++ and add Directory C as include search path using "Workspace..." button (would look like /Project4/C).
• Now let say make file in the folder A (source folder). We need to instruct IDE to run make from there.
  • Open Project Properties, click on C/C++ Build
  • As Build directory specify ${workspace_loc:/Project4/A}

Now Build Project, Clean Project should work. You should see your binaries in Binary container. And your includes in Includes container. Open a source and check that Include navigation works (Double click on external include in Outline view - you should navigate there).