Annotation of /libgig/trunk/README

Home
====
  You can always find the latest version of libgig at:
  http://www.linuxsampler.org/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.

  Windows:
  --------

  The precompiled versions of libgig (and its tools) should be compatible
  with any Windows operating system of at least Win95 or younger. Notice
  that all example / demo applications coming with libgig are pure console
  applications, thus you won't see a GUI showing up! :)

  If you want to compile libgig and its tools by yourself, please also
  notice the requirements under "Compiling for Windows".

  Other Operating Systems:
  ------------------------

  libgig was written to compile for any operating system, using standard C
  library functions. However the latest versions of libgig lack a portable
  implementation of one tiny method called RIFF::File::ResizeFile(). So you
  would either have to add native OS API calls for that particular method,
  that is dependant to your OS, or you have to add a portable
  implementation. No matter which way you choose, please let us know! :)

Compiling for Linux
===================
  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.

Compiling for Windows
=====================

  libgig and its tools can be compiled for Windows using Bloodshed Dev-C++,
  which is a free (GPL) C++ integrated development environment for Windows.
  It is also possible to use MSYS from MinGW, which allows you to use
  './configure && make' like the linux builds.

  You can download Dev-C++ here:

    http://www.bloodshed.net/devcpp.html

  Make sure you install a version with Mingw integrated.

  a) Compiling libgig.dll

  Simply open the project file "win32/libgig.dev" either directly in Dev-C++
  or by double clicking on the project file in the Windows explorer, then
  click on "Compile" in the Dev-C++ menu and that's it! After compilation
  finished, you can find the files "libgig.dll", "libgig.a" and
  "liblibgig.def" in the "win32" directory.

  b) Compiling the example tools "rifftree", "dlsdump" and "gigdump"

  You need to have libgig.dll compiled as described in a). Then you can
  compile the respective tool by simply opening the respective project
  (.dev) file and clicking on "Compile" from the Dev-C++ menu. After
  compilation you can find the respective .exe file in the "win32"
  directory.

  c) Compiling the example tool "gigextract"

  You need to have libgig.dll compiled as described in a). Also you need
  libsndfile (as DLL) which is used to create the .wav files. You can
  download libsndfile already precompiled as DLL here:

    http://www.mega-nerd.com/libsndfile/

  Extract the .zip file i.e. to "C:\". The libsndfile .dll file should then
  be i.e. under "C:\libsndfile-1_0_17". Beside the .dll file, make sure
  libsndfile's .lib file exists in that directory as well. If the .lib file
  does not exist yet, you have to create it with:

    dlltool --input-def libsndfile-1.def --output-lib libsndfile-1.lib

  Then you have to ensure the settings of gigextract's Dev-C++ project file
  are pointing to the correct location of your local copy of libsndfile. For
  that click in the Dev-C++ menu on "Project" -> "Project Options". Then
  click on the tab "Parameter" and make sure the path to "libsndfile-1.lib"
  in the "Linker" list view is correct. Then click on the tab "Directories"
  and then on the tab "Include Directories" and make sure the path to
  libsndfile points to the correct location there as well.

  After that you should finally be able to compile "gigextract" by clicking
  on "Compile" in the Dev-C++ menu. After compilation succeeded, you can
  find the "gigextract.exe" file in the "win32" 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	schoenebeck	1406	http://www.linuxsampler.org/libgig/
5	schoenebeck	859
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	schoenebeck	1063	Windows:
52			--------
53	schoenebeck	859
54	schoenebeck	1063	The precompiled versions of libgig (and its tools) should be compatible
55			with any Windows operating system of at least Win95 or younger. Notice
56			that all example / demo applications coming with libgig are pure console
57			applications, thus you won't see a GUI showing up! :)
58	schoenebeck	2
59	schoenebeck	1063	If you want to compile libgig and its tools by yourself, please also
60			notice the requirements under "Compiling for Windows".
61
62			Other Operating Systems:
63			------------------------
64
65			libgig was written to compile for any operating system, using standard C
66			library functions. However the latest versions of libgig lack a portable
67			implementation of one tiny method called RIFF::File::ResizeFile(). So you
68			would either have to add native OS API calls for that particular method,
69			that is dependant to your OS, or you have to add a portable
70			implementation. No matter which way you choose, please let us know! :)
71
72			Compiling for Linux
73			===================
74	schoenebeck	186	You can either compile the sources and install the library directly on
75			your system or you can create Redhat or Debian packages.
76	schoenebeck	2
77	schoenebeck	186	a) Compiling and installing directly
78
79	schoenebeck	650	Call './configure && make' on the console to compile the library, all
80			tools and demo applications, documentation and install them with
81			'make install'. The latter has to be called as root.
82	schoenebeck	186
83	schoenebeck	650	If you are compiling from CVS you have to call 'make -f Makefile.cvs'
84			to generate all autotools build files before calling
85			'./configure && make'.
86
87			You can use 'make distclean' and probably 'make -f Makefile.cvs clean'
88			to clean up everything again. The latter will also delete all automatic
89			generated autools build files.
90
91	schoenebeck	186	b) Creating Debian packages
92
93	schoenebeck	650	Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
94			packages. This will generate 3 Debian packages:
95	schoenebeck	186
96			libgig: Contains the shared library files.
97			libgig-dev: Contains the header files and documentation for building
98			applications using libgig.
99			gigtools: Contains the tools and demo applications.
100
101	schoenebeck	650	You can use 'fakeroot debian/rules clean' to clean up everything again.
102	schoenebeck	186
103			c) Creating Redhat packages
104
105	schoenebeck	191	You need to have the rpmbuild tool installed and properly configured to
106			create RPM packages. To create the RPM packages do the following:
107	schoenebeck	186
108	schoenebeck	191	* Get .spec file generated by ./configure and edit it as appropriate.
109
110			* Copy the source tarball to "/usr/src/<rpmdir>/SOURCES" directory,
111			where <rpmdir> is dependent to the system you are using. For SuSE
112			<rmpdir> will be "packages", for Mandrake <rpmdir> is "RPM" and for
113			Redhat / Fedora <rpmdir> always equals "redhat".
114
115			* Build the rpm(s) by invoking 'rpmbuild -bb <specfile>' from the
116			command line.
117
118			On success, the resulting rpm(s) can usually be found under the proper
119			"/usr/src/<rpmdir>/RPMS/<arch>" directory.
120
121	schoenebeck	1063	Compiling for Windows
122			=====================
123	persson	1330
124	schoenebeck	1063	libgig and its tools can be compiled for Windows using Bloodshed Dev-C++,
125			which is a free (GPL) C++ integrated development environment for Windows.
126	persson	1330	It is also possible to use MSYS from MinGW, which allows you to use
127			'./configure && make' like the linux builds.
128	schoenebeck	1063
129	persson	1330	You can download Dev-C++ here:
130
131	schoenebeck	1063	http://www.bloodshed.net/devcpp.html
132
133			Make sure you install a version with Mingw integrated.
134
135			a) Compiling libgig.dll
136
137			Simply open the project file "win32/libgig.dev" either directly in Dev-C++
138			or by double clicking on the project file in the Windows explorer, then
139			click on "Compile" in the Dev-C++ menu and that's it! After compilation
140			finished, you can find the files "libgig.dll", "libgig.a" and
141			"liblibgig.def" in the "win32" directory.
142
143			b) Compiling the example tools "rifftree", "dlsdump" and "gigdump"
144
145			You need to have libgig.dll compiled as described in a). Then you can
146			compile the respective tool by simply opening the respective project
147			(.dev) file and clicking on "Compile" from the Dev-C++ menu. After
148			compilation you can find the respective .exe file in the "win32"
149			directory.
150
151			c) Compiling the example tool "gigextract"
152
153			You need to have libgig.dll compiled as described in a). Also you need
154			libsndfile (as DLL) which is used to create the .wav files. You can
155			download libsndfile already precompiled as DLL here:
156
157			http://www.mega-nerd.com/libsndfile/
158
159			Extract the .zip file i.e. to "C:\". The libsndfile .dll file should then
160			be i.e. under "C:\libsndfile-1_0_17". Beside the .dll file, make sure
161			libsndfile's .lib file exists in that directory as well. If the .lib file
162			does not exist yet, you have to create it with:
163
164			dlltool --input-def libsndfile-1.def --output-lib libsndfile-1.lib
165
166			Then you have to ensure the settings of gigextract's Dev-C++ project file
167			are pointing to the correct location of your local copy of libsndfile. For
168			that click in the Dev-C++ menu on "Project" -> "Project Options". Then
169			click on the tab "Parameter" and make sure the path to "libsndfile-1.lib"
170			in the "Linker" list view is correct. Then click on the tab "Directories"
171			and then on the tab "Include Directories" and make sure the path to
172			libsndfile points to the correct location there as well.
173
174			After that you should finally be able to compile "gigextract" by clicking
175			on "Compile" in the Dev-C++ menu. After compilation succeeded, you can
176			find the "gigextract.exe" file in the "win32" directory.
177
178	schoenebeck	923	Test Cases
179			==========
180			The libgig sources come with a tiny console application which allows to
181			automatically test libgig's functions on your system. This test
182			application is not compiled by default, you have to compile it explicitly
183			with the following commands on the console (cppunit has to be installed):
184
185			cd src/testcases
186			make libgigtests
187
188			and then run the test application from the same directory with:
189
190			./libgigtests
191
192	schoenebeck	859	License
193			=======
194			libgig and its tools are released under the GNU General Public License.
195
196	schoenebeck	186	API Documentation
197			=================
198	schoenebeck	859	If you have Doxygen installed you can generate the API documentation by
199			running 'make docs' in the sources' top level directory. The API
200			documentation will be generated in the 'doc' subdirectory.
201	schoenebeck	2
202	schoenebeck	11	Patches
203			=======
204	schoenebeck	923	If you have bug fixes or improvements, your patches are always welcome!
205	schoenebeck	11	Send them either directly to me or to the LinuxSampler developer's mailing
206			list <linuxsampler-devel@lists.sourceforge.net>.
207
208	schoenebeck	923	Bugs
209			====
210			Please use http://bugs.linuxsampler.org to check and report possible bugs.
211			You might also try to run the "Test Cases" coming with libgig (see above),
212			especially in case you are running on an odd system.
213
214	schoenebeck	11	Credits
215			=======
216	schoenebeck	530	The initial library was based on the reverse engineering effort of
217			Paul Kellett and Ruben van Royen. We owe current support for the quite new
218			Gigasampler v3 format to Andreas Persson. Please also have a look at the
219	schoenebeck	859	ChangeLog for all those who contributed. Thanks to all of you for your
220			great work!
221	schoenebeck	11
222	schoenebeck	2	Christian Schoenebeck <cuse@users.sourceforge.net>