From b324d9d6bb9aed1e4d35e80bbd9594d3367c1a09 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Tue, 29 Jan 2019 18:55:44 +0000 Subject: [PATCH] Add info about the Supported and Experimental language module status 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". --- Doc/Manual/Contents.html | 12 +- Doc/Manual/Extending.html | 252 +++++++++++++++++++++++++++-------- Doc/Manual/Introduction.html | 97 ++++++++++++-- Doc/Manual/Preface.html | 5 +- 4 files changed, 293 insertions(+), 73 deletions(-) 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 @@
  • Debugging Options
  • Guide to parse tree nodes diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index 9d69ac2d1..53c2e68ae 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -64,8 +64,13 @@
  • Running the test-suite
  • Documentation -
  • Prerequisites for adding a new language module to the SWIG distribution
  • Coding style guidelines +
  • Target language status + +
  • Prerequisites for adding a new language module to the SWIG distribution
  • Debugging Options
  • Guide to parse tree nodes @@ -3531,64 +3536,7 @@ Some topics that you'll want to be sure to address include: if available. -

    43.10.14 Prerequisites for adding a new language module to the SWIG distribution

    - - -

    -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. -

    - -
      -
    1. - Demonstrate basic C code working by porting the "simple" example including - a runtime test, see for example Examples/python/simple. -
      2. -
    2. - Demonstrate basic C++ code working by porting the "class" example including - a runtime test, see for example Examples/python/class. -
      3. -
    3. - Modify configure.ac, Makefile.in and Examples/Makefile.in to run - these examples. Please make sure that if the new language is not - installed properly on a box, make -k check should still work by - skipping the tests and examples for the new language module. -
      4. -
    4. - Get the test-suite running for the new language (make check-[lang]-test-suite). - While the test-suite tests many corner cases, - we'd expect the majority of it to work by compiling the generated code - correctly as most of the corner cases are covered in the SWIG core. Get - at least one C and one C++ runtime test running in the test-suite. -
      5. -
    5. - Provide a chapter in the html documentation on the basics of using - the language module. -
      6. -
    6. - Ensure your source code is formatted according to the coding style guidelines. -
      7. -
    7. - Finally, email the SWIG developers with a patch and a demonstration of - commitment to maintaining the language module, - certainly in the short term and ideally long term. -
      8. -
    - -

    -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. -

    - -

    43.10.15 Coding style guidelines

    +

    43.10.14 Coding style guidelines

    @@ -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.

    + +

    43.10.15 Target language status

    + + +

    +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. +

    + +

    43.10.15.1 Supported status

    + + +

    +A target language is given the 'Supported' status when +

    + + + +

    43.10.15.2 Experimental status

    + + +

    +A target language is given the 'Experimental' status when +

    + + + +

    +Some minimum requirements and notes about languages with the 'Experimental' status: +

    + + + +

    43.10.16 Prerequisites for adding a new language module to the SWIG distribution

    + + +

    +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. +

    + +
      +
    1. + The "simple" example needs to be working to demonstrate basic C code wrappers. + Port the example from another language, such as from Examples/python/simple. +
      2. +
    2. + The "class" example needs to be working to demonstrate basic C++ code wrappers. + Port the example from another language, such as from Examples/python/class. +
      3. +
    3. + Modify configure.ac, Makefile.in and Examples/Makefile.in to run + these examples. Please make sure that if the new language is not + installed properly on a box, make -k check should still work by + skipping the tests and examples for the new language module. +
      4. +
    4. + Copying an existing language module and adapting the source for it is likely to be the most efficient + approach to fully developing a new module as a numbe of corner cases are covered in the existing implementations. + The most advanced scripting languages are Python and Ruby. + The most advanced compiled target languages are Java and C#. +
      5. +
    5. + Get the test-suite running for the new language (make check-[lang]-test-suite). + While the test-suite tests many corner cases, + we'd expect the majority of it to work without much effort once the generated code is compiling + correctly for basic functionality as most of the corner cases are covered in the SWIG core. Aim to first get + one C and one C++ runtime test running in the test-suite. + Adding further runtime tests should be a lot easier afterwards by porting existing runtime tests from another language module. +
      6. +
    6. + The structure and contents of the html documentation chapter can be copied and adapted from one of the other language modules. +
      7. +
    7. + Source code can be formatted correctly using the info in the coding style guidelines section. +
      8. +
    8. + When ready, post a patch on Github, join the swig-devel mailing list and email the SWIG developers with a demonstration of + commitment to maintaining the language module, + certainly in the short term and ideally long term. +
      9. +
    + +

    +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. +

    + +

    43.11 Debugging Options

    diff --git a/Doc/Manual/Introduction.html b/Doc/Manual/Introduction.html index ad6e34ed7..b7e12aada 100644 --- a/Doc/Manual/Introduction.html +++ b/Doc/Manual/Introduction.html @@ -13,6 +13,11 @@