This article describes 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 is based on IDE 4.5.1 and some IDE 4.6 features.
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 a shared drive (unless you're sure only one user is using it). The IDE also uses the concept of a project, 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 lets you filter and group projects if you have too many of them in a workspace. There is also a special QNX Container project that lets you control and 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 doesn't 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've 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 filesystem that contains the project root (for 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.
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 it's 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 is called Discovery and can be controlled using the Discovery Options. If you know what includes and defines you're using, it's probably easier just to enter them directly (via Project->Properties->C/C++ General -> Path and Settings).
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 (for details, see the Conventions for Recursive Makefiles and Directories chapter of the QNX Neutrino Programmer's Guide). These conventions allow the IDE to parse the makefile and provide UI control over makefile options and build variants. You can typically use a single QNX project to build one binary/library for several variants, such as x86 and PPC in debug, release, and profiling modes.
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.
Let's consider some scenarios where you'd create a project for the first time (in comparison to checking out a pre-made project, which we'll discuss later).
When you create a new IDE project, you have to pick from one of the following options:
New Project (#1): Pick one of the project types described above. Use the File->New... menu, pick C or C++ Project, and then:
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 the 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 (these aren't in version 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.
Here's how to create a project by checking out from several folders from a 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.
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, or else you'll overwrite the .project file for those original projects with the one for your combined project. To ensure you don't accidentally check it in, we recommend that you add it to svn's list of files to ignore, preventing it from showing up as changed resource.
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 (.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. Some metadata is stored in files other than .project and .cproject. For example, the Check Dependencies On/Off settings are manifested as additional Makefiles (two in IDE 4.5, one in IDE 4.6).
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.
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:
See more details in Example 4, below.
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:
You can adjust the build properties for Managed projects using the Project Properties.
Example of things you can do in Project Properties:
Other things:
For a Makefile project, you can change the location where the build starts from, and the make arguments (and even the command to launch make itself). You can also change environment variables for the make invocation in the Environment subcategory of the C/C++ Build options. You can change the same variables 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.
To do a simple build for an active configuration, select one or more project, and then select Build Project from the context menu or from the main Project menu. To clean one or more projects, select Clean Project.
For QNX and Makefile projects, you can create and build specific make targets. Use the context menu for that.
For Makefile and Managed projects, you can create several build configurations (for example debug, release, x86, arm or any combinations or these), you can switch the default active configuration and build using the Build Configurations menu. You can also set a global preference to build one configuration or all when you do a build on a Managed project (in IDE 4.6 or later).
A container project is a specific, complex, quasi-hierarchical project that lets you combine a set of projects in order to quickly switch between different build configurations. The root of a container project is always a container. A container's children are configurations. A configuration is a set of projects of various types (including other containers). Each member of a configuration has two important attributes specific to the container environment: a target and a variant. These are very generic attributes; their interpretation is completely defined by a particular configuration member. For example, for a QNX C project, the target is a build target, such as build, clean, and the variant can be something like x86/release, x86/debug. To build any desirable configuration, just select the container configuration from the pull-down menu. For Managed projects, you can use Working Sets to build them together.
To set up automated builds in version 4.5 of the IDE, you have to use make. If you're using a Managed project, you have to use Gnu Make Build, which generates makefiles for you. If a project doesn't depend on anything, just run make in a root (or appropriate) directory. If you want to build several projects, you have to create an external makefile that references all subprojects. For details, see the IDEBuildFAQ.
In version 4.6 of the IDE, you can use the mkbuild command (it comes with the QNX Momentics Tool Suite 6.4.1), which launches Eclipse in headless mode (that is, without the UI) and lets you build projects in your workspace as you would from the UI. For more information, see the IDE User Guide.
Example 1
Suppose your local source (c++) files are in the following structure:
-source
-a
+inc
-b
-mydir
+src
+out
Makefile
You work in the mydir directory and just run make, which picks up libraries from other parts of the filesystem and picks header files from inc (and local ones inside mydir). To create a project, do the following:
Example 2 (Makefile isn't in the root)
Suppose that the directory structure is the same as in example 1, except that the Makefile is in the out directory, and this is the build directory.
Example 3 (Link for output directory)
Once again, let's use the same directory structure as in example 1, except that the out directory is outside of mydir (but the Makefile is still in there).
Example 4 (Links for everything)
This time, the source code is in directory A, the output binaries are in directory B, and the extra header files in directory C. All of them have a common root, D (for example D/x/y/z/A, D/x/C, D/w/C)
You want the project itself with its metadata to be somewhere else. You also want to share it, if possible.
Procedure
The Build Project and Clean Project commands should now work. You should see your binaries in the Binary container. And your includes in the Includes container. Open a source file and check that Include navigation works (double-click on an external include in the Outline view; you should navigate there).