QxRunner

QxRunner Library Installation Instructions

These installation instructions describe how to build the library from source code.

Download the QxRunner distribution and extract its contents to a directory of your choice. This directory will be referred to as the QXRUNNER directory in the further documentation. The package contains the source code and the files needed to build the library on all supported platforms. The QxCppUnit library is part of the QxRunner distribution.

Directory Structure

After unpacking the QXRUNNER directory has the following structure:

	doc	Destination directory for generated documentation.
	docgen	Has scripts and Doxygen configuration files for generating the QxRunner API documentation.
	examples	Parent directory for the examples shipped with the distribution.
	examples/qxcppunitdemo	Source code and build files for the QxCppUnit library demo program.
	examples/qxrunnerdemo	Source code and build files for the QxRunner library demo program.
	include	Parent directory for include file folders.
	include/qxcppunit	Include files for the QxCppUnit library.
	include/qxrunner	Include files for the QxRunner library.
	lib	Destination directory for generated libraries.
	src	Parent directory for source code folders.
	src/qxcppunit	Source code and build files for the QxCppUnit library.
	src/qxrunner	Source code and build files for the QxRunner library.

Some of these directories might contain subfolders needed for the build process. These can be deleted without any objections since they get recreated as needed. There are also a number of undocumented scripts or data files of tools used during development, for example PSPad editor project files (.ppr).

Minimal Requirements

• The Qt framework with a version >= 4.1.4 is installed. If not yet then get it from http://www.qtsoftware.com/downloads.
• An environment variable named QTDIR must point to the top directory of the Qt installation.

Configurations

The library and its demo program can be built with different configurations. The following configuration names are used as CONFIG values for the qmake tool:

Configuration	Description
debug_static	Build target with debug information. If target is a library create it as a static library. If target is an application link it with debug static libraries. This is the default.
debug_dll	Build target with debug information. If target is a library create it as a DLL on Windows or as a shared image on Linux/Unix and link it with debug DLL's/shared images. If target is an application link it with debug DLL's/shared images.
release_static	Build target in release mode without debug information. If target is a library create it as a static library. If target is an application link it with release static libraries.
release_dll	Build target in release mode without debug information. If target is a library create it as a DLL on Windows or as a shared image on Linux/Unix and link it with debug DLL's/shared images. If target is an application link it with release DLL's/shared images.

In the further documentation these configuration names will be used when referring to a particular build mode.

Using qmake Project Files

With the qmake project files (.pro) contained in the distruibution you can use the platform independent qmake build system to create the library and its demo program on every platform supported by Qt. For simplified qmake usage the configuration names listed above are treated specifically by the Qx project files when assigned to the CONFIG variable.

To turn off special handling of these values and revert to the default qmake CONFIG values processing the QXRUNNER/qxconfig.pro file must be edited. See the comments in this file for the required modifications.

Pass one of the configuration values as an assignment to the CONFIG variable when running qmake on the command line. After successful processing of the project file a message is written to the console confirming the chosen configuration. The picture below shows how to run qmake for every possible configuration whereby the first qmake invocation uses the default:

qmake generates a Makefile in the current working directory which is used as input for your platform's make tool to build the project. qmake generated Makefiles have at least the two additional targets clean and distclean for workspace clean up.

Intermediate Build Directories

During the build process an intermediate directory is created below the source code directory where most of the produced objects get filed. The name of the directory depends on the platform and the chosen configuration.

Library Names

Depending on the platform and the chosen configuration the resulting library gets a unique name.

Build Everything

In the top level QXRUNNER directory are build files for creating all libraries and demo programs of the distribution at once:

File	Description
qxrunner_all.sln	Solution file for building with the Visual Studio 2005 IDE.
qxruner_all.pro	qmake file for building from the command line. If there are Makefiles already it is recommended to make a distclean before generating the Makefile for a particular configuration with this project file.

Building the Library on Windows

Directories and Library Names

Configuration specific intermediate build directories and resulting libraries have the following names:

Configuration	Build Directory	Library Name	Remarks
debug_static	Debug	qxrunnerd.lib
debug_dll	Debug_DLL	qxrunnerd_dll.dll qxrunnerd_dll.lib	(import library)
release_static	Release	qxrunner.lib
release_dll	Release_DLL	qxrunner_dll.dll qxrunner_dll.lib	(import library)

If the build of a configuration is successful the library and related artifacts are copied from the build directory to the QXRUNNER\lib directory.

Building with the Visual Studio IDE

These instructions are valid for the Visual Studio 2005 IDE with CL 14.x only.

1. Open the solution file qxrunner.sln in the QXRUNNER\src\qxrunner directory.
2. Select the configurations of your choice in the Batch build dialog and press the appropriate button to start the build process:
   
   
   
   

   Configurations in the IDE have names commonly used in the VS IDE, therefore use these mappings:

   VS IDE	corresponds to	qmake
   Debug	<->	debug_static
   Debug_DLL	<->	debug_dll
   Release	<->	release_static
   Release_DLL	<->	release_dll

Building from the Command Line

The qmake and nmake utilities are used when creating the library from the command line with the MSVC build tools. Although tested with the MSVC 8.0 command line compiler and linker only, it should be possible to create the library with any of the build tools supported by Qt. Be mindful of setting the environment for using the build tools of your choice from the command line (for example by executing vcvarsall.bat provided with the MSVC tools).

1. Open a command window.
2. Go to the QXRUNNER\src\qxrunner directory.
3. Enter

   qmake qxrunner.pro

   This expands the information in the qmake project file to the file Makefile in the current directory.
4. Execute the commands in Makefile for compiling and linking the project by entering

   nmake

By default the library is built as a static library in debug mode. Change the configuration by passing the corresponding CONFIG assignment on the command line.

Building the Library on Linux

Directories and Library Names

Configuration specific intermediate build directories and resulting libraries have the following names:

Configuration	Build Directory	Library Name
debug_static	.debug	libqxrunnerd.a
debug_dll	.debug_shared	libqxrunnerd_shared.so
release_static	.release	libqxrunner.a
release_dll	.release_shared	libqxrunner_shared.so

The library gets created directly in the QXRUNNER/lib directory.

Building from the Command Line

The qmake and GNU make utilities are used when creating the library from the command line on a Linux system. Although tested with gcc 4.x and GNU ld 2.16.x on a linux 2.6.x kernel it should be possible to create the library with any of the build tools supported by Qt.

1. Open a terminal window.
2. Go to the QXRUNNER/src/qxrunner directory.
3. Enter

   qmake qxrunner.pro

   This expands the information in the qmake project file to the file Makefile in the current directory.
4. Execute the commands in Makefile for compiling and linking the project by entering

   make

By default the library is built as a static library in debug mode. Change the configuration by passing the corresponding CONFIG assignment on the command line.

Verification with the Demo Program

A demo program is provided with the QxRunner distribution that can be used to verify the proper functioning of the QxRunner library. If the build of a configuration is successful the executable qxrunnerdemo.exe on Windows or qxrunnerdemo on Linux can be found in the configuration related build directory. When started the demo program appears on the screen as shown in the Screenshots page.

The same tools as used for building the QxRunner library are used to create the demo program. The debug_static and release_static configurations link with the static QxRunner library in the corresponding debug or release mode. Configurations debug_dll and release_dll link with the QxRunner DLL on Windows or the QxRunner shared image on Linux in the corresponding debug or release mode.

Building on Windows with the Visual Studio IDE

1. Open the solution file qxrunnerdemo.sln in the QXRUNNER\examples\qxrunnerdemo directory.
2. Select the configurations of your choice in the Batch build dialog and press the appropriate button to start the build process:
   
   

Building on Windows from the Command Line

1. Open a command window.
2. Go to the QXRUNNER\examples\qxrunnerdemo directory.
3. Enter

   qmake qxrunnerdemo.pro

4. Enter

   nmake

By default the program is built in debug mode and linked with the debug static QxRunner library. Change the configuration by passing the corresponding CONFIG assignment on the command line.

Building on Linux from the Command Line

1. Open a terminal window.
2. Go to the QXRUNNER/examples/qxrunnerdemo directory.
3. Enter

   qmake qxrunnerdemo.pro

4. Enter

   make

By default the program is built in debug mode and linked with the debug static QxRunner library. Change the configuration by passing the corresponding CONFIG assignment on the command line.

---