Verrazano depends on the following libs:
| ASDF | should be already set up in one way or another |
| S-XML | cvs -d:pserver:anonymous@common-lisp.net:/project/s-xml/cvsroot co s-xml |
| cl-ppcre | |
| Alexandria | darcs get --partial http://common-lisp.net/project/alexandria/darcs/alexandria |
| Iterate | darcs get --partial http://common-lisp.net/project/iterate/darcs/iterate |
| trivial-shell | darcs get --partial http://common-lisp.net/project/trivial-shell/darcs/trivial-shell |
| parse-number | |
| CFFI | darcs get --partial http://common-lisp.net/project/cffi/darcs/cffi/ |
| GCC-XML | Verrazano should offer a restart to check out the gccxml repo if the gccxml executable cannot be found, but for reference: cvs -d :pserver:anoncvs@www.gccxml.org:/cvsroot/GCC_XML co gccxml. |
It is recommended that to use the latest version of all the dependencies.
Verrazano itself is distributed in two parts, corresponding to two directories in the repository. The main program is in the 'verrazano' module, while the support library, is in the 'verrazano-support' module. The support library is a dependency of verrazano-generated bindings, and so must be visible by ASDF.
Verrazano is distributed with a number of pre-generated bindings, these are located in the 'bindings' subdirectory. There are some tests under 'testsuite' that can be run to try the bindings. You can run them with "(lisp) --load cairo.lisp". The generated bindings link to the libraries they bind, just like C code. As a general rule, if the system can build C programs using the libraries in question, it should be able to build Lisp programs doing the same. Note that the 'vfun' demo is not a real, useful library. It's simply a test of the virtual function mechanism, and its source is distributed with the demo.
To generate a binding you need to provide all the necessary information to Verrazano. The configuration class needs to be instantiated and filled in with the required data using make-configuration. When you have it ready, you should call generate-binding providing a backend, which should preferrably be :cffi (at the time of writing this is the preferred and the only working backend).
There are two mandatory arguments: the binding name and the header files to scan. Other then these you can specify various other options, please consult the source for details. Please note that it's not enough to provide a 'root' header file that includes the other headers, because Verrazano will only generate bindings for those definitions that were defined in a header file that was explicitly listed in the configuration.
(generate-binding
(make-configuration :vfun-cffi-bindings
'("vfun.h")
:package-nicknames '(:some-nicknames)
:working-directory (verrazano::system-relative-pathname
:verrazano "../testsuite/vfun/")
:gccxml-flags "-I.")
:cffi)
The specified header files are evaluated as if they were passed to an '#include "header.h"' declaration in a C source file. Specifically, the standard header-file search mechanism for the host compiler is used to find the target header file. The header-inclusion mechanism is recursive: if "header.h" includes "header-support.h", there is no need to specify both in the 'include' form. However, the standard C warnings about depending on header-internal organization apply. The 'export' form takes as its parameters a list of strings specifying symbols that should be exported from the generated package. These symbols are in the namespace of the target language, so if "MyWidget::do_foo" maps to "my-widget-do-foo" in the binding, the latter should be specified in the export declaration.
The resultant Lisp file is a standalone file that only needs the verrazano-support and cffi ASDF systems.
The input files used by Verrazano are not, at least at the moment, independent of the host's software configuration. They must be modified to accomodate the numerous differences that exist between the compiler configurations of various hosts. For example, on Windows, it is common to put the include files for a library in a seperate subdirectory, and add that subdirectory to the compiler's search list. On UNIX, include files are commonly in a few global directories, and no such extra step is necessary. To accomodate these differences, the 'gccxml-flags' form of the configuration object must be used. For example, let's consider the OpenAL binding example on a machine that uses the Borland C++ Builder compiler suite. Let's assume that the OpenAL libraries are installed in "C:\OpenAL". To reflect this build setup, we can modify the 'gccxml-flags' form in the input file to read:
(... :gccxml-flags "--gccxml-compiler bcc32 -IC:\\OpenAL\\include\\" ...)
The first element of the flags parameter, '--gccxml-compiler', signals to GCC-XML that it should emulate the Borland C++ compiler instead of GCC (the default). The second element adds the OpenAL header directory to the compiler's include file search path. Without these additional flags, GCC-XML would not be able to find the correct compiler to use, nor the location of the OpenAL header files.