diff options
Diffstat (limited to '')
| -rw-r--r-- | UPGRADING.html | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/UPGRADING.html b/UPGRADING.html new file mode 100644 index 0000000..98f187f --- /dev/null +++ b/UPGRADING.html @@ -0,0 +1,159 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="https://www.w3.org/1999/xhtml"> +<head> + <title>Raptor RDF Syntax Library - Upgrading to the Raptor V2 API</title> +</head> +<body> + + <h1>Raptor RDF Syntax Library - Upgrading to the Raptor V2 API</h1> + +<p>Raptor V2 is a major new version of the Raptor V1 API with many +cleanups and changes that include adding, removing and re-ordering +parameters, adding and removing return types as well as renaming the +functions. +</p> + +<p>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 libraries, the symbols will clash and the +program will fail in mysterious ways if it runs at all. There are +only two installed files that overlap - the <code>rapper</code> +utility and it's manual page. +</p> + + +<h2>Configuration and compiling changes</h2> + +<p>Raptor V2 uses <code>pkg-config(1)</code> to provide the compile +and link parameters whereas Raptor V1 supports that as well as a +script <code>raptor-config</code>. The recommended linking approach +is now as follows: +</p> +<pre> + cc -o prog prog.c `pkg-config raptor2 --cflags` `pkg-config raptor2 --libs` +</pre> +<p>Shown here as a compile in link all in one line but you typically +split that into two stages. +</p> +<pre> + cc -c `pkg-config raptor2 --cflags` raptor-module.c + ... + cc -o prog raptor-module.c ... other modules ... `pkg-config raptor2 --libs` +</pre> + + +<h2>Code changes</h2> + +<p>There are significant API changes, which are described in the +<a href="RELEASE.html">Release Notes</a> in long summary form with +some background to why, in the <a href="ChangeLog">ChangeLog</a> in +very long form. The reference manual contains +<a href="https://librdf.org/raptor/api/raptor-changes.html">a section</a> +describing what was added, deleted, renamed and otherwise changed for +both the functions exported from the library, as well as the +typedefs and enum values. +</p> + +<p>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. This cannot be automated in some +places such as when the fields of the raptor_statement object were +replaced with raptor_term pointers. The script is used like +<code>perl docs/upgrade-script.pl</code> <em>source files</em> for example</p> +<pre> + $ perl docs/upgrade-script.pl prog.c +</pre> + +<p>and then edit the file prog.c and search for <code>WARNING:</code> +for any places that manual editing is needed. +</p> + + +<h2>Handling Raptor V1 or Raptor V2 in the same code</h2> + +<p>If you need to handle both APIs in the same codebase as +alternatives, it is recommended that you use the following approach. +</p> + +<p> +Create an application <code>#define</code> that records the choice of +which API you want to use. You can do this triggered on whichever +<code>raptor.h</code> is in the include path by <code>#ifdef +RAPTOR_V2_AVAILABLE</code> but that may be dangerous if both +libraries and headers are present. A better choice is an application +specific define that is determined by a configuration step. +</p> + +<p>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: +</p> + +<pre> +#ifdef APP_WANTS_RAPTOR_V2 +/* nop */ + +#else +#define raptor_v2_function(arg1, arg2, arg3) raptor_v1_function(arg2, arg3) + +#endif +</pre> + +<p>Where the code cannot be done by simple expansion such as use of +<code>raptor_init()</code> and <code>raptor_finish()</code> in V1 +that are replaced by the functions around the world object in V2, use +an <code>#ifdef</code> that provides the two code paths. +</p> + +<p><a href="https://librdf.org/rasqal/">rasqal</a> +in GIT (will be 0.9.20) uses this approach. +</p> + +<p>Another approach if the Raptor V1 code is in a separate module / +source file is to copy it and make a V2 version and then choose the +file to use at configure or build time. +</p> + +<p><a href="https://librdf.org/">librdf</a> 1.0.11 uses this approach. +</p> + +<p>Either way, basing the interface on the V2 APIs makes it clear +what to remove when V1 is no longer supported. +</p> + + +<h2>Packaging recommendations for distributors</h2> + +<p>Since Raptor V2 probably needs to be installed in parallel with V1 +for some time, at least for the different libraries and headers, both +need to be packaged such that no files clash. +</p> + +<p>There are, however, two files that are shared after a 'make install': +<code>rapper(1)</code> and <code>rapper.1</code> the manual page. +</p> + +<p>For packaging systems that split the installation into multiple +packages (libraries, headers, docs, debug files), these two files +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 raptor-utils and raptor2-utils). 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. +</p> + +<p>The advantage of making the V2 version of rapper is that it means +the command-line utility under the well known name uses the latest +Raptor code. +</p> + +<hr /> + +<p>Copyright 2010-2023 <a href="https://www.dajobe.org/">Dave Beckett</a></p> + +</body> +</html> |