This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Ten Steps to Your First QNX Program

This guide will help you install and configure the QNX Momentics tools and the QNX Neutrino operating system, so you can start developing right away!

• 1. Requirements
• 2. Installing QNX Momentics
• 3. Installing the QNX Neutrino RTOS
• 4. Networking with QNX Neutrino
• 5. Creating a program project
• 6. Communicating with QNX Neutrino
• 7. Compiling and linking
• 8. Preparing to launch the program
• 9. Starting and debugging
• 10. Making the program your own

If you've installed QNX Momentics 6.3.0 Service Pack 1, but not Service Pack 2, use the SP1 version of this guide.

1. Requirements

To write programs that run under the QNX Neutrino realtime operating system (RTOS), the first thing you need is the QNX Momentics development suite. You can install it on Windows 2000, Windows XP, Linux, or Solaris, or as a self-hosted QNX Neutrino system.

If you don't have a QNX Momentics CD, you can download an ISO image of it from: www.qnx.com/products/eval.

The QNX Product Evaluation website.

In addition to a development system, you also need a target platform that runs the QNX Neutrino RTOS itself plus all the programs you're going to develop.

To become familiar with QNX Neutrino, you have two choices: either install QNX Neutrino as an operating system on a normal PC, or run QNX Neutrino on a reference platform, a reference design made by a CPU vendor (e.g. with a PPC, XScale, or SH4 CPU). Since QNX Neutrino is designed the same way for all platforms and is used the same way, for this Quickstart guide we'll use the PC installation. If instead you want to use a reference platform, you need a QNX Board Support Package for this platform. The documentation that comes with each BSP explains how to install QNX Neutrino on that target system.

One way to get started quickly is to use a second PC -- it can even be an older machine. On its hard disk, it should have a free partition of about 300 MB (if you want to install only the OS and its runtime components) up to 2.5 GB (if you prefer to install the development environment under QNX Neutrino for all supported processors). A Windows operating system, installed on another partition, will not be damaged. You can also boot QNX Neutrino directly from CD, in case you don't have enough room on your hard disk.

If you don't have a QNX Neutrino CD, you can download it as an ISO image from: www.qnx.com/products/eval.

2. Installing QNX Momentics

QNX Momentics contains everything you need to develop programs that run under the QNX Neutrino RTOS: an extensive Integrated Development Environment (IDE), compiler, linker, libraries and other QNX Neutrino components, precompiled for all CPU architectures that QNX Neutrino supports.

Boot your Windows 2000 or XP system and insert the QNX Momentics Windows Host CD. If the installation doesn't start automatically, simply run the program qnxSetupWin32.exe on the CD. You will be guided through the installation process. For more information, see the installation note.

The installation program will ask you for a license key. If you downloaded QNX Momentics as an ISO image, you should have received an email containing the key. Otherwise, you should have received your key when you bought a QNX Momentics development seat.

The Installer will ask you which components to install. The default is to install everything, which we recommend for evaluation, since you don't know yet what you will need.

After the installation, you'll find an icon for the QNX Momentics IDE on your Windows desktop, along with an HTML file that contains some interesting information about QNX Momentics and QNX Neutrino. Make sure you also install the latest QNX Momentics Service Pack from the Download Center of our website!

Installing the QNX development environment under Windows.

3. Installing the QNX Neutrino RTOS

Now insert the QNX Neutrino CD in the drive of your second machine and boot from it. At this point, you can choose to start the OS directly from CD (ideal for initial testing) or install QNX Neutrino onto your hard disk. Please choose the installation to hard disk and follow the onscreen instructions. For more details, see the installation note.

During installation, you will be asked if you also want to install the Software Development Kit under Neutrino. If you say yes, the complete QNX Momentics development environment (including our Eclipse-based IDE) will also be installed on your QNX Neutrino system. You can then develop, compile, and directly test on the same system running QNX Neutrino.

After rebooting, your hardware will automatically be detected. Once you select the graphics mode, you can log in as root without a password. On the right side of the screen, you'll find an icon bar. From there, you can, for example, open a shell by clicking on Terminal.

Logging into a self-hosted QNX Neutrino system.

You now are sitting in front of a preconfigured, fully featured QNX Neutrino realtime operating system including the QNX Photon microGUI windowing system. (Of course you can run QNX Neutrino without graphics, too.) Make sure you also install the latest available QNX Neutrino Service Pack from the Download Center on our website.

By using the pidin command, you can get a list of the processes that currently exist in your system. Each process is optional, which means that, later in your design, you can remove it to save resources -- or you can add other processes to increase the system's functionality. This also applies for graphics, network, or audio; each QNX Neutrino component is a single process that you can load dynamically. With the QNX Neutrino installation that you just created, you can easily familiarize yourself with many QNX capabilities and features. And all this without the need to create and configure a boot image yourself!

Lots of features and still capable of hard realtime: a self-hosted QNX Neutrino system.

4. Networking with QNX Neutrino

Now connect your QNX Neutrino machine (your target) to the network. Your development machine should be on the same network. With a DHCP server available, your QNX Neutrino machine will receive an IP address automatically. You can view it using the ifconfig en0 command:

In the terminal window you can use the command:

ifconfig en0 address

to manually assign an IP address (replacing address with the IP address you would like to assign to your system).

Alternatively, you can use the network configuration tool that comes with the QNX Neutrino installation. You'll find it under the Configure item on the icon bar on the right side of the screen, or in the Launch menu. Under Devices, you can select whether you would like to use DHCP or a manually assigned IP address. Under Network, please enter the IP addresses of the Gateway and DNS:

Using ping IP_address, you now can check that your development machine (host) can reach your QNX Neutrino system (target) on the network:

and your target can reach your host:

If your host machine uses a firewall, you might not be able to ping it from the target. On Windows XP SP2, you might have to enable Allow incoming echo request in the ICMP settings; choose Control Panel from the Start menu, then choose Security Center, and then choose the Advanced tab.

If the network doesn't work properly, you may be using an unsupported network card. For a full list of supported hardware, visit: www.qnx.com/developers/hardware_support If you have further questions regarding hardware support, please call your local sales representative.

The full Neutrino installation uses automatic hardware detection to start the corresponding device drivers. With the command enum-devices -n you can see which hardware was detected by the enumerators and which drivers have been started accordingly during booting.

5. Creating a program project

Start the QNX Momentics IDE on your development host. Now create a QNX C Project: in the File menu, select New-->QNX C Project:

In the resulting dialog, give your project a name:

and then click Next. In the next step, please select a CPU architecture for the binary you're creating; for a PC as target, choose x86. For projects on other processors, select the corresponding CPU type: PPC, SH4, ARM, or MIPS. Click Finish.

A ready-to-use project structure with a Makefile is created for you, including a small program ("Hello World"), which you will find in an automatically generated source code file.

You will now land in the IDE's C/C++ Perspective, which features the navigator, the editor and other useful views, areas that display information that's relevant to the task at hand:

6. Communicating with QNX Neutrino

Your target system must be able to respond to requests from the development environment. To make this possible, start the program qconn. On a PC running QNX Neutrino, you can do this from a terminal window:

To access your target system from the IDE, you have to create a Target Project. Open the System Information Perspective: In the Window menu, select Open Perspective, and then click Other. Now choose QNX System Information, and then OK.

In the empty Target Navigator view, press the right mouse button and select Add New Target from the context menu:

Now provide a name for your target system and enter its IP address in the corresponding field:

Click Finish. You will now see a list of all the processes in your QNX Neutrino system. The views (the tabs at the top) provide other information to you. You can find even more useful views in the Window menu under Show View.

Here you see what's going on inside your QNX Neutrino system.

7. Compiling and linking

Now switch back to the C/C++ perspective by doing one of the following:

• Choose the C/C++ perspective from the drop-down menu in the upper right of the display:

  

  Or:

• Hold down the Ctrl key, press F8 repeatedly until C/C++ is highlighted in the pop-up menu, and then release both keys:

  

  Or:

• Choose Window-->Navigation-->Next Perspective and choose C/C++ from the pop-up menu.

Before you compile, you may want to select compilation with or without debug information. To do so, right-click the project name and choose Properties. Click QNX C/C++ Project, click Build Variants, and then click on the small + symbol next to x86. By default, compiling with debug information is selected. Instead of this -- or additionally -- you can select compiling without debug information (the release variant).

Selecting build variants.

During the creation of the QNX C Project, a QNX-made directory structure with Makefiles was generated. Now to create a binary, please right-click the project name, and then select Build Project. The compiler and linker will now do their work.

You will find the compiler output in the C-Build output in the Console view, including any errors:

However, if errors occur during compiling, you will find the Problems view more useful, because it displays the output of the compiler in an interpreted and more readable fashion than the Console view:

The Editor view also gives you information about an error if you leave the pointer over it:

After the build operation, your binaries will be displayed in the Binaries folder. Physically, they're located in the CPU directory under o (for object) and o-g (-g for the debug option passed to the compiler). The IDE automatically created the corresponding Makefiles.

The QNX library libc.so, which contains many basic functions, is linked dynamically to your binary by default. If you want to add other libraries later, you can do this under the Project-->Properties section, too. From there, click on Linker and choose Extra Libs in the Category field:

Click Add, and type the name of the library, without the lib prefix or the extension. For example, to add the math library, libm.so, you just have to type m in the Name field:

Click OK. The linker will now link the library when you build the project.

8. Preparing to launch the program

To run and debug the newly built program on your target system, you need to create a launch configuration. It consists of various settings that affect how the program starts (e.g. command-line parameters, environment variables). You enter these once, and then you can use this collection of settings again and again.

Now create your own launch configuration: In the Run menu, select Debug.... A dialog window opens, where you can start existing launch configurations, change them, or create new ones. On the left, please select the type of launch configuration: C/C++ QNX QConn (IP). This type is meant for network-based (cross) development with QNX Neutrino running on the target system, using the qconn program. Now click on New to create a new launch configuration. You will now be presented with many configuration possibilities that all deal with starting your executable program. By default, only the Main tab needs your input. Later, however, you should also take a look at what the other tabs have to offer.

Next to the C/C++ Application field, press the Search button and choose your binary. If you compiled it with debug information, it carries a little beetle -- a "bug" -- as its symbol. If you compiled it without debug information, it will have a "running man" symbol. Since we would like to start the Debugger in the next step, please choose the binary with the debug information compiled in. Under Target Options, please select your target system, and then click Apply -- the launch configuration is now ready:

9. Starting and debugging

You should still be in the Launch Configuration dialog. You just created a configuration for launching your program, which you now can start in the debugger. To do this, please click Debug.

The IDE now switches to the Debug perspective and transfers your program from your development machine across the network to your target QNX Neutrino system, then starts it in the debugger. You will see that the debugger stops in the first line of your program. In the Debug view, you'll see an overview of your process, including the call stack. Using the buttons in the main bar of the Debug view, you can control the debugger.

The Debug perspective.

Using the Step Over button, you can jump to the next line of code:

During debugging, you can watch the Variables view on the right, which displays how your variables change. You can use the button Step Into to let the debugger go into the code of a function (which, of course, is useful only if you have the source code for this function).

To set a breakpoint, place the mouse pointer over the left border of the source display, press the right mouse button and choose Toggle Breakpoint from the context menu. The breakpoint is shown as a little pin, which you can also set or remove while you write your code.

Setting breakpoints.

When the running program hits a breakpoint, it stops in the debugger, and you can, for example, examine your variables. If you click the Resume button, your program continues until it hits the next breakpoint:

To abort program execution, use the Terminate button:

After the program has finished running, use the button Remove All Terminated Launches to end the debugger and have your binary (which was previously transferred) deleted from your target system.

To run your program as a standalone binary (without the debugger), use the Run menu again, but instead of clicking Debug..., click Run.... Then you can use the launch configuration (described in the previous step) to start your program. Or create a new launch configuration and select the binary without debug information. You can also transfer your binary manually using the System Information Perspective's File System Navigator (Window-->Show View) and start it from the terminal. Mounting a shared network drive is also possible (see the entry for fs-cifs in the QNX Neutrino Utilities Reference).

10. Making the program your own

To turn the whole thing into your own first QNX program, you can modify and extend the source code we just created. Try some of our sample programs and copy code from them into your project. And, now that you've started, you'll probably want a lot more information, e.g. how to create your own threads, how the QNX Neutrino message-passing works, which process-synchronization methods are available, how to get access to I/O areas, or how to build a QNX Neutrino resource manager. But don't worry: all this is (almost) as simple as the quick start you just experienced!

The Welcome to QNX Momentics guide helps you find out where to look for the information you need. We recommend browsing the QNX Neutrino System Architecture guide, the IDE User's Guide, and the QNX Neutrino Programmer's Guide. All documentation is available in the IDE's Help system. In the Help menu, click Help Contents:

In the Help window, please choose QNX Momentics Professional Edition:

To view the documentation on self-hosted Neutrino systems, just click the Help button on the icon bar on the right of the screen:

Also make frequent use of the Search function! Printed documentation is also available.

Source code examples covering thread creation, usage of mutexes, message-passing and other methods of interprocess communication as well as a QNX resource-manager template can be found on our FTP server ftp.qnx.de; just use an FTP client to log in as user qnx with the password qnx!neutrino and download the source package. It contains a ReadMe file that explains how to import the source examples into the QNX Momentics IDE. The source features extensive comments, explaining what is done there. For every function you are interested in, you also should consult the documentation, available inside the Helpviewer.

While you explore the QNX Momentics tools and the QNX Neutrino RTOS, you will probably have further questions. Please contact your QNX Account Manager, Field Application Engineer, or our support department. We want to be with you from the start, because we are successful only if you are!

Copyright © 2005 -- 2006, QNX Software Systems. All rights reserved.