Installation

The build and install processes require the SCons tool, it replaces the configure/Makefile usual production on UNIX based systems and also insures production on Windows. You don’t have to know how Scons works, you just have to specify some paths related to your platform. The way to configure SCons for your platform and to run it is detailed below. CHLone has obviously a dependancy on HDF5, you have to have this librarie and its headers installed on your platform. There is no other needs, in particular no CGNS.org [1] file is required.

Now the Python module of CHLone is also installed if numpy and cython are found on your platform.

HDF5 requirements

CHLone uses the HDF5 symbolic links and uses the object creation date index, thus you need at least release v1.8.2 which can be found on HDF5 web site.

The CHLone requires you have the thread-safe feature of HDF5 enabled. You have setup the HDF5 build with the thread-safe and the enable-pthreads flags in the configure command line. In the case you already have an installation, you can check this feature in the H5pubconf.h file (which is one of the HDF5 header files you would find on your platform): if you find H5_HAVE_PTHREAD and H5_HAVE_THREADSAFE defines set to 1 then you have the required features.

Note

CHLone uses these defines during build and when you use the library in your application. In the case the threads are not taken into account by HDF5, CHLone ignores them too.

Build and install

Now, you have scons and HDF5 and you can proceed with the CHLone installation. Just run:

scons

and:

scons install root=/my/installation/directory

That’s it, CHLone has been built and installed, you can open your html browser on the first page of the documentation which is into the CHLONE_INSTALL_DOCS directory (/my/installation/directory/share in the example above).

The script can look for and select an HDF5 version for you, if you are not happy with this version, or if scons fails to find out your HDF5, you can setup the configuration by yourself. The SConstructSetUp.py file is your configuration file. You change the values detailled hereafter in this file. The ‘SCons’ scripts uses the ‘Python’ installation directory to find the ‘HDF5’ files and also to install the ‘CHLone’ files. You can change these values in the SConstructSetUp.py file to fit your own platform. There are four variables you may change:

HDF5_INCLUDES_PATHS
HDF5_LIBRARIES_PATHS
CHLONE_INSTALL_INCLUDES
CHLONE_INSTALL_LIBRARIES
CHLONE_INSTALL_DOCS

You need to know where is your HDF5 installation: the directory where the hdf5.h file is should be set in HDF5_INCLUDES_PATHS and the place where you find the libhdf5 library should be set in the HDF5_LIBRARIES_PATHS variable.

The installation will create a CHLone directory and put all CHLone/*.h header files in the CHLONE_INSTALL_INCLUDES directory. When you use the #include directive in your source files you should prefix them with CHLone:

#include "CHLone/l3.h"

The installation copies the libraries in CHLONE_INSTALL_LIBRARIES.

Warning

The ‘CHLone’ install process doesn’t manage the versions. If you want to keep unchanged an existing ‘CHLone’ installation, you have to manage it by yourself, the ‘CHLone’ install will overwrite existing installation.

Warning

The rpath link option is used in ‘CHLone.so’ python module, you should set the installation directory before any build if you want to avoid existing libCHLone.so masking.

The commands you can use with scons are:

  • scons Builds the library and the demos, no installation.
  • scons docs Builds the docs, no installation. You are not supposed to build the docs, all the current docs are shipped with the source tar in the doc directory. At installation time, these files are copied into the installation directory. There are three files, the CHLone.pdf is a pdf version of the manual, the *.tar file is the html self-contained version of the same manual. Please note the tar extraction would produce data without a root directory, all the files would appear in the extraction directory. (this is the way ‘SourceForge’ wants the docs).
  • scons install Installs the CHLone headers, the libraries and the docs if available.
  • scons tests Builds and runs the tests in the current built directory.
  • scons clean Removes the whole build directory and files.

The command line options are the ‘SCons’ usual options plus the following, which is however reserved for development purpose:

  • scons trace=1 Shows the actual commands ‘SCons’ is currently performing. This can help if you have some option or path issue.
  • scons coverage=1 Is reserved for test coverage production. This requires the use of ‘gcc’ and ‘gcov’, it produces a result file into the ‘CHLone/doc’ directory. The CHLone library has to be built with the coverage option before any test run. If you build the library without the option, running the tests with the coverage flag would lead to... nothing. hen the best is to start from a clean build and then run tests from an empty prod. More about coverage and profiling in the implementation section.
  • scons profiling=1 Is reserved for library profiling. This requires the use of ‘gcc’ and ‘gprof’, the resulting files (one per test exec) are in the test directory of the production.
  • scons tests reference=1 Is reserved for test output files storage, that is to store a reference output for later comparison.

All the build and install process uses the .scons.*.tmp directory for product storage. No production files can be found elsewhere. (There is a exception if you run the test coverage, but you are not supposed to do so...).

Note

The demos and tests are produced (compiled, linked) with the files found in the .scons.*.tmp directory.

Tests

The tests have been performed with gcov and valgrind on selected platforms. You can run the tests before the actual installation. The tests are build and run, they produces a text output with is compared to the ‘test/ref’ files (some filters are applied before the compare).

All tests should produce an ‘OK’ like this output below:

CHLone: Run test         l3/01_OpenClose.x                           OK
CHLone: Run test         l3/02_NodeAndCursor.x                       OK
CHLone: Run test         l3/03_NodeCreateDeleteUpdate.x              OK

A bad result would produce a ‘FAILED’. In that case you can check the test logs (*.tst) in the build directory (i.e. .scons.*.tmp/build/tests). If you want to submit a bug report, please use the ‘SourceForge Trac’ tool, check your issue is not already registered and, if necessary, add a new ticket.

There is an ouput with unexpected failed tests:

CHLone: Run test         a2/01_InitializeFinalize.x                  OK
CHLone: Run test         a2/02_NodeCreateAndQueries.x            FAILED
CHLone: Run test         a2/03_NodeData.x                            OK
CHLone: Run test         a2/04_Queries.x                         FAILED
CHLone: Run test         a2/05_Enumerates.x                          OK

Note

The CGNS/Python interface is tested in the MAP module of the pyCGNS package.

Demos

The demos are build with the CHLone library. They are in the .scons.*.tmp/build/demos directory.

Troubleshooting

There is a problem with include search, in case of modificatio nof CHLone C interface the headers you have installed in previous versions may override the current headers:

# CHLone: Compiling shared pyx/pyCHLone.c
.scons.linux2.tmp/build/pyx/pyCHLone.c: In function '__pyx_pf_6CHLone_26load':
.scons.linux2.tmp/build/pyx/pyCHLone.c:4192: error: too many arguments to function 's2p_loadAsHDF'

Then you have to remove the include/CHLone old version.

Microsoft Windows

This build/install is still experimental. There are notes about the current state:

Warning

mspdb80.dll was not found

I’ve just encountered the same problem when I tried to run a platform SDK server 2003 SP1 sample using VS2005 in command line these days, fortunately I solve it now. Maybe useless for you: the key is the environment variable “PATH”

vs2005 c:program filesmicrosoft visual studio 8psdk c:program filesmicrosoft platform sdk

First, go to vs2005 install path c:program filesmicrosoft visual studio 8vc, run vcvarsall.bat to set environment variable; then c:program filesmicrosoft platform sdk, run setenv command: eg: setenv /SRV32 /DEBUG. I use it to make the program work properly.

[1]See Glossary