SWIG: Doc/Manual/Modules.html

"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.1.1/Doc/Manual/Modules.html" (30 Nov 2022, 14114 Bytes) of package /linux/misc/swig-4.1.1.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 <html> 3 <head> 4 <title>Working with Modules</title> 5 <link rel="stylesheet" type="text/css" href="style.css"> 6 <meta http-equiv="content-type" content="text/html; charset=UTF-8"> 7 </head> 8 9 <body bgcolor="#ffffff"> 10 <H1><a name="Modules">20 Working with Modules</a></H1> 11  12 <div class="sectiontoc"> 13 <ul> 14 <li><a href="#Modules_introduction">Modules Introduction</a> 15 <li><a href="#Modules_nn1">Basics</a> 16 <li><a href="#Modules_nn2">The SWIG runtime code</a> 17 <li><a href="#Modules_external_run_time">External access to the runtime</a> 18 <li><a href="#Modules_nn4">A word of caution about static libraries</a> 19 <li><a href="#Modules_nn5">References</a> 20 <li><a href="#Modules_nn6">Reducing the wrapper file size</a> 21 </ul> 22 </div> 23  24 25 26 27 <H2><a name="Modules_introduction">20.1 Modules Introduction</a></H2> 28 29 30 <p> 31 Each invocation of SWIG requires a module name to be specified. 32 The module name is used to name the resulting target language extension module. 33 Exactly what this means and what the name is used for 34 depends on the target language, for example the name can define 35 a target language namespace or merely be a useful name for naming files or helper classes. 36 Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types. 37 </p> 38 39 <p> 40 The module name can be supplied in one of two ways. 41 The first is to specify it with the special <tt>%module</tt> 42 directive. This directive must appear at the beginning of the interface file. 43 The general form of this directive is: 44 </p> 45 46 <div class="code"><pre> 47 <tt>%module(option1="value1", option2="value2", ...) modulename</tt> 48 </pre></div> 49 50 <p> 51 where the modulename is mandatory and the options add one or more optional additional features. 52 Typically no options are specified, for example: 53 </p> 54 55 <div class="code"><pre> 56 <tt>%module mymodule</tt> 57 </pre></div> 58 59 <p> 60 The second way to specify the module name is with the <tt>-module</tt> command line option, for example <tt>-module mymodule</tt>. 61 If the module name is supplied on the command line, it overrides the name specified by the 62 <tt>%module</tt> directive. 63 </p> 64 65 <p> 66 When first working with SWIG, users commonly start by creating a 67 single module. That is, you might define a single SWIG interface that 68 wraps some set of C/C++ code. You then compile all of the generated 69 wrapper code together and use it. For large applications, however, 70 this approach is problematic---the size of the generated wrapper code 71 can be rather large. Moreover, it is probably easier to manage the 72 target language interface when it is broken up into smaller pieces. 73 </p> 74 75 <p> 76 This chapter describes the problem of using SWIG in programs 77 where you want to create a collection of modules. 78 Each module in the collection is created via separate invocations of SWIG. 79 </p> 80 81 <H2><a name="Modules_nn1">20.2 Basics</a></H2> 82 83 84 <p> 85 The basic usage case with multiple modules is when modules do not have 86 cross-references (ie. when wrapping multiple independent C APIs). In that case, 87 swig input files should just work out of the box - you simply create multiple 88 wrapper .cxx files, link them into your application, and insert/load each in the 89 scripting language runtime as you would do for the single module case. 90 </p> 91 92 <p> 93 A bit more complex is the case in which modules need to share information. 94 For example, when one module extends the class of another by deriving from 95 it: 96 </p> 97 98 <div class="code"><pre> 99 // File: base.h 100 class base { 101 public: 102 int foo(); 103 }; 104 </pre></div> 105   106 107 <div class="code"><pre> 108 // File: base_module.i 109 %module base_module 110 111 %{ 112 #include "base.h" 113 %} 114 %include "base.h" 115 </pre></div> 116   117 118 <div class="code"><pre> 119 // File: derived_module.i 120 %module derived_module 121 122 %{ 123 #include "base.h" 124 %} 125 126 %import "base_module.i" 127 128 %inline %{ 129 class derived : public base { 130 public: 131 int bar(); 132 }; 133 %} 134 </pre></div> 135 136 <p>To create the wrapper properly, module <tt>derived_module</tt> needs to know about the 137 <tt>base</tt> class and that its interface is covered in another module. The 138 line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Often 139 the <tt>.h</tt> file is passed to <tt>%import</tt> instead of the <tt>.i</tt>, 140 which unfortunately doesn't work for all language modules. For example, Python requires the 141 name of module that the base class exists in so that the proxy classes can fully inherit the 142 base class's methods. Typically you will get a warning when the module name is missing, eg: 143 </p> 144 145 <div class="shell"> <pre> 146 derived_module.i:8: Warning 401: Base class 'base' ignored - unknown module name for base. Either 147 import 148 the appropriate module interface file or specify the name of the module in the %import directive. 149 </pre></div> 150 151 <p> 152 It is sometimes desirable to import the header file rather than the interface file and overcome 153 the above warning. 154 For example in the case of the imported interface being quite large, it may be desirable to 155 simplify matters and just import a small header file of dependent types. 156 This can be done by specifying the optional <tt>module</tt> attribute in the <tt>%import</tt> directive. 157 The <tt>derived_module.i</tt> file shown above could be replaced with the following: 158 159 <div class="code"><pre> 160 // File: derived_module.i 161 %module derived_module 162 163 %{ 164 #include "base.h" 165 %} 166 167 %import(module="base_module") "base.h" 168 169 %inline %{ 170 class derived : public base { 171 public: 172 int bar(); 173 }; 174 </pre></div> 175 176 <p> 177 Note that "base_module" is the module name and is the same as that specified in <tt>%module</tt> 178 in <tt>base_module.i</tt> as well as the <tt>%import</tt> in <tt>derived_module.i</tt>. 179 </p> 180 181 <p> 182 Another issue 183 to beware of is that multiple dependent wrappers should not be linked/loaded 184 in parallel from multiple threads as SWIG provides no locking - for more on that 185 issue, read on. 186 </p> 187 188 <H2><a name="Modules_nn2">20.3 The SWIG runtime code</a></H2> 189 190 191 <p> 192 Many of SWIG's target languages generate a set of functions commonly known as 193 the "SWIG runtime." These functions are primarily related to the runtime type 194 system which checks pointer types and performs other tasks such as proper 195 casting of pointer values in C++. As a general rule, the statically typed target 196 languages, such as Java, use the language's built in static type checking and 197 have no need for a SWIG runtime. All the dynamically typed / interpreted 198 languages rely on the SWIG runtime. 199 </p> 200 201 <p> 202 The runtime functions are private to each SWIG-generated module. That is, the 203 runtime functions are declared with "static" linkage and are visible only to the 204 wrapper functions defined in that module. The only problem with this approach is 205 that when more than one SWIG module is used in the same application, those 206 modules often need to share type information. This is especially true for C++ 207 programs where SWIG must collect and share information about inheritance 208 relationships that cross module boundaries. 209 </p> 210 211 <p> 212 To solve the problem of sharing information across modules, a pointer to the 213 type information is stored in a global variable in the target language 214 namespace. During module initialization, type information is loaded into the 215 global data structure of type information from all modules. 216 </p> 217 218 <p> 219 There are a few trade offs with this approach. This type information is global 220 across all SWIG modules loaded, and can cause type conflicts between modules 221 that were not designed to work together. To solve this approach, the SWIG 222 runtime code uses a define SWIG_TYPE_TABLE to provide a unique type table. This 223 behavior can be enabled when compiling the generated _wrap.cxx or _wrap.c file 224 by adding -DSWIG_TYPE_TABLE=myprojectname to the command line argument. 225 </p> 226 227 <p> 228 Then, only modules compiled with SWIG_TYPE_TABLE set to myprojectname will share 229 type information. So if your project has three modules, all three should be 230 compiled with -DSWIG_TYPE_TABLE=myprojectname, and then these three modules will 231 share type information. But any other project's types will not interfere or 232 clash with the types in your module. 233 </p> 234 235 <p> 236 Another issue relating to the global type table is thread safety. If two modules 237 try and load at the same time, the type information can become corrupt. SWIG 238 currently does not provide any locking, and if you use threads, you must make 239 sure that modules are loaded serially. Be careful if you use threads and the 240 automatic module loading that some scripting languages provide. One solution is 241 to load all modules before spawning any threads, or use SWIG_TYPE_TABLE to 242 separate type tables so they do not clash with each other. 243 </p> 244 245 <p> 246 Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in Lib/swigrun.swg and 247 near the top of every generated module. This number gets incremented when the 248 data structures change, so that SWIG modules generated with different versions 249 can peacefully coexist. So the type structures are separated by the 250 (SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION) pair, where by default SWIG_TYPE_TABLE 251 is empty. Only modules compiled with the same pair will share type information. 252 </p> 253 254 <H2><a name="Modules_external_run_time">20.4 External access to the runtime</a></H2> 255 256 257 <p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>, 258 the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need 259 to be called. Calling these functions from a typemap is supported, since the typemap code 260 is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need 261 to call the SWIG run-time functions from another C file, there is one header you need 262 to include. To generate the header that needs to be included, SWIG can be run in a different 263 mode via <tt>-external-runtime</tt> to generate the run-time instead of the normal mode of 264 processing an input interface file. For example: 265 266 <div class="shell"><pre> 267 $ swig -python -external-runtime <filename> 268 </pre></div> 269 270 <p>The filename argument is optional and if it is not passed, then the default filename will 271 be something like <tt>swigpyrun.h</tt>, depending on the language. This header file should 272 be treated like any of the other _wrap.c output files, and should be regenerated when the 273 _wrap files are. After including this header, your code will be able to call <tt>SWIG_TypeQuery</tt>, 274 <tt>SWIG_NewPointerObj</tt>, <tt>SWIG_ConvertPtr</tt> and others. The exact argument parameters 275 for these functions might differ between language modules; please check the language module chapters 276 for more information.</p> 277 278 <p>Inside this header the functions are declared static and are included inline into the file, 279 and thus the file does not need to be linked against any SWIG libraries or code (you might still 280 need to link against the language libraries like libpython-2.3). Data is shared between this 281 file and the _wrap.c files through a global variable in the scripting language. It is also 282 possible to copy this header file along with the generated wrapper files into your own package, 283 so that you can distribute a package that can be compiled without SWIG installed (this works 284 because the header file is self-contained, and does not need to link with anything).</p> 285 286 <p> 287 This header will also use the -DSWIG_TYPE_TABLE described above, so when 288 compiling any code which includes the generated header file should define the 289 SWIG_TYPE_TABLE to be the same as the module whose types you are trying to 290 access. 291 </p> 292 293 <H2><a name="Modules_nn4">20.5 A word of caution about static libraries</a></H2> 294 295 296 <p> 297 When working with multiple SWIG modules, you should take care not to use static 298 libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection 299 of SWIG modules with that library, each module will get its own private copy of the library code inserted 300 into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program 301 behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries. 302 </p> 303 304 <H2><a name="Modules_nn5">20.6 References</a></H2> 305 306 307 <p> 308 Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult 309 an outside reference. John Levine's "Linkers and Loaders" is highly recommended. 310 </p> 311 312 <H2><a name="Modules_nn6">20.7 Reducing the wrapper file size</a></H2> 313 314 315 <p> 316 Using multiple modules with the <tt>%import</tt> directive is the most common approach to modularising large projects. 317 In this way a number of different wrapper files can be generated, thereby avoiding the generation of a single large wrapper file. 318 There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features. 319 </p> 320 321 <p> 322 <b>-fcompact</b><br> 323 This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file. 324 It simply removes blank lines and joins lines of code together. 325 This is useful for compilers that have a maximum file size that can be handled. 326 </p> 327 328 <p> 329 <b>-fvirtual</b><br> 330 This command line option will remove the generation of superfluous virtual method wrappers. 331 Consider the following inheritance hierarchy: 332 </p> 333 334 <div class="code"> 335 <pre> 336 struct Base { 337 virtual void method(); 338 ... 339 }; 340 341 struct Derived : Base { 342 virtual void method(); 343 ... 344 }; 345 </pre> 346 </div> 347 348 <p> 349 Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>. 350 Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have 351 a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>. 352 </p> 353 354 <p> 355 <b>%feature("compactdefaultargs")</b><br> 356 This feature can reduce the number of wrapper methods when wrapping methods with default arguments. The section on <a href="SWIGPlus.html#SWIGPlus_default_args">default arguments</a> discusses the feature and its limitations. 357 </p> 358 359 </body> 360 </html>