This directory provides the user with an example of using CLAM for her own programs. So it is ment to be copied somewhere out of CLAM dir tree and it will be ready to compile with a little adjustment in one file

How to set up your own programs using CLAM

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.

An out-of-the-box example

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

1. Copy this directory structure (compiling_against_CLAM_example) somehere outside the CLAM dir tree. We recommend to place it just in the same level as the CLAM root. (in the same parent dir)
   Note that this directory, apart from the .cxx file with a main function, contains a subdir named build/ with the configuration files necessary to use the automatic CLAM build
   Hint: in linux, cp -ar <src> <dst> copies a directory recursively
2. Edit the build/clam-location.cfg and change CLAM_PATH so it points to the CLAM dir --maybe you'll find that this value is already properly set.
3. At this point we need to have srcdeps already compiled. How to do this is explained in this section [?] of the documentation.
4. Now our way forks depending on the choosed compiler
   • gcc
     Just call make with 'debug' or 'release' as argument:

     $ make CONFIG=debug

     This will generate the needed dependencies and compile the program
   • MS Visual 6
     The first time we'll need to generate the .dsp file. For that we'll need to use the command line.
     • change your current dir to the buid subdir of our example directory
     • from this dir execute the srcdeps --which is in the CLAM/build/srcdeps dir-- passing the settings.cfg as argument. For example:

       $ ../../CLAM/build/srcdeps/srcdeps settings.cfg

     • srdeps generate a .dsp with the smallest subset of the CLAM implementation files needed to compile the example.
     • further runs of srcdeps can be achieved directly from the MS Visual IDE (compile settings.cfg). See more details in [?]

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

Customizing your project

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

• modify clam_location.cfg making the CLAM_PA
• we recomend to create a buid/ directory inside your project dir. There you're going to place all the configuration files that the build-system needs. There you must copy --from the compiling_against_clam_example dir-- the following files:
  • clam-location.cfg
  • defaults.cfg
  • Makefile
  • Makefiles.rules
  • settings.cfg
  • system.cfg
• maybe you'll like to organize your code starting from a src/ directory. This is up to you but has to be taken in account when configuring the build files
• modify clam_location.cfg making the CLAM_PATH variable to point to the CLAM root directory. Either you can use an absolute or relative path.
• modify the TOP variable of Makefile. It must point to your project root dir. Its value should probably be just ../ but is also feasible that you want to spread severals Makefiles in different subdirectories of build/ thus the TOP variable must be defined accordingly.
• settings.cfg is the most important file you'll need to tweek. Notice that if you want too build several executables you'll need to create a directory for each one containing both settings.cfg and Makefile.
  What follows is a list of the settings.cfg variables you might need to modify. See [?] for more details.
  • TOP: must point to your project root.
  • PROGRAM: the name of your binary --the executable.
  • various library flags: changing its value {0,1} you can choose to link or not against several libraries (i.e. fltk, fftw, xerces-c, etc)
  • PRJ_SEARCH_INCLUDES: the directories that contains your headers. Notice that you don't have to add any CLAM directory here.
  • PRJ_SEARCH_RECURSE_INCLUDES: the same as before but now including all the recursive directory tree
  • SOURCES: all the entry points: the implementation files (i.e. .cxx files) that you'll want to compile and can not be automatically deduced. Write the source files relative to the TOP. I.e.:

    SOURCES = $(TOP)/program_using_clam.cxx

    
    Normally you'll only need to include the implementation file that contains the main function.
  • Note: More info about how the CLAM automatic build system works can be found in [?]

  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.

Remember to see the Build System chapter in CLAM documentation for further details.