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 futur 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 change manage this new parameter's value, available for programs that are aware of it.

Any program can then, at will, take into consideration new options or simply ignore them (and use defaut values for them), while new feature keep getting added dar release after dar 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 disapear at next major release (which will probably be version 2.5.0, while at that time the API should still be under version 5.x.x and thus stay compatible with current new API, if all work as expected).

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


foreach f ( *.c *.h *.cpp *.hpp )
{
    mv "$f" "$f.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>|' "$f.bak" > "$f"
}

Want to try the new 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.