diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1168e5dc0..47b435aa3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,6 +13,9 @@ on: - 'Doc/**' - 'appveyor.yml' +permissions: + contents: read + jobs: build: @@ -24,12 +27,13 @@ jobs: # By default, the name of the build is the language used and SWIG options, but matrix entries # can define the additional "desc" field with any additional information to include in the name. - name: ${{ matrix.SWIGLANG || 'none' }}${{ matrix.PY3 }} ${{ matrix.ENGINE}} ${{ matrix.VER }} ${{ matrix.SWIG_FEATURES }} ${{ (matrix.compiler || 'gcc') }}${{ matrix.GCC }} ${{ matrix.CPPSTD }} ${{ matrix.CSTD }} ${{ matrix.desc }} ${{ matrix.continue-on-error && '(can fail)' }} + name: ${{ matrix.SWIGLANG || 'none' }}${{ matrix.PY2 }} ${{ matrix.ENGINE}} ${{ matrix.VER }} ${{ matrix.SWIG_FEATURES }} ${{ (matrix.compiler || 'gcc') }}${{ matrix.GCC }} ${{ matrix.CPPSTD }} ${{ matrix.CSTD }} ${{ matrix.desc }} ${{ matrix.continue-on-error && '(can fail)' }} strategy: matrix: include: - SWIGLANG: "" + CPPFLAGS: "-DDOH_POISON" - SWIGLANG: "" GCC: 7 - SWIGLANG: "" @@ -40,6 +44,9 @@ jobs: GCC: 10 - SWIGLANG: "" GCC: 11 + - SWIGLANG: "" + GCC: 12 + os: ubuntu-22.04 - SWIGLANG: "" compiler: clang - SWIGLANG: c @@ -65,74 +72,87 @@ jobs: - SWIGLANG: go VER: '1.17' - SWIGLANG: guile + - SWIGLANG: guile + VER: '2.2' + - SWIGLANG: guile + VER: '3.0' - SWIGLANG: java + - SWIGLANG: javascript + ENGINE: node + VER: '6' + CPPSTD: c++11 + os: ubuntu-18.04 + - SWIGLANG: javascript + ENGINE: node + VER: '8' + CPPSTD: c++11 + os: ubuntu-18.04 + - SWIGLANG: javascript + ENGINE: node + VER: '10' + CPPSTD: c++11 + os: ubuntu-18.04 - SWIGLANG: javascript ENGINE: node VER: '12' CPPSTD: c++11 - SWIGLANG: javascript ENGINE: node - VER: '14' - CPPSTD: c++11 - - SWIGLANG: javascript - ENGINE: node - VER: '16' + VER: '18' CPPSTD: c++14 - SWIGLANG: javascript ENGINE: jsc - os: ubuntu-18.04 # libwebkitgtk-dev dependency not available in 20.04. - - SWIGLANG: javascript - ENGINE: v8 - os: ubuntu-18.04 # libv8-dev only actually provides v8 in 18.04. + VER: '4.0' - SWIGLANG: lua - SWIGLANG: lua VER: '5.3' - SWIGLANG: octave CPPSTD: c++11 - SWIGLANG: perl5 + - SWIGLANG: php + VER: '7.0' + - SWIGLANG: php + VER: '7.1' + - SWIGLANG: php + VER: '7.2' + - SWIGLANG: php + VER: '7.3' - SWIGLANG: php VER: '7.4' - SWIGLANG: php + - SWIGLANG: php + VER: '8.1' - SWIGLANG: python + PY2: 2 - SWIGLANG: python - PY3: 3 - VER: '3.2' - os: ubuntu-18.04 # Python < 3.5 not available for 20.04. - - SWIGLANG: python - PY3: 3 VER: '3.3' os: ubuntu-18.04 # Python < 3.5 not available for 20.04. - SWIGLANG: python - PY3: 3 VER: '3.4' os: ubuntu-18.04 # Python < 3.5 not available for 20.04. - SWIGLANG: python - PY3: 3 VER: '3.5' - SWIGLANG: python - PY3: 3 VER: '3.6' - SWIGLANG: python - PY3: 3 VER: '3.7' - SWIGLANG: python - PY3: 3 VER: '3.8' - SWIGLANG: python - PY3: 3 VER: '3.9' - SWIGLANG: python - PY3: 3 VER: '3.10' - SWIGLANG: python + VER: '3.11' + - SWIGLANG: python + PY2: 2 SWIG_FEATURES: -builtin - SWIGLANG: python + PY2: 2 SWIG_FEATURES: -builtin -O - SWIGLANG: python - PY3: 3 SWIG_FEATURES: -builtin - SWIGLANG: python - PY3: 3 SWIG_FEATURES: -builtin -O - SWIGLANG: r - SWIGLANG: ruby @@ -161,8 +181,14 @@ jobs: - SWIGLANG: ruby VER: '3.0' CPPSTD: c++11 + - SWIGLANG: ruby + VER: '3.1' + CPPSTD: c++11 + - SWIGLANG: scilab + VER: '5.5.2' + - SWIGLANG: scilab + os: ubuntu-18.04 # scilab 6.0 - SWIGLANG: scilab - os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working - SWIGLANG: tcl # c++11 testing - SWIGLANG: csharp @@ -175,14 +201,17 @@ jobs: CPPSTD: c++11 - SWIGLANG: java CPPSTD: c++11 + - SWIGLANG: javascript + ENGINE: jsc + VER: '4.1' + os: ubuntu-22.04 + CPPSTD: c++11 - SWIGLANG: javascript ENGINE: node VER: '14' CPPSTD: c++11 - SWIGLANG: lua CPPSTD: c++11 - # - SWIGLANG: octave - # CPPSTD: c++11 - SWIGLANG: perl5 CPPSTD: c++11 - SWIGLANG: php @@ -190,14 +219,12 @@ jobs: CSTD: gnu11 - SWIGLANG: python CPPSTD: c++11 - PY3: 3 - SWIGLANG: r CPPSTD: c++11 - SWIGLANG: ruby CPPSTD: c++11 - SWIGLANG: scilab CPPSTD: c++11 - os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working - SWIGLANG: tcl CPPSTD: c++11 # c++14 testing @@ -226,14 +253,12 @@ jobs: CSTD: gnu11 - SWIGLANG: python CPPSTD: c++14 - PY3: 3 - SWIGLANG: r CPPSTD: c++14 - SWIGLANG: ruby CPPSTD: c++14 - SWIGLANG: scilab CPPSTD: c++14 - os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working - SWIGLANG: tcl CPPSTD: c++14 # c++17 testing (using gcc11) @@ -253,7 +278,7 @@ jobs: GCC: 11 - SWIGLANG: javascript ENGINE: node - VER: '16' + VER: '18' CPPSTD: c++17 GCC: 11 - SWIGLANG: lua @@ -272,7 +297,6 @@ jobs: - SWIGLANG: python CPPSTD: c++17 GCC: 11 - PY3: 3 - SWIGLANG: r CPPSTD: c++17 GCC: 11 @@ -282,14 +306,21 @@ jobs: - SWIGLANG: scilab CPPSTD: c++17 GCC: 11 - os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working - SWIGLANG: tcl CPPSTD: c++17 GCC: 11 + # c++20 testing (using gcc12) + # ubuntu-22.04 is currently experimental on Github Actions, so limit to just one language for now + - SWIGLANG: python + CPPSTD: c++20 + GCC: 12 + os: ubuntu-22.04 # Experimental languages (these are allowed to fail) - SWIGLANG: mzscheme continue-on-error: true - SWIGLANG: ocaml + CPPSTD: c++17 + GCC: 11 continue-on-error: true os: ubuntu-18.04 # ocaml-4.08 in ubuntu-20.04 not yet working # Run all of them, as opposed to aborting when one fails @@ -297,13 +328,14 @@ jobs: env: SWIGLANG: ${{ matrix.SWIGLANG }} - PY3: ${{ matrix.PY3 }} + PY2: ${{ matrix.PY2 }} VER: ${{ matrix.VER }} ENGINE: ${{ matrix.ENGINE }} SWIG_FEATURES: ${{ matrix.SWIG_FEATURES }} GCC: ${{ matrix.GCC }} CSTD: ${{ matrix.CSTD }} CPPSTD: ${{ matrix.CPPSTD }} + CPPFLAGS: ${{ matrix.CPPFLAGS }} steps: - name: Checkout @@ -316,6 +348,10 @@ jobs: with: key: ${{ matrix.os || 'ubuntu-20.04' }}-${{ matrix.compiler || 'gcc' }}${{ matrix.GCC }} +# Uncomment to debug via ssh, see https://github.com/mxschmitt/action-tmate +# - name: Setup tmate session +# uses: mxschmitt/action-tmate@v3 + - name: Install Dependencies run: | set -x @@ -376,10 +412,12 @@ jobs: c++11) export CSTD=c11 ;; c++14) export CSTD=c11 ;; c++17) export CSTD=c17 ;; + c++20) export CSTD=c17 ;; esac echo CSTD="$CSTD" >> $GITHUB_ENV fi - if test -n "$CPPSTD"; then CONFIGOPTS+=(--enable-cpp11-testing "CXXFLAGS=-std=$CPPSTD $CXXFLAGS"); fi + if test -z "$CPPSTD"; then CONFIGOPTS+=("--disable-cpp11-testing"); fi + if test -n "$CPPSTD"; then CONFIGOPTS+=("CXXFLAGS=-std=$CPPSTD $CXXFLAGS"); fi if test -n "$CSTD"; then CONFIGOPTS+=("CFLAGS=-std=$CSTD $CFLAGS"); fi if test -n "$SWIGLANG"; then CONFIGOPTS+=(--without-alllang --with-$WITHLANG); fi echo "${CONFIGOPTS[@]}" @@ -416,8 +454,8 @@ jobs: esac # Stricter compile flags for examples. Various headers and SWIG generated code prevents full use of -pedantic. - cflags=$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) && echo $cflags - cxxflags=$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) && echo $cxxflags + cflags=$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) + cxxflags=$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) make check-$SWIGLANG-version make check-$SWIGLANG-enabled make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags" diff --git a/.gitignore b/.gitignore index b51da0fdf..4fee29d54 100644 --- a/.gitignore +++ b/.gitignore @@ -160,6 +160,14 @@ Examples/java/doxygen/javadocs Examples/test-suite/javascript/*/ *.gyp +# Lua +Examples/lua/dual/dual +Examples/lua/dual/swigluarun.h +Examples/lua/embed/embed +Examples/lua/embed2/embed2 +Examples/lua/embed3/embed3 +Examples/lua/embed3/swigluarun.h + # OCaml Examples/test-suite/ocaml/*.ml* Examples/test-suite/ocaml/*.cm* diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index c11479fed..000000000 --- a/.travis.yml +++ /dev/null @@ -1,499 +0,0 @@ -language: cpp -matrix: - include: - - compiler: clang - os: linux - env: SWIGLANG= - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG= - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG= BUILDSYSTEM=cmake - dist: xenial - - os: linux - env: SWIGLANG= GCC=4.4 - dist: xenial - - os: linux - env: SWIGLANG= GCC=4.6 - dist: xenial - - os: linux - env: SWIGLANG= GCC=4.7 - dist: xenial - - os: linux - env: SWIGLANG= GCC=4.8 - dist: xenial - - os: linux - env: SWIGLANG= GCC=4.9 - dist: xenial - - os: linux - env: SWIGLANG= GCC=6 - dist: xenial - - os: linux - env: SWIGLANG= GCC=7 - dist: xenial - - os: linux - env: SWIGLANG= GCC=8 - dist: xenial - - os: linux - env: SWIGLANG= GCC=9 - dist: xenial - - os: linux - env: SWIGLANG= GCC=10 - dist: focal - - compiler: gcc - os: linux - env: SWIGLANG=csharp - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=d VER=2.066.0 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=d VER=2.086.1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=go VER=1.3 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=go VER=1.8 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=go VER=1.12 CSTD=gnu99 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=go VER=1.16 CSTD=gnu99 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=guile - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=java - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=node VER=6 CPP11=1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=node VER=8 CPP11=1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=node VER=10 CPP11=1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=node VER=12 CPP11=1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=node VER=14 CPP11=1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=node VER=16 CPP14=1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=jsc - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=javascript ENGINE=v8 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=lua - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=lua VER=5.3 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=mzscheme - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ocaml - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=octave SWIGJOBS=-j2 - dist: xenial # Octave v4.0.0 - - compiler: gcc - os: linux - env: SWIGLANG=octave SWIGJOBS=-j2 CPP11=1 - dist: bionic # Octave v4.2.2 - - compiler: gcc - os: linux - env: SWIGLANG=perl5 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=php VER=7.4 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=php VER=8.0 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=php VER=7.0 CONFIGOPTS=--enable-cpp11-testing CPPSTD=c++11 - dist: bionic - - compiler: gcc - os: linux - env: SWIGLANG=php VER=7.1 CONFIGOPTS=--enable-cpp11-testing CPPSTD=c++11 - dist: bionic - - compiler: gcc - os: linux - env: SWIGLANG=php VER=7.2 CONFIGOPTS=--enable-cpp11-testing CPPSTD=c++11 - dist: bionic - - compiler: gcc - os: linux - env: SWIGLANG=php VER=7.3 CONFIGOPTS=--enable-cpp11-testing CPPSTD=c++11 - dist: bionic - - compiler: gcc - os: linux - env: SWIGLANG=php VER=7.4 CONFIGOPTS=--enable-cpp11-testing CPPSTD=c++11 - dist: bionic - - compiler: gcc - os: linux - env: SWIGLANG=php VER=8.0 CONFIGOPTS=--enable-cpp11-testing CPPSTD=c++11 - dist: bionic - - compiler: gcc - os: linux - env: SWIGLANG=python # 2.7 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.2 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.3 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.4 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.5 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.6 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.7 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.8 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python PY3=3 VER=3.9 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES="-builtin -O" - dist: xenial - - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1 PY3=3 VER=3.9 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.4 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.5 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.7 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.8 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.9 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES="-builtin -O" PY3=3 VER=3.9 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.9 SWIGOPTPY3= - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-O - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=python SWIG_FEATURES=-O PY3=3 VER=3.9 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=r - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=1.9 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.0 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.1 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.2 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.3 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.4 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.5 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.6 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=2.7 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ruby VER=3.0 CSTD=c99 - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=scilab - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=tcl - dist: xenial - - os: linux - env: SWIGLANG=csharp CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=go VER=1.6 CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=java CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=python CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=r CPP11=1 # Note: making 'R CMD SHLIB' use a different compiler is non-trivial - dist: xenial - - os: linux - env: SWIGLANG=ruby CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=tcl CPP11=1 - dist: xenial - - os: linux - env: SWIGLANG=csharp GCC=6 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=go VER=1.6 GCC=6 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=java GCC=6 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=python GCC=6 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=ruby GCC=6 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=tcl GCC=6 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=java GCC=7 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=python GCC=7 CPP14=1 - dist: xenial - - os: linux - env: SWIGLANG=csharp GCC=8 CPP17=1 - dist: xenial - - os: linux - env: SWIGLANG=java GCC=8 CPP17=1 - dist: xenial - - os: linux - env: SWIGLANG=python GCC=8 CPP17=1 PY3=3 VER=3.9 - dist: xenial - - os: linux - env: SWIGLANG=csharp GCC=9 CPP17=1 - dist: xenial - - os: linux - env: SWIGLANG=java GCC=9 CPP17=1 - dist: xenial - - os: linux - env: SWIGLANG=python GCC=9 CPP17=1 PY3=3 VER=3.9 - dist: xenial - - os: linux - arch: s390x - env: SWIGLANG=ruby CPP11=1 - dist: xenial - - compiler: gcc - os: osx - osx_image: xcode12.2 - env: SWIGLANG= - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG= BUILDSYSTEM=cmake - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG= - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=csharp - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=go CSTD=gnu99 - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=guile CSTD=c11 - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=java - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=lua -# octave-6.1 not working -# - compiler: clang -# os: osx -# osx_image: xcode12.2 -# env: SWIGLANG=octave SWIGJOBS=-j2 CPP11=1 - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=perl5 - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=python - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=python PY3=3 - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=ruby - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=tcl - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=java CPP17=1 - - compiler: clang - os: osx - osx_image: xcode12.2 - env: SWIGLANG=python PY3=3 CPP17=1 - - allow_failures: - # Newer version of D not yet working/supported - - compiler: gcc - os: linux - env: SWIGLANG=d VER=2.086.1 - dist: xenial - # Experimental languages - - compiler: gcc - os: linux - env: SWIGLANG=mzscheme - dist: xenial - - compiler: gcc - os: linux - env: SWIGLANG=ocaml - dist: xenial - -before_install: - - date -u - - uname -a - - if test "$TRAVIS_OS_NAME" = "linux"; then lscpu; grep "model name" /proc/cpuinfo || echo 'Unknown CPU model'; grep "MemTotal" /proc/meminfo || echo 'Unknown system memory amount'; fi - - if test "$TRAVIS_OS_NAME" = "osx"; then sysctl -a | grep brand_string; fi - # Travis overrides CC environment with compiler predefined values - - if test -n "$GCC"; then export CC="gcc-$GCC" && export CXX="g++-$GCC"; fi -install: - - if test "$TRAVIS_OS_NAME" = "linux"; then source Tools/travis-linux-install.sh; fi - - if test "$TRAVIS_OS_NAME" = "osx"; then source Tools/travis-osx-install.sh; fi - - ls -la $(which $CC) $(which $CXX) && $CC --version && $CXX --version -script: - - if test "$BUILDSYSTEM" = "cmake"; then cmake --version && mkdir -p build/build && cd build/build && CXXFLAGS="-Wall -Wextra -Werror" CFLAGS="-Wall -Wextra -Werror" cmake -DCMAKE_INSTALL_PREFIX=~/.local ../.. && make install && ctest --output-on-failure -V && exit 0; fi - - echo 'Configuring...' && echo -en 'travis_fold:start:script.1\\r' - - if test -n "$CPP11"; then CONFIGOPTS+=(--enable-cpp11-testing "CXXFLAGS=-std=c++11 $CXXFLAGS" "CFLAGS=-std=c11 $CFLAGS") && export CSTD=c11 && export CPPSTD=c++11; fi - - if test -n "$CPP14"; then CONFIGOPTS+=(--enable-cpp11-testing "CXXFLAGS=-std=c++14 $CXXFLAGS" "CFLAGS=-std=c11 $CFLAGS") && export CSTD=c11 && export CPPSTD=c++14; fi - - if test -n "$CPP17"; then CONFIGOPTS+=(--enable-cpp11-testing "CXXFLAGS=-std=c++17 $CXXFLAGS" "CFLAGS=-std=c17 $CFLAGS") && export CSTD=c17 && export CPPSTD=c++17; fi - - if test -n "$SWIGLANG"; then CONFIGOPTS+=(--without-alllang --with-$WITHLANG); fi - - echo "${CONFIGOPTS[@]}" - - ./autogen.sh && mkdir -p build/build && cd build/build && ../../configure "${CONFIGOPTS[@]}" - - echo -en 'travis_fold:end:script.1\\r' - - make -s $SWIGJOBS - - ./swig -version && ./swig -pcreversion - - if test -z "$SWIGLANG"; then make -s $SWIGJOBS check-ccache; fi - - if test -z "$SWIGLANG"; then make -s $SWIGJOBS check-errors-test-suite; fi - - echo 'Installing...' && echo -en 'travis_fold:start:script.2\\r' - - if test -z "$SWIGLANG"; then sudo make -s install && swig -version && ccache-swig -V; fi - - echo -en 'travis_fold:end:script.2\\r' - # Stricter compile flags for examples. Various headers and SWIG generated code prevents full use of -pedantic. - - if test -n "$SWIGLANG"; then cflags=$($TRAVIS_BUILD_DIR/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) && echo $cflags; fi - - if test -n "$SWIGLANG"; then cxxflags=$($TRAVIS_BUILD_DIR/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) && echo $cxxflags; fi - - if test -n "$SWIGLANG"; then make -s check-$SWIGLANG-version; fi - - if test -n "$SWIGLANG"; then make check-$SWIGLANG-enabled; fi - - if test -n "$SWIGLANG"; then make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags"; fi - - if test -n "$SWIGLANG"; then make $SWIGJOBS check-$SWIGLANG-test-suite CFLAGS="$cflags" CXXFLAGS="$cxxflags"; fi - - echo 'Cleaning...' && echo -en 'travis_fold:start:script.3\\r' - # Skip on osx as often fails with: rm: Resource temporarily unavailable - - if test "$TRAVIS_OS_NAME" != "osx"; then make check-maintainer-clean && ../../configure $CONFIGOPTS; fi - - echo -en 'travis_fold:end:script.3\\r' diff --git a/ANNOUNCE b/ANNOUNCE index e50bcd463..e78be2268 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -25,11 +25,11 @@ Availability ============ The release is available for download on Sourceforge at - http://prdownloads.sourceforge.net/swig/swig-4.1.0.tar.gz + https://prdownloads.sourceforge.net/swig/swig-4.1.0.tar.gz A Windows version is also available at - http://prdownloads.sourceforge.net/swig/swigwin-4.1.0.zip + https://prdownloads.sourceforge.net/swig/swigwin-4.1.0.zip Please report problems with this release to the swig-devel mailing list, details at http://www.swig.org/mail.html. diff --git a/CHANGES b/CHANGES index 05834910a..3ddd94d2b 100644 --- a/CHANGES +++ b/CHANGES @@ -3137,7 +3137,7 @@ Version 3.0.3 (30 Dec 2014) 2014-09-12: olly [PHP] Add support for specifying any PHP interfaces a wrapped class - implements, e.g.: %typemap("phpinterfaces") MyIterator "Iterator"; + implements, e.g.: %typemap("phpinterfaces") MyIterator "Iterator" 2014-09-11: olly [PHP] Fix throwing a PHP exception through C++ from a subclassed @@ -8396,8 +8396,8 @@ Version 1.3.30 (November 13, 2006) javabase/csbase typemap, eg in the following, 'Me' will be the base class, no matter what Foo is really derived from in the C++ layer. - %typemap(javabase, replace="1") Foo "Me"; - %typemap(csbase, replace="1") Foo "Me"; + %typemap(javabase, replace="1") Foo "Me" + %typemap(csbase, replace="1") Foo "Me" Previously it was not possible for the javabase/csbase typemaps to override the C++ base. @@ -9884,7 +9884,7 @@ Version 1.3.28 (February 12, 2006) solutions is to write: %typemap(in) A * {...} - %typemap(freeag) A * ""; + %typemap(freeag) A * "" overload 'freearg' with an empty definition. @@ -11314,20 +11314,20 @@ Version 1.3.27 (October 15, 2005) then the typemap will be inserted without the block imposed by the brackets, similar to - %typemap(in) Hello "..."; + %typemap(in) Hello "..." So, why you don't just use the quote style?, because: 1.- The quote style doesn't get preprocessed, for example - %typemap(in) Hello "$1= SWIG_macro($1);"; + %typemap(in) Hello "$1= SWIG_macro($1);" here, SWIG_macro doesn't get expanded 2.- Inside a quote typemap, you have to use quotes carefully - %typemap(in) Hello "$1 = \"hello\" "; + %typemap(in) Hello "$1 = \"hello\" " 3.- You can't make emacs and/or other editors to indent inside a string!. @@ -11529,7 +11529,7 @@ Version 1.3.26 (October 9, 2005) %define hello(name, Type) %define name ## a(Type) - %typemap(in) Type "hello;"; + %typemap(in) Type "hello;" %enddef %enddef @@ -13525,7 +13525,7 @@ Version 1.3.23 (November 11, 2004) whereupon the default of 0 was used. You can get the same behaviour for C code by using the "default" typemap: - %typemap(default) int val "$1 = 0;"; + %typemap(default) int val "$1 = 0;" %{ void foo(int val); %} @@ -13854,9 +13854,11 @@ Version 1.3.22 (September 4, 2004) specifiers from the C type. This makes it possible, for instance, to control whether a C "char" argument takes a Lisp character or a Lisp integer value. The default (taking Lisp characters) is done by these built-in typemaps: - %typemap(ffitype) char ":char"; %typemap(lisptype) char "character"; + %typemap(ffitype) char ":char" + %typemap(lisptype) char "character" If char means an integer instead, use these typemaps: - %typemap(ffitype) char ":char"; %typemap(lisptype) char "integer"; + %typemap(ffitype) char ":char" + %typemap(lisptype) char "integer" 08/22/2004: wsfulton As discussed in bug #772453, the SWIG library directory is now installed @@ -18874,9 +18876,9 @@ Version 1.3.14 (August 12, 2002) shadowinterface Note that it is possible to target a particular proxy class: - %typemap(javaimports) Foo "import java.util.*"; + %typemap(javaimports) Foo "import java.util.*" or a particular type wrapper class: - %typemap(javaimports) double* "import java.math.*"; + %typemap(javaimports) double* "import java.math.*" Note that $javaclassname in these typemaps are substituted with either the proxy classname when using proxy classes or the SWIGTYPE class name. @@ -19614,8 +19616,8 @@ Version 1.3.12 (June 2, 2002) typemap must exactly match up with the "in" or "ignore" typemap. For example: - %typemap(in) (char *data, int len) { ... }; - %typemap(freearg) char *data { ... }; + %typemap(in) (char *data, int len) { ... } + %typemap(freearg) char *data { ... } void foo(char *data, int len); @@ -21071,7 +21073,7 @@ Version 1.3.11 (January 31, 2002) Second, a typemap can force a no-match by defining - %typemap(in) sometype "pass"; + %typemap(in) sometype "pass" If this is used, the typemap system will *not* record a typemap match for "sometype". This can be used to block @@ -21079,7 +21081,7 @@ Version 1.3.11 (January 31, 2002) a typemap feature for some type, you could do this. // Do not allow global variables of type 'const char *' to be set. - %typemap(varin) const char * "pass"; + %typemap(varin) const char * "pass" It might also be possible to use this to do subtle and strange things with typemaps. For example, if you wanted to @@ -21093,8 +21095,8 @@ Version 1.3.11 (January 31, 2002) ... return a value ... } /* Block unqualified typemaps defined above */ - %typemap(ignore) const blah * "pass"; - %typemap(argout) const blah * "pass"; + %typemap(ignore) const blah * "pass" + %typemap(argout) const blah * "pass" %typemap(in) const blah * { ... get input value ... } @@ -21871,7 +21873,7 @@ Version 1.3.10 (December 10, 2001) %typemap directive can now accept nearly arbitrary keyword parameters. For example: - %typemap(in,parse="i",doc="integer") int "..."; + %typemap(in,parse="i",doc="integer") int "..." The purpose of the keyword parameters is to supply code generation hints to the target language module. The intepretation of the @@ -23949,7 +23951,7 @@ Version 1.3 Alpha 4 (September 4, 2000) Typemaps can now be specified using string literals like this: - %typemap(in) int "$target = SvIV($source);"; + %typemap(in) int "$target = SvIV($source);" When code is specified like this, it is *NOT* enclosed inside a local scope (as with older typemap declarations). diff --git a/CHANGES.current b/CHANGES.current index 0abed204a..6fe039d30 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -7,6 +7,821 @@ the issue number to the end of the URL: https://github.com/swig/swig/issues/ Version 4.1.0 (in progress) =========================== +2022-09-17: wsfulton + Add missing typecheck typemaps for std::auto_ptr and std::unique_ptr to + fix overloading when using these types. + +2022-09-17: wsfulton + [Guile] Add error checking to SWIGTYPE and SWIGTYPE & in typemaps to prevent + seg faults when passing #nil to these parameter types. + +2022-09-16: wsfulton + #999 Provide SWIGTYPE MOVE typemaps in swigmove.i for implementing full + move semantics when passing parameters by value. + +2022-08-31: wsfulton + #999 Improve move semantics when using rvalue references. + The SWIGTYPE && input typemaps now assume the object has been moved. + + These typemaps have been changed assuming that after the function call, + the rvalue reference parameter has been moved. The parameter's proxy class + that owns the C++ object thus has the underlying pointer set to null + so that the (moved from, but still valid) C++ object cannot be used again + and the the object is additionally deleted. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-08-28: wsfulton + [Octave] SWIG now marshalls a C/C++ NULL pointer into the null matrix, []. + SWIG has always marshalled the null matrix into a NULL pointer; this remains + and now we have consistency in representing a NULL pointer. + +2022-08-26: wsfulton + [Racket] SWIG now marshalls a C/C++ NULL pointer into a null value by calling + scheme_make_null(), so that scheme's null? is true for a NULL C/C++ pointer value. + +2022-08-18: wsfulton + [Racket] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-08-13: wsfulton + [Guile] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-08-11: wsfulton + [Lua] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-08-05: wsfulton + [D] Fix occasional undefined behaviour with inheritance hierarchies, particularly + when using virtual inheritance as the pointers weren't correctly upcast from derived + class to base class when stored in the base's proxy class. + +2022-08-05: wsfulton + [D] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-08-03: wsfulton + [Javascript] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-08-02: wsfulton + [Octave] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-08-01: wsfulton + [Python] Add initialisers for additional members in PyHeapTypeObject + (builtin mode) for Python-3.11 - _ht_tpname, _spec_cache. + +2022-07-30: wsfulton + C++20 has deprecated std::basic_string<>::reserve() and the C++11 method + std::basic_string<>::shrink_to_fit() is a replacement that can be used. + std_string.i and std_wstring.i provided wrappers for reserve with the following + template instantiations: + + %template(string) std::basic_string; + %template(wstring) std::basic_string; + + The reserve method is no longer wrapped, however the shrink_to_fit() method + can be used as an alternative from the target language (the generated wrappers + call reserve() instead if C++<=20). + + Note that std::basic_string<>::reserve(size_t n) is still wrapped unchanged. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-07-30: wsfulton + [Tcl] Add support for std::unique_ptr in std_unique_ptr.i. + Add support for std::auto_ptr in std_auto_ptr.i. + +2022-07-27: ZackerySpytz, olly + #1678 Support parsing C++20 templated lambdas. + +2022-07-27: ZackerySpytz, olly + #1622 Add support for the C++20 spaceship operator (<=>). + +2022-07-26: olly + [Tcl] https://sourceforge.net/p/swig/bugs/977/ + Fix handling of long long on 32-bit platforms. This fix raises + SWIG's minimum supported Tcl version to 8.4.0 (which was released + just under 20 years ago). + +2022-07-26: olly + Fix incorrect operator precedence in preprocessor expressions. + +2022-07-25: olly + Support for C++14 binary integer literals in preprocessor expressions. + +2022-07-20: wsfulton + [C#, Java] Ensure the order of interfaces generated in proxy interfaces for the + %interface family of macros is the same as that parsed from the bases in C++. + +2022-07-20: jicks, Ingener74, olly + #422 [Python] Fix mishandling of a Python class inheriting from + multiple SWIG-wrapped director classes. + +2022-07-19: wsfulton + #692 [C#, Java, Perl, Python, Ruby] std::unique_ptr and std::auto_ptr typemaps + provided for inputs types in std_unique_ptr.i and std_auto_ptr.i. + + Now these smart pointers can be used as input parameters to functions. A proxy + class instance transfers memory ownership of the underlying C++ object from the + proxy class to a smart pointer instance passed to the wrapped function. + +2022-07-19: jschueller + [Python] #2314 Drop support for Python 3.2. + +2022-07-19: olly + Remove remaining support code for classic macos, which has not been + supported by Apple for over 20 years now. + +2022-07-12: wsfulton + #999 Performance optimisation for parameters passed by value that are C++11 movable. + The C++ wrappers create a temporary variable for a parameter to be passed to a + function. This is initially default constructed and then copy assigned from the + instance being passed in from the target language. This is unchanged, however, + when the temporary variable is passed to the wrapped function, it is now done using + std::move. If the type is move constructible, the move constructor will be used + instead of the copy constructor. + +2022-07-12: wsfulton + [Perl] Add std::auto_ptr support in std_auto_ptr.i library file. + +2022-07-12: erezgeva + [Perl] Add std::unique_ptr support in std_unique_ptr.i library file. + +2022-07-07: olly + [xml] #2213 XML has been moved to "Experimental" target language + status. It's not in good shape and is likely to be removed unless + somebody steps up to bring it up to the expected standard (it fails + to even meet the criteria for "Experimental" currently). + +2022-07-07: jmarrec + #1158 #2286 Add basic support for C++11 attributes. These are now + crudely ignored by SWIG's parser's tokeniser, which is better that + failing with a parse error. + +2022-07-05: ianlancetaylor + [Go] #2245 Handle NULL pointers for string* conversions. + Rearrange generation of director methods and rename + receiver argument from p to swig_p. + +2022-07-03: wsfulton + #999 Performance optimisation for directors for classes passed by value. The directorin + typemaps in the director methods now use std::move on the input parameter when + copying the object from the stack to the heap prior to the callback into the target + language, thereby taking advantage of move semantics if available. + +2022-07-02: wsfulton + #1722 [C#, Java, Python, Ruby] Add std::unique_ptr support. Ported from std::auto_ptr. + Use the %unique_ptr(T) macro as follows for usage std::unique_ptr. For example, for + a class called Klass: + + %include "std_unique_ptr.i" + %unique_ptr(Klass) + + Support is currently limited to only returning a std::unique_ptr from a function. + +2022-06-29: wsfulton + #999 #1044 Enhance SWIGTYPE "out" typemaps to use std::move when copying + objects, thereby making use of move semantics when wrapping a function returning + by value if the returned type supports move semantics. + + Wrapping functions that return move only types 'by value' now work out the box + without having to provide custom typemaps. + + The implementation removed all casts in the "out" typemaps to allow the compiler to + appropriately choose calling a move constructor, where possible, otherwise a copy + constructor. The implementation also required modifying SwigValueWrapper to + change a cast operator from: + + SwigValueWrapper::operator T&() const; + + to + + #if __cplusplus >=201103L + SwigValueWrapper::operator T&&() const; + #else + SwigValueWrapper::operator T&() const; + #endif + + This is not backwards compatible for C++11 and later when using the valuewrapper feature + if a cast is explicitly being made in user supplied "out" typemaps. Suggested change + in custom "out" typemaps for C++11 and later code: + + 1. Try remove the cast altogether to let the compiler use an appropriate implicit cast. + 2. Change the cast, for example, from static_cast to static_cast, using the + __cplusplus macro if all versions of C++ need to be supported. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-06-15: wsfulton + #2039 Add move assignment operator to SwigValueWrapper used by the + valuewrapper feature. + +2022-06-04: sethrj + Enhance $typemap to support typemap attributes. + + $typemap(method:attribute, typepattern) + + For example: + + %typemap(cstype, out="object") XClass "XClass" + %typemap(cscode) BarClass %{ + $typemap(cstype:out, XClass) bar() { + return null; + } + + which expands to + + object bar() { + return null; + } + +2022-05-30: wsfulton + [C#, D] Add new special variable expansion: $imfuncname. + Expands to the function name called in the intermediary class. + +2022-05-30: LindleyF + [Java] #2042 Add new special variable expansion: $imfuncname. + Expands to the function name called in the intermediary class. + +2022-05-28: jkuebart + [Java] On some versions of Android, specifically Android 6, + detaching the current thread from the JVM after every invocation + causes a memory leak. + + Offer SWIG_JAVA_DETACH_ON_THREAD_END to configure a behaviour + where the JVM is only detached in the thread destructor. + + See https://developer.android.com/training/articles/perf-jni#threads. + +2022-05-27: xypron + [Python] #2277 Define PY_SSIZE_T_CLEAN macro before #include "Python.h" as + recommended in Python 3.7 and later. + + To avoid this macro definition, add the following to your interface file so + that SWIG_NO_PY_SSIZE_T_CLEAN is defined at the beginning of the C++ wrappers: + + %begin %{ + #define SWIG_NO_PY_SSIZE_T_CLEAN + %} + +2022-05-26: rokups + [C#] #1323 Modify SwigDerivedClassHasMethod for a more efficient director + implementation when calling virtual methods that are not overridden. + +2022-05-15: erezgeva, eiselekd + [Lua, Perl, Octave, PHP, Tcl] #2275 #2276 #2283 Add argcargv.i library containing + (int ARGC, char **ARGV) multi-argument typemaps. + + Document this library in Typemaps.html. + +2022-05-07: KrisThielemans + [Python] Fix "too many initializers for 'PyHeapTypeObject'" errors + using PyPy 3.8 and later. + +2022-05-04: wsfulton + [C#] Add C# wchar_t * director typemaps + +2022-04-20: cminyard + Fix an issue where newlines were not properly generated + for godirectorin typemaps. If you have a virtual function + not assigned to zero, in some cases it won't generate a + newline and you will see errors: + example.go:1508:3: expected ';', found swig_r + when compiling the go code. + + Also add an example of using goin and godirectorin and add + a test for this situation. + +2022-04-29: jason-daly, JerryJoyce, wsfulton + [C#] #1233 Add wchar_t * and std::wstring Unicode string support on Linux. + +2022-04-11: robinst + #2257 Fix new Ruby 3.2 warning "undefining the allocator of T_DATA + class swig_runtime_data". + +2022-04-07: olly + #1750 SWIG now recognises and ignores Doxygen group commands `@{` and `@}`. + +2022-04-06: wsfulton + ./configure now enables C++11 and later C++ standards testing by default (when + running: 'make check'). + + The options to control this testing are the same: + + ./configure --enable-cpp11-testing + ./configure --disable-cpp11-testing + + But the former is now the default and the latter can be used to turn off C++11 and + later C++ standards testing. + +2022-04-06: wsfulton + [Python] #1635 The "autodoc" feature no longer overrides Doxygen comments + in the generated docstring. + + If a "docstring" feature is present it will still override a Doxygen comment. + If the "autodoc" feature is also present, the combined "autodoc" and "docstring" + will override the Doxygen comment. If no "docstring" is present then the + "autodoc" feature will not be generated when there is a Doxygen comment. + + This way the "autodoc" feature can be specified and used to provide documentation + for 'missing' Doxygen comments. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-04-01: olly + Remove undocumented and non-functional -browse command line option. + +2022-03-26: eltoder + [Python] #1684 Use different capsule names with and without -builtin + + Types generated with and without -builtin are not compatible. Mixing + them in a common type list leads to crashes. Avoid this by using + different capsule names: "type_pointer_capsule" without -builtin and + "type_pointer_capsule_builtin" with. + +2022-03-25: wsfulton + The debug command line options that display parse tree nodes + (-debug-module, -debug-top, -debug-symtabs) now display previously hidden + linked list pointers which are useful for debugging parse trees. + + Added new command line option -debug-quiet. This suppresses the display + of most linked list pointers and symbol table pointers in the parse tree nodes. + + The keys in the parse tree node are now shown in alphabetical order. + +2022-03-24: wsfulton + #2244 Fix using declaration in derived class bugs when all the base + class's overloaded methods were overridden in the derived class - + fixes "multiply defined" errors. + +2022-03-23: wsfulton + [Python] #1779 The -py3 option is deprecated and now has no effect on the + code generated. Use of this option results in a deprecated warning. + The related SWIGPYTHON_PY3 macro that this option defined is no longer generated. + + Note that %pythonnondynamic feature generates a metaclass that works on both + Python 2 and Python 3. + +2022-03-21: wsfulton + [Python] #1779 pyabc.i for abstract base classes now supports versions of + Python prior to 3.3 by using the collection module for these older versions. + Python-3.3 and later continue to use the collections.abc module. + The -py3 option no longer has any effect on the %pythonabc feature. + +2022-03-21: jschueller, jim-easterbrook, wsfulton + [Python] #2137 C++ static member functions no longer generate a "flattened" + name in the Python module. For example: + + s = example.Spam() + s.foo() # Spam::foo() via an instance + example.Spam.foo() # Spam::foo() using class method + example.Spam_foo() # Spam::foo() "flattened" name + + The "flattened" name is no longer generated, but can be generated + by using the new -flatstaticmethod option. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-03-18: ianlancetaylor + [Go] #337 Implement %extend base methods in child classes. + +2022-03-17: olly + [Python] #1779 SWIG's Python test-suite and examples are now + run with Python 3 by default. To run them with Python 2, set + PY2 to a non-empty value, e.g.: + + make check-python-test-suite PY2=1 + +2022-03-16: olly + [Go] #683 -intgosize is now optional - if not specified the + generated C/C++ wrapper code will use ptrdiff_t for intgo and + size_t for uintgo. + +2022-03-15: ianlancetaylor + [Go] Add typemaps for std::string*. + +2022-03-15: ianlancetaylor + [Go] Don't convert arrays to pointers if there is a "gotype" + typemap entry. + +2022-03-15: ianlancetaylor + [Go] Add documentation note about Go and C++ exceptions. + +2022-03-12: wsfulton + #1524 %interface family of macros no longer contain the getter/setter + methods for wrapping variables. The interface only contains + virtual and non-virtual instance methods, that is, no static methods. + Enums are also no longer added to the interface (affects Java only where + they were missing from the proxy class, C# never had them in the interface). + + *** POTENTIAL INCOMPATIBILITY *** + +2022-03-12: wsfulton + #1277 Fixes for the family of %interface macros, %interface, + %interface_impl and %interface_custom fixes for overloaded methods + in an inheritance chain. + + When C++ methods are not able to be overloaded in a derived class, + such as when they differ by just const, or the target language + parameters types are identical even when the C++ parameter types + are different, SWIG will ignore one of the overloaded methods with + a warning. A %ignore is required to explicitly ignore one of the + overloaded methods to avoid the warning message. Methods added + in the derived classes due to one of the %interface macros are now + similarly ignored/not added to the derived class. + + The methods added to the derived classes can now also be modified + via %feature and %rename. + +2022-03-08: ianlancetaylor + [Go] Treat a nil argument as a NULL pointer. + +2022-03-08: ianlancetaylor + [Go] Add documentation notes about thread local storage. + +2022-03-08: olly + #1006 SWIG now copes with an interface filename specified on the + command line which contains a closing parenthesis `)`, and more + generally with attributes to `%include` and `%import` which + are quoted and contain parentheses. + +2022-03-07: Omar Medina + [Tcl] https://sourceforge.net/p/swig/bugs/1290/ + Fix SWIG_AsWCharPtrAndSize() to actually assign to result + variable. It looks like SWIG/Tcl wide character handling is + currently fundamentally broken except on systems which use wide + characters as the system encoding, but this should fix wrapping + functions which take a wide string as a parameter on Microsoft + Windows. + +2022-03-07: olly + [Javascript] #682 Fix handling of functions which take void*. + +2022-03-06: olly + SWIG should now reliably exit with status 0 if the run was + successful and status 1 if there was an error (or a warning and + -Werror was in effect). + + Previously in some situations SWIG would try to exit with the + status set to the number of errors encountered, but that's + problematic - for example if there were 256 errors this would + result in exit status 0 on most platforms. Also some error + statuses have special meanings e.g. those defined by . + Also SWIG/Javascript tried to exit with status -1 in a few places + (which typically results in exit status 255). + +2022-03-05: wsfulton + #1441 Fix using declaration in derived class incorrectly introducing a method + from a base class when the using declaration is declared before the method + declaration. Problem occurred when within a namespace and the parameter types + in the method signatures were not fully qualified. +2022-03-05: ianlancetaylor + [Go] Treat non-const references as pointers. + +2022-03-05: ianlancetaylor + In SWIG Go testsuite, fail test if "go build" fails. + +2022-03-03: olly + #1901 #2223 SWIG should now always exit cleanly if memory + allocation fails, including removing any output files created + during the current run. + + Previously most places in the code didn't check for a NULL return + from malloc()/realloc()/calloc() at all, typically resulting in + undefined behaviour; some places used assert() to check for a NULL + return (which is a misuse of assert() and such checks disappear if + built with NDEBUG defined leaving us back with undefined + behaviour). + +2022-03-03: olly + #891 Report errors for typemap attributes without a value + (previously SWIG segfaulted) and for typemap types with a value + (previously the value was quietly ignored). + + The old way of specifying a language name in the typemap attributes + is no longer supported (it has been deprecated for 16 years). + +2022-03-02: geographika, wsfulton + [Python] #1951 Add Python variable annotations support. + + Both function annotations and variable annotations are turned on using the + "python:annotations" feature. Example: + + %feature("python:annotations", "c"); + + struct V { + float val; + }; + + The generated code contains a variable annotation containing the C float type: + + class V(object): + val: "float" = property(_example.V_val_get, _example.V_val_set) + ... + + Python 3.5 and earlier do not support variable annotations, so variable + annotations can be turned off with a "python:annotations:novar" feature flag. + Example turning on function annotations but not variable annotations globally: + + %feature("python:annotations", "c"); + %feature("python:annotations:novar"); + + or via the command line: + + -features python:annotations=c,python:annotations:novar + + *** POTENTIAL INCOMPATIBILITY *** + +2022-02-27: wsfulton + [Python] #735 #1561 Function annotations containing C/C++ types are no longer + generated when using the -py3 option. Function annotations support has been + moved to a feature to provide finer grained control. It can be turned on + globally by adding: + + %feature("python:annotations", "c"); + + or by using the command line argument: + + -features python:annotations=c + + Also see entry dated 2022-03-02, regarding variable annotations. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-02-26: wsfulton + #655 #1840 Add new warning WARN_LANG_USING_NAME_DIFFERENT to warn when a + method introduced by a using declaration in a derived class cannot + be used due to a conflict in names. + +2022-02-24: olly + #1465 An invalid preprocessor expression is reported as a pair of + warnings with the second giving a more detailed message from the + expression evaluator. Previously SWIG prefixed the second message + with "Error:" - that was confusing as it's actually only a warning + by default so we've now dropped this prefix. + + Before: + + x.i:1: Warning 202: Could not evaluate expression '1.2' + x.i:1: Warning 202: Error: 'Floating point constant in preprocessor expression' + + Now: + + x.i:1: Warning 202: Could not evaluate expression '1.2' + x.i:1: Warning 202: Floating point constant in preprocessor expression + +2022-02-23: olly + #1384 Fix a preprocessor expression evaluation bug. A + subexpression in parentheses lost its string/int type flag and + instead used whatever type was left in the stack entry from + previous use. In practice we mostly got away with this because + most preprocessor expressions are integer, but it could have + resulted in a preprocessor expression incorrectly evaluating as + zero. If -Wextra was in use you got a warning: + + Warning 202: Error: 'Can't mix strings and integers in expression' + +2022-02-21: davidcl + [Scilab] Improve 5.5.2, 6.0.0 and 6.1.0 support. + + For Scilab 5, long names are reduced to small names preserving the + class prefix and accessor suffix (get or set). + + For Scilab 6, long names with the class prefix and accessor suffix + should be used on the user code. + + The `-targetversion` option has been removed as the generated code + now detects the Scilab version in loader.sce or builder.sce. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-02-20: wsfulton + Fix %warnfilter warning suppress for warning 315 SWIGWARN_PARSE_USING_UNDEF. + +2022-02-17: olly + [PHP] https://sourceforge.net/p/swig/bugs/1211/ + Fix to call cleanup code in exception situations and not to invoke + the freearg typemap twice in certain situations. + +2022-02-15: olly + #300 #368 Improve parser handling of % followed immediately by + an identifier. If it's not a recognised directive the scanner + now emits MODULO and then rescans what follows, and if the parser + then gives a syntax error we report it as an unknown directive. + This means that `a%b` is now allowed in an expression, and that + things like `%std::vector` now give an error rather + than being quietly ignored. + +2022-02-11: adr26 + [Python] #2154 Fix memory leak. + + SWIG python objects were being freed after the corresponding SWIG + module information was destroyed in Python 3, causing leaks when as + a result the object destructor could not be invoked. To prevent this + misordering, SWIG python objects now obtain a reference to the + Python capsule wrapping the module information, so that the module + information is correctly destroyed after all SWIG python objects + have been freed (and corresponding destructors invoked). + +2022-02-10: olly + [Tcl] https://sourceforge.net/p/swig/bugs/1207/ + https://sourceforge.net/p/swig/bugs/1213/ + + Fix Tcl generic input typemap for std::vector. + +2022-02-07: sethrj + #2196 Add alternative syntax for specifying fragments in typemaps. + + New syntax: + %typemap("in", fragment="frag1", fragment="frag2", fragment="frag3") {...} + which is equivalent to: + %typemap(in, fragment="frag1,frag2,frag3") {...} + + +2022-02-07: olly + #1806 Remove support for the "command" encoder, which was mostly + intended for use in `%rename` - most uses can be achieved using + the "regex" encoder, so we recommend using that instead. + + The "command" encoder suffers from a number of issues - as the + documentation for it admitted, "[it] is extremely slow compared to + all the other [encoders] as it involves spawning a separate process + and using it for many declarations is not recommended" and that it + "should generally be avoided because of performance + considerations". + + But it's also not portable. The design assumes that `/bin/sh` + supports `<<<` but that's a bash-specific feature so it doesn't + work on platforms where `/bin/sh` is not bash - it fails on + Debian, Ubuntu and probably some other Linux distros, plus most + non-Linux platforms. Microsoft Windows doesn't even have a + /bin/sh as standard. + + Finally, no escaping of the passed string is done, so it has + potential security issues (though at least with %rename the input + is limited to valid C/C++ symbol names). + +2022-02-06: olly + #2193 -DFOO on the SWIG command line now sets FOO to 1 for + consistency with C/C++ compiler preprocessors. Previously + SWIG set FOO to an empty value. + + Existing invocations of SWIG with `-DFOO` where the empty value + matters can be updated to `-DFOO=` which should work with both + old and new releases of SWIG. + + *** POTENTIAL INCOMPATIBILITY *** + +2022-02-06: sethrj + #2194 Classes that are non-assignable due to const data or const + reference members are now automatically detected. + +2022-02-04: friedrichatgc + [Octave] #1672 Fix for isobject for Octave 4.4 - 6.0. + +2022-02-03: olly + [C#] #283 #998 Fix memory leak in directorin typemap for + std::string. + +2022-02-03: olly + [Python] #967 Make `self` parameter available to user typemaps. + +2022-02-03: teythoon + [Python] #801 Fix -Wunused-parameter warnings with builtin, + +2022-02-03: teythoon + #801 Fix -Wstrict-prototypes warnings in generated pointer + functions. + +2022-02-03: olly + #660 https://sourceforge.net/p/swig/bugs/1081/ + Default parameter values containing method calls are now parsed and + handled - e.g. `x->foo(3,4)` and `y.z()`. + +2022-02-02: olly + [Ruby] https://sourceforge.net/p/swig/bugs/1136/ Fix remove of prefix + from method name to only remove it at the start. + +2022-02-01: olly + #231 Handle returning an object by reference in a C++ trailing + return type. + +2022-02-01: davidcl + [Scilab] #745 use SWIG__Init() as a C module init function. + +2022-02-01: olly + [OCaml] #2083 Fix to work when CAML_SAFE_STRING is on, which it is + by default in recent Ocaml releases. + +2022-01-31: mreeez + https://sourceforge.net/p/swig/bugs/1147/ + Fix copyToR() generated for a struct in a namespace. + +2022-01-29: fschlimb + #655 Better handling of using declarations. + +2022-01-29: dontpanic92 + [Go] #676 Fix code generated for a C++ class with a non-capitalised + name. + +2022-01-26: trex58 + #1919 #1921 #1923 Various fixes for AIX portability. + +2022-01-26: olly + #1935 Don't crash on an unclosed HTML tag in a doxygen comment + when -doxygen is specified. + +2022-01-25: olly + Constant expressions now support member access with `.` such as + `foo.bar`. Previous this only worked in a case like `x->foo.bar`. + +2022-01-25: olly + #2091 Support most cases of `sizeof` applied to an expression + in constant expressions. Previously there was only support for + `sizeof()` and expressions which syntactically look like a + type (such as `sizeof(foo)`). + +2022-01-25: olly + #80 #635 https://sourceforge.net/p/swig/bugs/1139/ + Add support for parsing common cases of `<` and `>` comparisons + in constant expressions. Adding full support for these seems hard + to do without introducing conflicts into the parser grammar, but in + fact all reported cases have had parentheses around the comparison + and we can support that with a few restrictions on the left side of + `<`. + +2022-01-25: wsfulton + New warning 327 for extern templates, eg: + + extern template class std::vector; + extern template void Func(); + + results in warning + + example.i:3: Warning 327: Extern template ignored. + example.i:4: Warning 327: Extern template ignored. + + Extern template classes previously resulted in warning 320. + +2022-01-24: romintomasetti + #2131 #2157 C++11 extern function template parsing error fix. + +2022-01-21: wsfulton + #2120 #2138 Replace legacy PCRE dependency with PCRE2. + This requires changes for building SWIG from source. See updated + html documentation in Preface.html and Windows.html. Updated + instructions are also shown when running ./configure if PCRE2 is not + found. Note that debian based systems can install PCRE2 using: + + apt install libpcre2-dev + + Note that https://github.com/swig/swig/wiki/Getting-Started also has + updated information for building from source. + +2022-01-19: olly + [PHP] #2027 Automatically generate PHP type declarations for PHP 8. + The generate code still compiles for PHP 7.x, but without type + declarations since PHP 7.x has much more limited type declaration + support. + +2022-01-18: olly + [Perl] #1629 Perl 5.8.0 is now the oldest version we aim to support. + +2022-01-14: wsfulton + [Python] Fix %callback and specifying the callback function as a + static member function using Python staticmethod syntax, such as + Klass.memberfunction instead of Klass_memberfunction when using + -builtin and -fastproxy. + +2022-01-11: wsfulton + [Python] Accept keyword arguments accessing static member functions when + using -builtin and kwargs feature and Python class staticmethod syntax. + The missing keyword argument support was only when using the + class staticmethod syntax, such as Klass.memberfunction, and not when + using the flat static method syntax, such as Klass_memberfunction. + +2022-01-04: juierror + [Go] #2045 Add support for std::array in std_array.i. + +2021-12-18: olly + [PHP] Add PHP keyword 'readonly' (added in 8.1) to the list SWIG + knows to automatically rename. This keyword is special in that PHP + allows it to be used as a function (or method) name. + +2021-12-07: vstinner + [Python] #2116 Python 3.11 support: use Py_SET_TYPE() + +2021-12-05: rwf1 + [Octave] #2020 #1893 Add support for Octave 6 up to and including 6.4. + Also add support for compiling with -Bsymbolic which is used by default + by mkoctfile. + +2021-12-02: jsenn + [Python] #2102 Fixed crashes when using embedded Python interpreters. + 2021-11-12: wsfulton [Javascript] v8 and node only. Fix mismatched new char[] and free() when wrapping C code char arrays. Now calloc is now used instead of @@ -257,7 +1072,6 @@ Version 4.1.0 (in progress) %typemap(csinterfacemodifiers) X "internal interface" - 2020-09-24: geefr [C#] #1868 Fix wchar_t* csvarout typemap for member variable wrappers. diff --git a/CMakeLists.txt b/CMakeLists.txt index 8a195de54..8a8862f63 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -73,11 +73,11 @@ if (MSVC) set (CMAKE_CXX_FLAGS "/EHsc ${CMAKE_CXX_FLAGS}") endif () -option (WITH_PCRE "Enable pcre" ON) +option (WITH_PCRE "Enable PCRE" ON) if (WITH_PCRE) - find_package (PCRE REQUIRED) + find_package (PCRE2 REQUIRED) set (HAVE_PCRE 1) - include_directories (${PCRE_INCLUDE_DIRS}) + include_directories (${PCRE2_INCLUDE_DIRS}) endif() if (WIN32) @@ -145,8 +145,8 @@ add_executable (swig ${PROJECT_BINARY_DIR}/Source/CParse/parser.c ${PROJECT_BINARY_DIR}/Source/CParse/parser.h ) -if (PCRE_FOUND) - target_link_libraries (swig ${PCRE_LIBRARIES}) +if (PCRE2_FOUND) + target_link_libraries (swig ${PCRE2_LIBRARIES}) endif () install (TARGETS swig DESTINATION bin) @@ -160,6 +160,7 @@ include (CPack) # few tests enable_testing () add_test (NAME cmd_version COMMAND swig -version) +add_test (NAME cmd_pcreversion COMMAND swig -pcreversion) add_test (NAME cmd_swiglib COMMAND swig -swiglib) add_test (NAME cmd_external_runtime COMMAND swig -external-runtime ext_rt.h) set_tests_properties(cmd_external_runtime PROPERTIES ENVIRONMENT "SWIG_LIB=${PROJECT_SOURCE_DIR}/Lib") diff --git a/Doc/Devel/cmdopt.html b/Doc/Devel/cmdopt.html index 5e90d2aba..10dc73170 100644 --- a/Doc/Devel/cmdopt.html +++ b/Doc/Devel/cmdopt.html @@ -60,7 +60,7 @@ and issues an error message if any unconsumed arguments are found. void Swig_check_options()
Checks all command line options to see if they have all been processed. If not, an error message is generated and -execution terminates with a call to exit(). This function is currently invoked in Source/Modules/main.cxx just before SWIG starts any processing of input files. +SWIG exits. This function is currently invoked in Source/Modules/main.cxx just before SWIG starts any processing of input files.

Utility Function

@@ -68,7 +68,7 @@ execution terminates with a call to exit(). This function is currentl void Swig_arg_error())
-A generic function that issues an error message about being unable to parse command line options. SWIG is terminated by a call to exit(). +A generic function that issues an error message about being unable to parse command line options and SWIG exits. diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html index c9082d3f6..d003d9dea 100644 --- a/Doc/Devel/internals.html +++ b/Doc/Devel/internals.html @@ -441,12 +441,12 @@ Resulting output: 
-hash len: 5
-get: hashval2
-hash item: hashval5 [h5]
-hash item: hashval1 [h1]
-hash item: hashval2 [h2]
-hash item: hashval3 [h3]
+list len: 5
+get: listval2
+list item: newlistval1
+list item: listval2
+list item: listval3
+list item: listval5
@@ -494,12 +494,12 @@ Resulting output: 
-list len: 5
-get: listval2
-list item: newlistval1
-list item: listval2
-list item: listval3
-list item: listval5
+hash len: 5
+get: hashval2
+hash item: hashval5 [h5]
+hash item: hashval1 [h1]
+hash item: hashval2 [h2]
+hash item: hashval3 [h3]
@@ -519,7 +519,27 @@ list item: listval5

2.10 Utility functions

-[ TODO ] +

+DOH wraps some standard C library functions - these wrapped versions should +always be used in code in the SWIG tool itself (but not in generated code). +When compiling with GCC or clang, the original library function names are +marked as "poisoned" symbols so you should get an error if you accidentally +use one of the unwrapped functions. These functions are: + +

    +
  • Calloc(m,n) : wrapper for calloc(m,n) which exits on memory failure so never returns NULL. +
  • Malloc(n) : wrapper for malloc(n) which exits on memory failure so never returns NULL. +
  • Realloc(p,n) : wrapper for realloc(p,n) which exits on memory failure so never returns NULL. +
  • Free(p) : wrapper for free(p) (doesn't currently do anything special, really done for consistency with Malloc() etc). +
  • Exit(r) : wrapper for exit(r) which for SWIG removes generated files if r>0. +
+ +abort() is also poisoned - please use Exit(EXIT_FAILURE) instead so that generated files are removed. +

+ +

+[ TODO document others ] +

3. Types and Typemaps

@@ -1194,12 +1214,12 @@ that are used after they have been deleted. This is because the DOH memory alloc grabs a chunk of memory from the C memory allocator and manages the usage internally. Stale DOH object usage can be checked for by defining DOH_DEBUG_MEMORY_POOLS in memory.c. If an attempt to use an object is made after the reference count is -zero, an assertion is triggered instead of quietly re-using the stale object... +zero, a fatal error is triggered instead of quietly re-using the stale object: 

-swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed.
+Fatal internal error: Attempt to delete a non-DOH object.
@@ -1209,7 +1229,7 @@ only recommended for diagnosing memory corruption problems.

-Copyright (C) 1999-2010 SWIG Development Team. +Copyright (C) 1999-2022 SWIG Development Team. diff --git a/Doc/Devel/plan-gsoc-2012.txt b/Doc/Devel/plan-gsoc-2012.txt index ac764fb2a..c217dad8d 100644 --- a/Doc/Devel/plan-gsoc-2012.txt +++ b/Doc/Devel/plan-gsoc-2012.txt @@ -45,7 +45,7 @@ Functionality ----------------- Note: - See 'http://www.stack.nl/~dimitri/doxygen/docblocks.html' for + See 'https://www.doxygen.nl/manual/docblocks.html' for the detailed description of Doxygen syntax and terms used in this section. @@ -72,10 +72,10 @@ Functionality ---- This section contains all doxygen tags taken from - http://www.stack.nl/~dimitri/doxygen/commands.html. If a tag is + https://www.doxygen.nl/manual/commands.html. If a tag is marked as 'ignored', then the tag is ignored, but the text is copied to the destination documentation. 'Not implemented' means that the - tag with it's contents is stripped out of the output. + tag with its contents is stripped out of the output. Doxygen tags: diff --git a/Doc/Devel/scanner.html b/Doc/Devel/scanner.html index 65ef1d8e9..d620c3d98 100644 --- a/Doc/Devel/scanner.html +++ b/Doc/Devel/scanner.html @@ -204,6 +204,7 @@ SWIG_TOKEN_LESSTHAN < SWIG_TOKEN_GREATERTHAN > SWIG_TOKEN_LTEQUAL <= SWIG_TOKEN_GTEQUAL >= +SWIG_TOKEN_LTEQUALGT <=> SWIG_TOKEN_NOT ~ SWIG_TOKEN_LNOT ! SWIG_TOKEN_LBRACKET [ diff --git a/Doc/Devel/tree.html b/Doc/Devel/tree.html index 5bb4b6a1e..2b9ac75dd 100644 --- a/Doc/Devel/tree.html +++ b/Doc/Devel/tree.html @@ -183,8 +183,8 @@ this function merely records that those attributes did not exist in the original void Swig_require(const char *namespace, Node *n, ...)
-This function is similar to Swig_save() except that adds additional attribute checking. There are different interpretations -of the attribute names. A name of "attr" merely requests that the function check for the presence of an attribute. If the attribute is missing, SWIG will exit with a failed assertion. An attribute name of "?attr" specifies that the attribute "attr" is optional and +This function is similar to Swig_save() except that it performs additional attribute checking. There are different interpretations +of the attribute names. A name of "attr" merely requests that the function check for the presence of an attribute. If the attribute is missing, SWIG will exit with a fatal error. An attribute name of "?attr" specifies that the attribute "attr" is optional and that its old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that its value must be saved. The saving of attributes is performed in the same manner as with Swig_save(). Here is an example: diff --git a/Doc/Manual/CPlusPlus11.html b/Doc/Manual/CPlusPlus11.html index e5d7fbc2d..861b80048 100644 --- a/Doc/Manual/CPlusPlus11.html +++ b/Doc/Manual/CPlusPlus11.html @@ -15,6 +15,11 @@
  • Core language changes
    • Rvalue reference and move semantics +
    • Generalized constant expressions
    • Extern template
    • Initializer lists @@ -95,6 +100,7 @@ class MyClass { ... std::vector<int> numbers; public: + MyClass() : numbers() {} MyClass(MyClass &&other) : numbers(std::move(other.numbers)) {} MyClass & operator=(MyClass &&other) { numbers = std::move(other.numbers); @@ -104,8 +110,8 @@ public:

      -Rvalue references are designed for C++ temporaries and so are not very useful when used from non-C++ target languages. -Generally you would just ignore them via %ignore before parsing the class. +Rvalue references are designed for C++ temporaries and are not particularly useful when used from non-C++ target languages. +One option is to just ignore them via %ignore. For example, ignore the move constructor:

      @@ -113,8 +119,49 @@ For example, ignore the move constructor: %ignore MyClass::MyClass(MyClass &&); +

      7.2.1.1 Rvalue reference inputs

      + +

      -The plan is to ignore move constructors by default in a future version of SWIG. Note that both normal assignment operators as well as move assignment operators are ignored by default in most target languages with the following warning: +Rvalue reference parameters are useful as input parameters in C++ for implementing move semantics, such as, +in the move constructor and move assignment operator. +This type of usage can be useful from target languages too to avoid copying large objects. +

      + +

      +If you do wrap a function/contructor with an rvalue reference parameter and pass a proxy class to it, SWIG will assume that after the call, the rvalue reference parameter object will have been 'moved'. +The proxy class passed as the rvalue reference, will own the underlying C++ object up until it is used as an rvalue reference parameter. +Afterwards, the proxy class will have the underlying C++ pointer set to the nullptr so that the proxy class instance cannot be used again and the underlying (moved from) C++ object will be deleted after the function/constructor call has returned. +

      + +

      +In this way, the SWIG proxy class works much like an exclusively owned smart pointer (think of std::unique_ptr), passing ownership to the called C++ function/constructor. +Let's consider an example in Java using the wrapped proxy class from above: +

      + +
      +MyClass mc = new MyClass();
+MyClass mc1 = new MyClass(mc); // move constructor
+MyClass mc2 = new MyClass(mc); // move constructor fails
+
      + +

      +The second call to the move constructor will fail as the mc proxy instance has been moved. +Each target language handles the moved proxy class slightly differently when attempting to move it again, but typically you'll get an exception such as in Java: +

      + +
      +
      +Exception in thread "main" java.lang.RuntimeException: Cannot release ownership as memory is not owned
+        at MyClass.swigRelease(MyClass.java:27)
+        at MyClass.<init>(MyClass.java:55)
+        at runme.main(runme.java:18)
+
      +
      + + +

      +Note that both normal copy assignment operators as well as move assignment operators are ignored by default in the target languages with the following warning:

      @@ -123,6 +170,332 @@ example.i:18: Warning 503: Can't wrap 'operator =' unless renamed to a valid ide
      +

      +Using a %rename will remove the warning and also makes the move assignment operator available from the target language: +

      +
      +%rename(MoveAssign) MyClass::operator=(MyClass &&);
+
      + +

      +You can then use it, but like the move constructor example above, you cannot use +a proxy class once it has already been moved: +

      + +
      +MyClass mc = new MyClass();
+MyClass mc2 = mc.MoveAssign(mc);
+MyClass mc3 = mc.MoveAssign(mc); // Use of mc again will fail
+
      + +

      +It is of course perfectly possible in C++ for a function/constructor to not move an object passed to it in an rvalue reference parameter. The assumption that SWIG makes would then not hold and customisation of the appropriate input typemaps would be required. +For scripting languages, this would be for the 'in' typemap and for the non-scripting languages additional typemaps such as the 'javain' typemap, which is used to set the memory ownership of the underlying C++ object for Java, would also need copying and modifying appropriately. +

      + +

      +Compatibility note: +SWIG-4.1.0 changed the way that rvalue reference parameters were handled and implemented typemaps assuming that the +proxy class owns the underlying C++ object and transfers ownership of the object when a function/constructor with an rvalue reference parameter is called. +

      + +

      7.2.1.2 Rvalue reference outputs

      + + +

      +While rvalue reference parameter inputs are not uncommon in C++ and can be usefully utilised from target languages, this cannot be said for rvalue reference outputs. +Firstly, it is quite unusual in C++ to have functions that return an rvalue reference. +Secondly, these cases are nigh on impossible to use from a target language. +The main problem is these references are for C++ compiler temporaries used on the stack and the target languages use objects on the heap +and the concept of compiler temporary objects doesn't make sense from another language. +

      + +

      +Using MyClass from earlier and this C++ code: +

      + +
      +void use(MyClass &&mc);
+MyClass && get1();
+MyClass & get2();
+
      + +

      +SWIG wraps the get1 and get2 functions more or less identically. +The returned references are converted into pointers that are not owned by the target language. +It means that the following perfectly valid C++ has no equivalent in any of the target languages: +

      + +
      +use(get1());
+use(std::move(get2()));
+
      + +

      +An attempt to call the equivalent use(get1()) from one of the target languages will result in the ownership failure mentioned in the previous section as the object being passed to the use function is not owned by the proxy class. +In order to own the object, it would need to be cloned for the object to move from the stack to the heap, for which an appropriate clone function would be required, but may not even be available. +Note that a move constructor or copy constructor may slice the object when inheritance is involved. +Alternatively, customising the input rvalue reference typemap, as mentioned in the previous section, could remove the ownership requirement. +Another alternative would be to modify the output rvalue reference typemap to always clone the rvalue reference object. +Fortunately you're highly unlikely to have to solve any of these issues! +

      + +

      7.2.1.3 Movable and move-only types by value

      + + +

      +SWIG has traditionally relied on wrapped C++ types to be copy constructible or copy assignable, either via an explicit or implicit copy constructor and copy assignment operator. +Prior to C++11, a function could not return nor take a type by value that was not copyable. +In C++11 this is no longer the case. A type can also be movable if it has has a move constructor and a move assignment operator. +A move-only type is movable but not copyable; it has both the copy constructor and copy assignment operator deleted. +Movable types can appear in function signatures for passing 'by value' and in C++11 the object can then be moved rather than copied. +

      + +

      +SWIG has support for both copyable and/or movable types. +Support for move semantics is quite seamless when returning by value from a function. +Support for move semantics is less so and may require some customisation when passing by value to a function. +First let's consider returning by value from a function. +

      + +

      +The support for function return values is generically implemented in the "out" SWIGTYPE typemap which supports any type, including copyable, movable and move-only types. +The typemap code is very simple and written so that the compiler will call the move constructor if possible, +otherwise the copy constructor: +

      + +
      +%typemap(out) SWIGTYPE %{
+  $result = new $1_ltype($1);
+%}
+
      + +

      +The above typemap is for C# and when used to wrap a move-only type such as: +

      + +
      +struct MoveOnly {
+  int  val;
+  MoveOnly(): val(0)  {}
+
+  MoveOnly(const MoveOnly &) = delete;
+  MoveOnly(MoveOnly &&) = default;
+
+  MoveOnly & operator=(const MoveOnly &) = delete;
+  MoveOnly & operator=(MoveOnly &&) = default;
+
+  static MoveOnly create() { return MoveOnly(); }
+  static void take(MoveOnly mo);
+};
+
      + +

      +will generate wrapper code for the create factory method: +

      + +
      +SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
+  void * jresult ;
+  SwigValueWrapper< MoveOnly > result;
+
+  result = MoveOnly::create();
+  jresult = new MoveOnly(result);
+  return jresult;
+}
+
      + +

      +SwigValueWrapper is covered in Pass and return by value. +Note that the generated code could be optimised further using the "optimal" attribute +in the "out" typemap, so if the above typemap is customised as follows (note that this is C# specific): +

      + +
      +%typemap(out, optimal="1") MoveOnly %{
+  $result = new $1_ltype($1);
+%}
+
      + +

      +then the generated code will result in the object being optimally moved: +

      + +
      +SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
+  void * jresult ;
+  jresult = new MoveOnly(MoveOnly::create());
+  return jresult;
+}
+
      + +

      +Now let's consider passing by value. +We'll consider three cases; namely types that are: +

      + +
        +
      1. Copyable and not movable - CopyOnly.
        2. +
      2. Copyable and movable - MovableCopyable.
        3. +
      3. Movable and not copyable - MoveOnly.
        4. +
      + +

      +and for clarification, define these two additional types as follows: +

      + +
      +struct CopyOnly {
+  int  val;
+  CopyOnly(): val(0)  {}
+
+  CopyOnly(const CopyOnly &) = default;
+  CopyOnly & operator=(const CopyOnly &) = default;
+
+  static CopyOnly create() { return CopyOnly(); }
+  static void take(CopyOnly co);
+};
+
+struct MovableCopyable {
+  int  val;
+  MovableCopyable(): val(0)  {}
+
+  MovableCopyable(const MovableCopyable &) = default;
+  MovableCopyable(MovableCopyable &&) = default;
+  MovableCopyable & operator=(const MovableCopyable &) = default;
+  MovableCopyable & operator=(MovableCopyable &&) = default;
+
+  static MovableCopyable create() { return MovableCopyable(); }
+  static void take(MovableCopyable mc);
+};
+
      + +

      +The generated code is shown below for CopyOnly::take (with additional comments for when constructors and assignment operators are called). +While the code shown is C# specific, the generated constructor and/or assignment operator calls are ultimately the same for all target languages. +

      + +
      +SWIGEXPORT void SWIGSTDCALL CSharp_CopyOnly_take(void * jarg1) {
+  CopyOnly arg1 ; // (a) Default constructor
+  CopyOnly *argp1 ;
+  
+  argp1 = (CopyOnly *)jarg1; 
+  if (!argp1) {
+    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null CopyOnly", 0);
+    return ;
+  }
+  arg1 = *argp1; // (b) Copy assignment
+  CopyOnly::take(SWIG_STD_MOVE(arg1)); // (c) Copy constructor
+}
+
      + +

      +Note that SWIG_STD_MOVE is a macro defined as shown below to use std::move which is only available from C++11 onwards: +

      + +
      +#if __cplusplus >=201103L
+# define SWIG_STD_MOVE(OBJ) std::move(OBJ)
+#else
+# define SWIG_STD_MOVE(OBJ) OBJ
+#endif
+
      + +

      +Also note: (c) Copy constructor. +Yes, when passing by value the copy constructor is called for all versions of C++, even C++11 and later even though std::move is specified. +It's a C++ language feature for types that don't have move semantics! +

      + +

      +The generated code for MovableCopyable::take is the same as for CopyOnly::take, however, the C++ compiler will choose the move constructor this time where commented (c) Move constructor: +

      + +
      +SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) {
+  MovableCopyable arg1 ; // (a) Default constructor
+  MovableCopyable *argp1 ;
+  
+  argp1 = (MovableCopyable *)jarg1; 
+  if (!argp1) {
+    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0);
+    return ;
+  }
+  arg1 = *argp1; // (b) Copy assignment
+  MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor
+}
+
      + +

      +There are two optimisation opportunities available. +

      +
        +
      1. Remove the default constructor call with the %feature("valuewrapper") covered in Pass and return by value and replace it with SwigValueWrapper. +
        2. +
      2. Apply the SWIGTYPE MOVE typemaps which are designed specifically to implement full move semantics when passing parameters by value. + They replace the copy assignment with a call to SwigValueWrapper::reset, which works much like std::unique_ptr::reset. + These typemaps could alternatively have replaced the copy assignment with a move assignment, but this is not maximally optimal. +
        3. +
      +

      +Simply add the following before the MovableCopyable::take method is parsed: +

      + +
      +%valuewrapper MovableCopyable;
+%include <swigmove.i>
+%apply SWIGTYPE MOVE { MovableCopyable }
+
      + +

      +will result in this optimal code where just one move constructor is invoked: +

      + +
      +SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) {
+  SwigValueWrapper< MovableCopyable > arg1 ; // (a) No constructors invoked
+  MovableCopyable *argp1 ;
+  
+  argp1 = (MovableCopyable *)jarg1;
+  if (!argp1) {
+    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0);
+    return ;
+  }
+  SwigValueWrapper< MovableCopyable >::reset(arg1, argp1);  // (b) No constructor or assignment operator invoked
+  MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor
+}
+
      + +

      +Note that SwigValueWrapper will call the destructor for the pointer passed to it in the reset function. +This pointer is the underlying C++ object that the proxy class owns. +The details aren't shown, but the 'csin' typemap also generates C# code to ensure that the proxy class releases ownership of the object. +Please see the 'SWIGTYPE MOVE' typemaps in the swigmove.i file provided for each target language. +Therefore full move semantics are implemented; ownership is moved from the proxy class into the C++ layer and the net effect +is the same as using an rvalue reference parameter discussed earlier. +

      + +

      +Lastly, let's consider the MoveOnly::take function defined earlier. +By default the generated code fails to compile as MoveOnly does not have a copy assignment operator. +SWIG is not designed to select a different typemap automatically for move-only types and the user +must apply the SWIGTYPE MOVE typemaps to ensure that only move-only semantics are used. +However, SWIG is able to automatically use %feature("valuewrapper") for move-only +types so it is not necessary to explicitly use this feature. +So in this move-only case, simply add the following before MoveOnly::take is parsed, which results in the same optimal code shown above for MovableCopyable: +

      + +
      +%include <swigmove.i>
+%apply SWIGTYPE MOVE { MoveOnly }
+
      + +

      +Compatibility note: +SWIG-4.1.0 introduced support for taking advantage of types with move semantics and making it possible to easily use move only types. +

      +

      7.2.2 Generalized constant expressions

      @@ -144,14 +517,39 @@ When either of these is used from a target language, a runtime call is made to o

      7.2.3 Extern template

      -

      SWIG correctly parses the keywords extern template. +

      SWIG correctly parses extern template explicit instantiation declarations. However, this template instantiation suppression in a translation unit has no relevance outside of the C++ compiler and so is not used by SWIG. -SWIG only uses %template for instantiating and wrapping templates.

      +SWIG only uses %template for instantiating and wrapping templates. +Consider the class template below: +

      -template class std::vector<int>;        // C++03 explicit instantiation in C++
-extern template class std::vector<int>; // C++11 explicit instantiation suppression in C++
-%template(VectorInt) std::vector<int>;  // SWIG instantiation
+// Class template
+template class std::vector<int>;        // C++03 template explicit instantiation definition in C++
+extern template class std::vector<int>; // C++11 template explicit instantiation declaration (extern template)
+%template(VectorInt) std::vector<int>;  // SWIG template instantiation
+
      + +

      +The above result in warnings: +

      + +
      +
      +example.i:2: Warning 320: Explicit template instantiation ignored.
+example.i:3: Warning 327: Extern template ignored.
+
      +
      + +

      +Similarly for the function template below: +

      + +
      +// Function template
+template void Func<int>();              // C++03 template explicit instantiation definition in C++
+extern template void Func<int>();       // C++11 template explicit instantiation declaration (extern template)
+%template(FuncInt) Func<int>;           // SWIG template instantiation

      7.2.4 Initializer lists

      @@ -985,7 +1383,9 @@ Use the preprocessor to work around this for now:

      -Attributes such as those shown below, are not yet supported and will give a syntax error. +Attributes such as those shown below, are supported since SWIG 4.1.0 but are +currently crudely ignored by the parser's tokeniser so they have no effect on +SWIG's code generation. 

      @@ -1132,8 +1532,10 @@ While SWIG could provide wrappers for the new C++11 regular expressions classes,
 
 
      
 SWIG provides special smart pointer handling for std::shared_ptr in the same way it has support for boost::shared_ptr.
-Please see the shared_ptr smart pointer library section.
-There is no special smart pointer handling available for std::weak_ptr and std::unique_ptr yet.
+Please see the shared_ptr smart pointer
+and unique_ptr smart pointer library sections.
+There is no special smart pointer handling available for std::weak_ptr.
+
 
      
 
 
      7.3.6 Extensible random number facility
      
diff --git a/Doc/Manual/CPlusPlus20.html b/Doc/Manual/CPlusPlus20.html
index 0a8b0027f..a289d776f 100644
--- a/Doc/Manual/CPlusPlus20.html
+++ b/Doc/Manual/CPlusPlus20.html
@@ -13,6 +13,10 @@
      @@ -35,6 +39,32 @@ Work has only just begun on adding C++20 support.

      10.2 Core language changes

      +

      10.2.1 Spaceship operator

      + + +

      +SWIG supports the spaceship operator <=> in constant +expressions. To simplify handling of the return value type, it is currently +treated as an integer rather than std::strong_ordering, etc. +In practice we think that should do the right thing in most cases. +

      + +

      +SWIG also recognises operator<=> which can be wrapped +if renamed. There is not currently any default renaming for the operator +or any attempt to automatically map it to a three-way comparison operator +in any of the target languages. +

      + +

      10.2.2 Lambda templates

      + + +

      +SWIG should parse lambda templates, but like + +non-templated lambdas they aren't currently wrapped. +

      +

      10.3 Standard library changes

      diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index fe8f7c4bd..405868b5c 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -550,6 +550,12 @@ This special variable expands to the intermediary class name. For C# this is usu unless the imclassname attribute is specified in the %module directive.

      +

      +$imfuncname
      +This special variable expands to the name of the function in the intermediary class that will be used in $imcall. +Like, $imcall, this special variable is only expanded in the "csout", "csvarin" and "csvarout" typemaps. +

      +

      The directory Examples/csharp has a number of simple examples. Visual Studio .NET 2003 solution and project files are available for compiling with the Microsoft .NET C# diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 47b41186e..d3106bf09 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -91,17 +91,16 @@

  • Instructions for using the Examples with other compilers -
  • SWIG on Cygwin and MinGW -
  • Microsoft extensions and other Windows quirks @@ -172,6 +171,7 @@
  • Renaming and ignoring declarations
  • Overloaded operators
  • Class extension +
  • Templates @@ -516,6 +534,7 @@
  • Special variables and typemap attributes
  • Special variables combined with special variable macros @@ -870,6 +889,8 @@
  • Go Class Inheritance
  • Go Templates +
  • Go and C/C++ Threads +
  • Go and C++ Exceptions
  • Go Director Classes
  • %feature("docstring") +
  • Doxygen comments
  • Python Packages
      @@ -1474,7 +1496,10 @@
  • Python 3 Support
      -
    • Function annotation +
    • Python function annotations and variable annotations +
    • Buffer interface
    • Abstract base classes
    • Byte string output conversion diff --git a/Doc/Manual/Customization.html b/Doc/Manual/Customization.html index 5fe0f5b52..aab3528ac 100644 --- a/Doc/Manual/Customization.html +++ b/Doc/Manual/Customization.html @@ -668,7 +668,7 @@ results. For example: 
      -%typemap(newfree) char * "free($1);";
+%typemap(newfree) char * "free($1);"
 ...
 %newobject strdup;
 ...
diff --git a/Doc/Manual/D.html b/Doc/Manual/D.html
index f9f2d53ca..9e733c401 100644
--- a/Doc/Manual/D.html
+++ b/Doc/Manual/D.html
@@ -267,12 +267,18 @@ SomeClass bar() {
      +
      $imfuncname
      +

      +This special variable expands to the name of the function in the intermediary class that will be used in $imcall. +Like, $imcall, this special variable is only expanded in the "dout" typemap. +

      +
      $importtype(SomeDType)

      This macro is used in the dimports typemap if a dependency on another D type generated by SWIG is added by a custom typemap.

      Consider the following code snippet:

      -%typemap(dinterfaces) SomeClass "AnInterface, AnotherInterface";
+%typemap(dinterfaces) SomeClass "AnInterface, AnotherInterface"

      This causes SWIG to add AnInterface and AnotherInterface to the base class list of SomeClass:

      diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html
index e7fd4c359..9d2cc7724 100644
--- a/Doc/Manual/Doxygen.html
+++ b/Doc/Manual/Doxygen.html
@@ -181,7 +181,7 @@ or enum element comments:
 
       enum E_NUMBERS
 {
-    EN_ZERO, ///< The first enum item, gets zero as it's value
+    EN_ZERO, ///< The first enum item, gets zero as its value
     EN_ONE, ///< The second, EN_ONE=1
     EN_THREE
 };
@@ -1114,7 +1114,7 @@ name of the type with namespace scope delimiters (::) replaced with a d
 change this, you can define your own typemaps for the custom types, e.g:
 
      
 
      -%typemap(doctype) MyDate "datetime.date";
+%typemap(doctype) MyDate "datetime.date"
 
      
 
 
      
diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html
index 5749f37ce..cbb78bef8 100644
--- a/Doc/Manual/Extending.html
+++ b/Doc/Manual/Extending.html
@@ -462,187 +462,220 @@ the stage being processed.
 There are a number of other parse tree display options, for example, swig -debug-module <n> will
 avoid displaying system parse information and only display the parse tree pertaining to the user's module at
 stage n of processing.
+Adding the -debug-quiet option is recommended as it removes some noise which is not usually needed,
+that is, the display of many linked list pointers and symbol table pointers.
 
      
 
 
      
 
      -$ swig -c++ -python -debug-module 4 example.i
-      +++ include ----------------------------------------
-      | name         - "example.i"
+$ swig -c++ -python -debug-module 1 -debug-quiet example.i
+debug-module stage 1
++++ module ----------------------------------------
+| name         - "example"
+| 
++++ insert ----------------------------------------
+| code         - "\n#include \"example.h\"\n"
+| 
++++ include ----------------------------------------
+| name         - "example.h"
 
-            +++ module ----------------------------------------
-            | name         - "example"
-            |
-            +++ insert ----------------------------------------
-            | code         - "\n#include \"example.h\"\n"
-            |
-            +++ include ----------------------------------------
-            | name         - "example.h"
+      +++ class ----------------------------------------
+      | abstracts    - 0x7f4f15182930
+      | allows_typedef - "1"
+      | kind         - "class"
+      | name         - "Shape"
+      | sym:name     - "Shape"
 
-                  +++ class ----------------------------------------
-                  | abstract     - "1"
-                  | sym:name     - "Shape"
-                  | name         - "Shape"
-                  | kind         - "class"
-                  | symtab       - 0x40194140
-                  | sym:symtab   - 0x40191078
+            +++ access ----------------------------------------
+            | kind         - "public"
+            | 
+            +++ constructor ----------------------------------------
+            | access       - "public"
+            | code         - "{\n    nshapes++;\n  }"
+            | decl         - "f()."
+            | feature:new  - "1"
+            | ismember     - "1"
+            | name         - "Shape"
+            | sym:name     - "Shape"
+            | 
+            +++ destructor ----------------------------------------
+            | access       - "public"
+            | code         - "{\n    nshapes--;\n  }"
+            | decl         - "f()."
+            | ismember     - "1"
+            | name         - "~Shape"
+            | storage      - "virtual"
+            | sym:name     - "~Shape"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "x"
+            | sym:name     - "x"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "y"
+            | sym:name     - "y"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f(double,double)."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "move"
+            | parms        - 'double dx,double dy'
+            | sym:name     - "move"
+            | type         - "void"
+            | 
+            +++ cdecl ----------------------------------------
+            | abstract     - "1"
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "area"
+            | storage      - "virtual"
+            | sym:name     - "area"
+            | type         - "double"
+            | value        - "0"
+            | valuetype    - "int"
+            | 
+            +++ cdecl ----------------------------------------
+            | abstract     - "1"
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "perimeter"
+            | storage      - "virtual"
+            | sym:name     - "perimeter"
+            | type         - "double"
+            | value        - "0"
+            | valuetype    - "int"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "nshapes"
+            | storage      - "static"
+            | sym:name     - "nshapes"
+            | type         - "int"
+            | 
+      +++ class ----------------------------------------
+      | allows_typedef - "1"
+      | baselist     - 0x7f4f15182ad0
+      | kind         - "class"
+      | name         - "Circle"
+      | privatebaselist - 0x7f4f15182b10
+      | protectedbaselist - 0x7f4f15182af0
+      | sym:name     - "Circle"
 
-                        +++ access ----------------------------------------
-                        | kind         - "public"
-                        |
-                        +++ constructor ----------------------------------------
-                        | sym:name     - "Shape"
-                        | name         - "Shape"
-                        | decl         - "f()."
-                        | code         - "{\n    nshapes++;\n  }"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ destructor ----------------------------------------
-                        | sym:name     - "~Shape"
-                        | name         - "~Shape"
-                        | storage      - "virtual"
-                        | code         - "{\n    nshapes--;\n  }"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "x"
-                        | name         - "x"
-                        | decl         - ""
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "y"
-                        | name         - "y"
-                        | decl         - ""
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "move"
-                        | name         - "move"
-                        | decl         - "f(double, double)."
-                        | parms        - double, double
-                        | type         - "void"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "area"
-                        | name         - "area"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | value        - "0"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "perimeter"
-                        | name         - "perimeter"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | value        - "0"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "nshapes"
-                        | name         - "nshapes"
-                        | decl         - ""
-                        | storage      - "static"
-                        | type         - "int"
-                        | sym:symtab   - 0x40194140
-                        |
-                  +++ class ----------------------------------------
-                  | sym:name     - "Circle"
-                  | name         - "Circle"
-                  | kind         - "class"
-                  | bases        - 0x40194510
-                  | symtab       - 0x40194538
-                  | sym:symtab   - 0x40191078
+            +++ access ----------------------------------------
+            | kind         - "private"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "private"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "radius"
+            | type         - "double"
+            | 
+            +++ access ----------------------------------------
+            | kind         - "public"
+            | 
+            +++ constructor ----------------------------------------
+            | access       - "public"
+            | code         - "{ }"
+            | decl         - "f(double)."
+            | feature:new  - "1"
+            | ismember     - "1"
+            | name         - "Circle"
+            | parms        - 'double r'
+            | sym:name     - "Circle"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "area"
+            | storage      - "virtual"
+            | sym:name     - "area"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "perimeter"
+            | storage      - "virtual"
+            | sym:name     - "perimeter"
+            | type         - "double"
+            | 
+      +++ class ----------------------------------------
+      | allows_typedef - "1"
+      | baselist     - 0x7f4f15183830
+      | kind         - "class"
+      | name         - "Square"
+      | privatebaselist - 0x7f4f15183870
+      | protectedbaselist - 0x7f4f15183850
+      | sym:name     - "Square"
 
-                        +++ access ----------------------------------------
-                        | kind         - "private"
-                        |
-                        +++ cdecl ----------------------------------------
-                        | name         - "radius"
-                        | decl         - ""
-                        | type         - "double"
-                        |
-                        +++ access ----------------------------------------
-                        | kind         - "public"
-                        |
-                        +++ constructor ----------------------------------------
-                        | sym:name     - "Circle"
-                        | name         - "Circle"
-                        | parms        - double
-                        | decl         - "f(double)."
-                        | code         - "{ }"
-                        | sym:symtab   - 0x40194538
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "area"
-                        | name         - "area"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194538
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "perimeter"
-                        | name         - "perimeter"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194538
-                        |
-                  +++ class ----------------------------------------
-                  | sym:name     - "Square"
-                  | name         - "Square"
-                  | kind         - "class"
-                  | bases        - 0x40194760
-                  | symtab       - 0x40194788
-                  | sym:symtab   - 0x40191078
-
-                        +++ access ----------------------------------------
-                        | kind         - "private"
-                        |
-                        +++ cdecl ----------------------------------------
-                        | name         - "width"
-                        | decl         - ""
-                        | type         - "double"
-                        |
-                        +++ access ----------------------------------------
-                        | kind         - "public"
-                        |
-                        +++ constructor ----------------------------------------
-                        | sym:name     - "Square"
-                        | name         - "Square"
-                        | parms        - double
-                        | decl         - "f(double)."
-                        | code         - "{ }"
-                        | sym:symtab   - 0x40194788
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "area"
-                        | name         - "area"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194788
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "perimeter"
-                        | name         - "perimeter"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194788
+            +++ access ----------------------------------------
+            | kind         - "private"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "private"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "width"
+            | type         - "double"
+            | 
+            +++ access ----------------------------------------
+            | kind         - "public"
+            | 
+            +++ constructor ----------------------------------------
+            | access       - "public"
+            | code         - "{ }"
+            | decl         - "f(double)."
+            | feature:new  - "1"
+            | ismember     - "1"
+            | name         - "Square"
+            | parms        - 'double w'
+            | sym:name     - "Square"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "area"
+            | storage      - "virtual"
+            | sym:name     - "area"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "perimeter"
+            | storage      - "virtual"
+            | sym:name     - "perimeter"
+            | type         - "double"
 
      
 
      
 
@@ -698,31 +731,28 @@ The parse tree can be viewed after the final stage of processing by running SWIG
 
 
      
 
      -$ swig -debug-top 4 example.i
+$ swig -debug-top 1 -debug-quiet example.i
 ...
             +++ cdecl ----------------------------------------
-            | sym:name     - "foo_i"
-            | name         - "foo"
             | decl         - "f(int)."
+            | name         - "foo"
             | parms        - int
+            | sym:name     - "foo_i"
             | type         - "void"
-            | sym:symtab   - 0x40165078
             |
             +++ cdecl ----------------------------------------
-            | sym:name     - "foo_d"
-            | name         - "foo"
             | decl         - "f(double)."
+            | name         - "foo"
             | parms        - double
+            | sym:name     - "foo_d"
             | type         - "void"
-            | sym:symtab   - 0x40165078
             |
             +++ cdecl ----------------------------------------
-            | sym:name     - "foo"
-            | name         - "foo"
             | decl         - "f(p.Bar)."
+            | name         - "foo"
             | parms        - Bar *
+            | sym:name     - "foo"
             | type         - "void"
-            | sym:symtab   - 0x40165078
 
      
 
      
 
@@ -787,19 +817,18 @@ public:
 The behavior of %feature is very easy to describe--it simply
 attaches a new attribute to any parse tree node that matches the
 given prototype.   When a feature is added, it shows up as an attribute in the feature: namespace.
-You can see this when running with the -debug-top 4 option.   For example:
+You can see this when running with the -debug-top 4 -debug-quiet option.   For example:
 
      
 
 
      
 
        +++ cdecl ----------------------------------------
- | sym:name     - "getitem"
- | name         - "getitem"
  | decl         - "f(int).p."
- | parms        - int
- | type         - "Object"
  | feature:except - "{\n    try {\n       $action\n    } catc..."
- | sym:symtab   - 0x40168ac8
+ | name         - "getitem"
+ | parms        - int
+ | sym:name     - "getitem"
+ | type         - "Object"
  |
 
      
 
      
@@ -1132,6 +1161,11 @@ DOH_REPLACE_FIRST     - Replace first occurrence only.
 Returns the number of replacements made (if any).
 
      
 
+
      
+At most one of DOH_REPLACE_ANY and DOH_REPLACE_FIRST should be specified.
+DOH_REPLACE_ANY is the default if neither is specified.
+
      
+
 
      
 
 
      40.5.2 Hashes
      
@@ -2802,7 +2836,7 @@ int Python::top(Node *n) {
   f_begin = NewFile(outfile, "w", SWIG_output_files());
   if (!f_begin) {
     FileErrorDisplay(outfile);
-    SWIG_exit(EXIT_FAILURE);
+    Exit(EXIT_FAILURE);
   }
   f_runtime = NewString("");
   f_init = NewString("");
@@ -2986,7 +3020,7 @@ virtual int functionWrapper(Node *n) {
   /* create the wrapper object */
   Wrapper *wrapper = NewWrapper();
 
-  /* create the functions wrappered name */
+  /* create the wrapper function's name */
   String *wname = Swig_name_wrapper(iname);
 
   /* deal with overloading */
@@ -2995,7 +3029,7 @@ virtual int functionWrapper(Node *n) {
   /* write the wrapper function definition */
   Printv(wrapper->def, "RETURN_TYPE ", wname, "(ARGS) {", NIL);
 
-  /* if any additional local variable needed, add them now */
+  /* if any additional local variables are needed, add them now */
   ...
 
   /* write the list of locals/arguments required */
@@ -3588,7 +3622,7 @@ A target language is given the 'Supported' status when
 
    • 
   It passes all of the main SWIG test-suite.
   The main test-suite is defined by the tests in the C_TEST_CASES, CPP_TEST_CASES and MULTI_CPP_TEST_CASES lists in Examples/test-suite/common.mk.
-  The tests in CPP11_TEST_CASES will also be required in the near future.
+  All the newer C++ standard tests need to work and are grouped together, such as CPP11_TEST_CASES for C++11. These more 'modern' C++ standards are only tested though if the compiler is detected as supporting the given standard.
 
      • 
 
    • 
   The test-suite must also include at least twenty wide-ranging runtime tests.
@@ -3760,6 +3794,7 @@ There are various command line options which can aid debugging a SWIG interface
 -debug-symbols    - Display target language symbols in the symbol tables
 -debug-csymbols   - Display C symbols in the symbol tables
 -debug-lsymbols   - Display target language layer symbols
+-debug-quiet      - Display less parse tree node debug info when using other -debug options
 -debug-tags       - Display information about the tags found in the interface
 -debug-template   - Display information for debugging templates
 -debug-top <n>    - Display entire parse tree at stages 1-4, <n> is a csv list of stages
diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html
index 4e230c78b..f4ef1fe57 100644
--- a/Doc/Manual/Go.html
+++ b/Doc/Manual/Go.html
@@ -29,6 +29,8 @@
 
    • Go Class Inheritance
  • Go Templates +
  • Go and C/C++ Threads +
  • Go and C++ Exceptions
  • Go Director Classes
    • Example C++ code @@ -176,10 +178,10 @@ swig -go -help -intgosize <s> Set the size for the Go type int. This controls the size that the C/C++ code expects to see. The <s> argument should - be 32 or 64. This option is currently required during the + be 32 or 64. This option was required during the transition from Go 1.0 to Go 1.1, as the size of int on - 64-bit x86 systems changes between those releases (from 32 bits to - 64 bits). In the future the option may become optional, and SWIG + 64-bit x86 systems changed between those releases (from 32 bits to + 64 bits). It was made optional in SWIG 4.1.0 and if not specified SWIG will assume that the size of int is the size of a C pointer. @@ -494,10 +496,6 @@ The usage of Go finalizers is problematic with C++'s RAII idiom as it isn't predictable when the finalizer will run and this might require a Close or Delete method to be added the Go object that stores a C++ object to mitigate.
      • -
    • -The Go finalizer function typically runs in a different OS thread which can be -problematic with C++ code that uses thread-local storage. -

    @@ -557,8 +555,37 @@ In order to use C++ templates in Go, you must tell SWIG to create wrappers for a particular template instantiation. To do this, use the %template directive. +

    25.4.7 Go and C/C++ Threads

    -

    25.4.7 Go Director Classes

    + +

    +C and C++ code can use operating system threads and thread local +storage. Go code uses goroutines, which are multiplexed onto +operating system threads. This multiplexing means that Go code can +change to run on a different thread at any time. C/C++ code, on the +other hand, may assume that it runs on a single thread; this is true +in particular if the C/C++ code uses thread local storage. +

    + +

    +In order to use Go code with C/C++ code that expects to run on a +single thread, the Go code must call +the runtime.LockOSThread +function to lock the goroutine onto a single thread. +

    + +

    25.4.8 Go and C++ Exceptions

    + + +

    +C++ exceptions do not interoperate with Go code. Attempts to throw +C++ exceptions through a Go caller are unreliable: in many cases the +C++ exception handler will be unable to unwind the stack, and the +program will crash. The only safe way to handle C++ exceptions is to +catch them in C++ before returning to Go. +

    + +

    25.4.9 Go Director Classes

    @@ -576,7 +603,7 @@ completely to avoid common pitfalls with directors in Go.

    -

    25.4.7.1 Example C++ code

    +

    25.4.9.1 Example C++ code

    @@ -648,7 +675,7 @@ be found in the end of the guide.

    -

    25.4.7.2 Enable director feature

    +

    25.4.9.2 Enable director feature

    @@ -683,7 +710,7 @@ documentation on directors.

    -

    25.4.7.3 Constructor and destructor

    +

    25.4.9.3 Constructor and destructor

    @@ -736,7 +763,7 @@ embedding.

    -

    25.4.7.4 Override virtual methods

    +

    25.4.9.4 Override virtual methods

    @@ -804,7 +831,7 @@ the Go methods.

    -

    25.4.7.5 Call base methods

    +

    25.4.9.5 Call base methods

    @@ -841,7 +868,7 @@ be found in the end of the guide.

    -

    25.4.7.6 Subclass via embedding

    +

    25.4.9.6 Subclass via embedding

    @@ -909,7 +936,7 @@ class.

    -

    25.4.7.7 Memory management with runtime.SetFinalizer

    +

    25.4.9.7 Memory management with runtime.SetFinalizer

    @@ -974,7 +1001,7 @@ before using runtime.SetFinalizer to know all of its gotchas.

    -

    25.4.7.8 Complete FooBarGo example class

    +

    25.4.9.8 Complete FooBarGo example class

    @@ -1103,7 +1130,7 @@ SWIG/Examples/go/director/.

    -

    25.4.8 Default Go primitive type mappings

    +

    25.4.10 Default Go primitive type mappings

    @@ -1210,7 +1237,7 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types.

    -

    25.4.9 Output arguments

    +

    25.4.11 Output arguments

    Because of limitations in the way output arguments are processed in swig, @@ -1263,7 +1290,7 @@ void f(char *output); -

    25.4.10 Adding additional go code

    +

    25.4.12 Adding additional go code

    Often the APIs generated by swig are not very natural in go, especially if @@ -1358,7 +1385,7 @@ func bar() { -

    25.4.11 Go typemaps

    +

    25.4.13 Go typemaps

    @@ -1397,7 +1424,7 @@ default as described above. An intermediate Go type used by the "goin", "goout", "godirectorin", and "godirectorout" typemaps. If this typemap is not defined for a -C/C++ type, the gotype typemape will be used. This is useful when +C/C++ type, the gotype typemap will be used. This is useful when gotype is best converted to C/C++ using Go code. diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index 26679dc4b..7f607f804 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.html @@ -52,15 +52,16 @@ This section details guile-specific support in SWIG.

    -SWIG works with Guile versions 1.8.x and 2.0.x. Support for version -1.6.x has been dropped. The last version of SWIG that still works with -Guile version 1.6.x is SWIG 2.0.9. +SWIG is known to work with Guile versions 2.0.x, 2.2.x and 3.0.x (these are +all tested via CI). SWIG probably still works with Guile 1.8.x but we're no +longer able to regularly test this either in CI or by hand. Support for Guile +1.6.x has been dropped (SWIG 2.0.9 was the last version of SWIG to support it).

    Note that starting with guile 2.0, the guile sources can be compiled for improved performance. This is currently not tested with swig so your mileage may vary. To be safe set environment variable -GUILE_AUTO_COMPILE to 0 when using swig generated guile code. +GUILE_AUTO_COMPILE to 0 when using swig generated guile code.

    26.2 Meaning of "Module"

    @@ -303,10 +304,12 @@ experimental; the (hobbit4d link) conventions are not well understood. Underscores are converted to dashes in identifiers. Guile support may grow an option to inhibit this folding in the future, but no one has complained so far. +

    -

    You can use the SWIG directives %name and -%rename to specify the Guile name of the wrapped -functions and variables (see CHANGES). +

    You can use the SWIG +directive %rename to specify the Guile +names of the wrapped functions and variables. +

    26.6 Typemaps

    diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index 2591b27b5..d15ef2f0b 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -644,7 +644,7 @@ java::

    To build the DLL and compile the java code, run NMAKE (you may need to run vcvars32 first). -This is a pretty simplistic Makefile, but hopefully its enough to get you started. +This is a pretty simplistic Makefile, but hopefully it's enough to get you started. Of course you may want to make changes for it to work for C++ by adding in the -c++ command line option for swig and replacing .c with .cxx.

    @@ -3434,9 +3434,11 @@ Consider the following C++ code: namespace Space { struct Base1 { virtual void Method1(); + virtual Base1(); }; struct Base2 { virtual void Method2(); + virtual Base2(); }; struct Derived : Base1, Base2 { }; @@ -3453,7 +3455,7 @@ SWIG generates a warning for the above code: 
    -example.i:10: Warning 813: Warning for Derived, base Base2 ignored. 
+example.i:12: Warning 813: Warning for Derived, base Base2 ignored.
 Multiple inheritance is not supported in Java.
    @@ -3506,7 +3508,7 @@ public class Base1SwigImpl implements Base1 {

    -In fact any class deriving from Base will now implement the interface instead of +In fact any class using Base as an immediate base class will now implement the interface instead of deriving from it (or ignoring the base in the case of multiple base classes). Hence the Derived proxy class will now implement both bases:

    @@ -3535,6 +3537,21 @@ public class Derived implements Base1, Base2 { +

    +The proxy class has methods added to it, from the implemented bases, so that +the underlying C++ implementation can be called. +In the example above, Method1 and Method2 have been added from the implemented bases. +If a method is ignored in the base, such as via %ignore, then that method +will be excluded from the interface and there will not be an additional method +added to the proxy class implementing that interface. +

    + +

    +The Java interface only ever contains virtual and non-virtual instance methods from the wrapped C++ class. +Any static methods, enums or variables in the wrapped C++ class are not supported and are not added to the interface. +They are of course still available in the Java proxy class. +

    +

    Wherever a class marked as an interface is used, such as the UseBases method in the example, the interface name is used as the type in the Java layer: @@ -4201,7 +4218,7 @@ You can copy the code below into an interface file and run SWIG on it and examin %} // Expose C++ exception as a Java Exception by changing the Java base class and providing a getMessage() -%typemap(javabase) MyNS::MyException "java.lang.RuntimeException"; +%typemap(javabase) MyNS::MyException "java.lang.RuntimeException" %rename(getMessage) MyNS::MyException::whatsup; %inline %{ @@ -6439,6 +6456,12 @@ This special variable expands to the intermediary class name. Usually this is th unless the jniclassname attribute is specified in the %module directive.

    +

    +$imfuncname
    +This special variable expands to the name of the function in the intermediary class that will be used in $jnicall. +Like, $jnicall, this special variable is only expanded in the "javaout" typemap. +

    +

    $javainterfacename
    This special variable is only expanded when the interface feature is applied to a class. @@ -7042,7 +7065,7 @@ The corrected interface file looks like: 

     // class Foo is handled in a different interface file:
 %import "Foo.i"
-%typemap("javapackage") Foo, Foo *, Foo & "com.wombat.foo";
+%typemap("javapackage") Foo, Foo *, Foo & "com.wombat.foo"
 %feature("director") Example;
 
 %inline {
@@ -7070,11 +7093,11 @@ Note the helper macros below, OTHER_PACKAGE_SPEC and ANOTHER_
                                             "package.for.most.classes";
 
 %define OTHER_PACKAGE_SPEC(TYPE...)
-%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.other.classes";
+%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.other.classes"
 %enddef
 
 %define ANOTHER_PACKAGE_SPEC(TYPE...)
-%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.another.set";
+%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.another.set"
 %enddef
 
 OTHER_PACKAGE_SPEC(Package_2_class_one)
@@ -7268,7 +7291,7 @@ The typemaps to use then are as follows:
 
 
    
 
    -%typemap(javabase) FileException "java.lang.Exception";
+%typemap(javabase) FileException "java.lang.Exception"
 %typemap(javacode) FileException %{
   public String getMessage() {
     return what();
@@ -9062,6 +9085,11 @@ You may have to add in some "jtype", "jstype", "javain" and "javaout" typemaps w
 Here the default typemaps work for int and char *.
 
    
 
+
    
+Note that if you're wanting to effectively replace the JNI code generated for a C/C++ function then you'll need to use %ignore as well
+to tell SWIG not to automatically generate a JNI wrapper for it.
+
    
+
 
    
 In summary the %native directive is telling SWIG to generate the Java code to access the JNI C code, but not the JNI C function itself.
 This directive is only really useful if you want to mix your own hand crafted JNI code and the SWIG generated code into one Java class or package.
diff --git a/Doc/Manual/Javascript.html b/Doc/Manual/Javascript.html
index 54bd68521..ab8657510 100644
--- a/Doc/Manual/Javascript.html
+++ b/Doc/Manual/Javascript.html
@@ -89,24 +89,10 @@ $ swig -javascript -jsc example.i
    
 
     $ swig -c++ -javascript -jsc example.i
    
 
    
-
    The V8 code that SWIG generates should work with most versions from 3.11.10.
-However, the only early version that receives some testing is 3.14.5, which is
-still shipped with Ubuntu for some reason. Other than that it's probably safer
-to assume that versions earlier than 5.0 are no longer supported. Keep in mind
-that these are V8 versions, not Node.js. To give some perspective, Node.js v6.0
+
    The V8 code that SWIG generates requires at least V8 5.0. Keep in mind
+that this is theV8 version, not Node.js. To give some perspective, Node.js v6.0
 uses V8 5.0, v12.0 - 7.4, v14.0 - 8.1...
    
-
    The API headers for V8 >= 4.3.10 define constants which SWIG can use to
-determine the V8 version it is compiling for.  For versions < 4.3.10, you
-need to specify the V8 version when running SWIG.  This is specified as a hex
-constant, but the constant is read as pairs of decimal digits, so for V8
-3.25.30 use constant 0x032530.  This scheme can't represent components > 99,
-but this constant is only useful for V8 < 4.3.10, and no V8 versions from
-that era had a component > 99.  For example:
    
-
    
-
    -$ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i
    
-
    
-
    If you're targeting V8 >= 4.3.10, you would just run swig like so:
    
+
    To generate code for V8, you would run swig like so:
    
 
    
 
     $ swig -c++ -javascript -v8 example.i
    
diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html
index 5f72b557d..f308c31f1 100644
--- a/Doc/Manual/Library.html
+++ b/Doc/Manual/Library.html
@@ -14,6 +14,7 @@
 
  • The %include directive and library search path
 
  • C arrays and pointers
 
+
  • unique_ptr smart pointer
 
  • auto_ptr smart pointer
 
 
  • Utility Libraries
 
 
 
    • 
@@ -111,7 +117,48 @@ pointers as class-like objects.   Since these functions provide direct access to
 memory, their use is potentially unsafe and you should exercise caution.
 
    
 
-
    12.2.1 cpointer.i
    
+
    12.2.1 argcargv.i
    
+
+
+
    
+The argcargv.i library is a simple library providing multi-argument typemaps for handling C
+argc argv command line argument C string arrays.
+The argc parameter contains the argument count and argv contains the argument vector array.
+
    
+
+
    
+This library provides the following multi-argument typemap:
+
    
+
+
    
+(int ARGC, char **ARGV)
+
    
+
+
    
+Apply this multi-argument typemap to your use case, for example:
+
    
+
+
    
+
    +%apply (int ARGC, char **ARGV) { (size_t argc, const char **argv) }
+
+int mainApp(size_t argc, const char **argv);
+
    
+
    
+
+
    
+then from Ruby:
+
    
+
+
    
+
    +$args = ["myarg1", "myarg2"]
+mainApp(args);
+
    
+
    
+
+
+
    12.2.2 cpointer.i
    
 
 
 
    
@@ -327,7 +374,7 @@ In this example,  the function int_to_uint() would be used to cast type
 Note: When working with simple pointers, typemaps can often be used to provide more seamless operation.
 
    
 
-
    12.2.2 carrays.i
    
+
    12.2.3 carrays.i
    
 
 
 
    
@@ -506,7 +553,7 @@ used with types of char or char *.
 SWIG's default handling of these types is to handle them as character strings and the two macros do not do enough to change this.
 
    
 
-
    12.2.3 cmalloc.i
    
+
    12.2.4 cmalloc.i
    
 
 
 
    
@@ -667,7 +714,7 @@ Now, in a script:
    -

    12.2.4 cdata.i

    +

    12.2.5 cdata.i

    @@ -1994,38 +2041,41 @@ The SWIG code below shows the required ordering: The languages that support shared_ptr also have support for using shared_ptr with directors.

    - -

    12.4.5 auto_ptr smart pointer

    +

    12.4.5 unique_ptr smart pointer

    -While std::auto_ptr is deprecated in C++11, some existing code may -still be using it, so SWIG provides limited support for this class: -std_auto_ptr.i defines the typemaps which apply to the functions -returning objects of this type. Any other use of std_auto_ptr.i is not -directly supported. +The std_unique_ptr.i library file provides SWIG's unique_ptr support. +It defines typemaps and a macro, %unique_ptr(T), to use for handling +std::unique_ptr<T> for a type T. +The type T must be non-primitive. +This macro should be used before any code declaring or using type T. +Ordering requirements for using this smart pointer macro are the same as the +equivalent %shared_ptr(T) macro covered in the previous section.

    -A typical example of use would be +Example usage of a std::unique_ptr being returned from a function is shown below.

    + 
    -%include <std_auto_ptr.i>
+%include <std_unique_ptr.i>
 
-%auto_ptr(Klass)
+%unique_ptr(Klass)
 %inline %{
+#include <memory>
 class Klass {
 public:
   // Factory function creating objects of this class:
-  static std::auto_ptr<Klass> Create(int value) {
-    return std::auto_ptr<Klass>(new Klass(value));
+  static std::unique_ptr<Klass> Create(int value) {
+    return std::unique_ptr<Klass>(new Klass(value));
   }
 
   int getValue() const { return m_value; }
 
 private:
-  DerivedIntValue(int value) : m_value(value) {}
+  Klass(int value) : m_value(value) {}
   int m_value;
 };
 %}
@@ -2044,6 +2094,144 @@ int value = k.getValue();
    +

    +The implementation simply calls std::unique_ptr::release() to obtain +the underlying raw pointer. The pointer is then used to create a target language +proxy class in the same way that SWIG handles a C++ function returning a class by value. +The target language proxy class then owns the memory pointed to by the raw pointer +and memory handling is identical to normal SWIG proxy class handling of the underlying C++ memory. +Note that an object returned by value is first copied/moved from the stack onto the heap in order to obtain +a raw pointer on the heap, whereas the underlying raw pointer in std::unique_ptr already points to an object the heap. +

    + +

    +Note that the implementation is quite different to the std::shared_ptr smart pointer, +where the proxy class manages the underlying C++ memory as a pointer to a shared_ptr instead of a plain raw pointer. +

    + +

    +A possibly less common usage of this smart pointer is as a parameter to a function. +When used like this it indicates that memory usage of the object pointed to by the underlying pointer +is transferred to the function being called. +The code that SWIG generates assumes this happens. +First, it is assumed that a proxy class already owns the underlying C++ object and is used to pass the object to the C++ function being called. +Second, the ownership is transferred from the proxy class to the C++ function being called and +lifetime is then controlled by the function. +Finally, it is assumed the lifetime of the object may not last beyond returning from the C++ function +and hence the proxy class can no longer be used. +

    + +

    +Consider expanding the example above with a function that takes a std::unique_ptr as follows: +

    + +
    +
    +void take(std::unique_ptr<Klass>);
+
    +
    + +

    +and use from C#: +

    + +
    +
    +Klass k = Klass.Create(17); // create an instance of Klass any way you like
+int value = k.getValue();   // ok
+example.take(k);            // memory ownership passes from C# layer to C++ layer
+int v = k.getValue();       // don't do this - invalid use of k
+
    +
    + +

    +Attempts to use k after the ownership has been passed into the take function +should not be attempted. +The implementation sets the proxy class to an invalid state by setting the class's underlying +C++ pointer to null after the return from the take function. +Subsequent use of an invalid proxy class instance is very much dependent on the implementation +in the target language and ranges from a segfault to giving a nice error. +Consider implementing additional checks via the 'check' typemap. +

    + +

    +Attempts to pass ownership from a proxy class to a std::unique parameter more than once will result +in a "Cannot release ownership as memory is not owned" exception. For example, if example.take(k) in the example above is called twice. +

    + +

    +Compatibility note: Support for std::unique_ptr was added in SWIG-4.1.0. +

    + +

    12.4.6 auto_ptr smart pointer

    + + +

    +While std::auto_ptr is deprecated in C++11, some existing code may +still be using it. SWIG provides support for this class which is nearly identical +to std::unique_ptr. +

    + +

    +The std_auto_ptr.i library file provides SWIG's auto_ptr support. +It defines typemaps and a macro, %auto_ptr(T), to use for handling +std::auto_ptr<T> for a type T. +The type T must be non-primitive. +This macro should be used before any code declaring or using type T. +Ordering requirements for using this smart pointer macro are the same as the +equivalent %shared_ptr(T) and %unique_ptr macros covered in +the previous two sections. +

    + +

    +Example usage of a std::auto_ptr being returned from a function is shown below. +

    + +
    +
    +%include <std_auto_ptr.i>
+
+%auto_ptr(Klass)
+%inline %{
+#include <memory>
+class Klass {
+public:
+  // Factory function creating objects of this class:
+  static std::auto_ptr<Klass> Create(int value) {
+    return std::auto_ptr<Klass>(new Klass(value));
+  }
+
+  int getValue() const { return m_value; }
+
+private:
+  Klass(int value) : m_value(value) {}
+  int m_value;
+};
+%}
+
    +
    + +

    +The returned objects can be used naturally from the target language, e.g. from +C#: +

    + +
    +
    +Klass k = Klass.Create(17);
+int value = k.getValue();
+
    +
    + +

    +The implementation simply calls std::auto_ptr::release() to obtain the underlying raw pointer. +That is, it works the same way covered in the previous section for std::unique_ptr. +

    + +

    +Input parameters also work the same way as std::unique_ptr covered in the previous section. +

    +

    12.5 Utility Libraries

    @@ -2108,5 +2296,244 @@ For example: +

    12.5.2 attribute.i

    + + +

    +The attribute library contains a set of macros to convert a pair of set/get methods +into a "native" attribute/property. +

    + +

    +Use %attribute when you have a pair of get/set methods to a +primitive type like: +

    + +
    +
    +%include "attribute.i"
+%attribute(A, int, a, get_a, set_a);
+
+struct A {
+  int get_a() const;
+  void set_a(int aa);
+};
+
    +
    + +

    +and you want to provide that variable as an attribute in the target +language. This example only works for primitive types, not derived +types. +Now you can use the attributes like so (in Python): +

    + +
    +
    +x = A()
+x.a = 3        # calls A::set_a(3)
+print(x.a)     # calls A::get_a() const
+
    +
    + +

    +If you don't provide a 'set' method, a 'read-only' attribute +is generated, ie, like: +

    + +
    +
    +%attribute(A, int, c, get_c);
+
    +
    + +

    +Use %attributeref when you have const/non-const reference +access methods for primitive types or class/structs, like: +

    + +
    +
    +%attributeref(A, int, b);
+
+struct A {
+  const int & b() const;
+  int & b();
+};
+
+%attributeref(B, int, c);
+
+struct B {
+  int & c();
+};
+
    +
    + +

    +Use the attributes like so (in Python): +

    + +
    +
    +x = A()
+x.b = 3        # calls A::b()
+print(x.b)     # calls A::b() const
+
    +
    + +

    +You can also use +

    + +
    +
    +%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
+
    +
    + +

    +if the internal C++ reference methods have a different name from the +attribute you want, so +

    + +
    +
    +%attributeref(B, int, d, c);
+
    +
    + +

    +is the same as the last example, but instead of the attribute 'c' being +called 'c', it is called 'd'. +

    + +

    +Use %attribute2 instead of %attribute to indicate +that reference-pointer translation is required. +Use %attribute2 instead of %attribute in cases like +this: +

    + +
    +
    +%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
+%inline %{
+  struct MyFoo {
+    int x;
+  };
+  class MyClass {
+    MyFoo foo;
+  public:
+    MyFoo & GetFoo() { return foo; }
+    void SetFoo(const MyFoo &other) { foo = other; }
+  };
+%}
+
    +
    + +

    +Here, the data type of the property is a wrapped type MyFoo and on +the C++ side it is passed by reference. The problem is that the SWIG +wrapper will pass around a pointer (MyFoo *) which is not compatible +with the reference type of the accessors (MyFoo &). Therefore, if you +use %attribute, you'll get an error from your C/C++ +compiler. %attribute2 translates between a pointer and a +reference to eliminate the error. In case you're confused, let's make +it simple: just use %attribute at first, but if the C/C++ +compiler gives an error while compiling the wrapper, +try %attribute2 instead. +

    + +

    +NOTE: remember that if the type contains commas, such as +std::pair<int, int>, you need to use the macro like: +

    + +
    +
    +%attributeref(A, %arg(std::pair<int, int>), pval);
+
    +
    + +

    +where %arg() 'normalizes' the type to be understood as a single +argument, otherwise the macro will get confused by the comma. +

    + +

    +The %attributeval is the same as %attribute, but +should be used when the type is a class/struct (ie a non-primitive +type) and when the get and set methods return/pass by value. The +following is very similar to the above example, but note that the +access is by value rather than reference. +

    + +
    +
    +%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
+%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
+%inline %{
+  class MyClassVal {
+    MyFoo foo;
+  public:
+    MyFoo GetFoo() { return foo; }
+    void SetFoo(MyFoo other) { foo = other; }
+  };
+%}
+
    +
    + +

    +The %attributestring is the same as %attributeval, +but should be used for string class types, which are unusual as they +are a class on the C++ side, but normally an immutable/primitive type +in the target language. Example usage for std::string: +

    + +
    +
    +%include <std_string.i>
+%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
+%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
+%inline %{
+  class MyStringyClass {
+    std::string str;
+  public:
+    MyStringyClass(const std::string &val) : str(val) {}
+    std::string GetString() { return str; }
+    void SetString(std::string other) { str = other; }
+  };
+%}
+
    +
    + +

    +The %attributestring also works for class types that +have %naturalvar turned on and so is also useful for +shared_ptr which has %naturalvar turned on in +%shared_ptr. +

    + +

    12.5.2.1 %attribute and C++ templates

    + + +

    + %attribute and friends have to be used on fully specified classes. For example +

    +
    +
    +%attributeref(A<int>, int, a);
+%inline %{
+  template <class T> struct A {
+    T a() const;
+    void a(T &);
+  };
+%}
+
    +
    +

    +Note the use of a template-id (i.e., A<int> not A<T> or just A). +This means that %attribute statements have to be repeated for any template-id that you want to use with %template. +

    diff --git a/Doc/Manual/Lisp.html b/Doc/Manual/Lisp.html index 6eb448a12..6d8463beb 100644 --- a/Doc/Manual/Lisp.html +++ b/Doc/Manual/Lisp.html @@ -264,7 +264,7 @@ Let's edit the interface file such that the C type "div_t*" is changed 
     %module test
 
-%typemap(cin) div_t* ":my-pointer";
+%typemap(cin) div_t* ":my-pointer"
 
 %feature("intern_function", "1");
 %feature("export");
diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html
index 80807baf4..682126dc9 100644
--- a/Doc/Manual/Lua.html
+++ b/Doc/Manual/Lua.html
@@ -1520,7 +1520,7 @@ function
 nil
 >
    -

    This behaviour was changed. Now unless -squash-bases option is provided, Derived store a list of it's bases and if some symbol is not found in it's own service tables +

    This behaviour was changed. Now unless -squash-bases option is provided, Derived stores a list of its bases and if some symbol is not found in its own service tables then its bases are searched for it. Option -squash-bases will effectively return old behaviour.

    @@ -1638,7 +1638,7 @@ More details can be found in the carrays. 
    // using the C-array
 %include <carrays.i>
-// this declares a batch of function for manipulating C integer arrays
+// this declares a batch of functions for manipulating C integer arrays
 %array_functions(int, int)
 
 extern void sort_int(int* arr, int len); // the function to wrap
@@ -1997,10 +1997,10 @@ So when 'p:Print()' is called, the __index looks on the object metatable for a '
 In theory, you can play with this usertable & add new features, but remember that it is a shared table between all instances of one class, and you could very easily corrupt the functions in all the instances.
 
    
 
    
-Note: Both the opaque structures (like the FILE*) and normal wrapped classes/structs use the same 'swig_lua_userdata' structure. Though the opaque structures has do not have a metatable attached, or any information on how to dispose of them when the interpreter has finished with them.
+Note: Both the opaque structures (like the FILE*) and normal wrapped classes/structs use the same 'swig_lua_userdata' structure. Though the opaque structures do not have a metatable attached, or any information on how to dispose of them when the interpreter has finished with them.
 
    
 
    
-Note: Operator overloads are basically done in the same way, by adding functions such as '__add' & '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
+Note: Operator overloads are basically done in the same way, by adding functions such as '__add' & '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming it's an operator overload.
 
    
 
    29.7.3 Memory management
    
 
diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html
index b9b7b2b94..1e3a8e7b1 100644
--- a/Doc/Manual/Modules.html
+++ b/Doc/Manual/Modules.html
@@ -119,6 +119,10 @@ public:
 // File: derived_module.i
 %module derived_module
 
+%{
+#include "base.h"
+%}
+
 %import "base_module.i"
 
 %inline %{
@@ -156,6 +160,10 @@ The derived_module.i file shown above could be replaced with the follow
 // File: derived_module.i
 %module derived_module
 
+%{
+#include "base.h"
+%}
+
 %import(module="base_module") "base.h"
 
 %inline %{
diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html
index 4ae07e969..9b59eec61 100644
--- a/Doc/Manual/Ocaml.html
+++ b/Doc/Manual/Ocaml.html
@@ -720,7 +720,6 @@ Here's a simple example using Trolltech's Qt Library:
 class QApplication {
 public:
   QApplication( int argc, char **argv );
-  void setMainWidget( QWidget *widget );
   void exec();
 };
 
@@ -736,16 +735,15 @@ public:
 
 
 
    -bash-2.05a$ QTPATH=/your/qt/path
-bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
-bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
-bash-2.05a$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
-bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include qt.i
-bash-2.05a$ mv qt_wrap.cxx qt_wrap.c
-bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
-bash-2.05a$ ocamlc -c qt.mli
-bash-2.05a$ ocamlc -c qt.ml
-bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
+$ QTPATH=/your/qt/path
+$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
+$ ocamlc -c swig.mli ; ocamlc -c swig.ml
+$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
+$ swig -ocaml -c++ -o qt_wrap.c qt.i
+$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
+$ ocamlc -c qt.mli
+$ ocamlc -c qt.ml
+$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
   camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
   -L$QTPATH/lib -cclib -lqt
 
    
diff --git a/Doc/Manual/Octave.html b/Doc/Manual/Octave.html
index bdef5db7c..de39a1d96 100644
--- a/Doc/Manual/Octave.html
+++ b/Doc/Manual/Octave.html
@@ -363,6 +363,10 @@ octave:2> f=swigexample.fopen("not there", "r");
 error: value on right hand side of assignment is undefined
 error: evaluating assignment expression near line 2, column 2
    +

    +NULL C/C++ pointers are represented by the Octave null matrix, []. +

    +

    30.3.6 Structures and C++ classes

    @@ -570,13 +574,13 @@ __mul__ a * b __div__ a / b __pow__ a ^ b __ldiv__ a \ b -__lshift__ a << b -__rshift__ a >> b -__lt__ a < b -__le__ a <= b +__lshift__ a << b +__rshift__ a >> b +__lt__ a < b +__le__ a <= b __eq__ a == b -__ge__ a >= b -__gt__ a > b +__ge__ a >= b +__gt__ a > b __ne__ a != b __el_mul__ a .* b __el_div__ a ./ b @@ -598,16 +602,16 @@ On the C++ side, the default mappings are as follows: %rename(__mul__) *::operator*; %rename(__div__) *::operator/; %rename(__mod__) *::operator%; -%rename(__lshift__) *::operator<<; -%rename(__rshift__) *::operator>>; +%rename(__lshift__) *::operator<<; +%rename(__rshift__) *::operator>>; %rename(__el_and__) *::operator&&; %rename(__el_or__) *::operator||; %rename(__xor__) *::operator^; %rename(__invert__) *::operator~; -%rename(__lt__) *::operator<; -%rename(__le__) *::operator<=; -%rename(__gt__) *::operator>; -%rename(__ge__) *::operator>=; +%rename(__lt__) *::operator<; +%rename(__le__) *::operator<=; +%rename(__gt__) *::operator>; +%rename(__ge__) *::operator>=; %rename(__eq__) *::operator==; %rename(__ne__) *::operator!=; %rename(__not__) *::operator!; @@ -634,7 +638,7 @@ You can use it to define special behavior, like for example defining Octave oper %extend A { string __str__() { stringstream sout; - sout<<$self->value; + sout<<$self->value; return sout.str(); } } diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 85c2545cf..c130cdef4 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -91,10 +91,10 @@

    This chapter describes SWIG's support of Perl5. Although the Perl5 module is one of the earliest SWIG modules, it has continued to evolve -and has been improved greatly with the help of SWIG users. For the -best results, it is recommended that SWIG be used with Perl 5.8 or -later. We're no longer testing regularly with older versions, but -Perl 5.6 seems to mostly work, while older versions don't. +and has been improved greatly with the help of SWIG users. As of SWIG +4.1.0, the minimum version of Perl we aim to support is Perl 5.8.0. +We can no longer easily test with older versions, and they no longer +seem to be in active use.

    31.1 Overview

    @@ -680,7 +680,6 @@ files(s) field". installation under "Additional include directories".
  • Define the symbols WIN32 and MSWIN32 under preprocessor options. -If using the ActiveWare port, also define the symbol PERL_OBJECT. Note that all extensions to the ActiveWare port must be compiled with the C++ compiler since Perl has been encapsulated in a C++ class. @@ -1065,7 +1064,7 @@ int *Foo_x_get(Foo *self) {

    If you want to set an array member, you will need to supply a "memberin" typemap described later in this chapter. As a special case, SWIG does generate -code to set array members of type char (allowing you to store a Python +code to set array members of type char (allowing you to store a Perl string in the structure).

    @@ -1494,7 +1493,7 @@ as well as a special error code: 
     /* send message, return number of bytes sent, along with success code */
-int send_message(char *text, int len, int *success);
+int send_message(char *text, int *success);
    @@ -1736,7 +1735,7 @@ See the chapter on "Customization fea 
    -%except(python) {
+%except(perl5) {
   try {
     $function
   }
@@ -2320,7 +2319,7 @@ typedef struct {
 
 
    
 By default, SWIG doesn't know how to the handle the values structure
-member it's an array, not a pointer.  In this case, SWIG makes the array member
+member because it's an array, not a pointer.  In this case, SWIG makes the array member
 read-only.   Reading will simply return a pointer to the first item in the array.
 To make the member writable, a "memberin" typemap can be used.
 
    
@@ -2651,8 +2650,8 @@ constructors and destructors for the package and are always named
 "new" and "DESTROY".  The constructor always returns a tied hash
 table.  This hash table is used to access the member variables of a
 structure in addition to being able to invoke member functions.  The
-%OWNER and %BLESSEDMEMBERS hash tables are used
-internally and described shortly.
+%OWNER and %BLESSEDMEMBERS hash tables are
+implementation details used internally and described shortly.
 
    
 
 
    
@@ -2740,8 +2739,15 @@ to a C function that remembers the object, and then destroy the
 corresponding Perl object (this situation turns out to come up
 frequently when constructing objects like linked lists and trees).
 When C takes possession of an object, you can change Perl's ownership
-by simply deleting the object from the %OWNER hash.  This is
-done using the DISOWN method.
+by calling the DISOWN method (which will delete the object
+from the internal %OWNER hash).
+
    
+
+
    
+The %OWNER hash is an implementation detail, discussed here
+only to help clarify the operation of ACQUIRE and DISOWN.
+You should not access %OWNER directly - the details of how it
+works (and possibly even its existence) may change in future SWIG versions.
 
    
 
 
    diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html
index 5aea878b2..72c914656 100644
--- a/Doc/Manual/Php.html
+++ b/Doc/Manual/Php.html
@@ -50,18 +50,19 @@
 
 
 
    
-In this chapter, we discuss SWIG's support of PHP.  SWIG currently supports
-generating wrappers for PHP7 and PHP8.  Support for PHP5 was removed in SWIG
-4.0.0 and support for PHP4 was removed in SWIG 1.3.37.
+In this chapter, we discuss SWIG's support of PHP.  Currently any PHP7 or PHP8
+release should work.
 
    
 
 
    
-Currently any PHP7 or PHP8 release should work.
+Support for PHP7 was added in SWIG 3.0.11 and for PHP8 in 4.1.0.
+Support for PHP5 was removed in SWIG 4.0.0 and support for PHP4 was removed in
+SWIG 1.3.37.  There never was a PHP6 release.
 
    
 
 
    
 In order to use this module, you will need to have a copy of the PHP
-include files to compile the SWIG generated files.  If you installed
+include files to compile the SWIG generated C/C++ sources.  If you installed
 PHP from a binary package, you may need to install a "php-dev" or "php-devel"
 package for these to be installed.  You can find out where these files are
 by running php-config --includes.  To use the built PHP module you
@@ -161,7 +162,7 @@ default extension directory, you also need to specify the path, for example:
 
    
 
 
    -	extension=/path/to/modulename.so
+        extension=/path/to/modulename.so
 
    
 
 
    
@@ -306,11 +307,10 @@ functions.
 
    
 
 
    
-SWIG honors the %immutable modifier by not generating code
-for the _set method.  This provides read-only access to the
-variable from the php script.  Attempting to access the _set
-method will result in a php fatal error because the function is
-undefined.
+SWIG honors the %immutable modifier by not generating a
+_set method (so attempting to call it will give a PHP fatal
+error).  A _get method is still generated so this provides read-only
+access to the variable from the PHP script.
 
    
 
 
    
@@ -343,6 +343,80 @@ $c = bar(3.5);  # Use default argument for 2nd parameter
 
 
    
 
+
    
+SWIG generates PHP type declarations for function parameters and return
+types for PHP 8 and later (we don't try to support PHP 7's more limited type
+declarations and the generated wrappers compiled for PHP 7 will not have any
+type declarations).
+
    
+
+
    
+You can control the generation of PHP type declarations using
+the "php:type" %feature.  This has three settings:
+
    
+
+
      
+    
    •  
      If unset or set to "0" then no type declarations are generated, e.g.: %feature("php:type", "0");
+      
      
+    
      • 
+    
    •  
      If set to "1" then type declarations are generated for both parameters and return types, e.g.: %feature("php:type", "1");
+      
      • 
+      
    •  
      The default setting is "compat", which is the same as "1" except no
+      return type declarations are generated for virtual methods for which
+      directors are enabled.  This provides better compatibility for PHP
+      subclasses of wrapped virtual methods in existing SWIG-generated bindings, e.g.: %feature("php:type", "compat");
+      
      • 
+
    
+
+
    
+If you have an existing PHP interface and are upgrading to SWIG >= 4.1.0
+then the default "compat" setting should work well.
+
    
+
+
    
+If you're writing a new set of bindings and only targeting PHP8 or newer
+then enabling type declarations everywhere probably makes sense.  It will
+only actually make a difference if you enable directors and are wrapping C++
+classes with virtual methods, but doing it anyway means you won't forget to if
+the code you are wrapping later evolves to have such classes and methods.
+
    
+
+
    
+The type declaration information will make the generated source code and
+compiler extension module larger, so you might want to turn off type
+declarations if keeping these small is important to you.  If you find you
+need to turn off type declarations to fix a problem, please let us know
+via our github issue tracker.
+
    
+
+
    
+Note that being a SWIG feature this can be specified globally (like above) or
+per class, per method, etc.  See the %feature directives
+section for full details of how to control at a fine-grained level.
+
    
+
+
    
+The PHP type information is specified via a "phptype" attribute on "in" and
+"out" typemaps, and these have been added for all the typemaps we supply for
+PHP.  We don't currently support this for "argout" templates, but probably
+will in a future version.
+
    
+
+
    
+If you have written custom SWIG typemaps for PHP and want to add PHP type
+declarations, then the syntax is very like how you'd specify the type in
+PHP code, e.g. %typemap(in, phptype="int|string|Foo") means the
+typemap accepts a PHP int or string or an object of class Foo,
+%typemap(in, phptype="?int") means a PHP int or NULL, etc.
+As well as the standard PHP type declaration types, SWIG also understands the
+special type "SWIGTYPE" as an entry in phptype, which means the PHP type
+corresponding to the type that this typemap matched on - for a object this
+will give you the PHP class for the object, and for a pointer to a non-class
+type it will give you the name of the PHP class SWIG created for that
+pointer type.
+
    
+