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.
Creating A New Library
Converting Exiting Code Into A Project
Working With A New Project
Working With An Existing Project Not Yet In The CVS Tree
Working With An Existing Project In The CVS Tree
Debugging with Momentics
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.)
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!
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:
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.
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.
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:
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.
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.
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:
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:
Double click the file named "common.mk". Add the following text to the end of the file:
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:
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.
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
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
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:
Working With An Existing Project In The CVS Tree
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:
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
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.
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.
In this section, I include a wish list of feature enhancements in the Momentics IDE.