XS-MLVP
/
swig
mirror of https://github.com/swig/swig
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Formalise the deprecation of target languages with a Deprecation status

This commit is contained in:
William S Fulton 2024-09-27 19:42:16 +01:00
parent 3b982b6d1b
commit 447cd4dd14
7 changed files with 60 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/Manual/Contents.html
View File

@ -50,6 +50,7 @@
<ul>
<li><a href="Introduction.html#Introduction_supported_status">Supported status</a>
<li><a href="Introduction.html#Introduction_experimental_status">Experimental status</a>
<li><a href="Introduction.html#Introduction_deprecated_status">Deprecated status</a>
</ul>
<li><a href="Introduction.html#Introduction_nn4">A SWIG example</a>
<ul>
@ -2046,6 +2047,7 @@
<ul>
<li><a href="Extending.html#Extending_supported_status">Supported status</a>
<li><a href="Extending.html#Extending_experimental_status">Experimental status</a>
<li><a href="Extending.html#Extending_deprecated_status">Deprecated status</a>
</ul>
<li><a href="Extending.html#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
</ul>

28
Doc/Manual/Extending.html
View File

@ -69,6 +69,7 @@
<ul>
<li><a href="#Extending_supported_status">Supported status</a>
<li><a href="#Extending_experimental_status">Experimental status</a>
<li><a href="#Extending_deprecated_status">Deprecated status</a>
</ul>
<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
</ul>
@ -3609,7 +3610,7 @@ should be avoided as unlike the SWIG developers, users will never have consisten
<p>
Target languages are given a status of either 'Supported' or 'Experimental' depending on their maturity as broadly outlined in
Target languages are given a status of either 'Supported', 'Experimental' or 'Deprecated' depending on their maturity as broadly outlined in
the <a href="Introduction.html#Introduction_target_languages">Target language introduction</a>.
This section provides more details on how this status is given.
</p>
@ -3726,6 +3727,31 @@ Some minimum requirements and notes about languages with the 'Experimental' stat
</li>
</ul>
<H4><a name="Extending_deprecated_status">41.10.15.3 Deprecated status</a></H4>
<p>
Unfortunately target languages that once met 'Experimental' or 'Supported' status can become non-functional and simply bit rot
due to neglect or due to the language's C/C++ API evolving and changing over time.
If there is no language maintainer and the maintenance burden becomes too much for the core
SWIG developers to keep the test-suite working with easily available versions of the target language,
the language is put into the 'Deprecated' status.
</p>
<p>
Changing the status to 'Deprecated' is an unfortunate step not done lightly and only if recent versions cannot successfully
run the test-suite and examples on the Github Actions Continuous Integration platform.
As the target language would once have had a working set of examples and test-suite, this usually only occurs
when the more modern operating system distributions available on Github can no longer run any distribution supplied version of the target language.
</p>
<p>
Changing status to 'Deprecated' flags it for removal from SWIG in a subsequent release (usually one SWIG release).
This step becomes the final plea for help from the community who use the target language.
The language will need updating by an interested community member to meet the requirements of at least 'Experimental' status in order to prevent removal.
If you are a user of a 'Deprecated' target language and would like to keep it available in future releases, please contact the SWIG developers for details of how you can help.
</p>
<H3><a name="Extending_prerequisites">41.10.16 Prerequisites for adding a new language module to the SWIG distribution</a></H3>

25
Doc/Manual/Introduction.html
View File

@ -17,6 +17,7 @@
<ul>
<li><a href="#Introduction_supported_status">Supported status</a>
<li><a href="#Introduction_experimental_status">Experimental status</a>
<li><a href="#Introduction_deprecated_status">Deprecated status</a>
</ul>
<li><a href="#Introduction_nn4">A SWIG example</a>
<ul>
@ -166,13 +167,13 @@ SWIG is very broadly composed of two components.
A core component creates a parse tree from the input ISO C/C++ and SWIG directives (extensions to the C/C++ standards).
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.
These target languages are given a status of either Supported, Experimental or Deprecated.
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 or being kept up to date.
</p>
<p>
The second part of the SWIG documentation contains a chapter for each target level language.
The target language chapters are under one of two sections indicating the status (Supported or Experimental) for that language.
The target language chapters are under one of the sections indicating the status (Supported, Experimental or Deprecated) for that language.
</p>
<H3><a name="Introduction_supported_status">2.3.1 Supported status</a></H3>
@ -221,6 +222,24 @@ The usual <a href="Warnings.html#Warnings_suppression">warning suppression</a> t
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>
<H3><a name="Introduction_deprecated_status">2.3.3 Deprecated status</a></H3>
<p>
A target language that was once 'Supported' or 'Experimental' is changed to the 'Deprecated' status when
it has been neglected over time and become non-functional.
It requires interested community member's contributions to restore it to its former status.
</p>
<p>
Please see the <a href="Extending.html#Extending_deprecated_status">Deprecated status</a> section in the Extending chapter for more details.
</p>
<p>
SWIG displays a deprecated warning notice whenever a 'Deprecated' language is used.
The usual <a href="Warnings.html#Warnings_suppression">warning suppression</a> techniques can be used if required.
</p>
<H2><a name="Introduction_nn4">2.4 A SWIG example</a></H2>

1
Doc/Manual/Javascript.html
View File

@ -147,7 +147,6 @@ $ make check-javascript-examples ENGINE=jsc</pre>
<pre>
$ make check-javascript-test-suite ENGINE=jsc</pre>
</div>
</p>
<H3><a name="Javascript_known_issues">28.2.3 Known Issues</a></H3>

7
Doc/Manual/Sections.html
View File

@ -63,10 +63,15 @@ Last update : SWIG-4.3.0 (in progress)
<ul>
<li><a href="C.html#C">C target language support</a></li>
<li><a href="Mzscheme.html#Mzscheme">MzScheme/Racket support</a></li>
<li><a href="Ocaml.html#Ocaml">OCaml support</a></li>
</ul>
<H3><a name="Sections_deprecated_language_modules">Deprecated Language Modules Documentation</a></H3>
<ul>
<li><a href="Mzscheme.html#Mzscheme">MzScheme/Racket support</a></li>
</ul>
<H3><a name="Sections_developers_docs">Developer Documentation</a></H3>
<ul>

1
Doc/Manual/Warnings.html
View File

@ -539,6 +539,7 @@ example.i(4) : Syntax error in input(1).
<li>524. Experimental target language. Target language <em>language</em> specified by <em>lang</em> is an experimental language. Please read about SWIG experimental languages, <em>htmllink</em>.
<li>525. Destructor <em>declaration</em> is final, <em>name</em> cannot be a director class.
<li>526. Using declaration <em>declaration</em>, with name '<em>name</em>', is not actually using the method from <em>declaration</em>, with name '<em>name</em>', as the names are different.
<li>527. Deprecated target language. Target language <em>language</em> specified by <em>lang</em> is a deprecated language. It will be removed in the next release of SWIG unless a new maintainer steps forward to bring it up to at least experimental status, <em>htmllink</em>.
</ul>
<H3><a name="Warnings_doxygen">19.9.6 Doxygen comments (560-599)</a></H3>

4
Source/Modules/main.cxx
View File

@ -1302,13 +1302,13 @@ int SWIG_main(int argc, char *argv[], const TargetLanguageModule *tlm) {
if (tlm->status == Experimental) {
Swig_warning(WARN_LANG_EXPERIMENTAL, "SWIG", 1, "Experimental target language. "
"Target language %s specified by %s is an experimental language. "
"Please read about SWIG experimental languages, https://swig.org/Doc4.0/Introduction.html#Introduction_experimental_status.\n",
"Please read about SWIG experimental languages, https://swig.org/Doc4.3/Introduction.html#Introduction_experimental_status.\n",
tlm->help ? tlm->help : "", tlm->name);
} else if (tlm->status == Deprecated) {
Swig_warning(WARN_LANG_DEPRECATED, "SWIG", 1, "Deprecated target language. "
"Target language %s specified by %s is a deprecated target language. "
"It will be removed in the next release of SWIG unless a new maintainer steps forward "
"to bring it up to experimental status, see https://swig.org/Doc4.0/Introduction.html#Introduction_experimental_status.\n",
"to bring it up to at least experimental status, see https://swig.org/Doc4.3/Introduction.html#Introduction_deprecated_status.\n",
tlm->help ? tlm->help : "", tlm->name);
}