diff options
Diffstat (limited to 'Doc/Manual/Preprocessor.html')
| -rw-r--r-- | Doc/Manual/Preprocessor.html | 124 |
1 files changed, 97 insertions, 27 deletions
diff --git a/Doc/Manual/Preprocessor.html b/Doc/Manual/Preprocessor.html index 3d1bb453e..e4d4425d5 100644 --- a/Doc/Manual/Preprocessor.html +++ b/Doc/Manual/Preprocessor.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Preprocessor">10 Preprocessing</a></H1> +<H1><a name="Preprocessor">11 Preprocessing</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -38,7 +38,7 @@ However, a number of modifications and enhancements have been made. This chapter describes some of these modifications. </p> -<H2><a name="Preprocessor_nn2">10.1 File inclusion</a></H2> +<H2><a name="Preprocessor_nn2">11.1 File inclusion</a></H2> <p> @@ -48,7 +48,7 @@ like this: <div class="code"> <pre> -%include "pointer.i" +%include "cpointer.i" </pre> </div> @@ -64,7 +64,7 @@ By default, the <tt>#include</tt> is ignored unless you run SWIG with the is that you often don't want SWIG to try and wrap everything included in standard header system headers and auxiliary files. -<H2><a name="Preprocessor_nn3">10.2 File imports</a></H2> +<H2><a name="Preprocessor_nn3">11.2 File imports</a></H2> <p> @@ -93,14 +93,29 @@ The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> sta as imports. This might be useful if you want to extract type definitions from system header files without generating any wrappers. -<H2><a name="Preprocessor_condition_compilation">10.3 Conditional Compilation</a></H2> +<H2><a name="Preprocessor_condition_compilation">11.3 Conditional Compilation</a></H2> <p> SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>, <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally -include parts of an interface. The following symbols are predefined -by SWIG when it is parsing the interface: +include parts of an interface. +</p> + +<p> +SWIG's preprocessor conditionals support the standard C/C++ preprocessor +integer expressions. As a SWIG-specific extension, string equality and +inequality tests are also supported, for example: +</p> + +<div class="code"> +<pre> +#if defined __cplusplus && (#__VA_ARGS__ != "" || #TYPE == "void") +</pre> +</div> + +<p> +The following symbols are predefined by SWIG when it is parsing the interface: </p> <div class="code"><pre> @@ -110,18 +125,21 @@ SWIG_VERSION Hexadecimal (binary-coded decimal) number contai such as 0x010311 (corresponding to SWIG-1.3.11). SWIGCSHARP Defined when using C# +SWIGD Defined when using D +SWIGGO Defined when using Go SWIGGUILE Defined when using Guile SWIGJAVA Defined when using Java SWIGJAVASCRIPT Defined when using Javascript -SWIG_JAVASCRIPT_JSC Defined when using Javascript for JavascriptCore -SWIG_JAVASCRIPT_V8 Defined when using Javascript for v8 or node.js +SWIG_JAVASCRIPT_JSC Defined when using Javascript with -jsc +SWIG_JAVASCRIPT_V8 Defined when using Javascript with -v8 or -node +SWIG_JAVASCRIPT_NAPI Defined when using Javascript with -napi SWIGLUA Defined when using Lua SWIGMZSCHEME Defined when using Mzscheme SWIGOCAML Defined when using OCaml SWIGOCTAVE Defined when using Octave SWIGPERL Defined when using Perl SWIGPHP Defined when using PHP (any version) -SWIGPHP7 Defined when using PHP7 +SWIGPHP7 Defined when using PHP 7 or later (with a compatible C API) SWIGPYTHON Defined when using Python SWIGR Defined when using R SWIGRUBY Defined when using Ruby @@ -131,6 +149,14 @@ SWIGXML Defined when using XML </pre></div> <p> +SWIG also defines <tt>SWIG_VERSION</tt> and a target language macro in +the generated wrapper file (since SWIG 4.1.0 - in older versions these +were defined for some target languages but this wasn't consistent). Best +practice is to use SWIG-time conditional checks because that results in smaller +generated wrapper sources. +</p> + +<p> In addition, SWIG defines the following set of standard C/C++ macros: </p> @@ -138,20 +164,64 @@ In addition, SWIG defines the following set of standard C/C++ macros: <pre> __LINE__ Current line number __FILE__ Current file name -__STDC__ Defined to indicate ISO C -__cplusplus Defined when -c++ option used +__STDC__ Defined to indicate ISO C/C++ +__cplusplus Defined when -c++ option used, value controlled by <tt>-std=c++NN</tt> +__STDC_VERSION__ May be defined when -c++ option is not used, value controlled by <tt>-std=cNN</tt> </pre> </div> <p> +Since SWIG 4.2.0, <tt>__STDC__</tt> is defined to <tt>1</tt> to match +the behaviour of ISO C/C++ compilers. Before this SWIG defined it to +have an empty value. +</p> + +<p> +Since SWIG 4.2.0, <tt>__cplusplus</tt> is defined to <tt>199711L</tt> +(the value for C++98) by default. Before this SWIG always defined it to have +the <b>value</b> <tt>__cplusplus</tt>. +</p> + +<p> +Since SWIG 4.2.0, SWIG supports command line options <tt>-std=cNN</tt> and +<tt>-std=c++NN</tt> to specify the C/C++ standards version. The only effect of +these options is to set appropriate values for <tt>__STDC_VERSION__</tt> and +<tt>__cplusplus</tt> respectively, which is useful if you're wrapping +headers which have preprocessor checks based on their values. +</p> + +<p> +If your code requires these macros to be set to a version of the standard +that is not a final official version, or one that SWIG is not yet aware of, +you can simply redefine the appropriate macro to an alternative value at the +top of your interface file, for example: +</p> + +<div class="code"><pre> +#undef __cplusplus +#define __cplusplus 202211L +</pre></div> + +<p> +The following are language specific symbols that might be defined: +</p> + +<div class="code"><pre> +SWIG_D_VERSION Unsigned integer target version when using D +SWIGGO_CGO Defined when using Go for cgo +SWIGGO_GCCGO Defined when using Go for gccgo +SWIGGO_INTGO_SIZE Size of the Go type int when using Go (32 or 64) +SWIGPYTHON_BUILTIN Defined when using Python with -builtin +SWIG_RUBY_AUTORENAME Defined when using Ruby with -autorename +</pre></div> + +<p> Interface files can look at these symbols as necessary to change the way in which an interface is generated or to mix SWIG directives with -C code. These symbols are also defined within the C code generated by -SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined -within the SWIG compiler). +C code. </p> -<H2><a name="Preprocessor_nn5">10.4 Macro Expansion</a></H2> +<H2><a name="Preprocessor_nn5">11.4 Macro Expansion</a></H2> <p> @@ -161,15 +231,15 @@ is also used to try and detect constants. Therefore, if you have something like <div class="code"> <pre> -#ifndef _FOO_H 1 -#define _FOO_H 1 +#ifndef FOO_H 1 +#define FOO_H 1 ... #endif </pre> </div> <p> -you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface. +you may get some extra constants such as <tt>FOO_H</tt> showing up in the scripting interface. </p> <p> @@ -206,7 +276,7 @@ like <tt>#x</tt>. This is a non-standard SWIG extension. </li> </ul> -<H2><a name="Preprocessor_nn6">10.5 SWIG Macros</a></H2> +<H2><a name="Preprocessor_nn6">11.5 SWIG Macros</a></H2> <p> @@ -252,7 +322,7 @@ many of SWIG's advanced features and libraries are built using this mechanism (s support). </p> -<H2><a name="Preprocessor_nn7">10.6 C99 and GNU Extensions</a></H2> +<H2><a name="Preprocessor_nn7">11.6 C99 and GNU Extensions</a></H2> <p> @@ -308,14 +378,14 @@ interface building. However, they are used internally to implement a number of SWIG directives and are provided to make SWIG more compatible with C99 code. </p> -<H2><a name="Preprocessor_delimiters">10.7 Preprocessing and delimiters</a></H2> +<H2><a name="Preprocessor_delimiters">11.7 Preprocessing and delimiters</a></H2> <p> The preprocessor handles { }, " " and %{ %} delimiters differently. </p> -<H3><a name="Preprocessor_nn8">10.7.1 Preprocessing and %{ ... %} & " ... " delimiters</a></H3> +<H3><a name="Preprocessor_nn8">11.7.1 Preprocessing and %{ ... %} & " ... " delimiters</a></H3> <p> @@ -340,7 +410,7 @@ the contents of the <tt>%{ ... %}</tt> block are copied without modification to the output (including all preprocessor directives). </p> -<H3><a name="Preprocessor_nn9">10.7.2 Preprocessing and { ... } delimiters</a></H3> +<H3><a name="Preprocessor_nn9">11.7.2 Preprocessing and { ... } delimiters</a></H3> <p> @@ -382,7 +452,7 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code. </p> -<H2><a name="Preprocessor_typemap_delimiters">10.8 Preprocessor and Typemaps</a></H2> +<H2><a name="Preprocessor_typemap_delimiters">11.8 Preprocessor and Typemaps</a></H2> <p> @@ -453,7 +523,7 @@ would generate </div> -<H2><a name="Preprocessor_nn10">10.9 Viewing preprocessor output</a></H2> +<H2><a name="Preprocessor_nn10">11.9 Viewing preprocessor output</a></H2> <p> @@ -463,7 +533,7 @@ Instead the results after the preprocessor has run are displayed. This might be useful as an aid to debugging and viewing the results of macro expansions. </p> -<H2><a name="Preprocessor_warning_error">10.10 The #error and #warning directives</a></H2> +<H2><a name="Preprocessor_warning_error">11.10 The #error and #warning directives</a></H2> <p> |