1 files changed, 216 insertions, 0 deletions
diff --git a/README-cmake.md b/README-cmake.md
new file mode 100644
index 00000000..3343779a
--- /dev/null
+++ b/README-cmake.md
@@ -0,0 +1,216 @@
+This file is based on the email that Daniel Richard G. sent to
+redland-dev:
+
+    http://lists.librdf.org/pipermail/redland-dev/2012-July/002502.html
+
+I lightly edited the email to fit into 80 chars and make more it
+markdowny and turn it into notes.
+
+-- Dave
+
+----------------------------------------------------------------------
+Date: Thu, 5 Jul 2012 14:56:01 -0400
+From: Daniel Richard G.
+To: redland-dev
+
+Hello list,
+
+I've implemented support for building the Raptor library using the
+CMake build configuration tool. This is intended not to replace the
+existing GNU-Autotools-based configuration / build framework, but to
+provide a better solution for building Raptor on Windows (and
+potentially other platforms) than hand-maintained project files for
+various popular IDEs.
+
+* [http://cmake.org/](CMake)
+
+* [http://en.wikipedia.org/wiki/CMake](CMake on Wikipedia)
+
+There are several reasons why I chose CMake for this:
+
+* It can generate project / solution / workspace files for basically
+  every version of Visual Studio in existence, from a common set of
+  definitions
+
+* Likewise, it can generate project files for less-common IDEs (e.g.
+  CodeBlocks, Apple Xcode) and makefile-trees for NMake, Borland,
+  MSYS...
+
+* A friendly GUI frontend is provided on Windows, great for IDE users
+  who like to click on things
+
+* CMake doesn't neglect to support Linux / Unix, of course; even
+  black-sheep systems like AIX are covered
+
+* The tool is actively maintained and developed by the folks at Kitware
+
+* The KDE folks moved whole-hog from Autotools to CMake due to its
+  solid support for Windows and popular IDEs, and while I certainly
+  wouldn't advocate a CMake-only zeitgeist, it certainly speaks to
+  their confidence in the tool
+
+* Of course: CMake is free software, distributed under the
+  three-clause BSD license
+
+* Teragram and I have used CMake extensively for the purpose of
+  facilitating Windows builds of primarily Autotools-based projects,
+  and so my own exerience has borne out the strengths of this
+  approach.
+
+
+That's not to say, of course, that the tool is perfect:
+
+* The syntax and naming conventions used in the CMake scripting
+  language and standard modules are more in line with Windows culture
+  than Unix (ALL_CAPS, semicolon separators and CamelCasing are in
+  abundance)
+
+* Some operations, like setting predefined compiler flags, are
+  needlessly harder to do compared to Autoconf (where you can just
+  e.g. assign to CFLAGS)
+
+* When CMake generates makefiles, they make the ones produced by
+  Automake look simple and elegant by comparison :> You definitely
+  get more of an IDE-like experience when building with these, which
+  some folks may like, but I don't care for at all.
+
+
+Nevertheless, I consider CMake's strengths to outweigh its
+weaknesses. I myself am as much an Autotools-alternative skeptic as
+anyone, and tend to look leerily at all the ones that have come
+along---especially when I've no choice but to deal with them
+(e.g. SCons in NSIS). But CMake not only stands strong where
+Autotools is weak (support for non-Cygwin / MSYS Windows
+environments, support for IDEs), it does so in a fully general,
+polished, and consistent way. This is the one that, in my view, has
+risen above the pack.
+
+All that said, then, I'll go on to the particulars of this CMake
+implementation for Raptor. (Everything is in the attached patch,
+against git master.)
+
+This turned out to be a fairly complex project, because the Raptor
+library has so many features that can be enabled / disabled /
+configured.  These are not merely controlled by #define'ing
+or #undefing cpp symbols; object files also need to be added or
+removed, as well as associated third-party library
+dependencies. Plus, the library conforms to various potential quirks
+in LibXML2, which need to be checked for at configure time. This
+complexity may be seen mostly in the top-level CMakeLists.txt file
+and src/CMakeLists.txt.
+
+The `win32_raptor_config.h` header is no longer used; this is replaced
+by the more general `raptor_config_cmake.h.in`, which CMake
+instantiates with configuration-specific values much as Autoconf
+instantiates `raptor_config.h.in`. Rather than remove the
+`#include <win32_raptor_config.h>` directive from numerous files,
+however, I added an `#if 0` block to the header to make it a no-op
+(to keep an already large patch from becoming even larger).
+
+In addition to reproducing the library build in CMake, I've also
+reproduced most of the test suite. Of course, the test suite is
+fairly extensive, and consists of numerous similar invocations of
+rapper and rdfdiff; maintaining all of these in Automake is enough of
+a task already without the extra work of maintaining it in CMake. So
+I opted for an approach wherein the CMake test definitions are
+generated as a side effect of the shell code that drives the tests in
+Automake.
+
+The patch contains `tests/*/CMakeLists.txt`, of course, but it also
+contains changes to the associated `Makefile.am` files that write out
+the bulk of the CMake script to `CMakeTests.txt` (filename is
+arbitrary; `make clean` deletes it). The intent is not full-auto
+generation of the `CMakeLists.txt` files, but to make most of the work
+in maintaining them a matter of cut-and-paste. (It wouldn't take much
+more to enable full-auto generation, but I think there is value in
+having the maintainer at least eyeball what's going in.)
+
+The CMake-based test suite does have a few shortcomings compared to
+the Automake-based one, and will need further refinement:
+
+* Tests that compare output to a reference do not check for file
+  equality as a way of avoiding the use of rdfdiff. This is a problem
+  because rdfdiff currently blows up on certain inputs (e.g. test
+  0176 in rdfa11).
+
+* That would be easier to resolve if it weren't for the issue of
+  comparing CRLF output from rapper on Windows to LF reference
+  files. CMake has built-in functionality to compare files, but as
+  currently implemented, it is basically a cross-platform
+  cmp(1) --- there's no way to see past differences in EOL
+  convention. I've filed a feature request on this...
+  [http://public.kitware.com/Bug/view.php?id=13007](CMake Isue 13007)
+  ...but for now, I'm using CMake's `CONFIGURE_FILE()` to normalize
+  line endings on the output files before doing the comparison.
+
+* `tests/turtle/CMakeLists.txt` has yet to be written, as the
+  exit-status logic there is a bit more involved than the other test
+  sections.
+
+* There is some awkwardness on Windows, when the rapper and rdfdiff
+  binaries depend on third-party DLLs (e.g. LibXML2). A correctly-set
+  PATH allows the DLLs to be found, but Visual Studio isn't terribly
+  straightforward about how to set PATH when running a program, and
+  (IIRC) the failure mode was not even obvious to begin with. I've
+  addressed this, if a little ham-handedly, by enabling the test
+  suite only when building Raptor with a makefile tree.
+
+
+Other caveats of this CMake implementation:
+
+* This build framework is not enough to produce a Raptor DLL. There
+  are issues regarding DLL-export linkage of various functions in
+  `raptor_internal.h` and `turtle_common.h` that need
+  addressing. I'll bring those up here on the list once the CMake
+  stuff is hashed out.
+
+* Support for JSON --- and more specifically, the YAJL library --- is
+  penciled in, but not yet working or tested. (I have no experience
+  with this library, let alone on Windows.)
+
+* Generation of `turtle_lexer.c`, `turtle_parser.c` and such is not
+  implemented at all. This can be added, but my working premise is
+  that the CMake build framework is meant for library users, not
+  developers.
+
+
+If you would like to kick the tires of this CMake implementation,
+here are some steps to get you started:
+
+1. Apply my patch to a copy of Raptor's git master source
+
+2. Run `./autogen.sh`, `./configure` and `make dist`
+
+3. Unpack the resulting dist tarball somewhere
+
+4. Download and install the CMake tool
+
+5. (Linux) Create a new, empty build directory, and from there,
+   invoke
+
+     $ cmake /path/to/raptor2-dist-src
+
+   This is the equivalent of running plain `./configure`, with
+   default values for everything. Provided that you have all the
+   requisite libraries installed, this should produce a makefile
+   tree.
+
+5. (Windows) Run the `cmake-gui` application, set the source and
+   build paths at the top (the latter should be a new, empty
+   directory) and hit Configure. Select an appropriate "generator"
+   (this is where you choose the specific IDE or other build system
+   you want), then hit Finish. Allow CMake to run the configuration
+   checks, and if these succeed, hit Generate. Once the generation
+   process is finished, you may close CMake and use the
+   newly-generated build system.
+
+6. If you are building with makefiles, the test suite is invoked with
+   the "test" target, not "check".
+
+Questions and comments on this implementation are welcome; I'll do my
+best to answer any. This framework addresses a difficulty that
+Teragram has had with this library, and I hope it will do the same
+for others here.
+
+
+--Daniel