.. ====================================================================== CHLone - CGNS HDF5 LIBRARY only node edition See license.txt in the root directory of this source release ====================================================================== Installation ============ The build and install processes require the :ref:`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 :ref:`HDF5 `, you have to have this librarie and its headers installed on your platform. There is no other needs, in particular no `CGNS.org` [#n0]_ file is required. Now the Python module of CHLone is also installed if *numpy* and *cython* are found on your platform. .. index:: pair: hdf5; requirements pair: hdf5; installation pair: scons; installation pair: hdf5; threadsafe 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 :ref:`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. .. _toolslinks: 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. Links ~~~~~ .. index:: pair: python; requirements pair: scons; requirements The `URL` list below gives the important references used by or related to `CHLone`: - CHLone: http://chlone.sourceforge.net - CGNS: http://www.cgns.org - HDF5: http://www.hdfgroup.org/HDF5 - SCons: http://www.scons.org - Sphinx: http://sphinx.pocoo.org - Python: http://www.python.org - Cython: http://www.cython.org - numpy: http://numpy.scipy.org/ .. note:: The `SCons` and `Sphinx` tools use `Python`. This powerful programming langage is now widely installed and used and this should not cause problem for you to install or to use it. `SCons` has no special dependancies. `Sphinx` has a lot of dependancies to various documentation packages, however you do *not* require it unless you want to re-generate the documentation. 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 files\microsoft visual studio 8\ psdk c:\program files\microsoft platform sdk\ First, go to vs2005 install path c:\program files\microsoft visual studio 8\vc, run vcvarsall.bat to set environment variable; then c:\program files\microsoft platform sdk\, run setenv command: eg: setenv /SRV32 /DEBUG. I use it to make the program work properly. .. [#n0] See Glossary