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

1 files changed, 131 insertions, 0 deletions

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