README

   1
   2 ***** WARNING *****
   3
   4 Liboil is now in maintenence-only mode.  No new features will
   5 be added, and bugs will be fixed according to their severity and
   6 availablility of patches.
   7
   8 Users of liboil are recommended to switch to Orc
   9 (http://code.entropywave.com/projects/orc/).  Please contact
  10 David Schleef <ds@schleef.org> about converting liboil functions
  11 to Orc code -- in many cases this work has already been done.
  12
  13 ***** WARNING *****
  14
  15
  16 Requirements
  17 ============
  18
  19 Liboil has no required dependecies (other than a decent C compiler
  20 and standard C library).  A few extra tests and examples are enabled
  21 if you have glib-2.0 installed, but these extras are neither required
  22 nor installed.
  23
  24 Using GCC is strongly recommended, since the most interesting bits
  25 of liboil are written in GCC-style inline assembly.  GCC versions
  26 prior to 3.4 are not supported.
  27
  28
  29 Problems Compiling?
  30 ===================
  31
  32 Function implementations in liboil are designed to be modular, so
  33 if your compiler is having difficulty compiling a particular function,
  34 simply disable it and the corresponding OIL_DEFINE_IMPL() line.
  35
  36
  37 ABI warning
  38 ===========
  39
  40 Only a portion of the liboil API is ABI stable.  This portion is
  41 guaranteed to be stable through the 0.3.x series, and by using
  42 a compatibility library, through the 0.4.x series as well.  This
  43 policy is designed to provide almost all applications the necessary
  44 ABI stability for the symbols likely to be used in liboil.
  45
  46 Any symbols declared by including <liboil/liboil.h> follow this
  47 ABI policy.  This includes all liboil function classes as well
  48 as a limited number of core functions, such as oil_init().
  49
  50 Functions defined in other header files should not be used.
  51
  52
  53 ABI Implementation
  54 ==================
  55
  56 The liboil-0.3.x series create the shared library liboil-0.3.so.
  57 Applications that use liboil are linked against this library, and
  58 will load liboil-0.3.so at runtime.
  59
  60 The liboil-0.4.x series will create two shared libraries,
  61 liboil-0.4.so and a compaitiblity library liboil-0.3.so that
  62 implements functionality removed in the 0.3->0.4 transition.
  63 The 0.3 shared library will be binary compatible with the
  64 liboil-0.3.x releases.  Thus, applictions compiled with a
  65 liboil-0.3.x release will continue to function after the shared
  66 library is upgraded to a 0.4.x release.  Applications compiled
  67 with 0.4.x will use liboil-0.4.so directly.
  68
  69 Distributions can use this compatibility library in order to
  70 smooth transitions between liboil major releases.  For example,
  71 consider the case where AppA depends on libB and libC, and both
  72 libraries use liboil.  When liboil-0.4 is released, the distro
  73 can start using it immediately, and AppA will continue to work
  74 correctly.  Then, at a convenient time, libB and libC can
  75 independently be recompiled using liboil-0.4.x, and the packages
  76 will no longer depend on liboil-0.3.so.
  77
  78 The traditional way of dealing with these changes is to migrate
  79 all packages to the new library as quickly as possible.  This is
  80 unduly cumbersome.
  81
  82
  83