| = Developer guide to C++ codebase = |
| |
| == Prerequisites == |
| |
| As per README-dist plus: |
| * autoconf 2.59: http://www.gnu.org/software/autoconf |
| * automake 1.9.6: http://www.gnu.org/software/automake |
| * libtool 1.5: http://www.gnu.org/software/libtool |
| * CppUnit 1.10.2: http://cppunit.sourceforge.net |
| |
| Optional: to generate documentation from source code comments you need: |
| * doxygen 1.4.6: http://sourceforge.net/projects/doxygen/ |
| * graphviz 2.8: http://www.graphviz.org/ |
| |
| If you use yum to install packages, do the command from the README-dist then: |
| |
| # yum install apr-devel cppunit-devel boost-devel doxygen graphviz |
| |
| == Recent changes == |
| |
| There have been two major changes on the C++ hierarchy: |
| - adds autoconf, automake, libtool support |
| - makes the hierarchy flatter and renames a few files (e.g., Queue.h, |
| Queue.cpp) that appeared twice, once under client/ and again under broker/. |
| |
| In the process, I've changed many #include directives, mostly |
| to remove a qpid/ or qpid/framing/ prefix from the file name argument. |
| Although most changes were to .cpp and .h files under qpid/cpp/, there |
| were also several to template files under qpid/gentools, and even one |
| to CppGenerator.java. |
| |
| Nearly all files are moved to a new position in the hierarchy. |
| The new hierarchy looks like this: |
| |
| src # this is the new home of qpidd.cpp |
| tests # all tests are here. See Makefile.am. |
| gen # As before, all generated files go here. |
| lib # This is just a container for the 3 lib dirs: |
| lib/client |
| lib/broker |
| lib/common |
| lib/common/framing |
| lib/common/sys |
| lib/common/sys/posix |
| lib/common/sys/apr |
| build-aux |
| m4 |
| |
| == Building == |
| |
| As we smooth off the rough edges with the new build setup the steps |
| for the most common development tasks will be scripted and/or |
| simplified and this README will be updated accordingly. |
| |
| Before building a fresh checkout do: |
| ./bootstrap |
| |
| This generates config, makefiles and the like - check the script for |
| details. You only need to do this once, "make" will keep everything up |
| to date thereafter (including re-generating configuration & Makefiles |
| if the automake templates change etc.) |
| |
| To build and test everything: |
| make |
| make check |
| |
| This builds in the source tree. You can have multiple builds in the |
| same working copy with different configuration. For example you can do |
| the following to build twice, once for debug, the other with |
| optimization: |
| |
| make distclean |
| mkdir .build-dbg .build-opt |
| (cd .build-opt |
| ../configure --enable-warnings --prefix=/tmp/x && make && make check) |
| (cd .build-dbg |
| ../configure --enable-warnings CXXFLAGS=-g --prefix=/tmp/x \ |
| && make && make check) |
| |
| === Portability === |
| |
| All system calls are abstracted by classes under lib/common/sys. This |
| provides an object-oriented C++ API and contains platform-specific |
| code. |
| |
| These wrappers are mainly inline by-value classes so they impose no |
| run-time penalty compared do direct system calls. |
| |
| Initially we will have a full linux implementation and a portable |
| implementation sufficient for the client using the APR portability |
| library. The implementations may change in future but the interface |
| for qpid code outside the qpid/sys namespace should remain stable. |
| |
| |
| === Unit tests === |
| |
| Unit tests are built as .so files containing CppUnit plugins. |
| |
| DllPlugInTester is provided as part of cppunit. You can use it to run |
| any subset of the unit tests. See Makefile for examples. |
| |
| NOTE: If foobar.so is a test plugin in the current directory then |
| surprisingly this will fail with "can't load plugin": |
| DllPluginTester foobar.so |
| |
| Instead you need to say: |
| DllPluginTester ./foobar.so |
| |
| Reason: DllPluginTester uses dlopen() which searches for shlibs |
| in the standard places unless the filename contains a "/". In |
| that case it just tries to open the filename. |
| |
| === System tests === |
| |
| The Python test suite ../python/run_tests is the main set of broker |
| system tests. |
| |
| There are some C++ client test executables built under client/test. |
| |
| == Doxygen == |
| |
| Doxygen generates documentation in several formats from source code |
| using special comments. You can use javadoc style comments if you know |
| javadoc, if you don't or want to know the fully story on doxygen |
| markup see http://www.stack.nl/~dimitri/doxygen/ |
| |
| Even even if the code is completely uncommented, doxygen generates |
| UML-esque dependency diagrams that are ''extremely'' useful in navigating |
| around the code, especially for newcomers. |
| |
| To try it out "make doxygen" then open doxygen/html/index.html |