Developing Concepts

This document describes various aspects when you want to enhance the library or dig into the details how it is structured and built.

Contents

1. Organisation of the Files and Projects, Additions
2. Building Concepts
3. Version Managment with CVS
4. Enhance this Documentation

Organisation of the Files and Projects, Additions

Every project has its own subdirectory under the main directory of Concepts (usually called concepts-2).

Registering a New File in a Project

If you want to register a new file in a already existing project you have to edit the Jamfile in the project directory and add the name of the file to the lines called SOURCES in case of it should go into a library or add a build target like found in applications/Jamfile. You have to add the name of the source file, eg. if you added element.hh and element.cc to a project, add element.cc the the Jamfile.

Examples can be found in almost all directories.

Registering a New Project in the Core Library

If you want to add a new project to the core library, you have to add a new subdirectory in the main directory of Concepts (usually concepts-2). Inside this directory, you need to place a Jamfile. See below for the kind of information which is hold by a Jamfile.

Add a header file to the top level directory with the same name as your new project e.g., geometry and geometry.hh. Add all header file in the directory geometry to this header file such that one only has to include geometry.hh in an application. If your project resides in a new namespace, also add the documentation of the namespace to the header file in the top level directory:

/** hp 3D edge elements for electromagnetics.
    @author Kersten Schmidt, 2003
*/
namespace hp3Dedge {
  // leave this empty, just for documentation
} 

Then, you need to modify the top level Jamfile and register the new project there. Ie., you have to add the name of the project with build-project.

Contents of a Jamfile

A Jamfile holds the following information:

• project: The name of the project. This is identical with the name of the subdirectory.
• usage-requirements: The names of the projects on which the current project depends (on the linking level, source level dependencies [#include] is handled automatically).
• SOURCES, lib exe, obj, unit-test: The files which are built in this project.

Examples can be found in geometry for a normal project and applications for the applications project.

Building Concepts

Changing into any source directory (or staying in the top level directory) and calling bjam should build the library and the executables. If you want to rebuild a subpart, you can issue bjam in its subdirectory again.

Version Managment with CVS

Documentation on CVS can be found here and there.

Obtaining Concepts

Checking out Concepts from CVS is as simple as this:

setenv CVSROOT /u/users/concepts/cvsroot
cvs checkout concepts-2 

When you already have a version of Concepts-2 and want to update to the most recent version, just type

cvs update -dP 

in the concepts-2 subdirectory. This is also a good method to find out which files where changed by you (they are marked with a "M"). Other marks which could show up are described here and there.

Giving Back Changes

When you have changed some files and want to give the changes back, you have to "commit" them using the cvs commit command:

cvs commit -m "Added anistropic polynomial degree" element.hh 

If you have a somewhat longer comment use cvs commit without the -m "message" and and an editor will be opened where you can enter your message.

If you want to check what your changes where, use

cvs diff -u element.hh 

before using the commit command. This will show you the changes of your local copy with respect to the current copy in the repository.

You can also check the previous log messages with

cvs log element.hh 

It is good practice to do an update before trying to give back changes.

Registering New Files

When you created a new file, then you first need to add this file to the repository using

cvs add -m "Abstract base classes for elements" element.hh 

The message is a general description of the file. After this, you can commit the new file using the cvs commit command.

Registering a new directory is even easier: it suffices to issue the cvs add command to create a new directory in the CVS repository.

Enhance this Documentation

The whole documentation is done using Doxygen. General pages are in the doc directory, the pages for the tutorials are in the applications directory: file.doxy contains the documentation for file.cc. The classes are documented right in the source files using special Doxygen-style comments.

To generate the documentation in concepts-2/doc/doxygen/html use the command

make -C $CONCEPTSDIR doxygen 

and to generate and install the documentation, use

make -C $CONCEPTSDIR html-install DEST=~concepts/www 

Author

Philipp Frauenfelder, 2004