| Previous | Index | Next |
This section explains how to:
CLAM source code and third party libraries binaries can be found on our web page --download area-- http://www.iua.upf.es/mtg/clam in both tarball and zip formats.
At this moment CLAM is provided as a source package which is not ment to be compiled as a binary library. Although in the future this is likely to change we provide an automatic build system in order to ease the job to the user (you will find information on this build system in the next chapter).
CLAM depends on other external libraries in order to implement low level task such as XML parsing or cross-platform abstractions (devices, threads, GUI, etc.). This implies that they must be present on your development environment in order to build applications with CLAM.
The full list of libraries CLAM depends on is:
The following sections will give you guidelines on how to deploy them in either GNU/Linux and Windows platforms. If, after having read these instructions, you still have problems please browse through the CLAM mailing list archives or post a new mail to the list if you find that your question has no answer there either.
Your GNU/Linux distribution should have the suited versions for the required libraries. However, it is possible that the normal package has some problems: it is inexistent, it is a wrong version, it is compiled with the non-default compiler, or it is compiled with wrong options.
In case you run on some of the above problems, check if there is a suitable tarball in our web: We provide some compiled libraries for Debian-Woody and Red Hat 9.
If this is not your case, or you still have problems we recommend to download and compile the sources directly.
If you do that take into account these hints:
$./configure --enable-shared --enable-threads --enable-xdbe --enable-xft
To make it easy for Windows users we have precompiled binaries of all the needed libraries. They are available for download in the CLAM web, download section
All of them are generated using Microsoft VisualC++ 7.1.(.NET) although we still keep the ones compiled with VisualC++ 6.0 for backwards compatibility.
Windows has no convention on how to install libraries --both precompiled binaries and development headers. We have configured our build system in order to find libraries at the same directory level than the CLAM root directory.
For example:
devel\CLAM\
devel\fltk\
devel\xercesc\
devel\fftw\
devel\...
Note on fftw: fftw can work on two modes with
different precission and speed: 'float' and 'double'. Both versions
are available on the web and you must make sure that the fftw
directory you place in the same level as CLAM dir must fit with the
value of CLAM_DOUBLE build system variable. (See
chapter III for more details on this).
CLAM uses 'float' as default so to start using CLAM extract the float-version zip.
Note on DLLs: Once you have downloaded all the development kits, you should scan the lib\ subdirectories inside each library folder, and copy all the Dynamic Linking Libraries (.dll) to some place pointed by your system PATH environment variable.
We recommend to create a directory named dll at the same level as the libraries directories. Copy there the dlls and add it to the PATH environment variable.
CLAM provides an automatic build system which allows you to generate and maintain GNU Makefiles and VisualC++ 6/7.1 project files (.dsp/.prj).
This automatic build system is most useful taking in account that at the moment CLAM is not distributed in a compiled (binary) library. Thus it manages to hide to the user all details regarding: necessary implementation files, include dirs, external libraries and compilation flags.
Consider the following source dependency graph:
Without a build system helper you would have to add by hand each .cxx file into your Makefile or Visual project in order to compile it. The CLAM automatic build system uses an small and fast application called srcdeps that finds the source files dependencies.
In the previous example, supposing we say to the srcdeps that we want to compile main.cxx. It would make the following deduction:
'As main.cxx must be compiled and includes both blue.hxx and green.hxx
then blue.cxx and green.cxx must be also compiled'
So, when srcdeps finds a header dependency to Foo.hxx, it looks for the Foo.cxx implementation file. And in the case that it is found, it applies the same search recursively.
Of course additional implementation files --not reachable from dependent headers-- can be specified as starting points. The common case is that only the .cxx with the main function has to be specified.
For each executable --or binary in general-- you want to generate, you must use a file named settings.cfg in order to provide those starting points and other build specifications. See section 19.1 for more details on how to do this.
Because the automatic build system relies on a compiled application srcdeps to do its job, after downloading CLAM we'll need to compile this application. Next section describes how to do it.
In order to keep track of what external libraries to use for each project, and whether they are available, the srcdeps configuration files used by CLAM contain several USE_[feature] and HAS_[feature] variables.
On Windows, the user has to make sure that the HAS_[feature] variables reflect it's system installation, on Linux and MacOSX they are set to 1 or 0 when running the configure script in build/
When srcdeps parses the configuration files, it makes sure that all HAS_[feature] and USE_[feature] variables are consistent. In other words, it will give an error if it noticed that a specific USE_[feature] is set to 1 while the corresponding HAS_[feature] is set to 0
Sometimes, the settings may specify only the use a certain feature when it is indeed possible. This can be done by setting
USE_[feature] = $(HAS_[feature])
See section 19.3 for a full list of these variables.
Looking at a typical srcdeps settings.cfg file, you can see the following files are included (directly or indirectly):
Before continuing, make sure that build/packages-win.cfg file reflects your installation. This file will be read (through includes) when you run srcdeps. If you make any change to this file, you will need to rerun srcdeps.
Open the Visual workspace file srcdeps.dsw located on CLAM_DIR\build\srcdeps\, and compile the srcdeps project. Make sure you are building the binary using the "release" configuration. That's just for efficency reasons.
Visual will leave the output executable srcdeps.exe on the CLAM_DIR\build\srcdeps\ directory. Now we have to configure Visual in order it can automatically execute srcdeps when some CLAM project (.dsp) needs to be redone.
Now we are going to compile the example application "SMSTools2" that comes with CLAM. Doing so you both will be able to play with an application that gives a taste of what CLAM can do, and will confirm --hopefully-- that the CLAM environment is correctly set up.
Open the Visual project SMSTools.dsp which is on CLAM_DIR\build\Examples\SMS\Tools\ and compile it (it takes a while...)
If something went wrong check you followed the above steps and see the Windows Troubleshooting section See section 22.
You can see that the file settings.cfg appears in the project files view. This file defines settings of the project and after any change you are able to apply them to the dsp project by just right clicking over that file and choose 'compile' from the contextual menu. This execute srcdeps taking settings.cfg as a parameter
Important note:
Don't change configuration values or add files directly to the project, instead you should modifiy settings.cfg and re-run srcdeps as explained before. Otherwise you'll lose the manual changes the next time you run srcdeps
Change dir to CLAM_DIR/build/srcdeps and invoke 'make' to build the srcdeps binary.
Once srcdeps has been created, we will check if all the required external libraries. To do so, change dir to CLAM_DIR/build and type:
$ autoconf -f $ ./configure
Now we are going to compile the example application "SMSTools2" that comes with CLAM. Doing so you both will be able to play with an application that gives a taste of what CLAM can do, and will confirm --hopefully-- that the CLAM environment is correctly set up.
Change dir to CLAM_DIR/build/Examples/SMS/Tools/. Execute make CONFIG=release to generate dependencies and compile the sources (it can take a while...).
If something went wrong check you followed the above steps and see the GNU/Linux Troubleshooting section See section 22.
This chapter is a little tutorial for setting up an example application using CLAM and its build system. In first place we're going to compile a given simple application --very straight. And in second place we're going to go through all possible customizations in the build settings that the user might need to set up more complicated projects.
Following this steps you'll get an application which performs an FFT of a random generated audio and stores its spectral equivalent in a file in XML
$ make CONFIG=debugThis will generate the needed dependencies and compile the program
$ ../../CLAM/build/srcdeps/srcdeps settings.cfg
Hopefully we've been able to run the example and play with spectral data in XML. From here we'll see how to customize the build options and to create more complex projects
Here we're going to go through the things you should know when setting your own project that compiles against CLAM and using its automatic build system.
First of all, we assume that you allready have created a root directory for your project
SOURCES = $(TOP)/program_using_clam.cxx
Now we should be ready for a nice compilation !
If we are using gcc just call make CONFIG=[debug|release] standing in the proper directory --where the settings.cfg and Makefile are. This will both generate the dependencies and will compile the project.
Otherwise, if you are stucked with MS Visual run the CLAM srcdeps.exe application from your directory --where the settings.cfg stands-- and you'll get a ready-to-use dsp file.
That's it, hopefully you are compiling your project agains CLAM, without dealing in manualy finding the CLAM sources it needs.
CLAM gives to the user complete support if he wants to use QT to develop his graphical user interfaces. This library uses a special kind of macros in its code that needs a preprocessing step in order to work correctly. In order to activate this support USE_QT=1 must be declared in the settings.cfg file of the project.. There are two kinds of actions:
There are two main kinds of config variables depending on the values they may take:
Note for Windows users: you should use frontslashes '/', as directory separator, instead of backslashes '\', which is the usual way in Windows.
Depending on the effect, there are three kinds of variables:
Now we will see a detailed explanation for each of the variables meaning and possible values.
Note that textual variable values should follow the GNU Makefile variable syntax. See section 21 if you are unfamiliar with GNU Makefile. If you are not working with GNU development tools and you are not interested in learning how to write Makefile scripts then take into account the following.
Note that you can assign several tokens (variable values separated by spaces) to the same variable as in:
PRJ_SEARCH_INCLUDES= ../../../foo/bar/whatever ../../../foo/bar/stuff ../../../foo/bar/thingamajig
sometimes you could have so many tokens that reading the variable assigned value can be hard. Then you may break the tokens into several lines as in:
PRJ_SEARCH_INCLUDES= \
../../../foo/bar/whatever \
../../../foo/bar/stuff \
../../../foo/bar/thingamajig \
note that the backslash, '\', tells srcdeps that the values assigned to PRJ_SEARCH_INCLUDES variable span several lines. Note that whenever you begin a new line you must type in a 'tab' character (spaces are not enough) and when you finish the last line you must ensure it finishes in a newline character (pressing Return should suffice).
TODO: No information about generating a CLAM library binary is available yet
To get some insight on the 'source dependencies issue' and GNU Makefile syntax you may visit the following links:
http://www.eng.hawaii.edu/Tutor/Make/
Microsoft C/C++ ANSI Standard Library run-time binaries come in six different versions: Single Threaded Release, Single Threaded Debug, Multi Threaded Release, Multi Threaded Debug and Multi-threaded with Dynamic Linking Release and Multi-threaded with Dynamic Linking Debug. This multiplicity makes possible the following pitfall: suppose you have some external library, such as FLTK which links statically against, say, the Single Threaded Release version, and then you try to link against FLTK binary ( and, of course the standard library binary ) you get a number of linking errors about duplicate symbols such as malloc, realloc, etc. The way of getting rid of this is to make your project link dynamically against the Multithreaded Dynamic Linking Library. This can be achieved by doing the following: go to Project->Settings ( or ALT+F7 ), select your project from the project browser on the left and then click on the C/C++ tab on the right, select Code Generation option on the Category combo-box and then you will see another combo-box labelled "Use run-time library:". Select there the "Debug Multithreaded DLL" option if your project is in Debug or the "Multithreaded DLL" option if otherwise. Note that this phenomenon not only arises with FLTK: it would be wise configure always the projects in this manner, since it is unharmful and saves many headaches about obscure linking errors.
It is common practice amongst library developers to allow library users to alter some inner mechanisms or configure the library for a concrete platform (either OS, hardware or compiler) by "prefixing" all library source files with a C header file containing some macros that define a concrete behaviour or policy for the library binary. Then the users can undefine or define the necessary macros for obtaining its desired configuration. However, especially under Microsoft Visual Studio it is easy to forget about including this prefixing file. Whenever you get some unexpected or unrelated to your work compiler errors it is wise to check that Visual Studio is prefixing Library sources by doing this: go to Project->Settings (or ALT+F7), select your project from the project browser on the left and then click on the C/C++ tab on the right, and check that inside the Project Options textbox on the right appears the following /FI"config.h". If it doesn't appear add it. If it is there check that your "Additional Include Directories" on the "Pre-processor" category are pointing to.../../src/Defines/Windows. If the compiler still complains then the problem could be elsewhere and that is beyond the scope of this document :).
Usually this pitfall is caused by having not specified to the compiler the needed additional include directories. This can be done by: go to Project->Settings (or ALT+F7), select your project from the project browser on the left and then click on the C/C++ tab on the right, select on the "Category:" combo-box on the right the "Pre-processor" option. Then appears on the right a textbox labelled "Additional include directories:", and then just add the path RELATIVE TO THE DIRECTORY WHERE THE .DSP FILE IS IN YOUR HARD DISK. This could have the form ".../../draft/mything" or something similar.
Just check that your C/C++ Project Settings, on the category Language enable RTTI (Run Time Type Information). If this setting is already set then you should revise your code (and remember that temporaries have not a reliable virtual function table).
The dreaded error messages 'par excellence'. These 'errors' are signalled by Microsoft IDE whenever the compiler dies ungracefully due to a Segmentation Fault. These compiler crashes happen whenever the parser found something extremely standard or some of extremely convoluted C++ code. Here you have a list of possible causes for these errors:
Sometimes, under Windows 2000, and especially whenever you have the option set but you are not using explicitly this Visual C++ feature you may get one these messages. If you do not intend to use them in your project, and you should not, deactivate this option from the project settings.
There are a number of C++ features related to templates that sometimes, even using them 'correctly' will make the parser to die hard. For instance things like:
template < typename A, typename B >
void foo_function( int t )
{
}
template <>
void foo_function< someA, someB >( int t )
{
}
int main( void )
{
foo_function< someA, someB >( 3 );
return 0;
}
The parser will die at the line containing the call to foo_function.
Not closing namespace declarations usually make the parser to die, since for some reason it confounds and match the bracket with the first available. Even if this 'first available bracket' is on another file. This may also happen with scope declarations such as class scopes, loop scopes, etc.
Visual C++ 6.0 behaviour is erratic at best. Some features do not work as expected ( i.e. as stated on the ANSI ) and others, such as references to identifiers declared inside nested namespace from outside those namespace ( i.e. MTG::MTGTest::foo or nasty errors as FFT::FFT::Do ) may kill the parser outright under certain conditions.
Difficult expressions such as
MemFunc &memFunc(*(MemFunc*)(void*)(ftor.memFunc))
are also Microsoft parser's silver bullets.
Visual C++ hosts a quite impressive list of bugs, so this is clearly a sign that you have uncovered some particularly nasty or weird. We cannot give you any outright solutions, since many times we are hassled by this kind of issues. But sometimes rebuilding your project from scratch or disable function-level linking (Incremental linking feature) helps to make thins saner. Good Luck!
Note that when in your code you use #include <something.h> you are telling the compiler that that header can be found in the System Headers path. This feature has a lot of sense under UNIX where you have a /usr/include or similar dir where all headers are neatly deployed. But under Microsoft Visual Studio this can mean two things: that either you have to copy manually the folders with the includes into Microsoft Visual Studio directory/VC98/Include dir or follow our guidelines for creating a sandbox.
This FAQ-like section does not covers all possible issues you might find while using Visual C++ but we hope they solve the most typical of them. Feedback about new issues or alternative solutions to situations described above is welcomed.
The motivation of executing autoconf & configure in CLAM_PATH/build is to check if your system configuration will be able to compile and execute CLAM applications. You can get a lot of different problems related to external libraries, so we have created a compilation of the most common, classified by the step where this problem arises.
You can search in config.log where is the error if the configure stops at the lib checking. Surely it will be related to the installation of fftw, because CLAM needs both versions (float and double) of libs and headers. Please check that.
Check that you use fltk-1.1.4, because some interface has been changed (and some has been created), so the errors can be related to the fltk version you are trying to compile against.
Make sure you have LD_LIBRARY_PATH pointing to all the locations needed
You have a fltk version without this utility (older than 1.1), or the PATH variable doesn't point against its location. Set PATH correctly or download a new version from fltk official web (or the binaries you can get in CLAM web). Anyway, it should work without this program if you have fltk-1.1.4 or newer.
Use QTDIR variable to tell the configure where you have qt (like export QTDIR=/usr/qt/3).
Make sure QTDIR is correctly pointed, and you have a qt version newer to 3.0.
Remove config.cache and rerun autoconf with 2.5X version. (like autoconf-2.57).
You'll need exactly xerces 2.3, because in newer versions they have broken the interface, and CLAM won't be capable of link against it.
Make sure you have LD_LIBRARY_PATH pointing to all the locations needed
checking for std::vector::at() method in libstdc++... no checking for standard sstream header in libstdc++... no checking if stringstream::str() returns std::string in libstdc++... no
Remove config.cache and rerun autoconf with 2.5X version. This error is related to a bug inside autoconf-2.1X combined with gcc-3.X, so you'll need to run an autoconf version newer in order to create a correct configure for this compiler version.
Make sure you have LD_LIBRARY_PATH pointing to all the locations needed. It's needed when you have installed external libraries in a local location. If you have, for example, fltk and xerces installed in the same directory where you have CLAM, you should set LD_LIBRARY_PATH in this way:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/xerces/lib:/path/to/fltk/lib/
| Previous | Index | Next |