Made doc test portal the official doc portal
This commit is contained in:
parent
4ecc0a8777
commit
78b74fc47a
143
doc/comments
143
doc/comments
@ -27,16 +27,16 @@ by help of existing cdrecord frontends.
|
|||||||
|
|
||||||
@subsection components The project components (list subject to growth, hopefully):
|
@subsection components The project components (list subject to growth, hopefully):
|
||||||
|
|
||||||
- libburn the library by which preformatted data get onto optical media.
|
- 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
|
It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or
|
||||||
/dev/hdX (e.g. on kernel 2.6).
|
/dev/hdX (e.g. on kernel 2.6).
|
||||||
libburn is the foundation of our cdrecord emulation.
|
libburn is the foundation of our cdrecord emulation.
|
||||||
|
|
||||||
- libisofs the library to pack up hard disk files and directories into a
|
- 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.
|
ISO 9660 disk image. This may then be brought to CD via libburn.
|
||||||
libisofs is to be the foundation of our upcoming mkisofs emulation.
|
libisofs is to be the foundation of our upcoming mkisofs emulation.
|
||||||
|
|
||||||
- cdrskin a limited cdrecord compatibility wrapper for libburn.
|
- cdrskin is a limited cdrecord compatibility wrapper for libburn.
|
||||||
cdrecord is a powerful GPL'ed burn program included in Joerg
|
cdrecord is a powerful GPL'ed burn program included in Joerg
|
||||||
Schilling's cdrtools. cdrskin strives to be a second source for
|
Schilling's cdrtools. cdrskin strives to be a second source for
|
||||||
the services traditionally provided by cdrecord.
|
the services traditionally provided by cdrecord.
|
||||||
@ -46,105 +46,76 @@ by help of existing cdrecord frontends.
|
|||||||
See cdrskin/README for more.
|
See cdrskin/README for more.
|
||||||
|
|
||||||
- "test" is a collection of application gestures and examples given by the
|
- "test" is a collection of application gestures and examples given by the
|
||||||
authors of the library features. cdrskin for example originally
|
authors of the library features. The main API example of libburn
|
||||||
emerged from test/burniso.c and you can see traces of my first
|
is named test/libburner.c .
|
||||||
steps in there. Explore these examples if you look for inspiration.
|
Explore these examples if you look for inspiration.
|
||||||
|
|
||||||
We plan to be a responsive upstream. Bear with us. Our build system is based on autotools.
|
We plan to be a responsive upstream. Bear with us.
|
||||||
|
|
||||||
|
|
||||||
|
@section using Using the libraries
|
||||||
|
|
||||||
|
Our build system is based on autotools.
|
||||||
User experience tells us that you will need at least autotools version 1.7.
|
User experience tells us that you will need at least autotools version 1.7.
|
||||||
|
|
||||||
To build libburn and its subprojects it should be sufficient to go into
|
To build libburn and its subprojects it should be sufficient to go into
|
||||||
its toplevel directory and execute
|
its toplevel directory and execute
|
||||||
./bootstrap (needed if you downloaded from SVN and not a release tarball)
|
|
||||||
./configure
|
- ./bootstrap (needed if you downloaded from SVN)
|
||||||
make
|
|
||||||
|
- ./configure
|
||||||
|
|
||||||
|
- make
|
||||||
|
|
||||||
To make the libraries accessible for running resp. developing applications
|
To make the libraries accessible for running resp. developing applications
|
||||||
make install
|
|
||||||
|
|
||||||
@section using Using the libraries
|
- make install
|
||||||
|
|
||||||
Both libraries are written in C language and get built by autotools.
|
Both libraries are written in C language and get built by autotools.
|
||||||
Thus we expect them to be useable by a wide range of Linux-implemented
|
Thus we expect them to be useable by a wide range of Linux-implemented
|
||||||
languages and development tools.
|
languages and development tools.
|
||||||
|
|
||||||
We are still practicing.
|
|
||||||
|
|
||||||
For the libburn library there is a reference and demo application
|
@section libburner Libburner
|
||||||
test/libburner
|
|
||||||
|
|
||||||
@subsection concepts Libburn library concepts
|
libburner is a minimal demo application for the library libburn
|
||||||
|
(see: libburn/libburn.h) as provided on http://libburn.pykix.org .
|
||||||
|
It can list the available devices, can blank a CD-RW and
|
||||||
|
can burn to CD-R or CD-RW.
|
||||||
|
|
||||||
There are a few concepts to introduce in order for you to understand how to
|
It's main purpose, nevertheless, is to show you how to use libburn and also
|
||||||
use Libburn. So, lets start with them:
|
to serve the libburn team as reference application. libburner does indeed
|
||||||
|
define the standard way how above three gestures can be implemented and
|
||||||
<ol>
|
stay upward compatible for a good while.
|
||||||
<li> Read - The process of reading the data on a disc for storage or
|
|
||||||
copying.
|
|
||||||
<li> Write - The process of writing data onto a disc to create a new
|
|
||||||
disc image or append to an existing one.
|
|
||||||
<li> Drive - A Drive is a hardware device used to reading and/or writing
|
|
||||||
discs. CD burners and CD-ROMs are examples of Drives.
|
|
||||||
</ol>
|
|
||||||
|
|
||||||
@subsection working Working with the library
|
|
||||||
|
|
||||||
Now that you understand the above @ref concepts, you're ready to look at the
|
|
||||||
actual use of the library.
|
|
||||||
|
|
||||||
In general, using the library to perform a process consists of the following
|
|
||||||
steps:
|
|
||||||
|
|
||||||
<ol>
|
|
||||||
<li> Initialize the library.
|
|
||||||
<li> Depends on wether you know the persisten drive address in advance
|
|
||||||
If yes:
|
|
||||||
2a. Aquire this drive alone and directly by function
|
|
||||||
burn_drive_scan_and_grab() and be done until step 5
|
|
||||||
If no address known yet:
|
|
||||||
2b. Scan for available Drives..
|
|
||||||
<li>b Choose a Drive for reading/writing and inquire its persistent address.
|
|
||||||
<li>b Shut down library, re-initialize it and like in step 2a aquire the
|
|
||||||
chosen drive by function burn_drive_scan_and_grab()
|
|
||||||
<li> Fill in the options for the operation.
|
|
||||||
<li> Wait for the operation to complete, displaying status along the wayi
|
|
||||||
if desired.
|
|
||||||
<li> Release the Drive.
|
|
||||||
<li> Destroy the library instance. (If you're done working with the library.)
|
|
||||||
</ol>
|
|
||||||
|
|
||||||
@section libburner Libburner
|
|
||||||
|
|
||||||
libburner is a minimal demo application for the library libburn (see: libburn.h)
|
|
||||||
as provided on http://libburn.pykix.org . It can list the available devices, can
|
|
||||||
blank a CD-RW and can burn to CD-R or CD-RW.
|
|
||||||
It's main purpose, nevertheless, is to show you how to use libburn and also
|
|
||||||
to serve the libburn team as reference application. libburner.c does indeed
|
|
||||||
define the standard way how above three gestures can be implemented and
|
|
||||||
stay upward compatible for a good while.
|
|
||||||
|
|
||||||
@subsection libburner-help Libburner --help
|
@subsection libburner-help Libburner --help
|
||||||
|
<pre>
|
||||||
|
Usage: test/libburner
|
||||||
|
[--drive <address>|<driveno>|"-"]
|
||||||
|
[--verbose <level>] [--blank_fast|--blank_full]
|
||||||
|
[--burn_for_real|--try_to_simulate] [--stdin_size <bytes>]
|
||||||
|
[<imagefile>|"-"]
|
||||||
|
Examples
|
||||||
|
A bus scan (needs rw-permissions to see a drive):
|
||||||
|
test/libburner --drive -
|
||||||
|
Burn a file to drive chosen by number:
|
||||||
|
test/libburner --drive 0 --burn_for_real my_image_file
|
||||||
|
Burn a file to drive chosen by persistent address:
|
||||||
|
test/libburner --drive /dev/hdc --burn_for_real my_image_file
|
||||||
|
Blank a used CD-RW (is combinable with burning in one run):
|
||||||
|
test/libburner --drive 0 --blank_fast
|
||||||
|
Burn a compressed afio archive on-the-fly, pad up to 700 MB:
|
||||||
|
( cd my_directory ; find . -print | afio -oZ - ) | \
|
||||||
|
test/libburner --drive /dev/hdc --burn_for_real --stdin_size 734003200 -
|
||||||
|
To be read from *not mounted* CD via:
|
||||||
|
afio -tvZ /dev/hdc
|
||||||
|
Program tar would need a clean EOF which our padded CD cannot deliver.
|
||||||
|
</pre>
|
||||||
|
|
||||||
Usage: test/libburner
|
@subsection libburner-source Sourceode of libburner
|
||||||
|
|
||||||
[--drive <address>|<driveno>|"-"]
|
|
||||||
|
|
||||||
[--verbose <level>] [--blank_fast|--blank_full]
|
Click on blue names of functions, structures, variables, etc in oder to
|
||||||
|
get to the according specs of libburn API or libburner sourcecode.
|
||||||
|
|
||||||
[--burn_for_real|--try_to_simulate] [--stdin_size <bytes>]
|
@include libburner.c
|
||||||
|
|
||||||
[<imagefile>|"-"]
|
|
||||||
|
|
||||||
Examples
|
|
||||||
|
|
||||||
<ol>
|
|
||||||
<li> A bus scan (needs rw-permissions to see a drive): test/libburner --drive -
|
|
||||||
<li> Burn a file to drive chosen by number: test/libburner --drive 0 --burn_for_real my_image_file
|
|
||||||
<li> Burn a file to drive chosen by persistent address: test/libburner --drive /dev/hdc --burn_for_real my_image_file
|
|
||||||
<li> Blank a used CD-RW (is combinable with burning in one run): test/libburner --drive 0 --blank_fast
|
|
||||||
<li> Burn a compressed afio archive on-the-fly, pad up to 700 MB: ( cd my_directory ; find . -print | afio -oZ - ) | \
|
|
||||||
test/libburner --drive /dev/hdc --burn_for_real --stdin_size 734003200 -
|
|
||||||
<li>To be read from *not mounted* CD via: afio -tvZ /dev/hdc
|
|
||||||
Program tar would need a clean EOF which our padded CD cannot deliver.
|
|
||||||
</ol>
|
|
||||||
*/
|
*/
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user