diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index f8a731fe2..22f6126de 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -46,6 +46,11 @@
-If you wish for a new language module to be distributed with SWIG, -which we encourage for all popular languages, there are a few requirements. -While we appreciate that getting all aspects of a new language working -won't happen at the outset, there are a set of minimum requirements before -a module can be committed into the official Github repository for distribution with future -versions of SWIG. The following are really a summary of this whole section with -details being outlined earlier on. -
- --Once accepted into the official Git repository, development efforts should concentrate on -getting the entire test-suite to work with plenty of runtime tests. -Runtime tests should be for existing testcases and new test cases -should be added should there be an area not already covered by -the existing tests. -
- -@@ -3612,6 +3560,192 @@ The generated C/C++ code should also follow this style as close as possible. How should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
+ ++Target languages are given a status of either 'Supported' or 'Experimental' depending on their maturity as broadly outlined in +the Target language introduction. +This section provides more details on how this status is given. +
+ ++A target language is given the 'Supported' status when +
+ ++A target language is given the 'Experimental' status when +
+ ++Some minimum requirements and notes about languages with the 'Experimental' status: +
+ ++New target language modules can be included in SWIG and contributions are encouraged for popular languages. +In order to be considered for inclusion, a language must at a minimum fit the 'Experimental' status described above. +
+ ++Below are some practical steps that should help meet these requirements. +
+ ++Once accepted into the official Git repository, development efforts should concentrate on +getting the entire test-suite to work +in order to migrate the language module to the 'Supported' status. +Runtime tests should be added for existing testcases and new test cases +can be added should there be an area not already covered by +the existing tests. +
+ ++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. +
+ ++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. +
+ ++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. +
+ ++A target language is given the 'Supported' status when +
+ ++The above is a short summary and further details are outlined in the Supported status section in the Extending chapter. +The good news is that all the well-known and most popular languages have this status. +
+ ++A target language is given the 'Experimental' status when +
+ ++Anyone using an experimental target language is strongly urged to assist with development of the target language module if they wish to use it. +
+ ++The above is a short summary and further details are outlined in the Experimental status section in the Extending chapter. +
+ +@@ -155,7 +228,7 @@ following C code:
/* 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 My_variable from Tcl. You start by making a SWIG
interface file as shown below (by convention, these files carry a .i
suffix) :
-2.3.1 SWIG interface file
+2.4.1 SWIG interface file
@@ -202,7 +275,7 @@ module that will be created by SWIG. The %{ %} block
provides a location for inserting additional code, such as C header
files or additional C declarations, into the generated C wrapper code.
-2.3.2 The swig command
+2.4.2 The swig command
@@ -235,7 +308,7 @@ and variables declared in the SWIG interface. A look at the file
example_wrap.c reveals a hideous mess. However, you
almost never need to worry about it.
-
2.3.3 Building a Perl5 module
+2.4.3 Building a Perl5 module
@@ -261,7 +334,7 @@ unix >
-2.3.4 Building a Python module
+2.4.4 Building a Python module
@@ -285,7 +358,7 @@ Type "copyright", "credits" or "license" for more information.
7.5
@@ -311,7 +384,7 @@ print $example::My_variable + 4.5, "\n"; 7.5 -
@@ -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. -
@@ -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.
-@@ -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.
-@@ -434,7 +507,7 @@ it allows others to forget about the low-level implementation details.
-diff --git a/Doc/Manual/Preface.html b/Doc/Manual/Preface.html index 78e2a1ab0..36a99bd1f 100644 --- a/Doc/Manual/Preface.html +++ b/Doc/Manual/Preface.html @@ -69,6 +69,9 @@ over a period of 10 years starting from the year 2000. The final version in the series was 1.3.40, but in truth the 1.3.x series had been stable for many years. An official stable version was released along with the decision to make SWIG license changes and this gave rise to version 2.0.0 in 2010. +Version 3.0.0 was released in 2014 focusing on adding C++11 support and C++ nested classes. +Version 4.0.0 was released in 2019 to add in Doxygen support. +Some target languages were disabled as part of a clean up and others were given a new status of either 'Supported' or 'Experimental'.
-Note: The test-suite currently contains over 500 tests. If you +Note: The test-suite currently contains over 600 tests. If you have many different target languages installed and a slow machine, it might take more than an hour to run the test-suite.