XParam - General-Purpose Object Serialization Framework for C++

Installing XParam

Contents:

1. Installation in Unix
2. Installation in Windows
3. Making Changes

Installation in Unix

• The XParam source files are available in the file xparam-1.22.tar.gz. Use tar zxvf xparam-1.22.tar.gz to uncompress and untar this file to where you want it. We will assume you put the XParam files under /usr/local/src/.
• The XParam files are under four main directories. Under lib you will find the code for building the library itself. Under examples you will find example programs using XParam. Under tests you will find regression testing code. Under doc you will find the library's html documentation, including this file. The tar file only contains sources for building the library, example code and regression testing code, and does not by itself contain the executables or the linkable library. Building XParam, according to the instructions given below, will create these executables and library code.
• XParam uses autoconf. Run './configure' from the main directory to create the library's Makefile, then run 'make install' from the main directory to build the library and install it. (Using 'make' will build the library, but will not install it.) 'make check' will run regression testing. 'make examples' will compile the example code. 'make check' and 'make examples' will only work after the library is installed.
• Set environment variable XPARAM_CLASSPATH to include all directories where you want XParam to search for its '.xpn' files (separated by colons). To run the example programs, you will need this path to include /usr/local/src/xparam-1.22/examples/classpath (or the equivalent to reach the examples/classpath subdirectory in the distribution, if you untarred XParam in a directory other than /usr/local/src).
• The standard XParam installation places the file libxparam.so under /usr/local/lib, the XParam header files xparam.h and xparam_extend.h under /usr/local/include, and the rest of XParam's include files (which are never used directly) under /usr/local/include/xparam. Use the './configure' directive '--disable-priv-includes' if you want to install all include files in the same directory, or '--enable-priv-includes[=path]' to install the private include files to a relative path other than 'xparam'.
• Use the './configure' directive '--disable-dynamic' if you wish to have the dynamic loading feature disabled. This will only affect your system if it has dynamic loading support. Otherwise, this feature will be automatically disabled.
• If, for some reason, you do not want XParam to be useable until a certain point in your program, use --enable-explicit-init. This will cause XParam not to work before a call to xparam_init(). Otherwise, XParam registrations will all be executed on the first use of XParam in the program. This option is particularly useful if you are concerned that someone might use XParam before "main()", when you can not be sure that all registrations have already been initiated. Typically, xparam_init() will be the first line of your "main()".
• XParam's configuration can make use of environment variables such as LDFLAGS, CPPFLAGS and CXXFLAGS, in the normal way. However, by default, it does not set the -O2 and -g flags in CXXFLAGS, even if your compiler supports them. This is because neither speed optimization nor debug information is usually important for the XParam user. (After all, this is an I/O package.) On the other hand, these flags can slow down compilation considerably. To override this default behavior, and have XParam turn on the -O2 and -g flags if they are available, use '--enable-cxxflags' when running './configure'.
• The examples subdirectory of XParam can be configured separately from the rest of the package. It is equipped with its own configure script. It can be executed using "examples/configure". By default, configuring the package also configures the examples subdirectory, using equivalent parameters. If you want to configure the library without configuring its examples, use the ./configure option --disable-config-examples.
• Make sure that the directory where you installed the XParam library is a trusted directory for loading shared objects. (See "man ldconfig" for details.)
• If, while running 'make install', environment variable DESTDIR is set, XParam will install to that directory. That is, any file that is meant to be installed to the directory /X will, instead, be installed to DESTDIR/X. This is useful for checking XParam's installation without actually installing. Running 'make check' with DESTDIR still set to the same value will run the XParam tests on the copy of the installation based in DESTDIR. Note that installing with DESTDIR causes no 'ldconfig' command to be executed. (See ldconfig's documentation for details.) If you install to DESTDIR, you should subsequently copy all files created in DESTDIR's subdirectory to their proper places and run ldconfig to complete the installation. This is not necessary when installing directly to the final destination.
• You have now finished the installation of XParam. All the usage instructions are in the doc library, including how to run the programs under examples to verify that the installation was successful.

Installation in Windows

• The XParam source files are available in the file xparam-1.22.tar.gz. Use WinZip or similar utility to uncompress and untar this file to where you want it.
• The XParam files are under four main directories. Under lib you will find the code for building the library itself. Under examples you will find example programs using XParam. Under tests you will find regression testing code. Under doc you will find the library's html documentation, including this file. The tar file only contains sources for building the library, example code and regression testing code, and does not by itself contain the executables or the linkable library. Building XParam, according to the instructions given below, will create these executables and library code.
• Load the workspace file xparam.dsw (for Visual C++ 6.0). It contains all the projects and settings for compiling the XParam library and examples with Visual C++ 6.0 - just run the build command on your selected project.
  When you want to create your own project using XParam, you should make the following project settings:
  • Turn on RTTI (Under the C/C++ tab, C++ Language category)
  • Add the include directory for XParam's include files (Under the C/C++ tab, Preprocessor category, Additional include directories field). You should enter here the directory lib/xparam in the XParam distribution.
  • Link with the XParam library. To do this go to the Link tab, input category. Add xparam.lib at the end of the field Object/library modules, and add the path to the XParam library in the Additional library path field
  (If you've used the supplied project settings to compile the library, this entry should be lib/bin relative to the root of the XParam distribution).
• If your non-Unix compiler is not Visual C++, there may be certain features that XParam uses that your compiler might not support. Consult the XParam header file xp_config.h in order to decide on the correct compilation flags that will make XParam work around the missing features.
• You have now finished the installation of XParam. All the usage instructions are in the doc library, including how to run the programs under examples to verify that the installation was successful.

Making Changes

• The XParam parser and lexer were written using a parser generator called ANTLR. The descriptions of the parser and lexer appear under directory lib/meta_sources/*.g. In order to re-create the parser, you must first install ANTLR. ANTLR is freeware, available from www.antlr.org. ANTLR is written in Java, so you must also have Java installed, in order to run it.
• Use lib/meta_sources/update_parsers.pl to run ANTLR, because XParam has to tweak the ANTLR output before it can use the files.
• XParam's ready-to-compile version can handle constructors of only up to 13 parameters. If you wish to exceed this limit, simply run lib/meta_sources/ctor_code_gen.pl with the upper limit you desire as a parameter. (See README.txt, in the same directory for further details.)
• The .pl files in lib/meta_sources are Perl files. In order to run them, you must have a Perl interpreter installed.
• If you write any patch, bug-fix or extension to XParam, make sure you send us a copy. Simply diff your version with ours, and send the resulting patch-file to the tracker at xparam.sourceforge.net.