Installation

How to Get Quantities

Download the code of Quantities from the sourceforge web site through project Quantity, where both packages and cvs development code are provided.

The packages represent complete stages of the software development. After installation they should work without major problems. Instructions on how to install the package can be found here.

The cvs code is under development. New versions are uploaded more or less frequently. Although it does contain additional features, it must also be expected that there are bugs. Thus, the cvs code should only be downloaded by experienced users. Please report any bugs that you find to the author. Install the cvs version as described here.

For both, packages and cvs code, you will need the Quantities and the BSUtilities software. The latter does provide some basic utility functions.

Prerequisites for the Installation

Quantities was developed with gcc version 3.2 or later. The use of the gcc compiler for installation of Quantities is recommended. More recent versions of the compiler may be needed. The current version of Quantities was used with gcc up to version 4.5.0.

The Quantities build process relies on the autotools (see also Developer Installation).

You need to have installed A. Alexandrescu's Loki library. Versions up to 0.1.7 were used for development. It is recommended to install this or a more recent version. If you have installed BSUtilities, the Loki library is already present. For installation details, see the instruction for BSUtilities.

You need the Boost library, which is included in most modern Linux installations. Various versions starting with 1.33.1 up to 1.34.1 were used successfully for the development of Quantities. Boost version 1.35.0 fails to compile with the code, and produces `multiple definition' errors, when more than one export header is included. Version 1.34.1. is recommended. Sometimes this library is located in a standard directory (e.g. /usr/include). However, you may have it installed in a different place in your file system, in particular if you needed to install version 1.34.1 in parallel to your system's Boost installation. You will have to define the location of the Boost library and header files as discussed below.

The following sub-libraries of Boost have to be installed in addition to the header files: filesystem, date_time, serialization and wave. See the instruction for BSUtilities on how to do this. Add --with-libraries=filesystem,date_time,serialization,wave to the configure flags if you compile Boost from source. Note that other software that uses Quantities may need additional Boost libraries.

You need the utility tools in package BSUtilities (version >= 0.6.2+). Installation instructions are given in the BSUtilities documentation.

To generate the graphical user interface to Quantities, a Qt4 installation is necessary (standard on many recent Linux systems).

User Installation

• Please check the prerequisites before!
• Download file quantities-<versionnumber>.tar.gz from http://sourceforge.net/projects/quantity into your <_download_directory_> and unpack the source:

  gunzip quantities-<versionnumber>.tar.gz
  tar xf quantities-<versionnumber>.tar
  

  The distribution source will then reside in <_download_directory_>/quantities_<versionnumber>. In the following, this is the <_source_directory_>.
• or, check out the cvs source code from here into <_source_directory_>. Read section Developer Installation below before continuing.
• Go to the <_source_directory_> with

  cd quantities-<versionnumber>
  

  where you substitute <versionnumber> by the version number.
• Configure, compile and install the package:
  
  

  1. ./configure <options>
     

     
     some options are noted here:
     
     
     • --prefix=<_install_directory_> (recommended) to choose an installation directory (default is /usr/local, which can only be used if you have root privileges). Although it is possible to fine tune the places where various pieces of Quantities are installed, it is advised not to change other directory information than `prefix'.
     • --with-loki=<_loki_directory_> (mandatory) to specify the path to the loki installation - this directory should contain subdirectories include/loki and, in subdirectory lib a file named libloki.so; default is /usr.
     • --with-boost=<_boost_directory_> (recommended) to specify the path to the boost installation, where a subdirectory include/boost or include/boost-<version>/boost exists with a file version.hpp, and at least libboost_filesystem<tag>.so is present in subdirectory lib; this option is particularly useful if there are several boost installations available. There is no simple default value. Rather the configure process checks for the boost installation in various standardized places if --with-boost is not given.
     • --with-BSUtilities=<_BSUtilities_install_directory_> (mandatory) to specify the path to the BSUtilities installation; default is /usr/local.
     • --with-BSUtilities-version=<versionnumber> (optional) to specify the BSUtilities version number; default is presently 0.6.2+.
     • --with-BSUtilities-libtag=<libtag> (optional) to specify the libtag of the BSUtilities library to be used. Note that the respective library must be present in <BSUtilities_install_directory>/lib/BSUtilities-<versionnumber><libtag>; default is <empty>.
     • --enable-debug (optional) to build the libraries and tests with debug information; default is not to build debugging code. If debug information is enabled, -d is appended to the subdirectory into which libraries are installed.
     • --enable-optimize (optional) to build the libraries and tests with optimized code; default is not to build optimized code. If optimization is enabled, -o is appended to the subdirectory into which libraries are installed.
     • --disable-Werror (optional) to build the libraries and tests without the -Werror option supplied to the compiler; default is to use this option, which is strongly recommended for developers); this results in treating warnings during compilation as errors.
     • --enable-staticTestProgs (optional) to build the tests as static executables; default is to build dynamically linked tests.
     • --enable-onlydoc (optional) to build the documentation only; default is not to build the documentation without compiling and linking.
     • --enable-latexdoc (optional) to build the LaTeX documentation; default is not to build the LaTeX documentation.
     • --enable-gui (optional) to specify if and possibly which type of a graphical user interface of EChem++ should be generated; default is no (corresponding to no interface), the only legal values are `no' (for no interface) and `yes'. The type of interface can be determined with the --with-gui option.
     • --with-gui=<type> (optional) specify the type of the graphical user interface to be generated. This option is only checked if --enable-gui is set to `yes'. Allowed values are currently, `Qt' (default; for a Qt4 based interface) and 'yes' (corresponds to the default value). If necessary, use the --with-qt option to specify more configuration details.
     • --with-qt=<path> (optional) to specify the path to the Qt4 installation, for the default, see ./configure --help.
       
       
     Note, that for each --enable-xxx option, a corresponding --disable-xxx option exists (and vice versa), which causes reverse behavior.
     
     The standard procedure generates and installs both shared and non-shared (static) libraries. If you ever want to generate shared or static libraries alone, use the --enable-shared, --enable-static, --disable-shared, and/or --disable-static options to the configure command.
     
     Type

     ./configure --help
     

     
     for more options, or check the INSTALL file.
     
     On 64-bit systems, you must include a Boost flag

     CXXFLAGS=-DBOOST_NO_INTRINSIC_INT64_T
     

     into the configure call to avoid redefinition errors during compilation.
     
     

  2. make
     

     
     

  3. make doc
     

     
     (optional)
     
     You need an installation of the doxygen program for this, see http://www.doxygen.org. The command will invoke doxygen to generate html documentation. The build process can be configure to generate LaTeX documentation additionally. The files are then in the respective documentation directories of the source tree. Point your browser at file:///<_source_directory_>/documentation/html/index.html .
     If you have installed the BSUtilities documentation in the respective subdirectory of the share directory, the build process should automatically generate links from the Quantities documentation to the relevant BSutilities pages.
     Note that running make doc will delete any tag files or links (BSUtilities.tag, quantities.tag) that is present in the top source directory.
     
     

  4. make install
     

     
     this will install the headers and libraries into the include/Quantities-<versionnumber>/xxx (xxx = Quantity, PhysicalQuantities, MathematicalQuantities, or GeneralQuantities) and lib/Quantities-<versionnumber><libtag> subdirectory trees in the installation directory specified with the --prefix option (default /usr/local), respectively, where <libtag> is either empty (neither optimization nor debug information is enabled), or a combination of -o and -d (either one or both options are enabled).
     
     

     make doc-install
     

     
     this will install the documentation files into the share/Quantities-<versionnumber> subdirectory in the installation directory specified with the --prefix option (default /usr/local).
     Point your browser at file:///<_install_directory_>/share/Quantities-<versionnumber>/documentation/html/index.html to access the full Quantities documentation.
     
     

  5. make check
     

     
     generate the test programs in subdirectories xxx/test, where xxx is Quantity, PhysicalQuantities, MathematicalQuantities, or GeneralQuantities. The test programs are dynamically linked executables by default. If you want to generate statically linked versions, use the --enable-staticTestProgs option to configure. For further information, see the section on test program use.
     
     
  6. If necessary, to clean up the generated files, use
     
     

     make clean
     make uninstall
     

     
     where make uninstall removes files from the <_install_directory_>, while make clean removes generated files in the <_source_directory_>. The command make clean is necessary between generation of libraries with different combinations of debug and optimization options (different libtags).
     
     
  7. To clean and/or uninstall documentation files, use
     
     

     make doc-clean
     make doc-uninstall
     

     
     Note that uninstalling the documentation may leave directories in the share subdirectory tree.
     
     
  8. To purge the configuration files, use
     
     

     make distclean
     

     
     
     
  9. To generate the documentation only, use
     
     

     ./configure --prefix=_installation_dir_ --with-BSUtilities=<_BSUtilities_install_directory_> --with-BSUtilities_version=<BSUtilities_versionnumber> --enable-onlydoc
     make doc
     make doc-install
     

     
     
     The options --with-BSUtilities and --with-BSUtilities_version are mandatory even if only the documentation is generated. The documentation will then be in <_install_directory_>/share/Quantities-<versionnumber>/documentation and you can direct your browser to
     
     

     file:///_install_directory_/share/Quantities-<versionnumber>/documentation/html/index.html
     

     
     
     This is recommended if you want to view the documentation without having all prerequisites available.
     
     
  10. If you want to generate LaTeX documentation additionally to the html type documentation, use
      
      

      ./configure --prefix=_installation_dir_ --with-BSUtilities=<_BSUtilities_install_directory_> --with-BSUtilities_version=<BSUtilities_versionnumber> --enable-latexdoc
      make doc
      make doc-install
      

      
      
      with or without --enable-onlydoc
      
      
  11. You may access on-line documentation through this link, where you can find documentation for the various releases of Quantities.
      
      

Using the Test Programs

There are two types of test programs for Quantities:

• programs that are expected to compile correctly and to produce results upon execution that can be checked versus some reference values (run-time test programs), and
• programs that are expected to not compile correctly and produce some compile time error message compile-time test programs.

At present, there is no automatic test procedure. Consequently, the various run-time test programs have to be executed one after the other. Also, the results of the compile-time test programs have to be checked by the installer. The command

make check

will compile the run-time test programs and also attempt to compile the compile-time test programs. The latter should all fail with a compiler or linker error message.

The following test programs are available:

• run-time test programs
  • in directory _srcdir_/Quantity/test
    • QuantityDimensionTest
    • QuantityConstructionTest
    • QuantityAssignmentTest
    • QuantityArithmeticsTest
    • QuantityTest
    • QuantitySerializationTest
  • ...
• compile-time test programs
  • in directory _srcdir_/Quantity/compiletest
    • QuantityAssignmentCompileTest1
    • QuantityAssignmentCompileTest2
    • QuantityAssignmentCompileTest3
    • QuantityAssignmentCompileTest4

Developer Installation

As a developer (or user) who downloaded the cvs version of Quantities, you have to create a configure script first. Autoconf, automake, and libtool must be installed.

Run

autoreconf --install

to generate the necessary files. See also the README file in <_source_directory_> and the page with specific information for developers.

As a developer, to generate a distribution package, use

make dist

or, preferably because the usability of the package is tested

make distcheck

back to Quantities start page