jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add info about the Supported and Experimental language module status

Browse source 
This is the result of an email discussion on the swig-devel mailing list
back in March 2017 titled "Radical new approach to development and
moving towards version 3.1 or version 4.0"

A new section in the Introduction chapter has been added, titled
"Target languages". The Extending chapter has the main details in a
new section called "Target language status".
This commit is contained in:
William S Fulton 2019-01-29 18:55:44 +00:00
commit b324d9d6bb
4 changed files with 293 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

97
Doc/Manual/Introduction.html
View file

@ -13,6 +13,11 @@
<ul>
<li><a href="#Introduction_nn2">What is SWIG?</a>
<li><a href="#Introduction_nn3">Why use SWIG?</a>
<li><a href="#Introduction_target_languages">Target languages</a>
<ul>
<li><a href="#Introduction_supported_status">Supported status</a>
<li><a href="#Introduction_experimental_status">Experimental status</a>
</ul>
<li><a href="#Introduction_nn4">A SWIG example</a>
<ul>
<li><a href="#Introduction_nn5">SWIG interface file</a>
@ -144,7 +149,75 @@ it provides a wide variety of customization features that let you change almost
every aspect of the language bindings. This is the main reason why SWIG has such a large
user manual ;-).
<H2><a name="Introduction_nn4">2.3 A SWIG example</a></H2>
<H2><a name="Introduction_target_languages">2.3 Target languages</a></H2>
<p>
SWIG in essence is a tool to generate code for making C/C++ code available to various other programming languages.
These higher level programming languages are the target languages for the SWIG code generator and C or C++ are the input languages.
A single target language must be specified when SWIG is run.
This results in generating code for C/C++ and the specified target language to interface with each other.
SWIG can be invoked multiple times, but with a different target language specified on each invocation.
This ability to interface C/C++ to many different target languages is one of SWIG's core strengths and features.
</p>
<p>
SWIG is very broadly composed of two components.
A core component creates a parse tree from the input C/C++ and SWIG directives (extensions to C/C++).
The parse tree is then passed to a second component, one of the target language modules for generating code specific to a higher level language.
SWIG supports many different target languages.
These target languages are given a status of either Supported or Experimental.
This status is provided to indicate the level of maturity to expect when using a particular target language as not all target languages are fully developed.
</p>
<p>
The second part of the SWIG documentation contains a chapter for each target level language.
Each chapter will state the status (Supported or Experimental) for that language.
</p>
<H3><a name="Introduction_supported_status">2.3.1 Supported status</a></H3>
<p>
A target language is given the 'Supported' status when
</p>
<ul>
<li>It is in a mature, well functioning state.</li>
<li>It has its own comprehensive chapter in the documentation.</li>
<li>It passes all of the main SWIG test-suite and has a range of working examples.</li>
<li>It supports the vast majority of SWIG features.</li>
<li>It provides strong backwards compatibility between releases.</li>
</ul>
<p>
The above is a short summary and further details are outlined in the <a href="Extending.html#Extending_supported_status">Supported status</a> section in the Extending chapter.
The good news is that all the well-known and most popular languages have this status.
</p>
<H3><a name="Introduction_experimental_status">2.3.2 Experimental status</a></H3>
<p>
A target language is given the 'Experimental' status when
</p>
<ul>
<li>It is of sub-standard quality, failing to meet the above 'Supported' status.</li>
<li>It is somewhere between the mid to mature stage of development.</li>
<li>It does not guarantee any backwards compatibility between releases.</li>
<li>It is in need of help to finish development.</li>
</ul>
<p>
Anyone using an experimental target language is strongly urged to assist with development of the target language module if they wish to use it.
</p>
<p>
The above is a short summary and further details are outlined in the <a href="Extending.html#Extending_experimental_status">Experimental status</a> section in the Extending chapter.
</p>
<H2><a name="Introduction_nn4">2.4 A SWIG example</a></H2>
<p>
@ -155,7 +228,7 @@ following C code:
<div class="code"><pre>
/* File : example.c */
double My_variable = 3.0;
double My_variable = 3.0;
/* Compute factorial of n */
int fact(int n) {
@ -177,7 +250,7 @@ variable <tt>My_variable</tt> from Tcl. You start by making a SWIG
interface file as shown below (by convention, these files carry a .i
suffix) :
<H3><a name="Introduction_nn5">2.3.1 SWIG interface file</a></H3>
<H3><a name="Introduction_nn5">2.4.1 SWIG interface file</a></H3>
<div class="code"><pre>
@ -202,7 +275,7 @@ module that will be created by SWIG. The <tt>%{ %}</tt> block
provides a location for inserting additional code, such as C header
files or additional C declarations, into the generated C wrapper code.
<H3><a name="Introduction_nn6">2.3.2 The swig command</a></H3>
<H3><a name="Introduction_nn6">2.4.2 The swig command</a></H3>
<p>
@ -235,7 +308,7 @@ and variables declared in the SWIG interface. A look at the file
<tt>example_wrap.c</tt> reveals a hideous mess. However, you
almost never need to worry about it.
<H3><a name="Introduction_nn7">2.3.3 Building a Perl5 module</a></H3>
<H3><a name="Introduction_nn7">2.4.3 Building a Perl5 module</a></H3>
<p>
@ -261,7 +334,7 @@ unix &gt;
</pre></div>
<H3><a name="Introduction_nn8">2.3.4 Building a Python module</a></H3>
<H3><a name="Introduction_nn8">2.4.4 Building a Python module</a></H3>
<p>
@ -285,7 +358,7 @@ Type "copyright", "credits" or "license" for more information.
7.5
</pre></div>
<H3><a name="Introduction_nn9">2.3.5 Shortcuts</a></H3>
<H3><a name="Introduction_nn9">2.4.5 Shortcuts</a></H3>
<p>
@ -311,7 +384,7 @@ print $example::My_variable + 4.5, "\n";
7.5
</pre></div>
<H2><a name="Introduction_nn10">2.4 Supported C/C++ language features</a></H2>
<H2><a name="Introduction_nn10">2.5 Supported C/C++ language features</a></H2>
<p>
@ -351,7 +424,7 @@ wrapping simple C++ code. In fact, SWIG is able to handle C++ code that
stresses the very limits of many C++ compilers.
<H2><a name="Introduction_nn11">2.5 Non-intrusive interface building</a></H2>
<H2><a name="Introduction_nn11">2.6 Non-intrusive interface building</a></H2>
<p>
@ -363,7 +436,7 @@ interface and reuse the code in other applications. It is also
possible to support different types of interfaces depending on the application.
</p>
<H2><a name="Introduction_build_system">2.6 Incorporating SWIG into a build system</a></H2>
<H2><a name="Introduction_build_system">2.7 Incorporating SWIG into a build system</a></H2>
<p>
@ -421,7 +494,7 @@ which will invoke SWIG and compile the generated C++ files into _example.so (UNI
For other target languages on Windows a dll, instead of a .pyd file, is usually generated.
</p>
<H2><a name="Introduction_nn12">2.7 Hands off code generation</a></H2>
<H2><a name="Introduction_nn12">2.8 Hands off code generation</a></H2>
<p>
@ -434,7 +507,7 @@ it allows others to forget about the low-level implementation
details.
</p>
<H2><a name="Introduction_nn13">2.8 SWIG and freedom</a></H2>
<H2><a name="Introduction_nn13">2.9 SWIG and freedom</a></H2>
<p>