Dar Documentation


Compatible API 4.4.x within libdar 5.0.x




The reasons for a new API


Libdar API (version 5.0.0) released with dar 2.4.0 provides a very different API compared to older releases. The main  reason for this major redesign of the API is that in the past, each new feature added in libdar broke the backward compatibility of the API, mainly because a new argument had to be added to a particular method of class archive.

The new API makes use of new "option" classes that all have a constructor without argument. Objects of theses classes carry all the current and future arguments used to manage dar archive through libdar API. This way, if a new option has to be added in the future, no change will be necessary to program that use the libdar API though an API version 5.x.x. The class option's constructor will set this new parameter to its default value, and a new method for that class will be added to manage this new parameter's value, available for programs that are aware of it.

Any program can then, at will, take into consideration the new options or simply ignore them (and use default values for them), while new features keep getting added to libdar release after release.

The old API is kept available beside the new one

But to ease the transition to this new API, beside the libdar namespace that contained in 2.3.x and older releases all the symbols for the API, and which now contain the symbols for the API 5.0.x can be found the libdar_4_4 namespace. As you guess it provides the API 4.4.x to libdar, which is the one used from release 2.3.5. However some small changes have still to be made for your program to compile and work with new libdar using the old API. This is the object of this document to describe them. This backward compatible API will probably disappear at next major release (which will probably be version 2.5.0. In the meanwhile, the API should still be available under versions 5.x.x and thus stay compatible with current new API).

Change to make to use the old API

  1. The first point is to no more include "libdar.hpp" but "libdar_4_4.hpp" instead. This file contains the libdar_4_4 namespace symbols.
  2. The second point, of course is to no more use the libdar namespace but instead the libdar_4_4 namespace.
The following table shows two code examples. On the left is placed the original code, while on the right is placed the modified code with changes in bold characters for the program to be used with old API of new libdar library.

Old program using Old libdar
 Old program using libdar 5.0.x
#include "libdar.hpp"

using namespace libdar;

int example()
{
   archive *arch = new archive(....);
   [...]
}
 #include "libdar_4_4.hpp"

using namespace libdar_4_4;

int example()
{
   archive *arch = new archive(....);
   [...]
}
#include "libdar.hpp"

int example()
{
   libdar::archive *arch = new libdar::archive(....);
   [...]
}		 #include "libdar_4_4.hpp"

int example()
{
   libdar_4_4::archive *arch = new libdar_4_4::archive(....);
   [...]
}

Compilation and linking stay unchanged, thus running sed on your code using the following script-like code should do the trick:


for file in *.c *.h *.cpp *.hpp ; do
    mv "$file" "$file.bak"
    sed -r -e 's/libdar::/libdar_4_4::/g' -e 's/using namespace libdar/using namespace libdar_4_4/' -e 's|#include <dar/libdar.hpp>|#include <dar/libdar_4_4.hpp>|' "$file.bak" > "$file"
done

Want to try the new API instead ?

If you want to go one step further and instead of using the backward compatible API, directly use the new libdar API, the first step is to read the API Tutorial. Then, if more detailed information is required, check the API documentation. Finaly you can subscribe to libdar-api mailing-list for any problem, questions or suggestions about the API.