Copyright, License, Contact =========================== Copyright ©2013 Franz All Rights Reserved License: TBD Author: Jianshi Huang (jianshi.huang@gmail.com) Build Netica Shared Library on Linux ==================================== Assume you're using x86 64bit Linux. Tested on Ubuntu 12.04 x8664 % gcc -shared -fPIC -INetica_API_504/src -LNetica_API_504/lib \ Netica_API_504/src/NeticaEx.c Netica_API_504/lib/64bit/libnetica.a \ -lm -lrt -lpthread -lstdc++ -o lib/libnetica.so.5.0.4 Development notes ================= There're about 250 functions in Netica C API, and dozens of other definitions. I used SWIG for generating the C API wrappers for eliminating human mistakes and saving time. Due to SWIG's limitation, a modified Netica header file and a hand-written patch are needed. The good news is that C API support is mostly done (except Listener functions which need callbacks, will add later). The SWIG interface definition is pretty straightforward, I only need to deal with output parameters. Note that there's a bug in SWIG that 'char** OUTPUT' will not be recognized. This is manually fixed in the patch. The header file needs fix as well. 'enum' without 'typedef' will not be recognized by SWIG; In the form 'typedef struct <name> <alias>', <name> will be used as lisp class name rather than <alias>. These are manually fixed. And I've found several bugs in CLisp's netica implementation and RNetica. As for Lisp-side API, it's a big task. CLisp only implements very basic ones. These are ported in src/netica.cl. RNetica seems to be a good reference, but still, it only implements 2/5 of the Netica API. Compile SWIG interface ---------------------- % swig -allegrocl -nocwrap -identifier-converter \ identifier-convert-lispify -module netica.ffi \ -Iinclude src/netica.i This will generate src/netica.ffi.cl file. Manual modification ------------------- - in src/netica.ffi.cl Change (ff:allocate-fobject ':char :c) to (ff:allocate-fobject ':char :c *mesg-len-ns*) NOTE: SWIG's support of string size doesn't seem working Package structure ----------------- - Package netica.ffi is the low-level wrapper for Netica's C API - Package netica is for Netica's Lisp interface, and the demonstration of using the low-level C API - Package netica.demo is for demonstration Lisp interface usage User Guide ========== C API support is almost done, getting familiar with C API usage is important. Currently only several Lisp interfaces are implemented. Use netica.cl as a reference for implementing your own Lisp interface. It's likely you'll use both Lisp interface and C API. You cannot have multiple netica instances, but you can call Netica API from multiple threads. All errors are checked and properly reported. Severe errors are signaled (error), less severe ones are warned, messages are printed out if *verbose* is true. Basic usage ----------- (load "defsystem.cl") (load-system :netica :compile t) ... (use-package :netica) (setf *license* "<your license>") (start-netica) ... ... ... (close-netica) Naming convention ----------------- Currently Lisp convention is enforced. For example, (in C) GetNodeNamed_bn ==> (in Lisp) get-node-named-bn Calling convention ------------------ C functions may return multiple values by output parameters (pointer arguments). Here are the conversion rules for output parameters. - for scalar values (int*, double*, state_bn*, etc.) and strings (char*), we will convert them to lisp values and return multiple values. The output parameter will be removed from the function signature. - for other values like arrays (state_bn*, double*, etc.) and structs (net*, node*, etc.), we will not return them as multiple values and you need to pass them to the function. When function returns, values passed in will get updated (so you need to hold them in variables). Notes for using Netica's C API in Lisp -------------------------------------- Use *null* for NULL. Use (truep ...), (nullp ...) for testing. Condition --------- - netica-condition - netica-error Documentation ------------- Please check the docstring of functions, or source file netica.cl. TODO ==== - More Lispy interface Current Lisp wrapper is minimal (ported from CLisp). RNetica is a good reference. - Return proper typed foreign pointers For struct object, SWIG generates proper CLOS definitions (subclass of foreign-pointer), but they're not used in function return types. So all non-primitive value returned is a foreign-pointer and the type information is lost. Need to fix SWIG. - Add NeticaEx.h support or implement Lisp equivalent Need to deal with varargs. So porting to Lisp seems a better choice. - Lisp callback support Used only by Netica's listener API. This will mark the full implementation of C API :) - More tests and examples