Defining External Functions in C++

You can define you own external functions in ccli. This is very useful for interfacing ccli with other APIs, such as the GTK, or to low level hardware code. In this section we outline how to do this. The procedure is, roughly:

1. Define a C++ function
2. Compile it into a shared object library
3. Delcare it within a ccli file

It is easiest to explain with an example. The rest of this section shows how the cos function is defined.

First, in standard/ccl_math.cc, we define the C++ function

#include <math.h>
#include "SymbolTable.hh"

extern "C" Value * ccl_cos ( list<Value *> * args ) {
  return new Value ( cos ( (*args->begin())->num_value() ) );
}

All external function definitions must be declared this way. The external "C" part tells the C++ compiler to use C naming conventions, important for making shared object code usable by other modules. The return value must be Value *, a pointer to a Value object. The Value class is defined in "SymbolTable.hh". The argument is a list of values (to be computed from within ccli when the function is called). We use the STL list template to define lists.

The body of the function makes a new value using the Value ( double ) constructor and the C++ cos function. The argument to the cos function is the numerical value of the first value in the argument list.

To compile, you do something like

g++ -shared -o ccl_math.so ccl_math.cc -I \$(CCL_ROOT)/base

where ccl_math.cc is the name of the file containing the aboce function. Look at standard/Makefile for details.

From within a ccl file you declare the cos function as in

external real cos ( real ) "libcclmath.so" "ccl_cos";

This declaration states that the symbol cos should be considered to be an external function that takes a single real value and returns a single real value. This type information is needed by ccli because, without access to its C++ definition, ccli is not able to infer the type of the function. Furthermore, the declaration tells ccli to find the object code for the function in the file libcclmath.so, which should be either in the current directory or in a directory listed in the LD_LIBRARY_PATH environment variable. The last argument gives the name of the C++ function, in this case ccl_cos, within the shared object library.

For more information, see the code in the standard and graphics directories. Also, learn about shared object libraries by reading the dlopen man page (i.e. man dlopen).