From c9aeb92283d103b959e69238e923a1e8a8b87676 Mon Sep 17 00:00:00 2001 From: Dave Beckett Date: Sun, 15 Aug 2010 14:42:29 -0700 Subject: Add UPGRADING.html --- UPGRADING.html | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 UPGRADING.html (limited to 'UPGRADING.html') diff --git a/UPGRADING.html b/UPGRADING.html new file mode 100644 index 00000000..4b8ff9c3 --- /dev/null +++ b/UPGRADING.html @@ -0,0 +1,135 @@ + + + + + Raptor RDF Syntax Library - Upgrading to the Raptor V2 API + + + +

Raptor RDF Syntax Library - Upgrading to the Raptor V2 API

+ +

Overview

+ +

Raptor V2 is a cleaned up version of the Raptor V1 API with +changes that include adding, removing and re-ordering parameters, +adding and removing return types as well as renaming the +functions.

+ +

The headers and libraries install to different places or names so +that Raptor V1 and Raptor V2 can both be present (including headers) +on the same system without clashing. However, if you do try linking +the same binary with both, that won't work! There are only two +installed files that overlap - the rapper utility +and it's manual page. +

+ + +

Configuration and compiling changes

+ +

Raptor V2 uses pkg-config(1) to provide the compile +and link parameters whereas Raptor V1 supports that as well as a +script raptor-config. The recommended linking approach +is now as follows: +

+  cc -o prog prog.c  `pkg-config raptor2 --cflags` `pkg-config raptor2 --libs`
+

Shown here as a compile in link all in one line but you typically +split that into two stages. +

+  cc -c `pkg-config raptor2 --cflags` raptor-module.c
+  ...
+  cc -o prog raptor-module.c ... other modules ... `pkg-config raptor2 --libs`
+

+ + +

Code changes

+ +

There are significant API changes, which are described in the +Release Notes in long summary form with +some background to why, in the ChangeLog in +very long form. The reference manual contains sections describing +what was added, deleted, renamed and otherwise changed for +both the functions exported from the library, as well as the +typedefs. +

+ +

+see html +

+ +

There is no fully automatic way to handle updating the code +however there is a perl script provided in the docs directory that +renames what it can, and otherwise inserts a WARNING comment near +code that needs manual updating. It is used like +perl docs/upgrade-script.pl source files for example

+  $ perl docs/upgrade-script.pl prog.c
+

+ +

and then edit the file prog.c and search for WARNING

+ + +

Handling Raptor V1 and Raptor V2 in the same code

+ +

If you need to handle both APIs in the same codebase, it is +recommended that after deciding which to use, you use the +following approach based on macros. +

+ +

+Create a #define that records the choice of which API +you want to use. You can do this triggered on whichever +raptor.h is in the include path by #ifdef +RAPTOR_V2_AVAILABLE but that may be dangerous if both +libraries and headers are present. Better is an application define +that is determined by a configuration step. +

+ +

Once the choice is made, it is recommended you convert the +code to the Raptor V2 API and then add backwards-compatible macros +for the changed functions: +

+ +

+#ifdef APP_WANTS_RAPTOR_V2
+/* nop */
+
+#else
+#define raptor_v2_function(arg1, arg2) raptor_v1_function(arg2, arg1, arg3)
+
+#endif
+

+ +

Another approach if the Raptor code is in a separate module / +source file is to fork it and make a V2 version and then choose the +file to use at configure or build time. +

+ +

Either way, basing the interface on the V2 APIs makes it clear +what to remove when V1 is no longer supported. +

+ + +

Packaging recommendations for distributors

+ +

Since Raptor V2 installs files independent from Raptor V1, it can +be given a new package name. There are two files that are shared, +rapper(1) and rapper.1 the manual page. +For packaging systems that split the files (libraries, headers, docs, +debug files) into multiple packages, these should be in a package of +their own that replace and conflict with the earlier files. (This is +what I have done with the debian packages). For packaging systems +that do not use multiple packages, you will have to either leave +these files out of the V2 package or migrate them from the V1 package +to the V2 package using dependencies to ensure there are no +conflicts. The advantage of the V2 versions is that it means +the useful command-line utility uses the latest Raptor code.

+ +

+ + + -- cgit v1.2.1