diff options
Diffstat (limited to 'cpp/README-dev')
| -rw-r--r-- | cpp/README-dev | 201 |
1 files changed, 0 insertions, 201 deletions
diff --git a/cpp/README-dev b/cpp/README-dev deleted file mode 100644 index 108e1f4b1f..0000000000 --- a/cpp/README-dev +++ /dev/null @@ -1,201 +0,0 @@ -= Developer guide to C++ codebase = - -== Extra stuff == -sudo cp /usr/share/aclocal/pkg.m4 `aclocal --print-ac-dir` - -== Prerequisites == - -If you have taken the sources from SVN you will need the following -packages (or later) - -We prefer to avoid spending time accommodating older versions of these -packages, so please make sure that you have the latest stable version. - - * All the prerequisites listed in README-dist. - * GNU make <http://www.gnu.org/software/make/> - * autoconf <http://www.gnu.org/software/autoconf/> - * automake <http://www.gnu.org/software/automake/> - * cppunit <http://cppunit.sourceforge.net> - * help2man <http://www.gnu.org/software/help2man/> - * libtool <http://www.gnu.org/software/libtool/> - * pkgconfig <http://pkgconfig.freedesktop.org/wiki/> (aka pkg-config) - -Note: Ensure cppunit-config and apr-1-config are in your PATH. - -Optional: to re-generated generated code from the XML specification: - - * java 5 - -Optional: to generate documentation you need: - - * doxygen <http://sourceforge.net/projects/doxygen/> - * graphviz <http://www.graphviz.org/> - * help2man <http://www.gnu.org/software/help2man/> - -== Setting up on Fedora 6 == - -# yum install apr apr-devel boost boost-devel cppunit cppunit-devel -# yum install pkgconfig doxygen graphviz help2man - -To get the latest versions of autoconf, automake, libtools and other -dependencies, run the script qpid-autotools-install: - -1. Decide where you would like to install the tools. It should be in a - local directory so that you do not need root privileges. (Suggest - $HOME/qpid-tools.) Create an empty directory. -2. Modify your environment variable PATH to ensure that the bin directory - within this directory comes first in the PATH string: - PATH=$HOME/qpid-tools/bin:$PATH -3. Set PKG_CONFIG_PATH=$HOME/qpid-tools/lib/pkgconfig:/usr/lib/pkgconfig - (or if it already exists, make sure that the above path to your - qpid-tools directory is first). -4. Run the install utility from the cpp directory: - ./qpid-autotools-install --prefix=$HOME/qpid-tools --skip-check - (Note that --prefix will only accept an absolute path, so don't use - ~/qpid-tools.) The utility will download, compile and install the - required tools into the qpid-tools directory (this may take a little - time). Watch for any notices about paths at the end of the install - - this means that your environment is not correct - see steps 2 and 3 - above. - NOTE: If you omit the --skip-check option, the check of the build - can add up to an hour to what is normally a few minutes of install - time. -5. Perform a check: from the command-line run "which automake" and - ensure that it finds the automake in your qpid-tools directory. If not, - check that the build completed normally and your environment. -6. (Optional) If having the build artifacts lying around bothers you, delete - the (hidden) build directory cpp/.build-auto-tools. - -To see help, run ./qpid-autotools-install --help. - -== 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 - ./configure - -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.) - -If you are developing code yourself, or if you want to help -us keep the code as tight and robust as possible, consider enabling -the use of valgrind. If you configure like this: - - ./configure --enable-valgrind - -that will arrange (assuming you have valgrind installed) for "make check" -to run tests via valgrind. That makes the tests run more slowly, but -helps detect certain types of bugs, as well as memory leaks. If you run -"make check" and valgrind detects a leak that is not listed as being -"ignorable-for-now", the test script in question will fail. However, -recording whether a leak is ignorable is not easy, when the stack -signature, libraries, compiler, O/S, architecture, etc., may all vary, -so if you see a new leak, try to figure out if it's one you can fix -before adding it to the list. - -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 --prefix=/tmp/x && make && make check) - (cd .build-dbg - ../configure 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 |