INTERROGATE(1)

NAME
interrogate - generate scripting language bindings for C/C++ APIs

SYNOPSIS
interrogate [ opts ] file.C [ file.C ... ]

DESCRIPTION
Interrogate is a program to parse a body of C++ code and build up a table of classes, methods, functions, and symbols found, for the purposes of calling into the codebase via a non-C++ scripting language like Scheme, Smalltalk, or Python.

In addition to identifying all the classes and their relationships, interrogate will generate a wrapper function for each callable function. The wrapper functions will be callable directly from the scripting language, with no understanding of C++ necessary; these wrapper functions will in turn call the actual C++ functions or methods.

Most exportable features of C++ are supported, including templates, default parameters, and function overloading.

OPTIONS

-oc output.C
    Specify the name of the file to which generated code will be written. This includes all of the function wrappers, as well as those tables which must be compiled into the library.

-od output.in
    Specify the name of the file to which the non-compiled data tables will be written. This file describes the relationships between all the types and the functions, and associates the function wrappers above with this data. This file will be opened and read at runtime when the scripting language first calls some interrogate query function.

-srcdir directory
    Specify the name of the directory to which the source filenames are relative.

-module module_name
    Defines the name of the module this data is associated with. This is strictly a code-organizational tool. Conceptually, a module is the highest level of grouping for interrogate data; a module may contain several libraries. If this is omitted, no module name is specified.

Sometimes, depending on the type of wrappers being generated, there may be additional code that needs to be generated on the module level, above that which was already generated at the library level. Python, for instance, generates the table of python-callable function wrappers at the module level. Use the program interrogate_module(1) to generate the appropriate code at the module level.

-library library_name
    Defines the name of the library this data is associated with. This is another code-organizational tool. Typically, there will be one invocation of interrogate for each library, and there will be multiple libraries per module. If this is omitted, no library name is specified.

-do-module
    Generate whatever module-level code should be generated immediately, rather than waiting for a special interrogate_module(1) pass. This, of course, prohibits grouping several libraries together into a single module.

-fptrs
    Make void* pointers to the function wrappers directly available. A scripting language will be able to call the interrogate functions directly by pointer.

-fnames
    Make the names of the function wrappers public symbols so that the scripting language will be able to call the interrogate functions by name.

Either or both of -fptrs and/or -fnames may be specified. If both are omitted, the default is -fnames.

-string
    Treat char* and basic_string<char> as special cases, and map parameters of these types to type atomic string. The scripting language will see only functions that receive and return strings, not pointers to character or structures of basic_string<char>. If C calling convention wrappers are being generated, the atomic string type means type char*. In any other calling convention, the atomic string type is whatever the native string type is.

-refcount
    Treat classes that inherit from a class called ReferenceCount as a special case. Any wrapper function that returns a pointer to one of these classes will automatically increment the reference count by calling ref() on the object first, and any destructors that are generated will call unref_delete() on the object instead of simply delete.

Furthermore, parameters of type PointerTo<N> or ConstPointerTo<N> will automatically be mapped to N * and const N *, respectively.

-assert
    Generate code in each wrapper that will check the state of the assert flag and trigger an exception in the scripting language when a C++ assertion fails. Presently, this only has meaning to the Python wrappers.

-true-names
    Use the actual name of the function being wrapped as the name of the generated wrapper function, instead of an ugly hash name. This means the wrapper functions may be called directly using a meaningful name (especially if -fnames is also given), but it also means that C++ function overloading (including default values for parameters) cannot be used, as it will lead to multiple wrapper functions with the same name.

-c  Generate function wrappers using the C calling convention. Any scripting language that can call a C function should be able to make advantage of the interrogate database.

-python
    Generate function wrappers using the Python calling convention. The shared library will be directly loadable as a Python module (especially if the module definitions are made available either by running interrogate_module(1) later, or by specifying -do-module on the command line now). However, C++ objects and methods will be converted into an object handle and a list of independent Python functions.

-python-obj
    Generate Python function wrappers that convert C++ objects to true python objects, with all methods converted to Python methods. This is currently experimental.

-python-native
    Generate Python function wrappers that convert C++ objects to true python objects, with all methods converted to Python methods. This is the recommended method for creating Python wrappers.

Any combination of -c, -python, or -python-obj may be specified. If all are omitted, the default is -c.

-track-interpreter
    Generate code within each wrapper function to adjust the global variable "in_interpreter" to indicated whether code is running within the Panda C++ environment or within the high-level language.

-unique-names
    Compile a table into the library (i.e. generate code into the -oc file) that defines a lookup of each function wrapper by its unique name. This makes it possible to consistently identify function wrappers between sessions, at the cost of having this additional table in memory.

-nodb
    Do not build a full interrogate database, but just generate function wrappers. It is assumed that the user will know how to call the function wrappers already, from some external source. This is most useful in conjunction with -true-names.

-longlong typename
    Specify the name of the 64-bit integer type for the current compiler. By default, this is "long long".

-promiscuous
    Export *all* public symbols, functions, and classes seen, even those not explicitly marked to be published.

-spam
    Generate wrapper functions that report each invocation to Notify. This can sometimes be useful for tracking down bugs.

-noangles
    Treat #include <file> the same as #include "file". This means -I and -S are equivalent.

SEE ALSO
interrogate_module(1), test_interrogate(1)