My goal is to have all the particularly useful information about the QNX Momentics IDE relevant to our conventions and computer set up all contained in this document.  Please send e-mail to Celia with corrections or additions.

Conventions

Installing Momentics

Configuring Momentics

Creating Projects

    Creating A New Application

    Creating A New Library

Converting Exiting Code Into A Project

Using CVS

    Working With A New Project

    Moving A Momentics Project From Your Workspace To The CVS Tree

    Working With An Existing Project Not Yet In The CVS Tree

    Working With An Existing Project In The CVS Tree

Running an Application

Debugging with Momentics

    Single Process

    Multiple Processes

Tips and Tricks

Wish List

Useful Links

Conventions

File Extension for C++ Files

Momentics uses .cc as the default extension for C++ files.  We will use this convention for all newly created C++ files.  Some of our already existing C++ files use the extension .cpp.  In the interest of maintaining CVS history, we will continue to use the .cpp extension for those files only.  (Note: I have not yet checked if Momentics handles the .cpp extension properly.  Please let me know if you have any difficulties.)

Libraries

If any of your code will be used in multiple places, consider putting it in a library archive.  All of the library files are to be located in gc/src/qnx/common/lib, except the header files, which are to be located in gc/src/qnx/common/include.  The libraries themselves (e.g., libgcui.a) are to be located in gc/src/qnx/common/lib, and the library project is to be a subdirectory of gc/src/qnx/common/lib (e.g., gcui).  Test programs should be created for each library module.  The name of the project for the test program should be called check_<modulename>, also a subdirectory in gc/src/qnx/common/lib (e.g., gc/src/qnx/common/lib/check_ask).  See the current files and directories in gc/src/qnx/common/lib for more examples.

There are 3 parts to the name of a library: <lib><gc><name>.a. "lib" is prepended to the library project name by Momentics.   To easily distinguish our libraries from others, the library name should be prepended with "gc".  "name" should give some indication of the contents of the library.  When you create a "QNX C++ Library Project", name the project <gc><name> (omit the angle brackets), and locate all the source and header files in the project.  For more information on linking to and creating libraries, see the sections on Creating a New Application and Creating a New Library below.

More Conventions to come!

...

Installing Momentics

We have 2 QNX Professional Edition (PE) seats.  According to Dave Dickey of QNX, this means that we can have PE installed on as many machines as we want, so long as only 2 people are using it at a time.  Also, according to Dave Dickey, the only features PE has above the Non-Commercial version (NC), are the Momentics IDE, and the Dinkum Runtime Libraries (apparently NC only includes the GNU Libraries).  He recommends using the Dinkum Libraries because they are smaller, faster, more POSIX compliant, and pass the C/C++ compliance test (especially significant for C++).

Is Momentics Installed Already?

If Momentics is already installed on your computer, you should be able to access it from the Launch menu in the lower left corner of the screen.  Select Launch->Development, then look for "Integrated Development Environment (IDE)".  If it is present, Momentics is already installed.

Are the Dinkum Runtime Libraries Installed Already?

The Dinkum Full C++ Library is called libcpp.so.  It lives in the /x86/lib directory, and is a symbolic link to libcpp.so.2a.  The Dinkum Abridged C++ Library is called libecpp.so.  It also lives in the /x86/lib directory, and is a symbolic link to libecpp.so.2.  If these files exist on your system, I presume the Dinkum Libraries are installed.

How to Install Momentics

You use the QNX Installer program to install Momentics.  Here are the steps:

• Get a copy of the "Professional Edition Product Installation" CD located in a QNX envelop in the computer cabinets near the desks in the shop
• Login as root
• Start up the Installer by clicking on "Installer" on the list on the right side of the screeen or type qnxinstall in a terminal window.
• Insert the CD
• Wait for the CD to be read ("Professional Edition V6.2.1" will appear on the Repositories list)
• Click on "Professional Edition V6.2.1"
• Select the checkbox for "QNX Momentics PE for Neutrino (x86)"
• Click on the "Install" button on the top toolbar
• Follow the prompts
• Reboot your machine
• When your machine reboots, you should no longer see the NC disclaimer
• Start Momentics with Launch->Development->Integrated Development Environment (IDE)
• Enter the product license key: 910080-00493567-12244 (located on a page in the QNX envelop)
• Return the CD to the computer cabinet

You're set to go.

How to Install the Dinkum Runtime Libraries

The Dinkum Libraries were already present on my system before I installed Momentics.  I don't know if they will be installed (if they aren't there already) when you install Momentics per the instructions above.  Good luck.

Configuring Momentics

In this section I've included tips that will make your time with Momentics more efficient and effective.

Turning Off/On Automatic Builds

By default, Momentics automatically builds the project anytime one of the project resources is changed.  That means, for example, if you change and save a file in the project, the top-level Makefile will be run.  This is convenient when you are making small changes and don't want to have to go through a series of mouse clicks to build the code.  But, when you are making a lot of changes, potentially to several files, and want to save your work along the way, the automatic build feature can be annoying.  To turn this feature on or off, select the menu item Window->Preferences.  At the top of the dialog box, for the Workbench, click on the checkbox for "Perform build automatically on resource modification" to put it in your prefered state.

Line Numbers in C/C++ Editor Window

By default, line numbers are not displayed in the C/C++ Editor view.  In editors like vi, it is very easy to go to a particular line number.  In the C/C++ Editor view, it is a pain to bring up the dialog box and type in a number just to go to a particular line.  The solution is to always display the line numbers.  To do this, select the menu item Window->Preferences.  Click on C/C++ to expand the sub-items.  Click on the C/C++ Editor sub-item.  On the General tab, click on the checkbox for "Show line numbers".  Don't ask me why this doesn't add line numbers when you display Makefile or common.mk files.

CVS Connection

The only time you will need the CVS Repository Exploring perspective is when you configure your CVS connection.  Get to that perspective by selecting the menu item Window->Open Perspective->CVS Repository Exploring.  In the blank view called "CVS Respositories", right click and select the menu item New->Respository Location.  Fill out the "Add a new CVS Respository" form as follows:

Host: overtux.overbot.org

Repository path: /cvs

User: <your_user_name>

Password: <your_user_password>

Connection type: pserver

select - Use default port

check - Validate Connection on Finish

Then click on "Finish".  You should now have an item in your "CVS Repositories" view named :pserver:<your_user_name>@overtux.overbot.org:/cvs.  You can edit the Connection type, User, and Password fields by right clicking on the respository name and selecting the menu item Properties.  If you need to change any of the other fields, you will need to remove this location by right clicking on the repository name and selecting the menu item "Discard Location", and then create a new location as described previously.  In the future, if you need to access the CVS Repository Exploring perspective, you can click on the CVS with orange storage icon on the left side of the window.

CVS Ignored Resources

Binary files, and their revisions, make the CVS tree very large.  Since object files (*.o) are intermediate files, and have no use by themselves, we have decided to not store them in our CVS tree.  To prevent from writing object files to the tree, follow these steps.  Select the menu item Window->Preferences.  Click Team to expand the sub-items.  Click on CVS to expand its sub-items.  Click on the Ignored Resources sub-item.  Click on the checkbox for *.o to ignore object files when commiting files with CVS.

We want CVS to also ignore the *.a files in the project directories (no need to store these; they are built).  Click on the checkbox for *.a.

Lastly, we want CVS to ignore the dependencies.mk files because these will need to be different for every user.  Click on the "Add..." button and type dependencies.mk in the "Please enter a pattern:" box and click "OK".

CVS Prune Empty Directories

When you synchonize with the CVS repository, you will want empty directories to be "pruned", i.e., they will not be created in your sandbox.  You aren't allowed to remove directories under CVS, so if you want to rename a directory, you need to create a new directory, and move all the contents of the old directory into the new one.  The convention is that directories that are empty are no longer in use.  In order to direct CVS to "prune" empty directories, select the menu item Window->Preferences.  In the outline to the left, expand the item "Team" and select the subitem "CVS".  In the form, check the box for "Prune empty directories".

CVS Label Decorations On

Momentics (actually Eclipse) has a convenient labeling convention so you can quickly see if a resource has been modified since it was committed to your CVS repository.  Also included in the label is the version number and file type.  To turn on the CVS labeling of resources, select the menu item Window->Preferences.  Expand the item "Workbench", and click on the subitem "Label Decorations".  Check the box near "CVS", and click on "OK".  When you commit a project to CVS, you will see the labeling of the project and its resources in the C/C++ Projects and Navigator views.

If you want to customize the labeling, select the menu item Window->Preferences.  Expand the item "Team", and expand the subitem "CVS".  Click on the subitem "Label Decorations".  Modify the formats in the form to your preferences.

Creating Projects

Each executable or library created under Momentics is called a project.  Each project is stored in a directory of the same name.  Projects, and therefore the directories that projects are stored in, cannot be nested.  Each project consists of a group of resources: files and directories.  When a project is built (i.e., compiled), different versions, with different compiler flags (e.g., optimize, debug, etc.), can be made.  The subdirectories of a project are used to store the object, library, and executable files for the various compiler combinations.

Before you create a new application, confirm that you are in the "C/C++ Development" perspective.  On the left edge of the screen, the icon selected should have a "C" in the lower right.  If not, or if you aren't sure, select the menu item Window->Open Perspective->C/C++ Development.

Creating A New Application

If you want to create an executable file, you are creating an "Application" in Momentics.  The easiest way to create an application is to follow these steps:

• Select the menu item "QNX C++ Application Project" from the File->New menu
• Enter the name of the new project.  This will also be the name of the directory in which the project is stored.  The default location for the project directory is $(HOME)/workspace.  If you would like to store the application project elsewhere, including a location in the CVS tree, deselect the checkbox "Use Default Location", and type in the name of a directory (or Browse... to find the directory).
• Use all the default settings for the "QNX C++ Application Settings".
• Click on "Finish"
• You will notice that Momentics has created a project in the C/C++ Projects view (and the Navigator view).  You can expand and collapse the project to see the contents.
• To get information about the project, right click on the project name and select the menu item "Properties".

Before you go any further, this is the best time to modify the makefiles for our environment.  Double click the file named "Makefile" in the project you just created (in the "C/C++ Projects" view).  Add the following code to the end of the file:

#===== Macros and Targets added to file

SANDBOX = $(HOME)/sandbox

LIBS+=

include $(SANDBOX)/gc/src/qnx/common/make/bin.mk

• SANDBOX is a macro defining the location of your CVS sandbox.  You only need to define this if you are using CVS, or any of the files in the CVS tree.
• LIBS is a macro where you put libraries to which you want to link.  For example, if you want to link to the libgcui.a library, you would put LIBS+=gcui
• The include file contains macros relevant to our CVS setup.  It adds gc/src/qnx/common/lib to your library path, and defines gc/src/qnx/common/bin as the location to install executables.  You only need to include this file if you are using CVS, or any of the files in the CVS tree.

Double click the file named "common.mk".  Add the following text to the end of the file:

#===== Macros and Targets added to file

include $(SANDBOX)/gc/src/qnx/common/make/depends.mk

• The include file contains macros relevant to our setup.  It adds gc/src/qnx/common/include to your include path.  It creates and includes a dependency file (named dependencies.mk).  This file contains the dependencies between the object files and the source and header files.  Such relations are not automatically generated by Momentics, but are needed so that the code will be built when modifications are made to the header files.

You are now ready to create your application code.  By default, Momentics has created a file named <projectname>.cc in your project.  To add more .cc files and .h files to your project, right click on the project name in the C/C++ Projects view, and select the menu item New->File.  In the "File Name" field at the bottom of the dialog box, type in the name of your new file.  You can freely add files to your project.  The Momentics makefiles will do the right thing, and compile all the .cc files in the project and create an executable.

If you have the "Automatic Build" feature turned on, your code will be compiled any time it is saved.  If you don't hve the "Automatic Build" feature turned on, you can compile your code by right-clicking on the project and selecting the menu item Build.  If you would like to completely rebuild your code (i.e., clean out all the object files, etc. and then build the code), right-click on the project and select the menu item Rebuild.

Look at the output from the makefiles in the C-Build view to find bugs, or to confirm that your executable has been built successfully.  For information on running the program, go the the section titled Running An Application.

When you are ready to install your new application out into the public directory gc/src/qnx/common/bin so that everyone can use it, you will need to "add" a make target.  Do this by following these steps:

• Right click on the project name
• Select the menu item "Add Make Targets"
• Type "install" in the "Enter Target(s):" box.  Be careful to type the name correctly.  I have not found a way to get rid of phony make targets.  (Let me know if you figure it out.)
• Click on "OK"
• You have just made the target accessible.  Now you need to execute it.
• Right click on the project name
• Select the menu item "Make->install"
• View the print out in the C-Build view to confirm installation.  If you are really paranoid, especially the first time, check that the executable is installed in gc/src/qnx/common/bin.

If you have a watchdog startfile associated with the project, you can install it out in the public directory gc/src/qnx/common/startfiles.  First you need to let make know about the file, then you need to add a make target.

• Create the startfile in your top-level project directory (in the same location as the source files).  Name the file start_<descriptive_name>.txt.  See gc/src/qnx/common/startfiles for example names.
• In your top-level Makefile, add the following macro just before including the bin.mk file:

PUBLIC_STARTFILES = start_<descriptive_name>.txt

• Note that multiple startfiles can be specified, and will be copied out to the public directory properly.
• Right click on the project name
• Select the menu item "Add Make Targets"
• Type "install_startfiles" in the "Enter Target(s):" box.
• Click on "OK"
• You have just made the target accessible.  Now you need to execute it.
• Right click on the project name
• Select the menu item "Make->install_startfiles"
• View the print out in the C-Build view to confirm installation.  If you are really paranoid, especially the first time, check that the startfile is installed in gc/src/qnx/common/startfiles.

Having all the make targets in one place is very convenient.  When you are done building and testing the project, merely select each of the supplemental make targets and all your code and support files will be installed in the public directories.

Creating A New Library

Converting Existing Code Into A Project

Using CVS

The steps to move a project over to CVS are a bit involved, but once it is under CVS control, you will find the interface very easy and intuitive to use.  With CVS Labels turned on, you can very easily see which project resources are under control, and which resources are out of synch with the repository.  The capability to display the differences between files is very slick.

Working With A New Project

Moving A Momentics Project From Your Workspace To The CVS Tree

Suppose you've been working on a Momentics project outside of the CVS tree, and now you want to put it under CVS control.  To illustrate the steps involved, let's suppose you created a Momentics C/C++ Application project called gearserver located in /home/celia/workspace.  Here are the steps to get gearserver under the CVS tree:

• Create a CVS sandbox (called sandbox in your home directory) if you haven't already (see the Concurrent Version System server note for more information).
• Decide where to store the project in the CVS tree (see Development Philosophy and the README.txt file in gc/).  For gearserver, a logical place would be in a directory called gearserver under the directory gc/src/qnx/control.
• If your CVS sandbox is not new, bring it up-to-date:
  • cd ~/sandbox/gc/src/qnx
  • cvs update -dP control
• Create the project directory:
  • cd ~/sandbox/gc/src/qnx/control
  • mkdir gearserver
• Add your newly created directory to the CVS server:
  • cvs add gearserver
• You now have a home in the CVS tree for your project, and Momentics will know that that directory is under CVS control.
• In Momentics, go to the Navigator view (this is a view that toggles with the C/C++ Projects view; select it by clicking on the Navigator tab at the bottom of that view).  The Navigator view is used because you can't move projects in the C/C++ Projects view.
• Move the project to your CVS directory by right clicking on the project name, and selecting the menu item "Move...".  In the dialog box, deselect the checkbox "Use default location," and type in the CVS tree location, in this case: /home/celia/sandbox/gc/src/qnx/control/gearserver.
• Your project is now in the CVS tree (in your sandbox).
• Since the project has been moved, you need to udpate the dependencies.mk file.  You can do this by deleting the dependencies.mk file and building the project.
• To commit the project to the CVS server, perform the following steps:
  • Right click on the project name and select Team->Share Project... . This step is critical.  You should see a dialog box titled "Connect Project to Repository".  If you see a dialog box titled "Share Project with CVS Repository" (with :pserver:...) you have done something wrong.  Do not continue.  If you continue, you will end up creating a new CVS module (top-level directory) in the CVS tree.  This is not what you want to do.  Review your steps and get help if necessary. You might find the right clicking on the project name and selecting the menu item "Properties" helpful.
  • Assuming you are at the "Connect Project to Repository" dialog box, click on "Finish."  You will now see an orange disk icon near the name of your project in the C/C++ Projects and Navigator views.  If you turned on CVS Labels (see Configuring Momentics), you will also see ">", indicating that the project is not yet synchronized with the repository.
  • Right click on the project name and select Team->Synchronize with Repository... .  This will bring up the Synchronize view.
  • In the Synchronize view, scroll the outline of the project until you get to the top.  Right click on the project name and select the menu item "Commit...".  A dialog box will come up stating that you will be committing resources that have not yet been added to version control.  This is true, so select "Yes." (Note: don't use the Commit... menu item by right clicking the project name in the C/C++ Projects or Navigator view.  This doesn't work properly.  Use the Commit... in the Synchronize view only.)
  • Enter a comment into the Commit Comment dialog box.  Click "OK."
  • In the CVS Console view, you should see the CVS commands and responses issued by Momentics to the CVS server.  Momentics does all this for you!
  • When the "Commit..." is complete, the ">" should be absent from the project name in the Navigator view.  (I have found that Momentics doesn't reliably remove the ">" from the project name in the C/C++ Projects view, even though a Team->Synchronize with Repository... will indicate that the Workspace resources are the same as remote.  The ">" will be removed from the C/C++ Projects view after some period of time.)
• Your project is now checked into CVS!  If you make any more modifications to the project and want to commit them, follow the steps in Working With An Exisiting Project In The CVS Tree.

Working With An Existing Project In The CVS Tree

Running An Application

Now that you have built an application, you are ready to run it.  To do this, you need to tell Momentics how to run it, e.g., what executable to use, what command line arguments to use, what environment variables to set, etc.  Intuitively, you would think you should right-click on the project to run it, but this is not the case.  Instead, select the menu item Run->Run...  Click on the item "C/C++ Local".  Fill out the form with your run launch information:

• Name: put the name of you run launch configuration here.  The convention is to use the name of your project, followed by the term "_local" to indicate that the code is to run locally, and then add "_g" to indicate that the executable has been compiled with debugging turned on.  e.g., the name of the run launch configuration for the test program for the Ask module of the libgcui.a library is check_ask_local_g.
• Project: use the Browse: button to select the project of interest.
• C/C++ Application: use the Search: button to select the executable of interest.
• Argument, Environment, Debugger, and Common tabs - select these tabs to customize the launch configuration further.

Click on "Apply" to store the configuration, or "Run" to run the configuration immediately.  If the executable is not up-to-date relative to the header and source files, Momentics will build the application before it is run.

You can run the most recently selected configuration by clicking on the Runner icon in the icon bar below the main menu bar.  Otherwise, you can click on the down arrow to the right of the Runner icon and select the name of the run launch configuration you wish to run.

Note that printed output generated by the program is displayed in the Console view.  If you wish to run programs interactively, you will need to set stdout to have line buffering or no buffering.  You can either call setvbuf, or link to the libgcui.a library, include the ideconsole.h header file, and call IDEConsole::StdoutNoBuffering(); once in your code.

Debugging with Momentics

Tips and Tricks

Full-Screen Editing

To expand an editor view (or any other view for that matter), double click on the title bar of the view.  To collapse back to the perspective view, double click on the title bar.

Menus

If you want to affect the global development environment, use the menu options from the pull-down menus at the top of the window.  If you want to affect a specific project, location, resource, etc., right click on the item of interest and select from the pop-up menu.

Long Delay For First Save

For some reason I have noticed a long delay for Momentics to respond when I perform my first save during a session.  I don't know why this occurs.  Perhaps it is saving configuration information that first time.  Later, the saves are very snappy.

Wish List

In this section, I include a wish list of feature enhancements in the Momentics IDE.

• Allow line numbers to be turned on in Makefiles.
• Allow the Search features to be used in other windows than the Editor view, e.g., in the C-Build view.