| 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 heterogeneous 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. |