--- libgig/trunk/README 2005/05/09 14:09:16 530 +++ libgig/trunk/README 2007/09/09 10:36:23 1330 @@ -1,3 +1,8 @@ +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: @@ -12,53 +17,88 @@ provide the necessary extensions for the Gigasampler file format. -Requirements -============ - I simply used automake & co this time so you will need to have automake, - autoconf and libtool installed. I used the following versions: + Beside the actual library there are four example applications: - automake 1.6.3 - autoconf 2.57 + 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. - If you want to compile the 'gigextract' application that comes with these - sources then you will additionally need to have libaudiofile (>= 0.2.3) - or libsndfile (>= 1.0.2) installed. Note: for Windows systems only - libsndfile is available. + Since version 3.0.0 libgig also provides write support, that is for + creating modifying .gig, DLS and RIFF files. -Non-POSIX systems -================= - 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. +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". -Compiling -========= + 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 - Use 'make -f Makefile.cvs && ./configure && make' to compile the library, - all tools, demo applications, documentation and install them with - 'make install'. You can use 'make distclean && make -f Makefile.cvs clean' - to clean up everything again. + 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 'make -f Makefile.cvs && dpkg-buildpackage -rfakeroot -b' to compile - and create the Debian packages. This will generate 3 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 && make -f Makefile.cvs clean' - to clean up everything again. + You can use 'fakeroot debian/rules clean' to clean up everything again. c) Creating Redhat packages @@ -78,35 +118,105 @@ On success, the resulting rpm(s) can usually be found under the proper "/usr/src//RPMS/" directory. -Tools -===== +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" - Beside the actual library there are four applications: + 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. - 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. + 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. + 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 find bugs or have improvements, your patches are always welcome! + 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 . +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 for your great work! + ChangeLog for all those who contributed. Thanks to all of you for your + great work! Christian Schoenebeck