Skip to content

Latest commit

 

History

History
216 lines (163 loc) · 8.86 KB

README-cmake.md

File metadata and controls

216 lines (163 loc) · 8.86 KB
Raw

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.

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.

  6. (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.

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