University of Sheffield   

    The Simons
    Component Library
Introduction   Class Hierarchy   Class Listing   Index of Classes   Index of Methods   Header Files  

Installation Guide

Standard Installation   Building the Library   Using the Library  

The Simons Component Library is provided as open source C++ software with instructions on how to build an archived library module libSCL.a to be linked in the usual way for Unix and Linux applications. Other target platforms, such as .NET may require slightly different build instructions. All installations are assumed to adopt a similar directory structure to the online SCL repository.

Standard Installation

 The standard installation allows you to copy source code, example programs and web documentation for all the current SCL components, but not to generate new documentation for your own components. This requires a custom installation, with third-party software.

Downloading Instructions

First, create a target directory in which to install the SCL. We shall assume that this is called SCL and in these instructions, we refer to it as the "SCL root directory". The root directory can be placed anywhere on the target filesystem; however, you may wish to place it inside your public web space, so that your web browser may access the documentation files. Make this directory your current working directory. These two steps can be accomplished in Unix or Linux by: Then, download the following compressed file bundle: and save it in the SCL directory. If you wish to view the contents of the download bundle before you choose to unpack it, make sure you are working in the SCL root directory enter the following Unix command: This will display the contents of the download bundle on your monitor, listing each directory and each file. To unpack the file bundle, make sure you are working in the SCL root directory and enter the following Unix command: This will create a number of subdirectories under the root SCL directory and populate these with source code and documentation files.

Standard Directory Structure

The online SCL repository organises its source code and documentation files in a particular directory structure. The local installation of SCL should produce a similar directory structure. A standard installation creates fewer directories than a custom installation and consists of: The root directory SCL contains some key files and all the other directories. The source directory contains all the C++ source code for the SCL components. The binary directory is initially an empty directory, ready to receive components as these are compiled. The example directory contains example programs that use the SCL components. The html directory contains all the web documentation.

The Source Code Files

All the source code files for the SCL components should have been unpacked from the download bundle and copied to the target directory: SCL/source. Similarly, all the source code files for example SCL programs should have been unpacked and copied to the target directory: SCL/example. These files have the following extensions: The header file pattern *.h is accepted by all C++ compilers. The implementation file pattern *.cc is the one preferred by the GNU C++ compiler, used to develop the SCL. Other C++ compilers may prefer a different extension, such as *.cpp or *.c++. Check your C++ compiler manual and rename files if required. To start using the components, refer to the building instructions below.

The Documentation Files

All the documentation files for the SCL components should have been unpacked from the download bundle and copied to the target directory: SCL/html. This is a mirror of the documentation provided by the online SCL repository. The files have the following extensions: The *.html web documents link to the other kinds of file. The stylesheet doxygen.css is needed to format all of the web documents correctly. The *.png diagram files are used to provide mouse-clickable maps in the web documentation. The University of Sheffield crest crest.gif is legally required to appear on every web page, along with the designation "The Simons Component Library". To start browsing the documentation, point your web browser to the directory SCL/html/.

Building the Component Library

 The SCL root directory should contain a master project file called Makefile to help manage and build SCL projects. It is a standard Unix makefile, that is used by the Unix make utility. The following instructions apply to Unix and Linux plaftorms that provide the standard make utility; and refer to the supplied Makefile. Other platforms may require a different style of project file and a different management utility, but the principles will be similar.

Compiler and Utility Requirements

The standard Makefile assumes that you have the following C++ compiler and utility programs: A different C++ compiler may be used under Unix or Linux if desired. The file Makefile must then be edited to indicate the chosen compiler. You can do this by modifying the line which indicates the default C++ compiler: in the supplied Makefile and replace g++ by the name of your preferred compiler.

Building the Library

The archived library libSCL.a will be installed under the SCL/binary target directory. To build the entire library, you must be in the root directory SCL. At the Unix or Linux command line, enter the command: to compile all components in the SCL/source directory and install the library libSCL.a under the SCL/binary target directory. This instruction will execute a series of commands to compile the source code files, to archive the binary files in a library and to index the library. The make utility only performs the minimal rebuild required, after particular files have been modified. To make a completely clean rebuild, enter the two commands: The the first command deletes everything in the SCL/binary directory and so forces the second command to rebuild the entire library from scratch.

Using the Component Library

 Once the component library has been built, you may compile software systems that use the components. Examples of whole programs are supplied in the SCL/example directory and may be used as templates for writing your own programs. In the following, it is assumed that you are working in the SCL root directory and all pathnames are relative to here.

An Example

The program SCL/example/hello.cc may be compiled and executed by the following kind of instruction (assuming that g++ is your C++ compiler): The command g++ invokes the GNU C++ compiler. The option -Isource tells the compiler to look for included header files in the source directory. The option -Lbinary tells the compiler to look for linkable libraries in the binary directory. The path example/hello.cc is the file pathname of the example program. The final command -lSCL is the instruction to link the SCL library and pull out any components required by the program. Assuming that compilation is successful, this generates an executable file under the root directory SCL with the standard default name a.out. To execute this program, enter the filename as a command at the Unix or Linux prompt: This example program should print the message "Hello world" on the standard output (ie on the terminal screen). To give an executable program a different name, you can compile it using the output renaming option: in which -o hello is a request for the binary output after compilation to have the indicated name. This generates an executable program called hello in the root directory SCL. Entering hello at the prompt will execute this program.

Other Examples

The example programs provided in the SCL/example directory include: More examples will be added to this list.

The Standard Program

The supplied Makefile is set up to compile one program with the conventional name prog.cc, which is assumed to exist in the root directory SCL. If you give your program this standard name and place it in the root directory, it can be built simply by entering the command: This command will also rebuild any out-of-date SCL components and archive them in the SCL library before compiling the standard program. Assuming that compilation is successful, this generates an executable file under the root directory SCL with the standard default name a.out. To execute this program, enter the filename as a command at the Unix or Linux prompt: and it will execute. The instructions for building prog are the following lines in the supplied Makefile :

Building Your Programs

To obtain similar behaviour for your own program myprog, you should edit the Makefile and add a similar building instruction for your own program, mimicking the lines for building prog and substituting throughout the name myprog for the standard prog name: The left-most name myprog: is called the build-target. You build this target by entering the instruction: at the Unix command line. You may do this for each new program, so long as you do not alias one of the existing build-targets in the Makefile. You may also organise your SCL projects in another subdirectory, for example SCL/project. In this case, your build instruction should look like this: Then, the instruction will compile the program project/myprog.cc and link it appropriately, placing the binary a.out in the root SCL directory. If desired, this executable can be renamed or moved to another location.

This documentation was created by Dr Anthony J H Simons, Department of Computer Science, University of Sheffield, Regent Court, 211 Portobello Street, Sheffield S1 4DP, United Kingdom.

Generated on Wed Nov 16 16:53:39 2005 for The Simons Component Library by doxygen1.3