cMsg Software Package You must install Java version 1.6 or higher if you plan to compile the cMsg code and run it. If you only plan to run C/C++ clients (i.e. if you will use someone else's cMsg server) you can skip the Java installation. If you only plan to use Java domains and clients you can skip the C/C++ installation. 1) Getting & Installing cMsg The cMsg package, including documentation, can be found on the JLab Data Acquisition Group CODA wiki at http://coda.jlab.org. For Java users, a jar file is available for download and is usually all that is needed. To install all of cMsg, download the cMsg-3.x.tar.gz file (or whatever version happens to be current) and untar it. This will give you a full cMsg distribution with the top level directory being cMsg-3.x. The documentation, is available on the above-mentioned web site but also exists in the doc subdirectory of the full distribution. Note that for C/C++, only Linux, Solaris, and Darwin (Mac OSX) operating systems are supported. The libraries and executables are placed into the $CODA//lib and bin subdirectories (eg. ...Linux-x86_64/lib). Be sure to change your LD_LIBRARY_PATH environmental variable to include the correct lib directory. 2) C/C++ code Compiling using SCons From the SCons website: "SCons is an Open Source software construction tool -- that is, a next-generation build tool. Think of SCons as an improved, cross-platform substitute for the classic Make utility with integrated functionality similar to autoconf/automake and compiler caches such as ccache. In short, SCons is an easier, more reliable and faster way to build software." SCons is written in python, thus to use this build system with cMsg, both python and SCons packages need previous installation. If your system does not have one or the other, go to the http://www.python.org/ and http://www.scons.org/ websites for downloading. The SCons files needed for compiling are already included as part of the cMsg distribution. To compile, the user needs merely to run "scons" in the top level cMsg directory. To compile and install libraries and header files, first define the CODA environmental variable containing the directory in which to install things and then run "scons install". The following is a table of SCons compilation options: scons -h print out help scons -c remove all generated files scons install make C and C++ library code; place libraries in architecture-specific lib directory and headers in an include directory scons examples make C and C++ executable example code; place executables in architecture-specific bin directory scons -c install uninstall libs & headers scons -c examples uninstall executable examples scons tar create a tar file (cMsg-3.x.tgz) of the cMsg top level directory and put in ./tar directory scons doc generate html documentation from javadoc and doxygen comments in the source code and put in ./doc directory scons undoc remove the doc/javadoc and doc/doxygen/C & CC directories with all the generated documentation scons --dbg compile with debug flag scons --32bits compile 32bit libraries & executables on 64bit system scons --vx5.5 cross compile for vxworks version 5.5 scons --vx6.0 cross compile for vxworks version 6.0 scons --prefix= use base directory when doing install. Defaults to CODA environmental variable. Libs go in //lib, headers in //include and executables in //bin scons --incdir= copy header files to directory when doing install (takes precedence over --prefix or default location) scons --libdir= copy library files to directory when doing install (takes precedence over --prefix or default location) scons --bindir= copy executable files to directory when doing install (takes precedence over --prefix or default location) You can see these options by running "scons -h" Note that currently only Linux, Solaris, and Darwin (Mac OSX) operating systems are fully supported. The libraries and executables are placed into the $CODA//lib and bin subdirectories (eg. ...Linux-x86_64/lib). Be sure to change your LD_LIBRARY_PATH environmental variable to include the correct lib directory. All libraries and a limited set of executables are also supported for vxworks versions 5.5 and 6.0 . 3) JAVA One can download the cMsg-3.x.jar file from the CODA website or it can be generated from the general cMsg distribution. In either case, put the jar file into your classpath and run your java application. Use java version 1.6 or higher. If you wish to recompile the java part of cMsg, ant must be installed on your system (http://ant.apache.org). First extract the package files from the general cMsg tar file: # download cMsg-3.x.tar.gz into $ cd $ tar -fxz cMsg-3.x.tar.gz $ cd cMsg-3.x $ ant To get a list of options with ant, type "ant help": ant help - print out usage ant env - print out build file variables' values ant compile - compile java files ant clean - remove class files ant cleanall - remove all generated files ant jar - compile and create cmsg jar file ant install - create cmsg jar file and install all jars into 'prefix' ant if given on command line by -Dprefix=dir', ant else install into CODA if defined ant (ET jar file is not installed) ant uninstall - remove all jar files previously installed into 'prefix' ant if given on command line by -Dprefix=dir', ant else installed into CODA if defined ant (ET jar file is not removed) ant all - clean, compile and create cmsg jar file ant javadoc - create javadoc documentation ant developdoc - create javadoc documentation for developer ant undoc - remove all javadoc documentation ant prepare - create necessary directories To generate a new cmsg jar file, type "ant jar" which will create the file and place it in /build/lib . Included in the /java/jars subdirectory are all auxiliary jar files used by the built-in domains and subdomains. Thus to use the Channel Access or the SmartSockets (sub)domains the user must include the necessary jar files in the classpath. These (all except the ET jar file) are installed when executing "ant install". Check the individual package web sites for more information. 4) Documentation All documentation is available from http://coda.jlab.org. However, if using the downloaded distribution, some of the documentation needs to be generated and some already exists. For existing docs look in doc/users_guide and doc/developers_guide for pdf and Microsoft Word format documents. Some of the documentation is in the source code itself and must be generated and placed into its own directory. The java code is documented with, of course, javadoc and the C/C++ code is documented with doxygen comments (identical to javadoc comments). To generate all the these docs, from the top level directory type: "scons doc" To remove it all type: "scons undoc" The javadoc is placed in the doc/javadoc directory. The doxygen docs for C code are placed in the doc/doxygen/C/html directory, and the doxygen docs for C++ code are placed in the doc/doxygen/CC/html directory. To view the html documentation, just point your browser to the index.html file in each of those directories. Alternatively, just the java documentation can be generated by typing "ant javadoc" for user-level documentation, or "ant developdoc" for developer-level documentation. To remove it: "ant undoc" 5) Problems Carl Timmer - timmer@jlab.org 6) Copyright For any issues regarding use and copyright, read the NOTICE file.