From d7ede78eb5ed21f13443234b1931e9d5e725fd64 Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Fri, 1 Dec 2006 18:49:01 +0000 Subject: Split README into README-dev for developers and README-dist for people building the source distro. The latter needs work. git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@481335 13f79535-47bb-0310-9956-ffa450edef68 --- cpp/README | 133 -------------------------------------------------------- cpp/README-dev | 131 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ cpp/README-dist | 26 +++++++++++ 3 files changed, 157 insertions(+), 133 deletions(-) delete mode 100644 cpp/README create mode 100644 cpp/README-dev create mode 100644 cpp/README-dist (limited to 'cpp') diff --git a/cpp/README b/cpp/README deleted file mode 100644 index 48c152d8cb..0000000000 --- a/cpp/README +++ /dev/null @@ -1,133 +0,0 @@ -= Developer guide to C++ codebase = - -== Prerequisites == - -Required to build: - * 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 - * Apache Portable Runtime 1.2.2: http://apr.apache.org - * CppUnit 1.11.4: http://cppunit.sourceforge.net - * boost 1.33.1: http://www.boost.org - -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: - -# yum install apr autoconf automake apr-devel cppunit cppunit-devel boost 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 diff --git a/cpp/README-dev b/cpp/README-dev new file mode 100644 index 0000000000..2cd20fbd95 --- /dev/null +++ b/cpp/README-dev @@ -0,0 +1,131 @@ += 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.11.4: 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 diff --git a/cpp/README-dist b/cpp/README-dist new file mode 100644 index 0000000000..133eb7da81 --- /dev/null +++ b/cpp/README-dist @@ -0,0 +1,26 @@ + +This README describes how to build Qpid from a source distribution. + +== Prerequisites == + + * Apache Portable Runtime 1.2.2: http://apr.apache.org + * boost 1.33.1: http://www.boost.org + +Optional: if you want to run the qpid unit tests: + * CppUnit 1.11.4: http://cppunit.sourceforge.net + +If you use yum to install packages you can do: + + # yum install apr boost + +== Building == + +Build and install with: + # ./configure + # make all + # make install + +TODO: add boilerplate README for standard autoconf/automake install. +TODO: document special qpid configure options. + ./bootstrap + -- cgit v1.2.1