------------------------------------------------------------------------------
                              libburnia-project.org
------------------------------------------------------------------------------
This all is under GPL.
(See GPL reference, our clarification and commitment at the end of this text)
------------------------------------------------------------------------------
libburn-project.org
By Mario Danic <mario.danic@gmail.com> and Thomas Schmitt <scdbackup@gmx.net>
Copyright (C) 2006-2011 Mario Danic, Thomas Schmitt
Still containing parts of Libburn. By Derek Foreman <derek@signalmarketing.com>
and Ben Jansens <xor@orodu.net>
Copyright (C) 2002-2006  Derek Foreman and Ben Jansens

     http://files.libburnia-project.org/releases/libburn-1.1.6.tar.gz

------------------------------------------------------------------------------

                           Build and Installation

                                From tarball

Obtain libburn-1.1.6.tar.gz, take it to a directory of your choice and do:

   tar xzf libburn-1.1.6.tar.gz
   cd libburn-1.1.6
   ./configure --prefix=/usr
   make

To make libburn accessible for running resp. application development,
and to install the cdrecord compatibility binary cdrskin, do
(as Superuser):

   make install

This procedure installs libburn.so.4 and cdrskin depending on it.
For a standalone cdrskin binary, see cdrskin/README.

A behavioral conflict is known between any burn software and demons like hald
which probe CD drives. This can spoil burn runs for CD-R or CD-RW.
You may have to keep your hald away from the drive. See for example
   http://www.freebsd.org/gnome/docs/halfaq.html


                                  From SVN

Our build system is based on autotools. For preparing the build of a SVN 
snapshot you will need autotools of at least version 1.7. 
Do in a directory of your choice:

   svn co http://svn.libburnia-project.org/libburn/trunk libburn-svn
   cd libburn-svn
   ./bootstrap
   ./configure --prefix=/usr
   make
   make install

Warning: The trunk might contain experimental features which might not
         persist until next release. 


                        Special ./configure options

make install on GNU/Linux will try to run program ldconfig with the library
installation directory as only argument. Failure to do so will not abort
installation. One may disable ldconfig by ./configure option:
   --disable-ldconfig-at-install

In some situations Linux may deliver a better write performance to drives if
the track input is read with O_DIRECT (see man 2 open). The API call
burn_os_open_track_src() and the input readers of cdrskin and libburn fifo
can be told to use this peculiar read mode by:
   --enable-track-src-odirect

But often libburn call burn_write_opts_set_dvd_obs(opts, 64*1024) will yield
even better performance in such a situation. 64k can be made default at
configure time by:
    --enable-dvd-obs-64k
This may be combined with above --enable-track-src-odirect .

Alternatively the transport of SCSI commands can be done via libcdio-0.83.
You may install it and re-run libburn's ./configure with option
    --enable-libcdio

By use of a version script, the libburn.so library exposes no other function
names but those of the API definition in libburn/libburn.h.
If -Wl,--version-script=... makes problems with the local compiler, then
disable this encapsulation feature by
    --disable-versioned-libs

Make sure to re-compile all source files after running ./configure
   make clean ; make
   make install


Linux only:

libburn tries to avoid a collision with udev's drive examination by waiting
0.1 seconds before opening the device file for a longer time, after udev
might have been alarmed by drive scanning activities.
The waiting time can be set at ./configure time with microsecond granularity.
E.g. 2 seconds:
  CFLAGS="$CFLAGS -DLibburn_udev_wait_useC=2000000"
  ./configure ...options...
Waiting can be disabled by zero waiting time:
  CFLAGS="$CFLAGS -DLibburn_udev_wait_useC=0"
Alternatively, libburn can try to be nice by opening the device file,
closing it immediately, waiting, and only then opening it for real:
  CFLAGS="$CFLAGS -DLibburn_udev_extra_open_cyclE -DLibburn_udev_wait_useC=500000"

------------------------------------------------------------------------------

An important part of the project, libisofs, is hosted in a bzr repository at
launchpad.net :
   bzr branch lp:libisofs

Another part the project, libisoburn, is hosted in the libburnia SVN, too:
   svn co http://svn.libburnia-project.org/libisoburn/trunk libisoburn

See README files there.

------------------------------------------------------------------------------


                        Overview of libburnia-project.org

libburnia-project.org is an open-source software project for reading, mastering
and writing optical discs.
For now this means CD media, all DVD media, all BD media.

The project comprises of several more or less interdependent parts which
together strive to be a usable foundation for application development.
These are libraries, language bindings, and middleware binaries which emulate
classical (and valuable) Linux tools.
Currently it is supported on GNU/Linux with kernels >= 2.4,
on FreeBSD with ATAPI/CAM enabled in the kernel (see man atapicam),
and on OpenSolaris (tested with kernel 5.11).
On other X/Open compliant systems there will only be pseudo drives, but no
direct MMC operation on real CD/DVD/BD drives.

For full ports to other systems we would need : login on a development machine
resp. a live OS on CD or DVD, advise from a system person about the equivalent
of Linux sg or FreeBSD CAM, volunteers for testing of realistic use cases.

We have a well tested code base for burning data and audio CDs, DVDs and BDs.
The burn API is quite comprehensively documented and can be used to build a
presentable application.
We have a functional application which emulates the core use cases of cdrecord
in order to prove that usability, and in order to allow you to explore
libburn's scope by help of existing cdrecord frontends.

ISO 9660 filesystems with Rock Ridge and Joliet extensions can be created
and manipulated quite freely. This capability together with our burn capability
makes possible a single binary application which covers all steps of image
composition, updating and writing. Quite unique in the Linux world.

The project components (list subject to growth, hopefully):

- libburn  is the library by which preformatted data get onto optical media.
           It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or
           /dev/srM or /dev/hdX (e.g. on kernel 2.6).
           libburn is the foundation of our cdrecord emulation. Its code is
           independent of cdrecord. Its DVD capabilities are learned from
           studying the code of dvd+rw-tools and MMC-5 specs. No code but only
           the pure SCSI knowledge has been taken from dvd+rw-tools, though.

- libisofs is the library to pack up hard disk files and directories into a
           ISO 9660 disk image. This may then be brought to CD via libburn.
           An own ISO 9660 extension stores ACLs, xattr, and MD5 of file
           content.

- libisoburn is an add-on to libburn and libisofs which coordinates both and
           also allows to grow ISO-9660 filesystem images on multi-session
           media as well as on overwriteable media via the same API.
           All media peculiarities are handled automatically.
           It also contains the methods of command oriented application
           xorriso and offers them via a C language API.

- cdrskin  is a limited cdrecord compatibility wrapper for libburn.
           cdrecord is a powerful GPL'ed burn program included in Joerg
           Schilling's cdrtools. cdrskin strives to be a second source for
           the services traditionally provided by cdrecord. Additionally it
           provides libburn's DVD capabilities, where only -sao is compatible
           with cdrecord.
           cdrskin does not contain any bytes copied from cdrecord's sources.
           Many bytes have been copied from the message output of cdrecord
           runs, though.
           See cdrskin/README for more.

- xorriso  is an application of all three libraries which creates, loads,
           manipulates and writes ISO 9660 filesystem images with
           Rock Ridge extensions. Manipulation is not only adding or
           overwriting of files but also deleting, renaming, attribute
           changing, incremental backups, activating boot images, and
           extracting of files from ISO images to disk. There is also a
           sparse emulation of cdrecord and a more laborate one of mkisofs.
           All features of xorriso are also available via a C language API
           of libisoburn.
           A static compilation of xorriso and the libraries is dedicated
           to the GNU Operating System. See xorriso/README_gnu_xorriso .

- "test"   is a collection of application gestures and examples given by the
           authors of the library features. The burn API example of libburn
           is named test/libburner.c . The API for media information inquiry is
           demonstrated in test/telltoc.c .
           Explore these examples if you look for inspiration.

We strive to be a responsive upstream.

Our libraries are committed to maintain older feature sets in newer versions.
This applies to source code headers (API) as well as to linkable objects (ABI).
The only exception from this rule is about non-release versions x.y.*[13579]
which are allowed to introduce new features, change those new features in
any way and even may revoke such new features before the next release of
x.y.*[02468]. As soon as it is released, a feature is promised to persist.

SONAMES:
libburn.so.4    (since 0.3.4, March    2007),
libisofs.so.6   (since 0.6.2, February 2008),
libisoburn.so.1 (since 0.1.0, February 2008).

Applications must use 64 bit off_t. E.g. by defining
#define _LARGEFILE_SOURCE
#define _FILE_OFFSET_BITS 64
or take special precautions to interface with the libraries by 64 bit integers
where the .h files prescribe off_t. To reduce libburn's off_t size to 32 bit
will keep it from processing tracks of more than 2 GB size.


------------------------------------------------------------------------------
Project history as far as known to me:

- Founded in 2002 as it seems. See mailing list archives
     http://lists.freedesktop.org/archives/libburn/
  The site of this founder team is reachable and offers download of a
  (somewhat outdated) tarball and from CVS :
     http://icculus.org/burn/
  Copyright holders and most probably founders:
  Derek Foreman and Ben Jansens.

- I came to using libburn in 2005. Founded the cdrskin project and submitted
  necessary patches which were accepted or implemented better. Except o                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         