@@ -3053,7 +3057,7 @@ but without the typemaps, there is still work to do.
-At the time of this writing, SWIG supports nearly a dozen languages, +At the time of this writing, SWIG supports nearly twenty languages, which means that for continued sanity in maintaining the configuration files, the language modules need to follow some conventions. These are outlined here along with the admission that, yes it is ok to violate @@ -3225,7 +3229,7 @@ The following are the minimum that are usually supported: Please copy these and modify for any new language.
-@@ -3254,7 +3258,226 @@ during this process, see the section on configuration files.
-+A test driven development approach is central to the improvement and development of SWIG. +Most modifications to SWIG are accompanied by additional regression tests and checking all +tests to ensure that no regressions have been introduced. +
+ ++The regression testing is carried out by the SWIG test-suite. +The test-suite consists of numerous testcase interface files in the Examples/test-suite directory +as well as target language specific runtime tests in the Examples/test-suite/[lang] directory. +When a testcase is run, it will execute the following steps for each testcase: +
+ ++For example, the ret_by_value testcase consists of two components. +The first component is the Examples/test-suite/ret_by_value.i interface file. +The name of the SWIG module must always be the name of the testcase, so the ret_by_value.i interface file thus begins with: +
+ ++%module ret_by_value ++
+The testcase code will then follow the module declaration, +usually within a %inline %{ ... %} section for the majority of the tests. +
+ ++The second component is the optional runtime tests. +Any runtime tests are named using the following convention: [testcase]_runme.[ext], +where [testcase] is the testcase name and [ext] is the normal extension for the target language file. +In this case, the Java and Python target languages implement a runtime test, so their files are respectively, +Examples/test-suite/java/ret_by_value_runme.java and +Examples/test-suite/python/ret_by_value_runme.py. +
+ ++The goal of the test-suite is to test as much as possible in a silent manner. +This way any SWIG or compiler errors or warnings are easily visible. +Should there be any warnings, changes must be made to either fix them (preferably) or suppress them. +Compilation or runtime errors result in a testcase failure and will be immediately visible. +It is therefore essential that the runtime tests are written in a manner that displays nothing to stdout/stderr on success +but error/exception out with an error message on stderr on failure. +
+ ++In order for the test-suite to work for a particular target language, the language must be correctly detected +and configured during the configure stage so that the correct Makefiles are generated. +Most development occurs on Linux, so usually it is a matter of installing the development packages for the target language +and simply configuring as outlined earlier. +
+ ++If when running the test-suite commands that follow, you get a message that the test was skipped, it indicates that the +configure stage is missing information in order to compile and run everything for that language. +
+ ++The test-suite can be run in a number of ways. +The first group of commands are for running multiple testcases in one run and should be executed in the top level directory. +To run the entire test-suite (can take a long time): +
+ ++make -k check-test-suite +
+To run the test-suite just for target language [lang], replace [lang] with one of csharp, java, perl5, python, ruby, tcl etc: +
+ ++make check-[lang]-test-suite +
+Note that if a runtime test is available, a message "(with run test)" is displayed when run. For example: +
+ ++$ make check-python-test-suite +checking python test-suite +checking testcase argcargvtest (with run test) under python +checking testcase python_autodoc under python +checking testcase python_append (with run test) under python +checking testcase callback (with run test) under python +
+The files generated on a previous run can be deleted using the clean targets, either the whole test-suite or for a particular language: +
+ ++make clean-test-suite +make clean-[lang]-test-suite +
+The test-suite can be run in a partialcheck mode where just SWIG is executed, that is, the compile, +link and running of the testcases is not performed. +Note that the partialcheck does not require the target language to be correctly configured and detected and unlike the other test-suite make targets, is never skipped. Once again, either all the languages can be executed or just a chosen language: +
+ ++make partialcheck-test-suite +make partialcheck-[lang]-test-suite +
+If your computer has more than one CPU, you are strongly advised to use parallel make to speed up the execution speed. +This can be done with any of the make targets that execute more than one testcase. +For example, a dual core processor can efficiently use 2 parallel jobs: +
+ ++make -j2 check-test-suite +make -j2 check-python-test-suite +make -j2 partialcheck-java-test-suite +
+The second group of commands are for running individual testcases and should be executed in the appropriate +target language directory, Examples/test-suite/[lang]. +Testcases can contain either C or C++ code and when one is written, a decision must be made as to which of these input +languages is to be used. +Replace [testcase] in the commands below with the name of the testcase. +
+ ++For a C language testcase, add the testcase under the C_TEST_CASES list in Examples/test-suite/common.mk and +execute individually as: +
++make -s [testcase].ctest +
+For a C++ language testcase, add the testcase under the CPP_TEST_CASES list in Examples/test-suite/common.mk and +execute individually as: +
++make -s [testcase].cpptest +
+A third category of tests are C++ language testcases testing multiple modules (the %import directive). +These require more than one shared library (dll/shared object) to be built and so are separated out from the normal C++ testcases. +Add the testcase under the MULTI_CPP_TEST_CASES list in Examples/test-suite/common.mk and +execute individually as: +
++make -s [testcase].multicpptest +
+To delete the generated files, execute: +
++make -s [testcase].clean +
+If you would like to see the exact commands being executed, drop the -s option: +
++make [testcase].ctest +make [testcase].cpptest +make [testcase].multicpptest +
+Some real examples of each: +
++make -s ret_by_value.clean +make -s ret_by_value.ctest +make -s bools.cpptest +make -s imports.multicpptest +
+Advanced usage of the test-suite facilitates running tools on some of the five stages. +The make variables SWIGTOOL and RUNTOOL are used to specify a tool to respectively, invoke SWIG +and the execution of the runtime test. +You are advised to view the Examples/test-suite/common.mk file for details but for a short summary, +the classic usage is to use Valgrind for memory checking. +For example, checking for memory leaks when running the runtime test in the target language interpreter: +
+ ++make ret_by_value.ctest RUNTOOL="valgrind --leak-check=full" +
+This will probably make more sense if you look at the output of the above as it will show the exact commands being executed. +SWIG can be analyzed for bad memory accesses using: +
+ ++make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes" +
@@ -3286,7 +3509,7 @@ Some topics that you'll want to be sure to address include: if available.
@@ -3343,7 +3566,7 @@ should be added should there be an area not already covered by the existing tests.
-