diff --git a/Doc/Manual/Pike.html b/Doc/Manual/Pike.html new file mode 100644 index 000000000..c258c0a23 --- /dev/null +++ b/Doc/Manual/Pike.html @@ -0,0 +1,129 @@ + + + + SWIG and Pike + + + +

SWIG and Pike
+

+This chapter describes SWIG support for Pike. As of this writing, the +SWIG Pike module is still under development and is not considered +ready for prime time. The Pike module is being developed against the +Pike 7.4.10 release and may not be compatible with previous versions +of Pike.

+ +This chapter covers most SWIG features, but certain low-level details +are covered in less depth than in earlier chapters. At the very +least, make sure you read the "SWIG Basics" +chapter.
+

Preliminaries

+

Running SWIG

+Suppose that you defined a SWIG module such as the following: +
+ 
%module example

%{
#include "example.h"
%}

int fact(int n);
+
+To build a C extension module for Pike, run SWIG using the -pike option : +
+ 
$ swig -pike example.i
+
+If you're building a C++ extension, be sure to add the -c++ option: +
+ 
$ swig -c++ -pike example.i
+
+This creates a single source file named example_wrap.c (or example_wrap.cxx, if you +ran SWIG with the -c++ option). +The SWIG-generated source file contains the low-level wrappers that need +to be compiled and linked with the rest of your C/C++ application to +create an extension module.

+ +The name of the wrapper file is derived from the name of the input +file. For example, if the input file is example.i, the name +of the wrapper file is example_wrap.c. To change this, you +can use the -o option: +

+ 
$ swig -pike -o pseudonym.c example.i
+
+

Getting the right header files

+In order to compile the C/C++ wrappers, the compiler needs to know the +path to the Pike header files. These files are usually contained in a +directory such as +

+
+ 
/usr/local/pike/7.4.10/include/pike
+
+There doesn't seem to be any way to get Pike itself to reveal the +location of these files, so you may need to hunt around for them. +You're looking for files with the names global.h, program.h +and so on. + +

Using your module

+To use your module, simply use Pike's import statement: + +
+$ pike
+Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
+> import example;
+> fact(4);
+(1) Result: 24
+
+ +

Basic C/C++ Mapping

+ +

Modules

+All of the code for a given SWIG module is wrapped into a single Pike +module. Since the name of the shared library that implements your +module ultimately determines the module's name (as far as Pike is +concerned), SWIG's %module directive doesn't really have any +significance. + +

Functions

+Global functions are wrapped as new Pike built-in functions. For +example, + +
+%module example
+
+int fact(int n);
+
+ +creates a new built-in function example.fact(n) that works +exactly as you'd expect it to: + +
+> import example;
+> fact(4);
+(1) Result: 24
+
+ +

Global variables

+ +Global variables are currently wrapped as a pair of of functions, one to get +the current value of the variable and another to set it. For example, the +declaration + +
+%module example
+
+double Foo;
+
+ +will result in two functions, Foo_get() and Foo_set(): + +
+> import example;
+> Foo_get();
+(1) Result: 3.000000
+> Foo_set(3.14159);
+(2) Result: 0
+> Foo_get();
+(3) Result: 3.141590
+
+ +

Constants and enumerated types

+ +Enumerated types in C/C++ declarations are wrapped as Pike constants, +not as Pike enums. +