Developer Installation Guide:Linux
From Resound-wiki
Contents |
[edit]
Installation of Linux
The following has been tested with Ubuntu 8.04 (Hardy Heron) with the real-time kernel. The following installation guide is geared towards this configuration; other configurations may deviate and/or require tweaking. Resound has been tested and is known to run on the following other Linux distributions (although the specifics of getting it to run may differ slightly from this installation guide):
- Ubuntu 8.04 (Hardy Heron), kernels: 2.6.24-17-generic, 2.6.24-17-rt
- Ubuntu 7.10 (Gutsy Gibbon), kernels: 2.6.22-14-generic, 2.6.22-14-rt
- Ubuntu 7.04 (Feisty Fawn)
- Ubuntu Studio (http://ubuntustudio.org/)
- Ubuntu 6.06 (Dapper Drake)
Remember when installing applications manually under Ubuntu - or most Debian based distributions - to set the install path to /usr, otherwise it may default to /usr/local.
The remainder of this guide assumes that you have Linux installed and functioning correctly.
[edit]
Installation Procedure
The following steps can be followed in order to perform a minimal install of the Resound Server and GUI applications on the same machine. If each step is completed without errors before progressing on to the next, any errors that do occur should be easy to pin-point. This guide assumes that you will be downloading and compiling source code in the directory ~/sandbox/.
- Install Subversion:
sudo apt-get install subversion
- Create a sandbox directory (e.g. ~/sandbox) and use Subversion to download the latest Resound source code into a folder called resound-trunk inside that directory:
mkdir ~/sandbox cd ~/sandbox svn co https://resound.svn.sourceforge.net/svnroot/resound/trunk resound-trunk
- Get the tools required to generate Make files using CMake and to compile the source code:
sudo apt-get install build-essential cmake
- Get the dependencies required to generate the Make files without errors. Note: Be sure to install version 2.6 of wx. There are known issues with version 2.8.
sudo apt-get install libwxgtk2.6-dev libboost-program-options-dev libboost-serialization-dev
- If needed, modify the CMakeFiles.txt files in each directory to use release version compiler flags if necessary. TO DO: Make this process more obvious.
- Use CMake to generate UNIX Make files, ensuring that the project files are generated without errors (you can ignore warnings at this stage). The following command will prepare the applications for installation with your chosen prefix (in this example, /usr):
cd ~/sandbox/resound-trunk/src cmake -DCMAKE_INSTALL_PREFIX=/usr .
- Get the further dependencies required to compile the Resound source code:
sudo apt-get install liblo0-dev libjack0.100.0-dev libasound2-dev
- Use Make to compile the source code, ensuring that compilation is completed without any errors (again, warnings can be ignored) and copy to the correct installation path:
make sudo make install
- At this stage it is worth checking the install by running the provided script. Change into the docs directory and run ./check_wx_and_resound_paths. See CONTENTS.txt for an explanation of what output to expect. If all is well, continue.
~/sandbox/resound-trunk/docs/check_wx_and_resound_paths.sh | grep '2.8'
- The next stage is to install the JACK daemon, which is required to run the Resound server. If you know that your audio interface works with the current packaged version of JACK, you can get it as follows:
sudo apt-get install jackd
- If no errors have been encountered up to this point, minimal installation is complete and can be tested.
[edit]
Testing the Installation
- Start the JACK daemon using a dummy audio driver:
jackd -ddummy
- Run the Resound Server. It is not necessary to worry about audio interfaces at this stage; use some dummy parameters (8 inputs and 8 outputs in this example). The -v flag enables verbose output:
resound_server -i8 -o8 -v
- The following excerpt from the end of the console output is typical, and indicates that the Server application is up and running:
---- Resound Server Running ---- Inputs : 8 Outputs : 8 OSC Port: 4567 -------------------------------- OSC client osc.udp://127.0.0.1:4567/ has disconnected. Removing from active client list.
- Open a new console window and run the Resound GUI with the same dummy parameters, again enabling verbose output with the -v flag:
resound_gui -i8 -o8 -v
- Console output will show that the GUI registers parameters with the Server, with the following output at the end before the GUI interface window opens:
Initialising OSC listen thread... Adding OSC methods... Sending self-test OSC messages... OSC recvfrom osc.udp://127.0.0.1:8000/ to /syn Args(["resound_server selftest syn/ack"] ) OSC new client detected at osc.udp://127.0.0.1:8000/ OSC recvfrom osc.udp://127.0.0.1:8000/ to /ack Args(["resound_server build 1.0"] ) recv_ack
- Communication between the GUI and the Server can be tested by assigning a parameter to one of the faders using the GUI. Click the Assign button on any fader, opening the Collective Builder Dialog. Assign a parameter - it doesn't matter which one - to the fader by clicking on a matrix element (one of the red, green or blue boxes), confirming the assignment by clicking OK. Whilst watching the Server application's console window, move the fader to which the parameter has just been assigned. The changing values should be reflected in real time in the Server's console window, for example thus:
OSC recvfrom osc.udp://127.0.0.1:8000/ to /matrix/att/1/1 Args([0.039062] ) OSC recvfrom osc.udp://127.0.0.1:8000/ to /matrix/att/1/1 Args([0.054688] ) OSC recvfrom osc.udp://127.0.0.1:8000/ to /matrix/att/1/1 Args([0.070312] ) OSC recvfrom osc.udp://127.0.0.1:8000/ to /matrix/att/1/1 Args([0.085938] ) OSC recvfrom osc.udp://127.0.0.1:8000/ to /matrix/att/1/1 Args([0.093750] )
- If this happens then minimal installation is complete and functioning properly
[edit]
Install Real-Time Kernel
- Note: For best performance, JACK should be run in realtime mode using the -R flag. This requires the correct permissions for realtime and memory locking. If these are not in place, JACK will return an error. There are two ways to ensure that JACK can run in realtime mode. The first method is to run everything (JACK, resound_gui, resound_server, any additional apps, the lot) as super-user. This is the quickest and easiest way to test performance but is less secure as it requires users to have full superuser privileges. The recommended solution is to install and configure the real-time kernel, as explained below. The real-time kernel is available as a package for Ubuntu 7.10 (Gutsy Gibbon) onwards and can be downloaded and installed as follows (for other Linux distributions, you're on your own I'm afraid):
sudo apt-get install linux-rt
- After installing the realtime kernel you will need to reboot and ensure that you boot into the realtime kernel.
- You then need to allow users access to real-time priority and memory locking. This is done by editing the file /etc/security/limits.conf. The simplest (but least secure) way is to grant these privileges to any user, which can be done by adding the following lines:
* - rtprio 99 * - nice -10 * - memlock 4000000
- As a more secure option, replace * with the username of a single authorised user, or the name of an authorised group prefixed with the @ symbol (e.g. @audiogroup).
- Log out, then log in again as a real-time authorised user. Or, if you didn't reboot previously after installing the realtime kernel, reboot now.
- You can view the memory limit with the following :
ulimit -l
- The finished installation can be tested, in real-time mode, with the following : Making a fader assignment in the GUI and moving the fader should result in console output from the GUI and Server as before...
jackd -R -ddummy & resound_server -i8 -o8 -v & resound_gui -i8 -o8 -v &
[edit]
Uninstallation / List of Files Installed
- The procedure detailed on this page installs the following top-level files and folders (not including dependencies and additional applications):
[prefix]/bin/resound_server [prefix]/bin/resound_gui [prefix]/lib/libresound_common.a [prefix]/share/resound_gui
- The applications can be uninstalled by recursively removing these files/directories
[edit]
Audio Interfaces
See the Audio Interfaces page for details of tested audio interfaces and associated guidelines.
[edit]
Developers
Developers might also want to install some of the following:
- kdevelop3 >= 3.3.2 -- a nice IDE that works well with CMake -- see CMake options below
- esvn >= 0.6.11 -- a useful graphical client for Subversion -- optional, but useful
- rapidsvn >= 0.9.4 -- a useful and more fully featured graphical client for subversion, works great with meld see below
- meld >= 1.1.4 -- a really nice looking graphical diff tool that seems to work well with rapidsvn
- CMake can be used to generate KDevelop project files (rather than UNIX Make files as described above) with the following.
cd ~/sandbox/resound/src cmake -G KDevelop3 make
[edit]
Additional Applications
The following might be useful as additional components to the minimal install described above.
- qjackctl >= 0.2.19a-2. A useful GUI for JACK.
- VLC. This is a useful Jack enabled media player, but must be compiled from source in order for Jack support to be enabled. This site was helpful. See also [[1]] for further details.
- Ardour. Useful for multichannel file playback. Note: Ardour 2.0, although not strictly a requirement for use with Resound, is strongly recommended for reasons of compatibility with associated applications. At the time of writing, Ardour 2 is not yet available as a package, but comes bundled with, for example, the Ubuntu Studio distribution of Linux. Alternatively, Ardour 2.0 can be installed from source code. Ardour 0.99 (ardour-gtk 0.99) is the stable release at the time of writing and can normally be obtained as a package.
