Customizing the STK for Development

Download the file stk4p2p1josoverlay.tar.gz and unpack it as follows (assuming ~/stk/stk/ contains release 4.2.1 of the STK as prescribed above):

 
$ cd ~/stk
$ wget http://ccrma.stanford.edu/~jos/stk4p2p1josoverlay.tar.gz
$ tar -zxf stk4p2p1josoverlay.tar.gz
$ cp -rp stk4p2p1josoverlay/* stk/

Notice that one new directory (~/stk/stk/myproj) has appeared. This directory is logically parallel to the STK projects directory. It is kept separate so that it can be easily copied into new releases of the STK.

Now, as described in the new file ~/stk/stk/INSTALL.jos, to configure and compile the STK, just type, in the directory ~/stk/stk/,

 
configure --enable-debug CFLAGS="-g -O0"
make

The configure command generates all the various Makefiles^A.2 based on automatically detected characteristics of your system [535]. The file INSTALL contains more detailed installation instructions which you should not need under UNIX if you are following this example. On the other hand, it is good to read INSTALL and README for your general edification. Similarly, the doc/ directory should be explored to learn about the STK in general.

The -enable-debug configure-option is desirable during software development. It results in two changes to the C++ compiler options written into the various makefiles:

1. Symbols are retained in the executable file by adding the -g compiler option.
2. Optimization level is reduced using the -O2 option in place of the -O3 option. The second argument to configure, namely CFLAGS="-g -O0", sets the optimization level to zero. This is because even optimization level 2 results in eliminated intermediate variables, which cannot be inspected while single-stepping gdb.

Additionally, -enable-debug results in the compile-time macro _STK_DEBUG_ being defined. This turns on debugging code such as assertions and warnings. In particular, various warnings from STK library modules are enabled by the _STK_DEBUG_ macro:

#if defined(_STK_DEBUG_)
  handleError( StkError::DEBUG_WARNING );
#endif

To enable support for the jack audio server, add the configure option -with-jack. The jack server ``owns'' the audio I/O resources, and provides connection services among multiple client applications. If you do not already start the jack server on your Linux system, you can do it using qjackctl (conveniently available along with the jack audio server itself via the Planet CCRMA distribution).

Say configure -help in the main STK directory (~/stk/stk in the above examples) to see other STK configuration options.

To test out the added ~/stk/stk/myproj directory from the JOS Overlay, type

 
cd myproj
make

The default make target in the myproj directory makefile is test. Therefore, you should hear a test sound emitted after each subdirectory is made. Before the tests are compiled, however, the STK library is made, so first you will see the many library files being compiled. (See the various Makefiles regarding how this is carried out.) If you do not hear the test sounds, read myproj/delay/README for some trouble-shooting tips. If the problem is that you don't have the program sndplay, which comes with sndlib and is available via Planet CCRMA, you can change the SNDPLAY variable in the make-file myproj/Makefile.proj to something else (such as play, which comes with the sox distribution, but note that play does not work with jack running).

If the above tests make sound, then in principle you are enabled to read the make-files and source-code in order to figure out everything that is going on. However, to make the road a little smoother, the following sections provide further introduction and overview. Please cd now to  /stk/stk and follow along below.