LinuxSampler for Debian     HOWTO by Christian Schoenebeck 


February 7th, 2008

1.  Introduction
2.  Requirements
3.  Building the Backend
4.  Benchmark
5.  Building the Frontend(s) and Instrument Editor
6.  Troubleshooting
7.  Detailed Documentation
8.  Bugs, Problems and Feature Requests
9.  Contact

1.  Introduction

There are two ways to install LS & friends on your Debian system. You can either download and install our precompiled Debian binary packages (x86 only), or you can compile those Debian packages by yourself. Our precompiled Debian packages are cooked for the latest Debian stable distribution (a.k.a. "etch"). Installing them is pretty easy. Just download the latest versions of the Debian binary packages from our server and install them (as root) with: 
  dpkg -i REPLACE_BY_DEB_FILE
However we recommend you to recompile at least libgig and LinuxSampler (the backend) by yourself, to get the maximum performance out of your box (because libgig and LinuxSampler are the software components which take the most of your machine's resources under heavy setups which you're probably going to do). Another reason at the moment for you to recompile them is when you have an old machine that doesn't support SSE instructions. Because the latest Debian binary packages were accidently compiled with using SSE floating point instructions (see bug report #71). In the latter case, linuxsampler would die with a "FATAL ERROR: Illegal instruction (SIGILL) occured!" error message. We're going to address this Debian binary issue with the next LS (LinuxSampler) release. And of course, if you don't have a x86 based system, you currently have to build the Debian packages by yourself as well.

So this HOWTO is focused on how to cook optimized Debian packages of LS & friends for your specific system. Of course you could also compile everything the old fashioned way, that is: 
  cd SOURCEDIR
  make -f Makefile.cvs
  ./configure
  make
  su
  make install
But many users who use a Debian based system (e.g. Ubuntu) prefer (building and) installing Debian packages, since it's cleaner for their environment and, which is probably more important to you, the Debian packaging mechanism takes care of compile time and runtime library dependencies etc.

2.  Requirements

Each of the software components you're going to compile will have additional requirements, but we'll address this later. The ones mentioned above are absolute prerequisites for continueing, so make sure you have them installed. If not, do so now (as root): 
  apt-get install g++ debhelper pkg-config automake1.8 libtool fakeroot
If this is the first Debian packages you're going to build, you may wonder about the fakeroot tool. This is needed to "fool" the Debian packaging tools that we're compiling as root. Because usually you don't actually want to compile things as root, but the Debian packaging scripts expect it.

3.  Building the Backend

Grab the source code files of libgig (e.g. from our Subversion server, as described on the downloads site). Then you should optimize the compilation flags for your machine. This really depends on what kind of CPU and other hardware you use. Open the file debian/rules of the libgig sources in a text editor and watch out for the following line: 
  ./configure --host=$(DEB_HOST_GNU_TYPE) --build=$(DEB_BUILD_GNU_TYPE) --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info
This is the line where you'll place all your optimization options. Remove the arguments --host and --build which are only meant for cross compilation and prefix the line with your preferred optimization flags. So, for a Pentium4 machine it could look like: 
  CXXFLAGS="-O3 -msse -march=pentium4 -mfpmath=sse -ffast-math -fomit-frame-pointer -funroll-loops" ./configure --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info
save the file and finally you can start the build process (as ordinary user) with: 
  dpkg-buildpackage -rfakeroot -b
from the libgig source directory, which should compile and build the .deb files for you. In case it immediately aborts with the following error message: 
  Unmet build dependencies: ...
Simply install the requested packages with "apt-get install" (or whatever you prefer for package installation) and call the dpkg-buildpackage command again. After a minute or so it should have left 3 .deb files one directory above your libgig source directory. Install those 3 .deb files now, i.e. with dpkg (as root): 
  dpkg -i libgig_3.2.1-1_i386.deb libgig-dev_3.2.1-1_i386.deb
  dpkg -i gigtools_3.2.1-1_i386.deb
and now repeat these steps for LS. That is grab the LS sources, edit the debian/rules files at the similar configure line. The only difference with LS is that you have much more options now. For example on a recent Pentium4 machine, the LS compile time options in LS's debian/rules file could become: 
  CXXFLAGS="-O3 -msse -march=pentium4 -mfpmath=sse -ffast-math -fomit-frame-pointer -funroll-loops" ./configure --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info --enable-refill-streams=2 --enable-stream-size=320000 --enable-preload-samples=65536 --enable-max-voices=200 --enable-max-streams=220
Just to let you know the difference: the options you apply to the "CXXFLAGS" variable are options of the compiler (usually the GNU compiler, see "man gcc" for all available gcc options). The parameters after the "./configure" token are LS specific compile time options, i.e. the amount of disk streams etc. For a full list of LS's compile time options and brief explanations of them you can call: 
  ./configure --help
from LS's source directory. So after you modified the configure line in LS's debian/rules file, you can once again call: 
  dpkg-buildpackage -rfakeroot -b
to get the LS packages cooked. This time it should take a bit longer. Once again you'll get 3 Debian packages (liblinuxsampler, liblinuxsampler-dev and linuxsampler). Install those 3 new LS packages again e.g. with "dpkg -i" like already explained above with libgig.

And that's it!

The good thing: if you grabbed the sources of libgig and LS from Subversion, you only have to call: 
  svn update
  dpkg-buildpackage -rfakeroot -b
once in a while from the source directory to conveniently compile the latest version with your personal optimizations and configuration parameters for your system, because "svn update" updates your local source files to the latest bleeding edge version from our Subversion server but won't touch your modifications!
The problematic part is to find good compile time options for your specific system. Unfortunately there is no real recipe for that, it always requires to play around a bit with the various options. A little help on this however is described next.

4.  Benchmark

You're most probably unsure which gcc (compiler) flags to use. As said, this always means a bit playing around. For that you can use our stripped down benchmark, which is located in the "benchmarks" directory of the LS sources. The good thing about the benchmark: it's really light-weight, that is it's a benchmark of our full gig sampling engine, but it doesn't depend on any MIDI or audio drivers, nor does it require to load any sounds or to handle with automake / ./configure crap and compiles really fast.

Here's how it goes:
  1. adjust the file benchmarks/Makefile in the LS source directory with the CFLAGS (pretty much the same as CXXFLAGS) of your choice
  2. call "make" from the benchmarks/ directory
  3. run the compiled binary "benchmarks/gigsynth"
which will print you out benchmark values for your system on the console. There are different kind of so called "synthesis modes", i.e. one with filter on, one with filter off, one with resampling on, one with no resampling, etc. each will shoot its own benchmark result.

So that way you can easily and quickly play around with CFLAGS (a.k.a CXXFLAGS) and figure out which one is beloved by your machine.

5.  Building the Frontend(s) and Instrument Editor

QSampler: Building the QSampler Debian package is pretty much the same process are described above for the backend. However usually you don't need to take the hassle to optimize the compile time flags as thoroughly as you would do for the backend. Since the frontend doesn't use much resources anyway. Note however that you need to cook and install the liblscp Debian packages before starting to build the QSampler package.

JSampler: Many users prefer to use JSampler instead of QSampler, since it currently provides more features and has a very slick skin based user interface. Unfortunately JSampler hasn't been debianized yet, so there is no way at the moment to build JSampler and jlscp Debian packages yet. But this certainly going to change as soon as the GPL transition of the Java SDK has been completed. So for now please use either the precompiled JSampler .jar file (e.g. from our downloads site) or refer to the build instructions of the JSampler documentation.

gigedit: This is the graphical instrument editor for .gig files. Once again, building Debian packages of gigedit is similar to the other software components. Just note that you should build gigedit after you compiled and installed libgig and linuxsampler. Otherwise gigedit might just be compiled as a stand-alone editor, that is you might not use it in conjunction with LS & friends. If you have any trouble getting gigedit to work with LS, please refer to the "live mode" chapter of the gigedit documentation and its respective trouble shooting section.

6.  Troubleshooting

7.  Detailed Documentation

You find more detailed documentation about our software, i.e. about JSampler or gigedit on our official LinuxSampler documentation site.

8.  Bugs, Problems and Feature Requests

Our Forum is a good place to ask for help:

    http://bb.linuxsampler.org

We have a dedicated forum section for newbies and support.

No software is perfect, nor is ours, if you found bugs, please report them using our bug tracking system:

    http://bugs.linuxsampler.org/

In case you encountered a crash, please report it! To be able to solve such a problem, we need a back trace though. For this you need to recompile your LinuxSampler Debian packages like this: 
  DEB_BUILD_OPTIONS="nostrip noopt" fakeroot dpkg-buildpackage -b
The two options at the beginning will cause the package to be compiled with debugging symbols turned on and all optimizations turned off.

9.  Contact

If you have questions or want to help us to improve the sampler, please subscribe to the LinuxSampler Developer's mailing list. If you want to contact a certain developer instead, your can find our email addresses here:

    http://www.linuxsampler.org/developers.html

That's it, enjoy!