Build SoundComp

Build SoundComp

There's essentially two ways to build SoundComp from source; via command line and via IDE (eclipse).
Both ways are supported to a certain extent, but not on all platforms.
Building SoundComp needs a certain amount of prerequisites on the machine used for building;
these prerequisites differ depending on the choice of build system.
SoundComp attempts to provide as many of these prerequisites on its own, but due to the variety of build systems it cannot succeed in all instances. Therefore it might be necessary to know about the whereabouts of what is used in which way for building SoundComp.

Common prerequisites:

You need to have installed
- a JDK
- ant
- a C/C++ compiler
- subversion in a supported version
- an online connection to the SoundComp svn repository

"A supported version" of subversion means one that a suitable version of svnkit is present in the "tools" directory. At the time of writing this is svnkit 1.8 (as no newer svnkit yet existed), which implies that your subversion client should have some version from 1.6 to 1.8 but not newer (i.e. not 1.9).
Achieving this may be non-trivial, as for example a fresh install on ubuntu 16.04 LTS does not easily fulfill this condition. In such a case, it is the easiest solution to build subversion from source tarball as a standalone binary (not using shared libraries), in the version that eclipse uses, and install and use this under a separate name (e.g. svn18 instead of svn). Building svn will incorporate the steps

./configure --disable-shared
make svn

and installing will look like

sudo cp subversion/svn/svn /bin/svn18

within the svn source directory. You might have to have some prerequisites installed for the build to succeed, i.e. libserf-dev, libapr-dev (precise names may vary) and others, The configure script is supposed to give hints when it fails due to missing dependencies. I suggest to name the resulting executable so that you don't mess up your installed svn package, i.e. svn18 or similar, and don't forget to always use this when dealing with the checked out SoundComp source. This makes you independent from the installed svn version on your system, and from independently happening version upgrades.

Additional prerequisites for building via command line (not yet supported on windows):

• none yet specified

Additional prerequisites for building via eclipse:

• eclipse platform, cdt, jdt
• preferably a subversion provider for eclipse. If you want to use subversion both from command line and eclipse, they MUST use the same main subversion version (e.g. it is not possible to have subversion 1.9 on command line and 1.8 in eclipse). I really suggest that you use the pure java implementation, to be independent from which subversion version is installed otherwise; a connector that relies on what is natively installed it might be difficult to get running if you encounter version conflicts between what you have installed. In really messed up cases I have seen that it was necessary to completely remove eclipse and all its folders (some of them manually after uninstall), also in the home directory, to achieve a working reinstall. I found it easier to get subversive running with svnkit (by adding the relevant update sites in eclipse), but you might also succeed with subclipse and/or other connectors. If you install both subversive and subclipse, both will get their own "svn" entries and pages in eclipse and you won't easily see which is which, but nonetheless it will work.
• if you fail to get subversion running in eclipse, building and running SoundComp should still work if you check out with subversion 1.7 or 1.8 - don't use 1.9 or newer as the svnkit instance used during build is not compatible with this newest svn release. Look under the chapter "common prerequisites" for more info. You just can't use the "team" features in eclipse in such an installation, which makes checking out and committing slightly less comfortable as you have to resort to external svn tools (command line, or on windows tortoise).

Getting started:

If you want to use eclipse and its subversion connectors, install this. Make sure it is working as expected before you continue. Many problems come from not having subversion connectors running correctly later on.
Check out SoundComp via command line svn, unless you want to use eclipse only and your command line svn version does not match. In the latter case you need to check out the project via eclipse, via Import->SVN->Project from SVN,

After the project has been successfully checked out, you are not yet ready to start. The source tree contains build file templates and binaries for a number of platforms; you have to carry out some preparations to get the files for your platform in place and build some libraries that are necessary for building SoundComp on your platform.

1. Configure project files: In the main directory there are configure scripts for a number of platforms.
   They have not been tested for all platforms in all releases, but usually they should more or less do all that is necessary to get the build files in place.
   If no specific file for your platform is available, not all is lost if your platform fulfills the main conditions: C/C++ compiler (preferably gnu style) and JDK are installed. Just look into the script of a mostly similar platform, copy and change it as necessary. You may commit it to svn under the new name when you get it working. If your C/C++-compiler does not support gnu style command lines, this may mean a bit more of work for you.
2. In addition to copying prepared build files, the main configure script sets a link to (or copies) the byacc/j executable in the tools directory. If no such executable is there for your platform: the sources for byacc/j are available as zip file in the tools directory. You can unzip it and build it with your C compiler and copy it as "yacc" in the tools directory. Don't forget that it needs to be executable. It is NOT sufficient to have any package 'yacc' installed in your system, it needs to be the most recent byacc/j variant, which is not everywhere available as installable package - that's why the executable is held in the tools directory..
3. In the "csupport" directory there are several subprojects, 3 of which are presently actually used: helper, flac, monkey. Carry out the configuration scripts in there as well.
4. The first to build of these is the "helper" project. The executable built here detects some hardware attributes and makes them available to the following steps; use its output by writing it to a C include file "intsizes.h" which has to be linked to in or copied to "csrc/includes/intsizes,h". Since this is a 1-file project, it can easily be compiled on the command line via gcc -o inthelper helper.c, followed by ./inthelper ../../csrc/includes/intsizes.h. Of course, you as well can open the cdt project in eclipse and build from there.
5. When the intsizes.h file exists, you never need the helper project again unless you switch target hardware platform, so you can close and forget it in eclipse. You can now build the project "flac" in the directory "flac" and the project "ape" in the director "monkey". Either use the shell scripts, ant "build.xml" files or eclipse projects for these. When you succeeded to build these, you may close and forget these projects as well; they are not supposed to change during development ever. The goal is to have correct "libape.a" and "libflac.a" (the filename suffix may vary between platforms) libraries in csrc/lib.
6. Only when you got that far, it is time to switch to "the real thing", i.e. building and changing SoundComp. You can now open the main project in eclipse (if you use eclipse) or build with "ant -f build.xml" (choose a suitable file for your platform) from the main directory.
7. If your build succeeds, you end up with a SoundComp.jar in the main directory and a libSoundComp.so (or .dll in windows) in the Debug directory. Copy or link the shared library to the main directory.
8. Run a test run with "start.sh" or execute one of the junit tests in de.maramuse.soundcomp.test in eclipse. This should produce a sound file in the main directory.
9. Play the result with a media player program, or (preferable) open it in Audacity, where you can zoom and scroll the wave form while listening. Looking at the waves in Audacity in parallel to listening is probably one of the best ways of learning and debugging.
10. As long as SoundComp is not working as a real compiler, you might have a look at the test case sources to see how you can make it produce sound files without being able to write it in SoundComp language; and you see how SoundComp puts things together internally on the signal processing side. Don't fear to experiment when writing your own testing stuff; you cannot break anything at least as long as you don't commit anything to svn.
11. If you create or change build files like eclipse projects or control files for other IDEs, don't check them in in their original place. Adhere to the scheme used in SoundComp, where build files are copied in place by configure scripts. The reason is that most IDEs hold some project state like opened files, breakpoints and similar stuff in these files, which should not lead to changed files that are committed to subversion on each change. Only when there are substantial changes, copy back your local version to the template directory and commit. Attempt to make build scripts independent from things like source paths and similar; everything should be relative to this path if at all possible. If this will not work, document in a text file and in the wiki where the user will have to change your template according to his system.