Documentation for Concepts 2.0 (Developing) | Tutorials | Class Documentation | Developer Tools

Developing Concepts

Contents

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

Organisation of the Files and Projects, Additions Top

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 project.mk file in the project directory and add the name of the file to one of the lines called object, library (ie. a shared or static library) or executable (ie. a real program). You have to add the name of the file after building it, eg. if you added element.hh and element.cc to a project, add element.o the the project.mk file on the object line.

With this, the file is automatically compiled the next time you build the library and added to the library (in the case of an object file).

Examples can be found in the basics project.

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 project.mk file. See below for the kind of information which is hold by a project.mk file.

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 makesupport/config.mk file and register the new project there. Ie., you have to add the name of the project on the PROJECTS line.

Contents of a project.mk File

A project.mk file holds the following informations:

project
The name of the project. This is identical with the name of the subdirectory.
import
The names of the projects which have to be imported to build the project.
object, library, executable
The files which are built in this project.

After the lines holding these information, you need to include

include $(CONCEPTSDIR)/makesupport/generic.mk
which includes some general rules of the makefile. For normal projecs, the project.mk file should end here. The project file for the applications directory has some dependencies after this.

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

Registering a New Extending Library

To create a new extending library, you have to create a new project. Instead of registering it under PROJECTS, register it under extPROJECTS in makesupport/config.mk.

As for a normal project, create a project.mk file using the same variables. You don't need to provide any dependency information (besides the import variable).

Finally, you need to provide a makefile for your new extending project in the makesupport directory. Its name has to be lib<project>.mk, eg. if the project has the name hp3D, you need the create the file makesupport/libhp3D.mk. It is copied to libhp3D/Makefile in the builds directory during the build process. If you do not want to build a whole new library but add your files to an existing library, just add your project name to the list of imports and to the $(call expand ...) call.

An example can be found in hp3D and makesupport/libhp3D.mk. The first few lines are standard:

# ################################################ generic lib/hp3D makefile ##
# is copied to builds/$(config)/lib/hp3D

include $(CONCEPTSDIR)/makesupport/config.mk   
include $(CONCEPTSDIR)/makesupport/$(config).mk
Then, there are the project name, the imported projects and what is built here and the standard inclusion of makesupport/generic.mk (as seen before):
project = libhp3D
import = lib hp3D
library = libconceptshp3D.$(LIBSUFFIX).$(VERSION)

include $(CONCEPTSDIR)/makesupport/generic.mk
The next lines create a rule to build the imported projects from here (calling the target lib is not very sensible, tough):
all: lib
lib:
	set -e; for i in $(import); do \
	  make -C ../$$i ;\
	done
.PHONY: lib
Finally, there are the dependencies for building the library which is exported (one for the static case and one for the dynamic case):
library += $(patsubst libconc%.$(LIBSUFFIX).$(VERSION),-lconc%,$(shell cat $(CONCEPTSDIR)/builds/$(config)/lib/export))

ifeq ($(LIBSUFFIX),a)
libconceptshp3D.$(LIBSUFFIX).$(VERSION): $(call expand, hp3D)
else
libconceptshp3D.$(LIBSUFFIX).$(VERSION): LIBS = -lconcepts
libconceptshp3D.$(LIBSUFFIX).$(VERSION): $(call expand, hp3D)
endif

After adding the files and directories in the source, you need to call make once in the builds/$config directory to create the compile directory and compile the new sources.

Building Concepts Top

Make sure you have set the environment variables CONCEPTSDIR and config. CONCEPTSDIR has to contain the value of the Concepts base directory. You can set this variable with

setenv CONCEPTSDIR `pwd`
when you are in the base directory. config should contain the code for your configuration, eg. i586-linux-gnu or sun4u-solaris-gnu. The idea behind this is <hardware>-<operating system>-<compiler suite>.

There has to exist a makesupport/${config}.mk file and a directory builds/${config}. Changing into this directory and calling make should build the library and the executables. If you want to rebuild a certain project, you can issue make in builds/${config} again or go to that directory and call make there.

If you want to build the files in a test suite, go to the project's testsuite directory in the builds tree and call make there. The test suites are not automatically built, if you call make in the builds/${config} directory.

For a not yet Supported Architecture

You need to write a makesupport/${config}.mk file (see the already available examples) and create a builds/${config} subdirectory.

Version Managment with CVS Top

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
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

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 Top

There are three parts of the documentation,
  1. the static part Documentation for Concepts 2.0 with abstract, description of the concepts, history, authors and references,
  2. the tutorials and
  3. the Class Documentation.
The first part consists of static html-files in the directory $CONCEPTSDIR/doc, i.e. index.html and this page developing.html.

About the tutorials see here.

The Class Documentation is generated automatically by Doxygen. All hh-files are consulted. Perform the generation of documentation e.g. by

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

Create Tutorial in this Documentation Top

The tutorials are built around a cc-file which is located in $CONCEPTSDIR/applications like fem1D.cc. The following explanations are based on that example.
A tutorial consists of The tutorial main page shows a list of all tutorials with its short description. This text is taken from the file $CONCEPTSDIR/applications/tutorials/fem1D.data/short.html.
Documentation for Concepts 2.0 (Developing) | Tutorials | Class Documentation | Developer Tools