-This will generate an example_wrap.c file or, in the latter case, example_wrap.cxx file, along with example_proxy.h and example_proxy.c files. The name of the file is derived from the name of the input file. To change this, you can use the -o option common to all language modules. +This will generate an example_wrap.c file or, in the latter case, example_wrap.cxx file, along with example_wrap.h (the same extension is used in both C and C++ cases for the last one). The names of the files are derived from the name of the input file by default, but can be changed using the -o and -oh options common to all language modules.
-The wrap file contains the wrapper functions, which perform the main functionality of SWIG: it translates the input arguments from C to C++, makes calls to the original functions and marshalls C++ output back to C data. The proxy header file contains the interface we can use in C application code. The additional .c file contains calls to the wrapper functions, allowing us to preserve names of the original functions. +The xxx_wrap.c file contains the wrapper functions, which perform the main functionality of SWIG: each of the wrappers translates the input arguments from C to C++, makes calls to the original functions and marshals C++ output back to C data. The xxx_wrap.h header file contains the declarations of these functions as well as global variables.
-The following table list the additional commandline options available for the C module. They can also be seen by using: +The following table list the additional command line options available for the C module. They can also be seen by using:
@@ -131,11 +131,6 @@ $ swig -c -helpC specific options -- --noproxy -do not generate proxy files (i.e. filename_proxy.h and filename_proxy.c) --noexcept generate wrappers with no support of exception handling; see Exceptions chapter for more details @@ -153,8 +148,7 @@ The next step is to build a dynamically loadable module, which we can link to ou$ swig -c example.i $ gcc -c example_wrap.c -$ gcc -c example_proxy.c -$ gcc -shared example_wrap.o example_proxy.o -o libexample.so +$ gcc -shared example_wrap.o -o libexample.so@@ -164,8 +158,7 @@ Or, for C++ input:
$ swig -c++ -c example.i $ g++ -c example_wrap.cxx -$ gcc -c example_proxy.c -$ g++ -shared example_proxy.o example_wrap.o -o libexample.so +$ g++ -shared example_wrap.o -o libexample.so@@ -176,7 +169,7 @@ Now the shared library module is ready to use. Note that the name of the generat
-The simplest way to use the generated shared module is to link it to the application code during the compilation stage. We have to compile the proxy file as well. The process is usually similar to this: +The simplest way to use the generated shared module is to link it to the application code during the compilation stage. The process is usually similar to this:
@@ -184,14 +177,14 @@ $ gcc runme.c -L. -lexample -o runme-This will compile the application code (runme.c), along with the proxy code and link it against the generated shared module. Following the -L option is the path to the directory containing the shared module. The output executable is ready to use. The last thing to do is to supply to the operating system the information of location of our module. This is system dependant, for instance Unix systems look for shared modules in certain directories, like /usr/lib, and additionally we can set the environment variable LD_LIBRARY_PATH (Unix) or PATH (Windows) for other directories. +This will compile the application code (runme.c) and link it against the generated shared module. Following the -L option is the path to the directory containing the shared module. The output executable is ready to use. The last thing to do is to supply to the operating system the information of location of our module. This is system dependant, for instance Unix systems look for shared modules in certain directories, like /usr/lib, and additionally we can set the environment variable LD_LIBRARY_PATH (Unix) or PATH (Windows) for other directories.
36.3 Basic C wrapping
-Wrapping C functions and variables is obviously performed in a straightforward way. There is no need to perform type conversions, and all language constructs can be preserved in their original form. However, SWIG allows you to enchance the code with some additional elements, for instance using check typemap or %extend directive. +Wrapping C functions and variables is obviously performed in a straightforward way. There is no need to perform type conversions, and all language constructs can be preserved in their original form. However, SWIG allows you to enhance the code with some additional elements, for instance using check typemap or %extend directive.
36.3.1 Functions
@@ -221,16 +214,6 @@ int _wrap_gcd(int arg1, int arg2) { } --Then again, this wrapper function is usually called from C using helper function declared in proxy file, preserving the original name: -
- ---int gcd(int arg1, int arg2) { - return _wrap_gcd(arg1,arg2); -} -Now one might think, what's the use of creating such functions in C? The answer is, you can apply special rules to the generated code. Take for example constraint checking. You can write a "check" typemap in your interface file:
@@ -501,7 +484,7 @@ Let's assume we have the following C++ interface file, we'd like to generate cod What we would like to generate as a C interface of this function would be something like this:-When we generate the bindings, we generate code for two translation units: --//proxy header file +// wrapper header file typedef struct SwigObj_SomeClass SomeClass; SomeClass * new_SomeClass(); @@ -518,15 +501,8 @@ SomeIntTemplateClass * new_SomeIntTemplateClass(); void delete_SomeIntTemplateClass(SomeIntTemplateClass * carg1);-
-We need 2 translation units to be able to have C types with the same names as the original C++ types. -- The proxy
-- The wrapper
-The Wrapper
-Since the proxy embeds a call to the wrapper function, we'll examine the generation of the wrapper function first. +We'll examine the generation of the wrapper function first.If it's a C++ function that is wrapped (in this case it is), another variable is emitted for the 'original' return value of the C++ function. -At this point, we simply 'inject' behavior if it's a C++ function that is wrapped (in this cas it obviously is). +At this point, we simply 'inject' behavior if it's a C++ function that is wrapped (in this case it obviously is).SWIGEXPORTC SwigObj * _wrap_someFunction(SwigObj * carg1, int carg2) { @@ -593,7 +569,7 @@ int arg2 ;cppouttype @@ -639,11 +615,12 @@ return result;The Proxy
-Compared to the wrapper code generation, the proxy code is very simple. -Basically it just casts types for the wrapper call. Let's have a look at the corresponding proxy header file code of the interface above. +Compared to the wrapper code generation, the header code is very simple. +Basically it contains just the declarations corresponding to the definitions +above.-For shortness sake, we'll only examine one function that uses all proxy typemaps, as the other functions are analogous. - --//proxy header file +// wrapper header file typedef struct SwigObj_SomeClass SomeClass; SomeClass * new_SomeClass(); @@ -660,33 +637,8 @@ SomeIntTemplateClass * new_SomeIntTemplateClass(); void delete_SomeIntTemplateClass(SomeIntTemplateClass * carg1);- -Again, let's first examine the protype: --SomeClass* someFunction(SomeIntTemplateClass* carg1, int carg2) { - return (SomeClass*)_wrap_someFunction((SwigObj *)carg1, (int)carg2); -} -- -In the body of this function, we'll reuse the 'proxycouttype' and 'ctype' to cast the return value and arguments of the wrapper function. - --ctype ctype ctype ----------- --------------------- --- -SomeClass* someFunction(SomeIntTemplateClass* carg1, int carg2); --- ctype cmodtype cmodtype - ---------- --------- ___ -return (SomeClass*)_wrap_someFunction((SwigObj *)carg1, (int)carg2); -36.5 Exception handling