libburn-0.4.0/doc/comments

Go to the documentation of this file.
00001 /**
00002    @author Mario Danic, Thomas Schmitt
00003 
00004    @mainpage Libburnia Documentation Index
00005 
00006    @section intro Introduction
00007 
00008 Libburnia is an open-source project for reading, mastering and writing
00009 optical discs.
00010 For now this means CD-R, CD-RW, DVD-RAM, DVD+RW, DVD+R, DVD-RW, DVD-R.
00011 
00012 Not supported yet are dual layer media, HD-DVD, BD (blue ray). Testers for
00013 dual layer DVD+/-R are wanted, though.
00014 
00015 The project comprises of several more or less interdependent parts which
00016 together strive to be a usable foundation for application development.
00017 These are libraries, language bindings, and middleware binaries which emulate
00018 classical (and valuable) Linux tools.
00019 
00020 Our scope is currently Linux 2.4 and 2.6 only. For ports to other systems
00021 we would need : login on a development machine resp. a live OS on CD or DVD,
00022 advise from a system person about the equivalent of Linux sg or FreeBSD CAM,
00023 volunteers for testing of realistic use cases.
00024 
00025 We have a workable code base for burning data and audio CDs and many DVD types.
00026 The burn API is quite comprehensively documented and can be used to build a
00027 presentable application.
00028 We have a functional binary which emulates the core use cases of cdrecord in
00029 order to prove that usability, and in order to allow you to explore libburn's
00030 scope by help of existing cdrecord frontends.
00031 
00032 @subsection components The project components (list subject to growth, hopefully):
00033 
00034 - libburn  is the library by which preformatted data get onto optical media.
00035            It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or
00036            /dev/srM or /dev/hdX (e.g. on kernel 2.6).
00037            libburn is the foundation of our cdrecord emulation. Its code is
00038            independent of cdrecord. Its DVD capabilities are learned from
00039            studying the code of dvd+rw-tools and MMC-5 specs. No code but only
00040            the pure SCSI knowledge has been taken from dvd+rw-tools, though.
00041 
00042 - libisofs is the library to pack up hard disk files and directories into a
00043            ISO 9660 disk image. This may then be brought to CD via libburn.
00044            libisofs is to be the foundation of our upcoming mkisofs emulation.
00045 
00046 - libisoburn is an add-on to libburn and libisofs which allows to grow
00047            ISO-9660 filesystem images on multi-session media as well as
00048            on overwriteable media via the same API. All media peculiarities
00049            are handled automatically.
00050 
00051 - cdrskin  is a limited cdrecord compatibility wrapper for libburn.
00052            cdrecord is a powerful GPL'ed burn program included in Joerg
00053            Schilling's cdrtools. cdrskin strives to be a second source for
00054            the services traditionally provided by cdrecord. Additionally it
00055            provides libburn's DVD capabilities, where only -sao is compatible
00056            with cdrecord.
00057            cdrskin does not contain any bytes copied from cdrecord's sources.
00058            Many bytes have been copied from the message output of cdrecord
00059            runs, though.
00060            See cdrskin/README for more.
00061 
00062 - xorriso  is an upcomming application of all three libraries which creates,
00063            loads, manipulates and writes ISO 9660 filesystem images with
00064            Rock Ridge extensions. Manipulation will not only be adding or
00065            overwriting of files but also deletion, renaming, and attribute
00066            changing.
00067            See SVN of libisoburn, man test/xorriso.1, test/compile_xorriso.sh
00068 
00069 - "test"   is a collection of application gestures and examples given by the
00070            authors of the library features. The burn API example of libburn
00071            is named test/libburner.c . The API for media information inquiry is
00072            demonstrated in test/telltoc.c .
00073            Explore these examples if you look for inspiration.
00074 
00075 We plan to be a responsive upstream. Bear with us.
00076 
00077 
00078    @section using Using the libraries
00079 
00080 Our build system is based on autotools.
00081 User experience tells us that you will need at least autotools version 1.7.
00082 
00083 To build libburn and its subprojects it should be sufficient to go into
00084 its toplevel directory and execute
00085 
00086 -  ./bootstrap  (needed if you downloaded from SVN)
00087 
00088 -  ./configure
00089 
00090 -  make
00091 
00092 To make the libraries accessible for running resp. developing applications 
00093 
00094 -  make install
00095 
00096 Both libraries are written in C language and get built by autotools.
00097 Thus we expect them to be useable by a wide range of Linux-implemented
00098 languages and development tools.
00099 
00100 
00101 @section libburner Libburner
00102 
00103 libburner is a minimal demo application for the library libburn 
00104 (see: libburn/libburn.h) as provided on  http://libburnia-project.org .
00105 It can list the available devices, can blank a CD-RW or DVD-RW and
00106 can burn to recordable CD and recordable single layer DVD.
00107 
00108 It's main purpose, nevertheless, is to show you how to use libburn and also
00109 to serve the libburnia team as reference application. libburner does indeed
00110 define the standard way how above three gestures can be implemented and
00111 stay upward compatible for a good while.
00112 
00113    @subsection libburner-help Libburner --help
00114 <pre>
00115 Usage: test/libburner
00116        [--drive <address>|<driveno>|"-"]  [--audio]
00117        [--blank_fast|--blank_full|--format_overwrite]
00118        [--try_to_simulate]
00119        [--multi]  [<one or more imagefiles>|"-"]
00120 Examples
00121 A bus scan (needs rw-permissions to see a drive):
00122   test/libburner --drive -
00123 Burn a file to drive chosen by number, leave appendable:
00124   test/libburner --drive 0 --multi my_image_file
00125 Burn a file to drive chosen by persistent address, close:
00126   test/libburner --drive /dev/hdc my_image_file
00127 Blank a used CD-RW (is combinable with burning in one run):
00128   test/libburner --drive /dev/hdc --blank_fast
00129 Blank a used DVD-RW (is combinable with burning in one run):
00130   test/libburner --drive /dev/hdc --blank_full
00131 Format a DVD-RW to avoid need for blanking before re-use:
00132   test/libburner --drive /dev/hdc --format_overwrite
00133 Burn two audio tracks (to CD only):
00134   lame --decode -t /path/to/track1.mp3 track1.cd
00135   test/dewav /path/to/track2.wav -o track2.cd
00136   test/libburner --drive /dev/hdc --audio track1.cd track2.cd
00137 Burn a compressed afio archive on-the-fly:
00138   ( cd my_directory ; find . -print | afio -oZ - ) | \
00139   test/libburner --drive /dev/hdc -
00140 To be read from *not mounted* media via: afio -tvZ /dev/hdc
00141 </pre>
00142 libburner has two companions, telltoc and dewav, which help to perform some
00143 peripheral tasks of burning.
00144 
00145 telltoc prints a table of content (sessions, tracks and leadouts), it tells
00146 about type and state of media, and also is able to provide the necessary
00147 multi-session information for program mkisofs option -C. Especially helpful
00148 are its predictions with "Write multi" and "Write modes" where availability
00149 of "TAO" indicates that tracks of unpredicted length can be written.
00150 See: test/telltoc --help.
00151 
00152 dewav extracts raw byte-swapped audio data from files of format .wav (MS WAVE)
00153 or .au (SUN Audio). See example in libburner --help.
00154 
00155    @subsection libburner-source Sourceode of libburner
00156 
00157 Click on blue names of functions, structures, variables, etc in oder to
00158 get to the according specs of libburn API or libburner sourcecode.
00159  
00160 @include libburner.c
00161 */

Generated on Thu Feb 14 16:50:29 2008 for libburn by  doxygen 1.5.4