diff options
Diffstat (limited to '')
| -rw-r--r-- | README-cmake.md | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/README-cmake.md b/README-cmake.md new file mode 100644 index 0000000..3343779 --- /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 |