7.2. Exercise: Installing Libraries

7.2. Exercise: Installing Libraries
	Chapter 7. Libraries and Design Patterns

[ fromfile: installing-libs.xml id: installing-libs ]

Abstract

A number of examples in this book make use of classes found in libraries that were written for this book. The source code for these classes is available for download. API documentation is included, generated with Doxygen. In this exercise, you can see how to build and install some libraries.

Instructions for installing libraries on a *nix platform for use with the book examples follow. For help installing Qt and MySQL on Windows with MinGW check the QtCentre Wiki.

As we suggested in Section 7.1 and Section 7.1.2:

Create a directory especially for your C++/Qt work; e.g., ~/oop/projects/.
Download src.tar.gz from the distfiles directory.
Unpack this tarball in the new directory. That should result in a src/libs directory with a number of subdirectories including libs/dataobjects and libs/customer.
Examine the subdirs project file, named libs.pro, in the src/libs directory.
It is designed to build the libraries and the tests.
Feel free to comment out the libraries and tests you do not plan to use, but do not change the order of the libraries.
Create a shell/environment variable named CPPLIBS that contains the absolute path of your new libs directory. For convenience, you can place the definition for this environment variable inside a shell script, as demonstrated in Example 7.3.

Note

	Note
If you decide to comment out a particular library directory in `libs.pro`, you should also comment out the corresponding test dir in libs/tests/tests.pro (or else the tests part of libs won't build). Reminder: You can comment out any line in a project file by inserting the poundsign char '#' at the beginning of that line.

If you decide to comment out a particular library directory in libs.pro, you should also comment out the corresponding test dir in libs/tests/tests.pro (or else the tests part of libs won't build).

Reminder: You can comment out any line in a project file by inserting the poundsign char '#' at the beginning of that line.

libs.pro

  TEMPLATE = subdirs
  CPPLIBS=$$(CPPLIBS)
  isEmpty(CPPLIBS) {
     error("Define CPPLIBS environment variable to point to this location.")
  }
  SUBDIRS += dataobjects \
             actioneditor \
             customer \
             metadata \
             sqlmetadata

Build the libraries from the libs directory in two steps:

qmake -recursive // creates Makefiles in current dir and in each subdir.
make // builds the libraries and tests.^[56]

Verify that the libraries are built and that the shared object files (e.g., libdataobjects.so ^[57]) are located in the CPPLIBS directory. Following is an abbreviated directory listing from a typical linux box:

libs> ls -l
drwxr-xr-x  5 dataobjects
lrwxrwxrwx  1 libactioneditor.so -> libactioneditor.so.1.0.0
lrwxrwxrwx  1 libactioneditor.so.1 -> libactioneditor.so.1.0.0
lrwxrwxrwx  1 libactioneditor.so.1.0 -> libactioneditor.so.1.0.0
-rwxrwxr-x  1 libactioneditor.so.1.0.0
[...]
lrwxrwxrwx  1 libdataobjects.so -> libdataobjects.so.1.0.0
lrwxrwxrwx  1 libdataobjects.so.1 -> libdataobjects.so.1.0.0
lrwxrwxrwx  1 libdataobjects.so.1.0 -> libdataobjects.so.1.0.0
-rwxr-xr-x  1 libdataobjects.so.1.0.0
-rw-r--r--  1 libs.pro
-rw-r--r--  1 Makefile
libs>

Lines that begin with drwxr-xr-x are directories. Lines that begin with lrwxrwxrwx are symbolic links. Use Google to find out why each shared object file has three symbolic links.

Fixing the Linker Path

Update the shell/environment variable LD_LIBRARY_PATH (*nix) or PATH (win32) to include CPPLIBS using the appropriate syntax.
Create a projects/tests directory. This is where you can keep code for testing various library components.
Run the test apps that came with the libs tarball. They are in subdirs of libs/tests that correspond to the libraries that you built.

Note

	Note
On a nix platform a shell script is generally used to define environment variables. Example 7.3 shows a bash shell script that handles the job. Example 7.3. src/bash/env-script.sh* export CPPLIBS=$HOME/oop/projects/libs export LD_LIBRARY_PATH=$CPPLIBS <include src="src/bash/env-script.sh" href="src/bash/env-script.sh" id="env-script" mode="code"/> Note the bash syntax details in this script: The environment variable `HOME` contains the absolute path to your personal "home" directory. You can also use the tilde symbol `~` for this. An environment variable on the left of an assignment has no dollar sign `$` prefix. An environment variable on the right of an assignment must have a `$` prefix. The command `export` is needed if the environment variable is to become a part of the environment – and not simply be local to the script file. The environment variable QTDIR is used by some programs to find the executable and #includable components of the current Qt installation. Because more than one version of Qt might be in use on some older *nix systems (e.g., systems still using KDE 3.x) QTDIR can ensure that the right version is engaged. QTDIR is generally not needed if Qt has been installed from binaries by your system's package manager. That kind of installation tends to distribute the component parts of Qt to several different directories. QTDIR is probably needed if you have downloaded, unzipped, and built Qt yourself from a source package, in which case it should store the path of the installed Qt main directory (i.e., the parent of its `bin` directory). You can run this script by typing one of the following commands: source env-script.sh or . env-script.sh Notice the dot (.) at the beginning of the second version. In the bash shell, the dot is equivalent to the command, `source`. If you want to make sure that these environment variables are automatically set at the start of each shell, you can source the script from `~/.bashrc`, which runs automatically whenever `bash` starts (for example, whenever you bring up a terminal or console). Hamish Whittal has put together a nice online course on Shell Scripting.

On a *nix platform a shell script is generally used to define environment variables. Example 7.3 shows a bash shell script that handles the job.

Example 7.3. src/bash/env-script.sh

export CPPLIBS=$HOME/oop/projects/libs
export LD_LIBRARY_PATH=$CPPLIBS

Note the bash syntax details in this script:

The environment variable HOME contains the absolute path to your personal "home" directory. You can also use the tilde symbol ~ for this.
An environment variable on the left of an assignment has no dollar sign $ prefix.
An environment variable on the right of an assignment must have a $ prefix.
The command export is needed if the environment variable is to become a part of the environment – and not simply be local to the script file.

The environment variable QTDIR is used by some programs to find the executable and #includable components of the current Qt installation. Because more than one version of Qt might be in use on some older *nix systems (e.g., systems still using KDE 3.x) QTDIR can ensure that the right version is engaged.

QTDIR is generally not needed if Qt has been installed from binaries by your system's package manager. That kind of installation tends to distribute the component parts of Qt to several different directories. QTDIR is probably needed if you have downloaded, unzipped, and built Qt yourself from a source package, in which case it should store the path of the installed Qt main directory (i.e., the parent of its bin directory).

You can run this script by typing one of the following commands:

   source env-script.sh
      or
   . env-script.sh

Notice the dot (.) at the beginning of the second version. In the bash shell, the dot is equivalent to the command, source.

If you want to make sure that these environment variables are automatically set at the start of each shell, you can source the script from ~/.bashrc, which runs automatically whenever bash starts (for example, whenever you bring up a terminal or console).

Hamish Whittal has put together a nice online course on Shell Scripting.

^[56]You may need to install some specialized Qt packages before building some of our libraries. For example, the libphonon-dev package is required for our phononmetadata library. The linker will inform you of these dependencies.

^[57] Or on Windows, libdataobjects.lib and dataobjects.dll, the latter which must be in a directory listed in your PATH, so be sure to include %CPPLIBS% in your PATH.