Annotation of /libgig/trunk/README

Home
====
  You can always find the latest version of libgig at:
  http://stud.hs-heilbronn.de/~cschoene/projects/libgig/

Content
=======
  libgig actually consists of three parts:

  - RIFF classes (RIFF.h, RIFF.cpp): Provides convenient methods to parse and
                                     access arbitrary RIFF files.
  - DLS classes (DLS.h, DLS.cpp):    They're using the RIFF classes to parse
                                     DLS (Downloadable Sounds) Level 1 and 2
                                     files and provide abstract access to the
                                     data.
  - gig classes (gig.h, gig.cpp):    These are based on the DLS classes and
                                     provide the necessary extensions for
                                     the Gigasampler file format.

  Beside the actual library there are four example applications:

    gigdump:     Demo app that prints out the content of a .gig file.
    gigextract:  Extracts samples from a .gig file.
    dlsdump:     Demo app that prints out the content of a DLS file.
    rifftree:    Tool that prints out the RIFF tree of an arbitrary RIFF
                 file.

  Since version 3.0.0 libgig also provides write support, that is for
  creating modifying .gig, DLS and RIFF files.

Requirements
============
  POSIX systems (e.g. Linux, OS X):
  ---------------------------------

  You need at least to have libtool installed to be able to build the
  library with "./configure && make".

  Additionally you need to have either libaudiofile (>= 0.2.3) or
  libsndfile (>= 1.0.2) installed which is mandatory to be able to compile
  the 'gigextract' example application. But of course 'gigextract' is still
  just an example application, so it would make sense to compile it only if
  one of those libraries are available. That would remove that hard
  dependency to those two libs. But that's not a priority for me now.
  Note: for Windows systems only libsndfile is available.

  If you want to regenerate all autotools build files (that is configure,
  Makefile.in, etc.) then you need to have automake (>= 1.5) and autoconf
  installed.

  Non-POSIX systems (e.g. Windows):
  ---------------------------------

  If you don't have a POSIX system, you have to set 'POSIX' to '0' in RIFF.h.
  Instead of using POSIX calls then standard C calls will be used for file
  access. This applies e.g. to Windows systems. I would appreciate if
  somebody sends me his MS Visual Studio / .NET, Borland C++ Builder or
  Apple XCode project file! This might help others to conveniently compile
  libgig on those platforms as well.

Compiling
=========
  You can either compile the sources and install the library directly on
  your system or you can create Redhat or Debian packages.

  a) Compiling and installing directly

  Call './configure && make' on the console to compile the library, all
  tools and demo applications, documentation and install them with
  'make install'. The latter has to be called as root.

  If you are compiling from CVS you have to call 'make -f Makefile.cvs'
  to generate all autotools build files before calling
  './configure && make'.

  You can use 'make distclean' and probably 'make -f Makefile.cvs clean'
  to clean up everything again. The latter will also delete all automatic
  generated autools build files.

  b) Creating Debian packages

  Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
  packages. This will generate 3 Debian packages:

    libgig:      Contains the shared library files.
    libgig-dev:  Contains the header files and documentation for building
                 applications using libgig.
    gigtools:    Contains the tools and demo applications.

  You can use 'fakeroot debian/rules clean' to clean up everything again.

  c) Creating Redhat packages

  You need to have the rpmbuild tool installed and properly configured to
  create RPM packages. To create the RPM packages do the following:

    * Get .spec file generated by ./configure and edit it as appropriate.

    * Copy the source tarball to "/usr/src/<rpmdir>/SOURCES" directory,
      where <rpmdir> is dependent to the system you are using. For SuSE
      <rmpdir> will be "packages", for Mandrake <rpmdir> is "RPM" and for
      Redhat / Fedora <rpmdir> always equals "redhat".

    * Build the rpm(s) by invoking 'rpmbuild -bb <specfile>' from the
      command line.

  On success, the resulting rpm(s) can usually be found under the proper
  "/usr/src/<rpmdir>/RPMS/<arch>" directory.

Test Cases
==========
  The libgig sources come with a tiny console application which allows to
  automatically test libgig's functions on your system. This test
  application is not compiled by default, you have to compile it explicitly
  with the following commands on the console (cppunit has to be installed):

    cd src/testcases
    make libgigtests

  and then run the test application from the same directory with:

    ./libgigtests

License
=======
  libgig and its tools are released under the GNU General Public License.

API Documentation
=================
  If you have Doxygen installed you can generate the API documentation by
  running 'make docs' in the sources' top level directory. The API
  documentation will be generated in the 'doc' subdirectory.

Patches
=======
  If you have bug fixes or improvements, your patches are always welcome!
  Send them either directly to me or to the LinuxSampler developer's mailing
  list <linuxsampler-devel@lists.sourceforge.net>.

Bugs
====
  Please use http://bugs.linuxsampler.org to check and report possible bugs.
  You might also try to run the "Test Cases" coming with libgig (see above),
  especially in case you are running on an odd system.

Credits
=======
  The initial library was based on the reverse engineering effort of
  Paul Kellett and Ruben van Royen. We owe current support for the quite new
  Gigasampler v3 format to Andreas Persson. Please also have a look at the
  ChangeLog for all those who contributed. Thanks to all of you for your
  great work!

 Christian Schoenebeck <cuse@users.sourceforge.net>
1	schoenebeck	859	Home
2			====
3			You can always find the latest version of libgig at:
4			http://stud.hs-heilbronn.de/~cschoene/projects/libgig/
5
6	schoenebeck	2	Content
7			=======
8			libgig actually consists of three parts:
9
10			- RIFF classes (RIFF.h, RIFF.cpp): Provides convenient methods to parse and
11			access arbitrary RIFF files.
12			- DLS classes (DLS.h, DLS.cpp): They're using the RIFF classes to parse
13			DLS (Downloadable Sounds) Level 1 and 2
14			files and provide abstract access to the
15			data.
16			- gig classes (gig.h, gig.cpp): These are based on the DLS classes and
17	schoenebeck	312	provide the necessary extensions for
18	schoenebeck	2	the Gigasampler file format.
19
20	schoenebeck	650	Beside the actual library there are four example applications:
21
22			gigdump: Demo app that prints out the content of a .gig file.
23			gigextract: Extracts samples from a .gig file.
24			dlsdump: Demo app that prints out the content of a DLS file.
25			rifftree: Tool that prints out the RIFF tree of an arbitrary RIFF
26			file.
27
28	schoenebeck	859	Since version 3.0.0 libgig also provides write support, that is for
29			creating modifying .gig, DLS and RIFF files.
30
31	schoenebeck	2	Requirements
32			============
33	schoenebeck	650	POSIX systems (e.g. Linux, OS X):
34			---------------------------------
35	schoenebeck	2
36	schoenebeck	650	You need at least to have libtool installed to be able to build the
37			library with "./configure && make".
38	schoenebeck	2
39	schoenebeck	650	Additionally you need to have either libaudiofile (>= 0.2.3) or
40			libsndfile (>= 1.0.2) installed which is mandatory to be able to compile
41			the 'gigextract' example application. But of course 'gigextract' is still
42			just an example application, so it would make sense to compile it only if
43			one of those libraries are available. That would remove that hard
44			dependency to those two libs. But that's not a priority for me now.
45			Note: for Windows systems only libsndfile is available.
46
47			If you want to regenerate all autotools build files (that is configure,
48			Makefile.in, etc.) then you need to have automake (>= 1.5) and autoconf
49	schoenebeck	859	installed.
50	schoenebeck	650
51			Non-POSIX systems (e.g. Windows):
52			---------------------------------
53	schoenebeck	859
54	schoenebeck	2	If you don't have a POSIX system, you have to set 'POSIX' to '0' in RIFF.h.
55			Instead of using POSIX calls then standard C calls will be used for file
56	schoenebeck	530	access. This applies e.g. to Windows systems. I would appreciate if
57			somebody sends me his MS Visual Studio / .NET, Borland C++ Builder or
58			Apple XCode project file! This might help others to conveniently compile
59			libgig on those platforms as well.
60	schoenebeck	2
61	schoenebeck	186	Compiling
62			=========
63			You can either compile the sources and install the library directly on
64			your system or you can create Redhat or Debian packages.
65	schoenebeck	2
66	schoenebeck	186	a) Compiling and installing directly
67
68	schoenebeck	650	Call './configure && make' on the console to compile the library, all
69			tools and demo applications, documentation and install them with
70			'make install'. The latter has to be called as root.
71	schoenebeck	186
72	schoenebeck	650	If you are compiling from CVS you have to call 'make -f Makefile.cvs'
73			to generate all autotools build files before calling
74			'./configure && make'.
75
76			You can use 'make distclean' and probably 'make -f Makefile.cvs clean'
77			to clean up everything again. The latter will also delete all automatic
78			generated autools build files.
79
80	schoenebeck	186	b) Creating Debian packages
81
82	schoenebeck	650	Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
83			packages. This will generate 3 Debian packages:
84	schoenebeck	186
85			libgig: Contains the shared library files.
86			libgig-dev: Contains the header files and documentation for building
87			applications using libgig.
88			gigtools: Contains the tools and demo applications.
89
90	schoenebeck	650	You can use 'fakeroot debian/rules clean' to clean up everything again.
91	schoenebeck	186
92			c) Creating Redhat packages
93
94	schoenebeck	191	You need to have the rpmbuild tool installed and properly configured to
95			create RPM packages. To create the RPM packages do the following:
96	schoenebeck	186
97	schoenebeck	191	* Get .spec file generated by ./configure and edit it as appropriate.
98
99			* Copy the source tarball to "/usr/src/<rpmdir>/SOURCES" directory,
100			where <rpmdir> is dependent to the system you are using. For SuSE
101			<rmpdir> will be "packages", for Mandrake <rpmdir> is "RPM" and for
102			Redhat / Fedora <rpmdir> always equals "redhat".
103
104			* Build the rpm(s) by invoking 'rpmbuild -bb <specfile>' from the
105			command line.
106
107			On success, the resulting rpm(s) can usually be found under the proper
108			"/usr/src/<rpmdir>/RPMS/<arch>" directory.
109
110	schoenebeck	923	Test Cases
111			==========
112			The libgig sources come with a tiny console application which allows to
113			automatically test libgig's functions on your system. This test
114			application is not compiled by default, you have to compile it explicitly
115			with the following commands on the console (cppunit has to be installed):
116
117			cd src/testcases
118			make libgigtests
119
120			and then run the test application from the same directory with:
121
122			./libgigtests
123
124	schoenebeck	859	License
125			=======
126			libgig and its tools are released under the GNU General Public License.
127
128	schoenebeck	186	API Documentation
129			=================
130	schoenebeck	859	If you have Doxygen installed you can generate the API documentation by
131			running 'make docs' in the sources' top level directory. The API
132			documentation will be generated in the 'doc' subdirectory.
133	schoenebeck	2
134	schoenebeck	11	Patches
135			=======
136	schoenebeck	923	If you have bug fixes or improvements, your patches are always welcome!
137	schoenebeck	11	Send them either directly to me or to the LinuxSampler developer's mailing
138			list <linuxsampler-devel@lists.sourceforge.net>.
139
140	schoenebeck	923	Bugs
141			====
142			Please use http://bugs.linuxsampler.org to check and report possible bugs.
143			You might also try to run the "Test Cases" coming with libgig (see above),
144			especially in case you are running on an odd system.
145
146	schoenebeck	11	Credits
147			=======
148	schoenebeck	530	The initial library was based on the reverse engineering effort of
149			Paul Kellett and Ruben van Royen. We owe current support for the quite new
150			Gigasampler v3 format to Andreas Persson. Please also have a look at the
151	schoenebeck	859	ChangeLog for all those who contributed. Thanks to all of you for your
152			great work!
153	schoenebeck	11
154	schoenebeck	2	Christian Schoenebeck <cuse@users.sourceforge.net>