QP/C: 1. Installing QP/C and Building QP Libraries and Applications

This QP/C Tutorial is adapted from Chapter 1 of Practical UML Statecharts in C/C++, Second Edition
by Miro Samek, the founder and president of Quantum Leaps, LLC.

Prev: QP/C Tutorial
Next: 2. Let's Play

QP/C is distributed in a simple platform-independent ZIP file, or in a self-extracting Windows executable. Either way, installing QP requires simply decompressing the provided archive into a directory of your choice (e.g., <qpc> for QP/C). The Section Directories and Files in the QP/C Distribution describes the directories and files included in the standard QP/C distribution.

Specifically to the "Fly 'n' Shoot" example, the companion code contains two versions of the game. I provide a DOS version for the standard Windows-based PC (see Figure 2-1) so that you don't need any special embedded board to play the game and experiment with the code.

Note:: I've chosen the legacy 16-bit DOS platform because it allows programming a standard PC at the bare-metal level. Without leaving your desktop, you can work with interrupts, directly manipulate CPU registers, and directly access the I/O space. No other modern 32-bit development environment for the standard PC allows this much so easily. The ubiquitous PC running under DOS (or a DOS console within any variant of Windows) is as close as it gets to emulate embedded software development on the commodity 80x86 hardware. Additionally, you can use free, mature tools, such as the Open Watcom C/C++ compiler.

I also provide an embedded version for the inexpensive ARM Corterx-M3-based ARM Cortex-M3 LM3S811 evaluation kit from Luminary Micro (see Figure 2-2). Both the PC and ARM-Cortex versions use the exact same source code for all application components and differ only in the Board Support Package (BSP).

1.1 Building QP Libraries

Note:: The pre-compiled QP libraries are provided in the standard QP distribution (see Directories and Files in the QP/C Distribution), so you can start experimenting with all examples without building the QP libraries. However, if you want to re-build the QP libraries, this section provides the details.

Figure 1-1 illustrates the steps required to build the QF library. The process of building other QP components, such as QEP or QK, is essentially identical. The key point of the design is that all platform-independent QF source files include the same qf_port.h header file as the application source files (see Figure 1-1). At this point you can clearly see that the Platfrom Abstraction Layer (PAL) provided in QP plays the dual role of facilitating the porting of QP as well as using it in the applications. Figure 1-1 shows also that every QP component, such as QF, can contain a platform-specific source file (qf_port.c in this case). The platform-specific source file is optional and many ports don't require it.

Figure 1-1 Building the QF library.

The standard QP ports often contain a simple make.bat script or a Makefile for building all the QP libraries for the port. You typically can choose the build configuration by providing a target to the make.bat script or to the Makefile. The default target is "dbg". Other possible targets are "rel", and "spy". The following table summarizes the targets accepted by the make.bat scripts or the Makefiles.

Build Configuration	Build Command
Debug	make
Release	make rel
Spy	make spy

Note:: All QP components are designed to be deployed in fine-granularity object libraries. QP libraries allow the linker to eliminate any unreferenced QP code at link time, which results in automatic scaling of every QP component for a wide range of applications. This approach eliminates the need to manually configure and recompile the QP source code for each application at hand.

1.2 Building QP Applications

Note:: The standard QP distribution contains pre-compiled examples (see Directories and Files in the QP/C Distribution), so you can start experimenting with all examples without building them. However, if you want to re-build the QP examples, this section provides the details.

Figure 1-2 shows the process of building a QP application. Each QP component requires inclusion of only one platform-specific header file and linking one platform-specific library. For example, to use the QF real-time framework, you need to include the qf_port.h header file and you need to link the qf.lib library file from the specific QP port directory. It really doesn't get any simpler than that.

Figure 1-2 Building a QP-based Application.

The QP port you are using is determined by the directory branch in which the qf_port.h header file and the QF library file are located. Section Directories and Files in the QP/C Distribution shows some examples of such port directories. Typically you need to instruct the C/C++ compiler to include header files from the specific QP port directory and also from the platform-independent include directory <qpc>\include\. I strongly discourage hard-coding full path-names of the include files in your source code. You should simply include the QP port header file (#include "qf_port.h") without any path. Then you specify to the compiler to search the QP port directory for include files, typically through the -I option.

Prev: QP/C Tutorial
Next: 2. Let's Play