1 files changed, 147 insertions, 0 deletions
diff --git a/subversion/bindings/cxx/README b/subversion/bindings/cxx/README
new file mode 100644
index 0000000..6126c5a
--- /dev/null
+++ b/subversion/bindings/cxx/README
@@ -0,0 +1,147 @@
+WORK IN PROGRESS
+================
+
+This directory contains an experimental implementation of SVN++, a
+high-level Subversion C++ API.
+
+It is far from complete and may never see the light of day.
+
+On the other hand, one good reason for having a high-level C++ API is
+to use it as a baseline for Swig-generated bindings. Our current set
+of Perl, Python and Ruby bindings is too heterogenous in terms of
+feature set, object and usage model. They're almost as hard to use as
+the C API itself.
+
+
+DESIGN GOALS
+============
+
+In no particular order:
+
+  * Use modern C++ constructs (the current baseline is C++11).
+
+  * Hide the dependency on APR that is exposed in Subversion's C API.
+
+  * Use separate C++ types for different kinds of values returned
+    from the C API (e.g., dirent vs. property value vs. URL), to make
+    it easier to create generic typemaps for Swig.
+
+  * Provide both synchronous and asynchronous interfaces.
+
+  * Avoid unnecessary copies by defining strict lifetimes for
+    returned values.
+
+  * Provide API variants that accept wide strings as well as
+    UTF-8-encoded narrow strings.
+
+  * Provide high-level constructs for common parameter types; e.g.,
+    revision ranges and lists for diff, merge, etc.
+
+  * Provide optional header-only conversions and overload for Boost types (e.g.,
+    boost::tribool, boost::filesystem::path), which can be enabled by users by
+    defining the SVNXX_USE_BOOST symbol.
+
+    These convenience overloads and conversions must *not* make the SVN++
+    library depend on any Boost runtime libraries.
+
+  * API versioning (how?).
+
+
+API COVERAGE
+============
+
+Planned:
+
+  * libsvn_client (highest priority)
+  * svn_mtcc_*
+  * utilities (diff, revision ranges/lists, etc.)
+  * libsvn_ra
+  * libsvn_repos/libsvn_fs (lowest priority)
+
+Not planned:
+  * libsvn_subr
+  * libsvn_wc
+
+
+C++ NAMESPACES AND SOURCE LAYOUT
+================================
+
+Public API
+----------
+
+The public API is in namespace apache::subversion::svnxx and we define
+a namespace alias for that:
+
+    namespace svn = ::apache::subversion::svnxx
+
+All elements of the public API are defined or declared in header files
+in the directory
+
+    .../include/svnxx/*.hpp
+
+with the single header file
+
+    .../include/svnxx.hpp
+
+importing all relevant headers from that directory.
+
+Implementation details used by the public API and visible to user
+code but that should not be directly used by user code are in the
+namespace apache::subversion::svnxx::detail and should be defined
+in header files in the directory:
+
+    .../include/svnxx/detail/*.hpp
+
+Note on API versioning
+----------------------
+
+Version-specific elements of the public API should be defined in
+namespaces within the public namespace; e.g., for version 1.13:
+
+    apache::subversion::svnxx::v_1_13
+
+and the default (or selected) version will be exposed in the
+parent namespace by inlining the namespace declaration.
+This versioning does not apply to things declared in svn::detail.
+
+Implementation
+--------------
+
+All entities that are private to the implementation should be
+in the namespace apache::subversion::svnxx::impl and defined
+in header files within the source directory tree:
+
+    .../src/private/*_private.hpp
+
+with the single header file
+
+    .../src/private.hpp
+
+importing all relevant headers from that directory. The exception to
+this rule are C++ wrappers for APR types, which are defined in the
+namespace apache::subversion::svnxx::apr in header files in the
+directory:
+
+    .../src/aprwrap/*.hpp
+
+with the single header file
+
+    .../src/aprwrap.hpp
+
+importing all relevant headers from that directory.
+
+====================================================================
+
+IMPLEMENTATION NOTES
+====================
+
+Asynchronous Operations (TODO)
+------------------------------
+
+In the current model of asyncrhonous operations, we do not protect
+against using the same svn_client_ctx_t object from multiple
+threads. This _should_ be safe as long as the callback
+implementations are aware of it, but we should consider changing the
+design so that whilst svn::client::context can be shared, we create
+the actual svn_client_ctx_t on the fly for each operation --
+similarly to how we create a the scratch pool.