jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'master' into director-unwrap-result

Browse source
This commit is contained in:
Olly Betts 2022-03-01 11:34:59 +13:00 • committed by GitHub
commit deb7cbf741
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1099 changed files with 14845 additions and 34359 deletions
Download patch file Download diff file Expand all files Collapse all files

457
.github/workflows/ci.yml vendored Normal file
View file

@ -0,0 +1,457 @@
name: CI
on:
push:
paths-ignore:
- 'CHANGES*'
- 'Doc/**'
- 'appveyor.yml'
pull_request:
branches: master
paths-ignore:
- 'CHANGES*'
- 'Doc/**'
- 'appveyor.yml'
jobs:
build:
# When continue-on-error is true for an individual build, that build can fail (it'll show red),
# but it won't fail the overall build
continue-on-error: ${{ matrix.continue-on-error || false }}
runs-on: ${{ matrix.os || 'ubuntu-20.04' }}
# 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)' }}
strategy:
matrix:
include:
- SWIGLANG: ""
- SWIGLANG: ""
GCC: 7
- SWIGLANG: ""
GCC: 8
- SWIGLANG: ""
GCC: 9
- SWIGLANG: ""
GCC: 10
- SWIGLANG: ""
GCC: 11
- SWIGLANG: ""
compiler: clang
- SWIGLANG: csharp
# D support can't be enabled because dmd 2.066 fails to build anything
# under Ubuntu 18.04 due to its standard library (libphobos2.a) not
# being compiled with -FPIC, but system gcc using -fpie by default,
# resulting in linking errors for any output. And later versions, such
# as 2.086.1, are not supported and result in errors in SWIG test suite.
#
# - SWIGLANG: d
# VER: '2.066.0'
# os: ubuntu-18.04 # This dlang version doesn't work under 20.04.
- SWIGLANG: go
VER: '1.6'
CSTD: gnu11
- SWIGLANG: go
VER: '1.8'
- SWIGLANG: go
VER: '1.12'
CSTD: gnu11
- SWIGLANG: go
VER: '1.17'
- SWIGLANG: guile
- 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: '17'
CPPSTD: c++14
- SWIGLANG: javascript
ENGINE: jsc
- SWIGLANG: lua
- SWIGLANG: lua
VER: '5.3'
- SWIGLANG: octave
CPPSTD: c++11
- SWIGLANG: octave
VER: '6.4'
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
- 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
SWIG_FEATURES: -builtin
- SWIGLANG: python
SWIG_FEATURES: -builtin -O
- SWIGLANG: python
PY3: 3
SWIG_FEATURES: -builtin
- SWIGLANG: python
PY3: 3
SWIG_FEATURES: -builtin -O
- SWIGLANG: r
- SWIGLANG: ruby
VER: '1.9'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.0'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.1'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.2'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.3'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.4'
- SWIGLANG: ruby
VER: '2.5'
- SWIGLANG: ruby
VER: '2.6'
- SWIGLANG: ruby
VER: '2.7'
- SWIGLANG: ruby
VER: '3.0'
CPPSTD: c++11
- SWIGLANG: scilab
VER: '5.5.2'
- SWIGLANG: scilab
os: ubuntu-18.04 # scilab 6.0
- SWIGLANG: scilab
- SWIGLANG: tcl
# c++11 testing
- SWIGLANG: csharp
CPPSTD: c++11
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++11
CSTD: gnu11
- SWIGLANG: guile
CPPSTD: c++11
- SWIGLANG: java
CPPSTD: c++11
- SWIGLANG: javascript
ENGINE: node
VER: '14'
CPPSTD: c++11
- SWIGLANG: lua
CPPSTD: c++11
- SWIGLANG: perl5
CPPSTD: c++11
- SWIGLANG: php
CPPSTD: c++11
CSTD: gnu11
- SWIGLANG: python
CPPSTD: c++11
PY3: 3
- SWIGLANG: r
CPPSTD: c++11
- SWIGLANG: ruby
CPPSTD: c++11
- SWIGLANG: scilab
CPPSTD: c++11
- SWIGLANG: tcl
CPPSTD: c++11
# c++14 testing
- SWIGLANG: csharp
CPPSTD: c++14
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++14
CSTD: gnu11
- SWIGLANG: guile
CPPSTD: c++14
- SWIGLANG: java
CPPSTD: c++14
- SWIGLANG: javascript
ENGINE: node
VER: '16'
CPPSTD: c++14
- SWIGLANG: lua
CPPSTD: c++14
- SWIGLANG: octave
CPPSTD: c++14
- SWIGLANG: perl5
CPPSTD: c++14
- SWIGLANG: php
CPPSTD: c++14
CSTD: gnu11
- SWIGLANG: python
CPPSTD: c++14
PY3: 3
- SWIGLANG: r
CPPSTD: c++14
- SWIGLANG: ruby
CPPSTD: c++14
- SWIGLANG: scilab
CPPSTD: c++14
- SWIGLANG: tcl
CPPSTD: c++14
# c++17 testing (using gcc11)
- SWIGLANG: csharp
CPPSTD: c++17
GCC: 11
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++17
GCC: 11
CSTD: gnu17
- SWIGLANG: guile
CPPSTD: c++17
GCC: 11
- SWIGLANG: java
CPPSTD: c++17
GCC: 11
- SWIGLANG: javascript
ENGINE: node
VER: '17'
CPPSTD: c++17
GCC: 11
- SWIGLANG: lua
CPPSTD: c++17
GCC: 11
- SWIGLANG: octave
CPPSTD: c++17
GCC: 11
- SWIGLANG: perl5
CPPSTD: c++17
GCC: 11
- SWIGLANG: php
CPPSTD: c++17
CSTD: gnu17
GCC: 11
- SWIGLANG: python
CPPSTD: c++17
GCC: 11
PY3: 3
- SWIGLANG: r
CPPSTD: c++17
GCC: 11
- SWIGLANG: ruby
CPPSTD: c++17
GCC: 11
- SWIGLANG: scilab
CPPSTD: c++17
GCC: 11
- SWIGLANG: tcl
CPPSTD: c++17
GCC: 11
# Experimental languages (these are allowed to fail)
- SWIGLANG: mzscheme
continue-on-error: true
- SWIGLANG: ocaml
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
fail-fast: false
env:
SWIGLANG: ${{ matrix.SWIGLANG }}
PY3: ${{ matrix.PY3 }}
VER: ${{ matrix.VER }}
ENGINE: ${{ matrix.ENGINE }}
SWIG_FEATURES: ${{ matrix.SWIG_FEATURES }}
GCC: ${{ matrix.GCC }}
CSTD: ${{ matrix.CSTD }}
CPPSTD: ${{ matrix.CPPSTD }}
steps:
- name: Checkout
uses: actions/checkout@v2
with:
submodules: recursive
- name: Install CCache
uses: hendrikmuhs/ccache-action@v1
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
export PATH="/usr/lib/ccache:/usr/local/opt/ccache/libexec:$PATH"
echo PATH="$PATH" >> $GITHUB_ENV
source $GITHUB_WORKSPACE/Tools/GHA-linux-install.sh
echo WITHLANG="$WITHLANG" >> $GITHUB_ENV
case $(uname) in
Linux)
cpu_count=$(nproc)
;;
Darwin)
cpu_count=$(sysctl -n hw.ncpu)
;;
*)
cpu_count=1
;;
esac
if [[ $cpu_count != 1 ]]; then
echo SWIGJOBS=-j$cpu_count >> $GITHUB_ENV
fi
if test '${{ matrix.compiler }}' = 'clang'; then
CC="clang"
CXX="clang++"
CFLAGS="$CFLAGS -fPIE"
CXXFLAGS="$CXXFLAGS -fPIE"
elif test -n "$GCC"; then
CC="gcc-$GCC"
CXX="g++-$GCC"
else
CC="gcc"
CXX="g++"
fi
export CC CXX
echo CC="$CC" >> $GITHUB_ENV
echo CXX="$CXX" >> $GITHUB_ENV
ls -la $(which $CC) $(which $CXX)
$CC --version
$CXX --version
- name: Configure
run: |
source $GITHUB_WORKSPACE/Tools/CI-linux-environment.sh
set -x
if [[ -z "$CSTD" ]]; then
case "$CPPSTD" in
c++11) export CSTD=c11 ;;
c++14) export CSTD=c11 ;;
c++17) 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 -n "$CSTD"; then CONFIGOPTS+=("CFLAGS=-std=$CSTD $CFLAGS"); 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[@]}"
- name: Build
working-directory: build/build
run: |
set -x
make -s $SWIGJOBS
./swig -version && ./swig -pcreversion
- name: Test
working-directory: build/build
run: |
source $GITHUB_WORKSPACE/Tools/CI-linux-environment.sh
set -x
if test -z "$SWIGLANG"; then
make $SWIGJOBS check-ccache
make $SWIGJOBS check-errors-test-suite
else
case "$SWIGLANG" in
javascript)
case "$ENGINE" in
v8 | jsc)
# Running tests using v8 or jsc involves creating a custom
# interpreter in Tools/javascript, which is currently broken
# for parallel builds (we attempt to update this interpreter
# while running, resulting in "Text file busy" error).
unset SWIGJOBS
esac
;;
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)
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"
make $SWIGJOBS check-$SWIGLANG-test-suite CFLAGS="$cflags" CXXFLAGS="$cxxflags"
fi
- name: Install
working-directory: build/build
run: |
set -x
if test -z "$SWIGLANG"; then sudo make install && swig -version && ccache-swig -V; fi
- name: Clean
working-directory: build/build
run: |
set -x
make check-maintainer-clean && ../../configure

7
.gitignore vendored
View file

@ -150,6 +150,8 @@ Examples/guile/*/my-guile
# Java # Java
Examples/test-suite/java/*/ Examples/test-suite/java/*/
Examples/test-suite/java/expected.txt
Examples/test-suite/java/got.txt
Examples/java/*/*.java Examples/java/*/*.java
!Examples/java/*/runme.java !Examples/java/*/runme.java
Examples/java/doxygen/javadocs Examples/java/doxygen/javadocs
@ -182,11 +184,8 @@ Examples/perl5/*/*.pm
# PHP # PHP
Examples/test-suite/php/php_*.h Examples/test-suite/php/php_*.h
Examples/test-suite/php/*.php
!Examples/test-suite/php/*runme.php
!Examples/test-suite/php/skel.php
Examples/php/*/php_*.h Examples/php/*/php_*.h
Examples/php/*/example.php Examples/php/pragmas/example.php
# Python # Python
# Based on https://github.com/github/gitignore/blob/master/Python.gitignore # Based on https://github.com/github/gitignore/blob/master/Python.gitignore

536
.travis.yml
View file

@ -1,536 +0,0 @@
language: cpp
matrix:
include:
- compiler: clang
os: linux
env: SWIGLANG=
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.4
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.6
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.7
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.8
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.9
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=6
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=7
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=8
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=9
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=csharp
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=d VER=2.066.0
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=d VER=2.086.1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=go VER=1.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=go VER=1.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=go VER=1.12
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=guile
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=java
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=0.10
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=4 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=6 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=8 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=10 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=jsc
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=v8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=lua
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=lua VER=5.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=mzscheme
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ocaml
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=octave SWIGJOBS=-j2
sudo: required
dist: xenial # Octave v4.0.0
- compiler: gcc
os: linux
env: SWIGLANG=octave SWIGJOBS=-j2 CPP11=1
sudo: required
dist: bionic # Octave v4.2.2
- compiler: gcc
os: linux
env: SWIGLANG=perl5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.0
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python # 2.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.4
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.6
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES="-builtin -O"
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1 PY3=3 VER=3.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.4
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES="-builtin -O" PY3=3 VER=3.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.8 SWIGOPTPY3=
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-O
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-O PY3=3 VER=3.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=r
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=1.9
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.0
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.4
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.6
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=scilab
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=tcl
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=go VER=1.6 CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=r CPP11=1 # Note: making 'R CMD SHLIB' use a different compiler is non-trivial
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=ruby CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=tcl CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=go VER=1.6 GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=ruby GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=tcl GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=7 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=7 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp GCC=8 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=8 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=8 CPP17=1 PY3=3 VER=3.8
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp GCC=9 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=9 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=9 CPP17=1 PY3=3 VER=3.8
sudo: required
dist: xenial
- os: linux
arch: s390x
env: SWIGLANG=ruby CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: osx
env: SWIGLANG=
- compiler: clang
os: osx
env: SWIGLANG=
- compiler: clang
os: osx
env: SWIGLANG=csharp
- compiler: clang
os: osx
env: SWIGLANG=go
- compiler: clang
os: osx
env: SWIGLANG=guile CSTD=c11
- compiler: clang
os: osx
env: SWIGLANG=java
- compiler: clang
os: osx
env: SWIGLANG=lua
- compiler: clang
os: osx
env: SWIGLANG=octave SWIGJOBS=-j2 CPP11=1
- compiler: clang
os: osx
env: SWIGLANG=perl5
- compiler: clang
os: osx
env: SWIGLANG=python
- compiler: clang
os: osx
env: SWIGLANG=python PY3=3
- compiler: clang
os: osx
env: SWIGLANG=ruby
- compiler: clang
os: osx
env: SWIGLANG=tcl
- compiler: clang
os: osx
env: SWIGLANG=java CPP17=1
osx_image: xcode10.2
- compiler: clang
os: osx
env: SWIGLANG=python PY3=3 CPP17=1
osx_image: xcode10.2
allow_failures:
# Newer version of D not yet working/supported
- compiler: gcc
os: linux
env: SWIGLANG=d VER=2.086.1
sudo: required
dist: xenial
# seg fault in director_basic testcase
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.2
sudo: required
dist: xenial
# Experimental languages
- compiler: gcc
os: linux
env: SWIGLANG=mzscheme
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ocaml
sudo: required
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:
- echo 'Configuring...' && echo -en 'travis_fold:start:script.1\\r'
- if test -n "$CPP11"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++11 -Wall -Wextra" "CFLAGS=-std=c11 -Wall -Wextra") && export CSTD=c11 && export CPPSTD=c++11; fi
- if test -n "$CPP14"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++14 -Wall -Wextra" "CFLAGS=-std=c11 -Wall -Wextra") && export CSTD=c11 && export CPPSTD=c++14; fi
- if test -n "$CPP17"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++17 -Wall -Wextra" "CFLAGS=-std=c17 -Wall -Wextra") && 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'
- make check-maintainer-clean && ../../configure $CONFIGOPTS
- echo -en 'travis_fold:end:script.3\\r'

4
ANNOUNCE
View file

@ -25,11 +25,11 @@ Availability
============ ============
The release is available for download on Sourceforge at 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 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, Please report problems with this release to the swig-devel mailing list,
details at http://www.swig.org/mail.html. details at http://www.swig.org/mail.html.

2
CCache/README.swig
View file

@ -2,7 +2,7 @@ This directory contains a version of ccache. The initial version was based on cc
debian patches 01-02, 04-14, see the debian/patches subdirectory. The ccache-win32-2.4 modifications debian patches 01-02, 04-14, see the debian/patches subdirectory. The ccache-win32-2.4 modifications
to ccache-2.4 have also been merged in. to ccache-2.4 have also been merged in.
Changes have been made to support cacheing the output from SWIG. The ability to cache c/c++ compiler Changes have been made to support caching the output from SWIG. The ability to cache c/c++ compiler
output has been retained. output has been retained.
Additional features added are the CCACHE_VERBOSE and CCACHE_SWIG environment variables, see docs. Additional features added are the CCACHE_VERBOSE and CCACHE_SWIG environment variables, see docs.

20
CCache/configure.ac
View file

@ -1,12 +1,12 @@
dnl Process this file with autoconf to produce a configure script. dnl Process this file with autoconf to produce a configure script.
AC_INIT([ccache-swig], [0.0]) # Get version from SWIG in ccache_swig_config.h.in AC_INIT([ccache-swig],[0.0]) # Get version from SWIG in ccache_swig_config.h.in
AC_PREREQ(2.52) AC_PREREQ([2.60])
AC_CONFIG_SRCDIR([ccache.h]) AC_CONFIG_SRCDIR([ccache.h])
AC_MSG_NOTICE([Configuring ccache]) AC_MSG_NOTICE([Configuring ccache])
AC_CONFIG_HEADER(config.h) AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([config_win32.h]) AC_CONFIG_FILES([config_win32.h])
dnl Checks for programs. dnl Checks for programs.
@ -41,7 +41,7 @@ else
fi fi
AC_HEADER_DIRENT AC_HEADER_DIRENT
AC_HEADER_TIME
AC_HEADER_SYS_WAIT AC_HEADER_SYS_WAIT
AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h sys/time.h) AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h sys/time.h)
@ -51,19 +51,16 @@ AC_CHECK_FUNCS(gethostname getpwuid)
AC_CHECK_FUNCS(utimes) AC_CHECK_FUNCS(utimes)
AC_CACHE_CHECK([for compar_fn_t in stdlib.h],ccache_cv_COMPAR_FN_T, [ AC_CACHE_CHECK([for compar_fn_t in stdlib.h],ccache_cv_COMPAR_FN_T, [
AC_TRY_COMPILE( AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <stdlib.h>]], [[
[#include <stdlib.h>],
[
void test_fn(void) { qsort(NULL, 0, 0, (__compar_fn_t)NULL); } void test_fn(void) { qsort(NULL, 0, 0, (__compar_fn_t)NULL); }
], ]])],[ccache_cv_COMPAR_FN_T=yes],[ccache_cv_COMPAR_FN_T=no])])
ccache_cv_COMPAR_FN_T=yes,ccache_cv_COMPAR_FN_T=no)])
if test x"$ccache_cv_COMPAR_FN_T" = x"yes"; then if test x"$ccache_cv_COMPAR_FN_T" = x"yes"; then
AC_DEFINE(HAVE_COMPAR_FN_T, 1, [ ]) AC_DEFINE(HAVE_COMPAR_FN_T, 1, [ ])
fi fi
dnl Note: This could be replaced by AC_FUNC_SNPRINTF() in the autoconf macro archive dnl Note: This could be replaced by AC_FUNC_SNPRINTF() in the autoconf macro archive
AC_CACHE_CHECK([for C99 vsnprintf],ccache_cv_HAVE_C99_VSNPRINTF,[ AC_CACHE_CHECK([for C99 vsnprintf],ccache_cv_HAVE_C99_VSNPRINTF,[
AC_TRY_RUN([ AC_RUN_IFELSE([AC_LANG_SOURCE([[
#include <sys/types.h> #include <sys/types.h>
#include <stdarg.h> #include <stdarg.h>
void foo(const char *format, ...) { void foo(const char *format, ...) {
@ -81,8 +78,7 @@ void foo(const char *format, ...) {
exit(0); exit(0);
} }
main() { foo("hello"); } main() { foo("hello"); }
], ]])],[ccache_cv_HAVE_C99_VSNPRINTF=yes],[ccache_cv_HAVE_C99_VSNPRINTF=no],[ccache_cv_HAVE_C99_VSNPRINTF=cross])])
ccache_cv_HAVE_C99_VSNPRINTF=yes,ccache_cv_HAVE_C99_VSNPRINTF=no,ccache_cv_HAVE_C99_VSNPRINTF=cross)])
if test x"$ccache_cv_HAVE_C99_VSNPRINTF" = x"yes"; then if test x"$ccache_cv_HAVE_C99_VSNPRINTF" = x"yes"; then
AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ]) AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ])
fi fi

2
CCache/execute.c
View file

@ -137,7 +137,7 @@ int execute(char **argv,
_dup2(fd, 2); _dup2(fd, 2);
_close(fd); _close(fd);
/* Spawn process (_exec* familly doesn't return) */ /* Spawn process (_exec* family doesn't return) */
status = _spawnv(_P_WAIT, argv[0], (const char **)argv); status = _spawnv(_P_WAIT, argv[0], (const char **)argv);
/* Restore descriptors */ /* Restore descriptors */

4
CCache/snprintf.c
View file

@ -16,7 +16,7 @@
* for string length. This covers a nasty loophole. * for string length. This covers a nasty loophole.
* *
* The other functions are there to prevent NULL pointers from * The other functions are there to prevent NULL pointers from
* causing nast effects. * causing nasty effects.
* *
* More Recently: * More Recently:
* Brandon Long <blong@fiction.net> 9/15/96 for mutt 0.43 * Brandon Long <blong@fiction.net> 9/15/96 for mutt 0.43
@ -30,7 +30,7 @@
* probably requires libm on most operating systems. Don't yet * probably requires libm on most operating systems. Don't yet
* support the exponent (e,E) and sigfig (g,G). Also, fmtint() * support the exponent (e,E) and sigfig (g,G). Also, fmtint()
* was pretty badly broken, it just wasn't being exercised in ways * was pretty badly broken, it just wasn't being exercised in ways
* which showed it, so that's been fixed. Also, formated the code * which showed it, so that's been fixed. Also, formatted the code
* to mutt conventions, and removed dead code left over from the * to mutt conventions, and removed dead code left over from the
* original. Also, there is now a builtin-test, just compile with: * original. Also, there is now a builtin-test, just compile with:
* gcc -DTEST_SNPRINTF -o snprintf snprintf.c -lm * gcc -DTEST_SNPRINTF -o snprintf snprintf.c -lm

2
CCache/web/index.html
View file

@ -34,7 +34,7 @@ on the new options.<p>
You can get this release from the <a href="http://ccache.samba.org/ftp/ccache/">download directory</a> You can get this release from the <a href="http://ccache.samba.org/ftp/ccache/">download directory</a>
<p>NOTE! This release changes the hash input slighly, so you will <p>NOTE! This release changes the hash input slightly, so you will
probably find that you will not get any hits against your existing probably find that you will not get any hits against your existing
cache when you upgrade. cache when you upgrade.

549
CHANGES.current
View file

@ -7,3 +7,552 @@ the issue number to the end of the URL: https://github.com/swig/swig/issues/
Version 4.1.0 (in progress) Version 4.1.0 (in progress)
=========================== ===========================
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
*** 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<std::string>` now give an error rather
than being quietly ignored.
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.
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_<module>_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(<type>)` 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<int>;
extern template void Func<int>();
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
new char[] in SWIG_AsCharPtrAndSize.
2021-10-03: ajrh1
[Perl] #2074: Avoid -Wmisleading-indentation in generated code
when using gcc11.
2021-10-03: jschueller
[CMake] #2065: Add option to enable or disable PCRE support.
2021-09-16: ianlancetaylor
[Go] Improved _cgo_panic implementation.
2021-09-16: ianlancetaylor
[Go] Don't use crosscall2 for panicking. Instead rely on documented
and exported interfaces.
2021-09-14: ianlancetaylor
[Go] Remove -no-cgo option (long unsupported in Go)
2021-05-04: olly
[PHP] #2014 Throw PHP exceptions instead of using PHP errors
PHP exceptions can be caught and handled if desired, but if they
aren't caught then PHP exits in much the same way as it does for a
PHP error.
In particular this means parameter type errors and some other cases
in SWIG-generated wrappers now throw a PHP exception, which matches
how PHP's native parameter handling deals with similar situations.
`SWIG_ErrorCode()`, `SWIG_ErrorMsg()`, `SWIG_FAIL()` and `goto thrown;`
are no longer supported (these are really all internal implementation
details and none are documented aside from brief mentions in CHANGES
for the first three). I wasn't able to find any uses in user interface
files at least in FOSS code via code search tools.
If you are using these:
Use `SWIG_PHP_Error(code,msg);` instead of `SWIG_ErrorCode(code);
SWIG_ErrorMsg(msg);` (which will throw a PHP exception in SWIG >= 4.1
and do the same as the individual calls in older SWIG).
`SWIG_FAIL();` and `goto thrown;` can typically be replaced with
`SWIG_fail;`. This will probably also work with older SWIG, but
please test with your wrappers if this is important to you.
*** POTENTIAL INCOMPATIBILITY ***
2021-05-17: adr26
[Python] #1985 Fix memory leaks:
1. Python object references were being incorrectly retained by
SwigPyClientData, causing swig_varlink_dealloc() never to run / free
memory. SwigPyClientData_New() / SwigPyClientData_Del() were updated
to fix the object reference counting, causing swig_varlink_dealloc()
to run and the memory swig_varlink owns to be freed.
2. SwigPyClientData itself was not freed by SwigPyClientData_Del(),
causing another heap leak. The required free() was added to
SwigPyClientData_Del()
3. Fix reference counting/leak of python cached type query
4. Fix reference counting/leak of SwigPyObject dict (-builtin)
5. Python object reference counting fixes for out-of-memory
scenarios were added to: SWIG_Python_RaiseOrModifyTypeError(),
SWIG_Python_AppendOutput(), SwigPyClientData_New(),
SwigPyObject_get___dict__() and SwigPyObject_format()
6. Add error handling for PyModule_AddObject() to
SWIG_Python_SetModule() (failure could be caused by OOM or a name
clash caused by malicious code)
2021-05-13: olly
[UFFI] #2009 Remove code for Common Lisp UFFI. We dropped support
for it in SWIG 4.0.0 and nobody has stepped forward to revive it in
over 2 years.
2021-05-13: olly
[S-EXP] #2009 Remove code for Common Lisp S-Exp. We dropped
support for it in SWIG 4.0.0 and nobody has stepped forward to
revive it in over 2 years.
2021-05-13: olly
[Pike] #2009 Remove code for Pike. We dropped support for it in
SWIG 4.0.0 and nobody has stepped forward to revive it in over 2
years.
2021-05-13: olly
[Modula3] #2009 Remove code for Modula3. We dropped support for it
in SWIG 4.0.0 and nobody has stepped forward to revive it in over 2
years.
2021-05-13: olly
[CLISP] #2009 Remove code for GNU Common Lisp. We dropped support
for it in SWIG 4.0.0 and nobody has stepped forward to revive it in
over 2 years.
2021-05-13: olly
[Chicken] #2009 Remove code for Chicken. We dropped support for it
in SWIG 4.0.0 and nobody has stepped forward to revive it in over 2
years.
2021-05-13: olly
[Allegrocl] #2009 Remove code for Allegro Common Lisp. We dropped
support for it in SWIG 4.0.0 and nobody has stepped forward to
revive it in over 2 years.
2021-05-04: olly
[PHP] #1982 #1457 https://sourceforge.net/p/swig/bugs/1339/
SWIG now only use PHP's C API to implement its wrappers, and no
longer generates PHP code to define classes. The wrappers should
be almost entirely compatible with those generated before, but
faster and without some previously hard-to-fix bugs.
The main notable difference is SWIG no longer generates a .php
wrapper at all by default (only if %pragma(php) code=... or
%pragma(php) include=... are specified in the interface file).
This also means you need to load the module via extension=...
in php.ini, rather than letting the dl() in the generated
.php wrapper load it (but dl() has only worked for command-line
PHP for some years now).
*** POTENTIAL INCOMPATIBILITY ***
2021-04-30: olly
#1984 Remove support for $source and $target.
These were officially deprecated in 2001, and attempts to use them have
resulted in a warning (including a pointer to what to update them to)
for most if not all of that time.
2021-04-27: wsfulton
#1987 [Java] Fix %interface family of macros for returning by const
pointer reference.
2021-04-19: olly
Fix use of uninitialised variable in the generated code for an
empty typecheck typemap, such as the dummy one we include for
std::initializer_list.
2021-04-12: olly
#1777 [Python] Specifying -py3 now generates a check for Python
version >= 3.0.
2021-03-26: olly
[PHP] Add PHP keywords 'fn' (added in 7.4) and 'match' (added in
8.0) to the list SWIG knows to automatically rename.
2021-03-23: wsfulton
#1942 [Python] Fix compilation error in wrappers when using -builtin
and wrapping varargs in constructors.
2021-03-22: goto40
#1977 Fix handling of template template parameters.
2021-03-21: olly
#1929, #1978 [PHP] Add support for PHP 8.
2021-03-19: wsfulton
#1610 Remove -ansi from default compilation flags.
2021-03-19: dot-asm
#1934 [Java] Clean up typemaps for long long arrays.
2021-03-19: olly
#1527 [PHP] Improve PHP object creation in directorin case.
Reportedly the code we were using in this case gave segfaults in
PHP 7.2 and later - we've been unable to reproduce these, but the
new approach is also simpler and should be bit faster too.
2021-03-18: olly
#1655 [PHP] Fix char* typecheck typemap to accept PHP Null like the
corresponding in typemap does.
2021-03-18: olly
#1900, #1905 [PHP] Fix wrapping of overloaded directed methods with
non-void return.
2021-03-11: murillo128
#1498 [Javascript] Support type conversion.
2021-03-06: nshmyrev
#872 [Javascript] Various typemap issues in arrays_javascript.i fixed.
2021-03-03: vaughamhong
#577 [Javascript] Implemented SetModule/GetModule for JSC to allow type sharing
across modules.
2021-03-01: xantares, Oliver Buchtala, geographika
#1040 Add support for building SWIG with CMake. See documentation in Windows.html.
2021-03-01: vadz
#1952 Fix incorrect warning "Unknown Doxygen command: ."
2021-02-28: p2k
#969 [Javascript] v8/node - prevent crash calling a constructor without new keyword.
2021-02-28: alecmev
#405 #1121 [Javascript] Fix OUTPUT typemaps on methods that don't return void.
The output value is appended to the return value.
2021-02-26: murillo128, wsfulton
#1269 [Javascript] Fix handling of large positive unsigned long and
unsigned long long values.
2021-02-24: tomleavy, yegorich, tungntpham
#1746 [Javascript] Add support for Node v12, v14 and v16.
SWIG support for Node is now for v6 and later only.
2020-02-09: ZackerySpytz
#1872 Fix typos in attribute2ref macros.
2020-10-10: wsfulton
[Javascript] Fix so that ccomplex.i interface to file can be used.
2020-10-10: wsfulton
#252 complex can now be used as a C identifier and doesn't give a syntax error.
2020-10-10: lpsinger
#1770 Correct C complex support.
_Complex is now parsed as a keyword rather than complex as per the C99 standard.
The complex macro is available in the ccomplex.i library file along with other
complex number handling provided by the complex.h header.
2020-10-07: ZackerySpytz
[Python] #1812 Fix the error handling for the PyObject_GetBuffer() calls in
pybuffer.i.
2020-10-07: treitmayr
#1824 Add missing space in director method declaration returning
const pointer.
2020-10-07: adelva1984
#1859 Remove all (two) exceptions from SWIG executable.
2020-09-25: wsfulton
[C#, Java] #1874 Add ability to change the modifiers for the interface
generated when using the %interface macros.
For C# use the 'csinterfacemodifiers' typemap.
For Java use the 'javainterfacemodifiers' typemap.
For example:
%typemap(csinterfacemodifiers) X "internal interface"
2020-09-24: geefr
[C#] #1868 Fix wchar_t* csvarout typemap for member variable wrappers.
2020-08-28: wsfulton
[Java] #1862 Fix crashes in swig_connect_director during director class construction
when using the director class from multiple threads - a race condition initialising
block scope static variables. The fix is guaranteed when using C++11, but most
compilers also fix it when using C++03/C++98.
2020-08-16: wsfulton
[Python] Add missing initializer for member ‘_heaptypeobject::ht_module’ when using
-builtin to complete Python 3.9 support.
2020-08-16: wsfulton
[Python] Remove PyEval_InitThreads() call for Python 3.7 and later as Python calls
it automatically now. This removes a deprecation warning when using Python 3.9.
2020-08-15: wsfulton
[Python] All Python examples and tests are written to be Python 2 and Python 3
compatible, removing the need for 2to3 to run the examples or test-suite.
2020-08-13: wsfulton
[C#] Add support for void *VOID_INT_PTR for member variables.
2020-07-29: chrisburr
#1843 [Python] Compilation error fix in SwigPyBuiltin_SetMetaType when using PyPy.
2020-06-14: ZackerySpytz
#1642 #1809 Fix virtual comparison operators in director classes - remove incorrect
space in the function name, for example, operator= = is now operator==.

167
CMakeLists.txt Normal file
View file

@ -0,0 +1,167 @@
cmake_minimum_required (VERSION 3.2)
if (NOT DEFINED CMAKE_BUILD_TYPE)
set (CMAKE_BUILD_TYPE Release CACHE STRING "Build type")
endif ()
project (swig)
if (POLICY CMP0074)
cmake_policy (SET CMP0074 NEW)
endif()
file (STRINGS configure.ac line LIMIT_COUNT 1 REGEX "AC_INIT\\(.*\\)" )
if (line MATCHES "AC_INIT\\(\\[(.*)\\],[ \t]*\\[(.*)\\],[ \t]*\\[(.*)\\]\\)" )
set (SWIG_VERSION ${CMAKE_MATCH_2})
set (PACKAGE_BUGREPORT ${CMAKE_MATCH_3})
else ()
message (SEND_ERROR "Could not parse version from configure.ac")
endif ()
set (SWIG_ROOT ${PROJECT_SOURCE_DIR})
set (SWIG_LIB share/swig/${SWIG_VERSION})
# Project wide configuration variables
# ------------------------------------
set (SWIG_SOURCE_DIR ${SWIG_ROOT}/Source CACHE INTERNAL "Path of swig sources" FORCE)
set (PACKAGE_NAME swig)
set (PACKAGE_VERSION ${SWIG_VERSION})
# Configure
# ---------
list (APPEND CMAKE_MODULE_PATH ${SWIG_ROOT}/Tools/cmake)
include (CheckIncludeFiles)
include (CheckIncludeFile)
include (CheckIncludeFileCXX)
include (CheckTypeSize)
include (CheckSymbolExists)
include (CheckFunctionExists)
include (CheckLibraryExists)
include (CheckCSourceCompiles)
# HACK: didn't get the bool check working for Visual Studio 2008
if (MSVC)
set(HAVE_BOOL 1)
else()
set (CMAKE_EXTRA_INCLUDE_FILES stdbool.h)
check_type_size ("bool" HAVE_BOOL)
set (CMAKE_EXTRA_INCLUDE_FILES)
endif()
check_include_file ("inttypes.h" HAVE_INTTYPES_H)
check_include_file ("stddef.h" HAVE_STDDEF_H)
check_include_file ("stdint.h" HAVE_STDINT_H)
check_include_file ("stdio.h" HAVE_STDIO_H)
check_include_file ("stdlib.h" HAVE_STDLIB_H)
check_include_file ("string.h" HAVE_STRING_H)
check_include_file ("strings.h" HAVE_STRINGS_H)
check_include_file ("sys/stat.h" HAVE_SYS_STAT_H)
check_include_file ("sys/types.h" HAVE_SYS_TYPES_H)
check_include_file ("unistd.h" HAVE_UNISTD_H)
check_include_files ("stdlib.h;stdarg.h;string.h;float.h" STDC_HEADERS)
check_include_file_cxx ("boost/shared_ptr.hpp" HAVE_BOOST)
check_library_exists (dl dlopen "" HAVE_LIBDL)
check_function_exists (popen HAVE_POPEN)
if (MSVC)
set (CMAKE_CXX_FLAGS "/EHsc ${CMAKE_CXX_FLAGS}")
endif ()
option (WITH_PCRE "Enable PCRE" ON)
if (WITH_PCRE)
find_package (PCRE2 REQUIRED)
set (HAVE_PCRE 1)
include_directories (${PCRE2_INCLUDE_DIRS})
endif()
if (WIN32)
file (TO_NATIVE_PATH ${CMAKE_INSTALL_PREFIX}/${SWIG_LIB} SWIG_LIB_WIN_UNIX)
string (REGEX REPLACE "\\\\" "\\\\\\\\" SWIG_LIB_WIN_UNIX "${SWIG_LIB_WIN_UNIX}")
endif ()
configure_file (${SWIG_ROOT}/Tools/cmake/swigconfig.h.in
${CMAKE_CURRENT_BINARY_DIR}/Source/Include/swigconfig.h)
find_package (BISON REQUIRED)
# Compiler flags
# --------------
include_directories (
${SWIG_SOURCE_DIR}/CParse
${SWIG_SOURCE_DIR}/Include
${SWIG_SOURCE_DIR}/DOH
${SWIG_SOURCE_DIR}/Swig
${SWIG_SOURCE_DIR}/Preprocessor
${SWIG_SOURCE_DIR}/Modules
${PROJECT_BINARY_DIR}/Source/Include
${PROJECT_BINARY_DIR}/Source/CParse
${PROJECT_SOURCE_DIR}/Source/Doxygen
)
# generate the parser source code (depends on bison)
file (MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/Source/CParse)
BISON_TARGET (swig_parser
${SWIG_SOURCE_DIR}/CParse/parser.y
${PROJECT_BINARY_DIR}/Source/CParse/parser.c
)
# generate swigwarn.swg
file (READ ${SWIG_SOURCE_DIR}/Include/swigwarn.h SWIG_WARN_H)
string (REGEX REPLACE "#define WARN([^ \\t]*)[ \\t]*([0-9]+)" "%define SWIGWARN\\1 \\2 %enddef" SWIG_WARN_SWG ${SWIG_WARN_H})
file (WRITE ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg ${SWIG_WARN_SWG})
set_property (SOURCE ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg PROPERTY GENERATED 1)
# install lib
install (DIRECTORY ${SWIG_ROOT}/Lib/ DESTINATION ${SWIG_LIB})
install (FILES ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg DESTINATION ${SWIG_LIB})
# sources
# ---------
file (GLOB DOH_SOURCES ${SWIG_SOURCE_DIR}/DOH/*.c)
file (GLOB CPARSE_SOURCES ${SWIG_SOURCE_DIR}/CParse/*.c)
list (APPEND CPARSE_SOURCES)
file (GLOB PREPROCESSOR_SOURCES ${SWIG_SOURCE_DIR}/Preprocessor/*.c)
file (GLOB CORE_SOURCES ${SWIG_SOURCE_DIR}/Swig/*.c)
file (GLOB DOXYGEN_SOURCES ${SWIG_SOURCE_DIR}/Doxygen/*.cxx)
file (GLOB MODULES_SOURCES ${SWIG_SOURCE_DIR}/Modules/*.cxx)
add_executable (swig
${CPARSE_SOURCES}
${DOH_SOURCES}
${DOXYGEN_SOURCES}
${MODULES_SOURCES}
${CORE_SOURCES}
${PREPROCESSOR_SOURCES}
${PROJECT_BINARY_DIR}/Source/Include/swigconfig.h
${SWIG_SOURCE_DIR}/Include/swigwarn.h
${PROJECT_BINARY_DIR}/Source/CParse/parser.c
${PROJECT_BINARY_DIR}/Source/CParse/parser.h
)
if (PCRE2_FOUND)
target_link_libraries (swig ${PCRE2_LIBRARIES})
endif ()
install (TARGETS swig DESTINATION bin)
# 'make package-source' creates tarballs
set (CPACK_PACKAGE_NAME ${PACKAGE_NAME})
set (CPACK_SOURCE_GENERATOR "TGZ;TBZ2")
set (CPACK_SOURCE_IGNORE_FILES "/.git;/build;.*~;${CPACK_SOURCE_IGNORE_FILES}")
set (CPACK_SOURCE_PACKAGE_FILE_NAME ${PACKAGE_NAME}-${PACKAGE_VERSION})
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")

24
Doc/Devel/internals.html
View file

@ -441,12 +441,12 @@ Resulting output:
<blockquote> <blockquote>
<pre> <pre>
hash len: 5 list len: 5
get: hashval2 get: listval2
hash item: hashval5 [h5] list item: newlistval1
hash item: hashval1 [h1] list item: listval2
hash item: hashval2 [h2] list item: listval3
hash item: hashval3 [h3] list item: listval5
</pre> </pre>
</blockquote> </blockquote>
@ -494,12 +494,12 @@ Resulting output:
<blockquote> <blockquote>
<pre> <pre>
list len: 5 hash len: 5
get: listval2 get: hashval2
list item: newlistval1 hash item: hashval5 [h5]
list item: listval2 hash item: hashval1 [h1]
list item: listval3 hash item: hashval2 [h2]
list item: listval5 hash item: hashval3 [h3]
</pre> </pre>
</blockquote> </blockquote>

6
Doc/Devel/plan-gsoc-2012.txt
View file

@ -45,7 +45,7 @@ Functionality
----------------- -----------------
Note: 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 the detailed description of Doxygen syntax and terms used in this
section. section.
@ -72,10 +72,10 @@ Functionality
---- ----
This section contains all doxygen tags taken from 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 marked as 'ignored', then the tag is ignored, but the text is copied
to the destination documentation. 'Not implemented' means that the 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: Doxygen tags:

2150
Doc/Manual/Allegrocl.html
View file

File diff suppressed because it is too large Load diff

39
Doc/Manual/CPlusPlus11.html
View file

@ -144,14 +144,39 @@ When either of these is used from a target language, a runtime call is made to o
<H3><a name="CPlusPlus11_extern_template">7.2.3 Extern template</a></H3> <H3><a name="CPlusPlus11_extern_template">7.2.3 Extern template</a></H3>
<p>SWIG correctly parses the keywords <tt>extern template</tt>. <p>SWIG correctly parses <tt>extern template</tt> 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. 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 <tt>%template</tt> for instantiating and wrapping templates.</p> SWIG only uses <tt>%template</tt> for instantiating and wrapping templates.
Consider the class template below:
</p>
<div class="code"><pre> <div class="code"><pre>
template class std::vector&lt;int&gt;; // C++03 explicit instantiation in C++ // Class template
extern template class std::vector&lt;int&gt;; // C++11 explicit instantiation suppression in C++ template class std::vector&lt;int&gt;; // C++03 template explicit instantiation definition in C++
%template(VectorInt) std::vector&lt;int&gt;; // SWIG instantiation extern template class std::vector&lt;int&gt;; // C++11 template explicit instantiation declaration (extern template)
%template(VectorInt) std::vector&lt;int&gt;; // SWIG template instantiation
</pre></div>
<p>
The above result in warnings:
</p>
<div class="shell">
<pre>
example.i:2: Warning 320: Explicit template instantiation ignored.
example.i:3: Warning 327: Extern template ignored.
</pre>
</div>
<p>
Similarly for the function template below:
</p>
<div class="code"><pre>
// Function template
template void Func&lt;int&gt;(); // C++03 template explicit instantiation definition in C++
extern template void Func&lt;int&gt;(); // C++11 template explicit instantiation declaration (extern template)
%template(FuncInt) Func&lt;int&gt;; // SWIG template instantiation
</pre></div> </pre></div>
<H3><a name="CPlusPlus11_initializer_lists">7.2.4 Initializer lists</a></H3> <H3><a name="CPlusPlus11_initializer_lists">7.2.4 Initializer lists</a></H3>
@ -336,6 +361,10 @@ int i; int j;
decltype(i+j) k; // syntax error decltype(i+j) k; // syntax error
</pre></div> </pre></div>
<p>SWIG does not support <tt>auto</tt> as a type specifier for variables, only
for specifying the return type of <a href="#CPlusPlus11_lambda_functions_and_expressions">lambdas</a>
and <a href="#CPlusPlus11_alternate_function_syntax">functions</a>.</p>
<H3><a name="CPlusPlus11_range_based_for_loop">7.2.7 Range-based for-loop</a></H3> <H3><a name="CPlusPlus11_range_based_for_loop">7.2.7 Range-based for-loop</a></H3>

1
Doc/Manual/CSharp.html
View file

@ -240,6 +240,7 @@ javabody -&gt; csbody
javafinalize -&gt; csfinalize javafinalize -&gt; csfinalize
javadestruct -&gt; csdisposing and csdispose javadestruct -&gt; csdisposing and csdispose
javadestruct_derived -&gt; csdisposing_derived and csdispose_derived javadestruct_derived -&gt; csdisposing_derived and csdispose_derived
javainterfacemodifiers -&gt; csinterfacemodifiers
javainterfacecode -&gt; csinterfacecode javainterfacecode -&gt; csinterfacecode
</pre></div> </pre></div>

597
Doc/Manual/Chicken.html
View file

@ -1,597 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Chicken</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Chicken">23 SWIG and Chicken</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Chicken_nn2">Preliminaries</a>
<ul>
<li><a href="#Chicken_nn3">Running SWIG in C mode</a>
<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a>
</ul>
<li><a href="#Chicken_nn5">Code Generation</a>
<ul>
<li><a href="#Chicken_nn6">Naming Conventions</a>
<li><a href="#Chicken_nn7">Modules</a>
<li><a href="#Chicken_nn8">Constants and Variables</a>
<li><a href="#Chicken_nn9">Functions</a>
<li><a href="#Chicken_nn10">Exceptions</a>
</ul>
<li><a href="#Chicken_nn11">TinyCLOS</a>
<li><a href="#Chicken_nn12">Linkage</a>
<ul>
<li><a href="#Chicken_nn13">Static binary or shared library linked at compile time</a>
<li><a href="#Chicken_nn14">Building chicken extension libraries</a>
<li><a href="#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a>
</ul>
<li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn17">Pointers</a>
<ul>
<li><a href="#Chicken_collection">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
<ul>
<li><a href="#Chicken_nn19">TinyCLOS problems with Chicken version &lt;= 1.92</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of CHICKEN. CHICKEN is a
Scheme-to-C compiler supporting most of the language features as
defined in the <i>Revised^5 Report on Scheme</i>. Its main
attributes are that it
</p>
<ol>
<li>generates portable C code</li>
<li>includes a customizable interpreter</li>
<li>links to C libraries with a simple Foreign Function Interface</li>
<li>supports full tail-recursion and first-class continuations</li>
</ol>
<p>
When confronted with a large C library, CHICKEN users can use
SWIG to generate CHICKEN wrappers for the C library. However,
the real advantages of using SWIG with CHICKEN are its
<strong>support for C++</strong> -- object-oriented code is
difficult to wrap by hand in CHICKEN -- and its <strong>typed
pointer representation</strong>, essential for C and C++
libraries involving structures or classes.
</p>
<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2>
<p>
CHICKEN support was introduced to SWIG in version 1.3.18. SWIG
relies on some recent additions to CHICKEN, which are only
present in releases of CHICKEN with version number
<strong>greater than or equal to 1.89</strong>.
To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a>
section below.
</p>
<p>
You may want to look at any of the examples in Examples/chicken/
directory for the basic steps to run SWIG CHICKEN.
</p>
<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3>
<p>
To run SWIG CHICKEN in C mode, use
the -chicken option.
</p>
<div class="shell">
<pre>% swig -chicken example.i</pre>
</div>
<p>
To allow the wrapper to take advantage of future CHICKEN code
generation improvements, part of the wrapper is direct CHICKEN
function calls (<tt>example_wrap.c</tt>) and part is CHICKEN
Scheme (<tt>example.scm</tt>). The basic Scheme code must
be compiled to C using your system's CHICKEN compiler or
both files can be compiled directly using the much simpler <tt>csc</tt>.
</p>
<div class="shell">
<pre>
% chicken example.scm -output-file oexample.c
</pre>
</div>
<p>
So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
<tt>oexample.c</tt> are the files that must be compiled to
object files and linked into your project.
</p>
<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3>
<p>
To run SWIG CHICKEN in C++ mode, use
the -chicken -c++ option.
</p>
<div class="shell">
<pre>% swig -chicken -c++ example.i</pre>
</div>
<p>
This will generate <tt>example_wrap.cxx</tt> and
<tt>example.scm</tt>. The basic Scheme code must be
compiled to C using your system's CHICKEN compiler or
both files can be compiled directly using the much simpler <tt>csc</tt>.
</p>
<div class="shell">
<pre>% chicken example.scm -output-file oexample.c</pre>
</div>
<p>
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
and <tt>oexample.c</tt> are the files that must be compiled to
object files and linked into your project.
</p>
<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2>
<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3>
<p>
Given a C variable, function or constant declaration named
<tt>Foo_Bar</tt>, the declaration will be available
in CHICKEN as an identifier ending with
<tt>Foo-Bar</tt>. That is, an underscore is converted
to a dash.
</p>
<p>
You may control what the CHICKEN identifier will be by using the
<tt>%rename</tt> SWIG directive in the SWIG interface file.
</p>
<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3>
<p>
The name of the module must be declared one of two ways:
<ul>
<li>Placing <tt>%module example</tt> in the SWIG interface
file.</li>
<li>Using <tt>-module example</tt> on the SWIG command
line.</li>
</ul>
<p>
The generated example.scm file then exports <code>(declare (unit modulename))</code>.
If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
the -nounit option to SWIG.
<p>
CHICKEN will be able to access the module using the <code>(declare
(uses <i>modulename</i>))</code> CHICKEN Scheme form.
</p>
<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3>
<p>
Constants may be created using any of the four constructs in
the interface file:
</p>
<ol>
<li><code>#define MYCONSTANT1 ...</code></li>
<li><code>%constant int MYCONSTANT2 = ...</code></li>
<li><code>const int MYCONSTANT3 = ...</code></li>
<li><code>enum { MYCONSTANT4 = ... };</code></li>
</ol>
<p>
In all cases, the constants may be accessed from within CHICKEN
using the form <tt>(MYCONSTANT1)</tt>; that is, the constants
may be accessed using the read-only parameter form.
</p>
<p>
Variables are accessed using the full parameter form.
For example, to set the C variable "int my_variable;", use the
Scheme form <tt>(my-variable 2345)</tt>. To get the C variable,
use <tt>(my-variable)</tt>.
</p>
<p>
The <tt>%feature("constasvar")</tt> can be applied to any constant
or immutable variable. Instead of exporting the constant as
a function that must be called, the constant will appear as a
scheme variable. This causes the generated .scm file to just contain the code
<tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.
</p>
<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3>
<p>
C functions declared in the SWIG interface file will have
corresponding CHICKEN Scheme procedures. For example, the C
function "int sqrt(double x);" will be available using the
Scheme form <tt>(sqrt 2345.0)</tt>. A <code>void</code> return
value will give C_SCHEME_UNDEFINED as a result.
</p>
<p>
A function may return more than one value by using the
<code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i).
They will be returned as multiple values using <code>(values)</code> if there is more than one
result (that is, a non-void return value and at least one argout
parameter, or a void return value and at least two argout
parameters). The return values can then be accessed with <code>(call-with-values)</code>.
</p>
<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3>
<p>The SWIG chicken module has support for exceptions thrown from
C or C++ code to be caught in scheme.
See <a href="Customization.html#Customization_exception">Exception handling with %exception</a>
for more information about declaring exceptions in the interface file.
</p>
<p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface
as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from
inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code
(as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>,
which can be handled by <code>(handle-exceptions)</code>. See
the Chicken manual on Exceptions
and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown
directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
</p>
<p>The following simple module</p>
<div class="code"><pre>
%module exception_test
%inline %{
void test_throw(int i) throws (int) {
if (i == 1) throw 15;
}
%}
</pre></div>
<p>could be run with</p>
<div class="targetlang"><pre>
(handle-exceptions exvar
(if (= exvar 15)
(print "Correct!")
(print "Threw something else " exvar))
(test-throw 1))
</pre></div>
<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2>
<p>
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
"Tiny CLOS is a Scheme implementation of a 'kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than
the simple CLOS found in 'The Art of the Metaobject Protocol',
weighing in at around 850 lines of code, including (some)
comments and documentation."
</p>
<p>
Almost all good Scheme books describe how to use metaobjects and
generic procedures to implement an object-oriented Scheme
system. Please consult a Scheme book if you are unfamiliar
with the concept.
</p>
<p>
CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN
uses if the -proxy argument is given. If -proxy is passed, then
the generated example.scm file will contain TinyCLOS class definitions.
A class named Foo is declared as &lt;Foo&gt;, and each member variable
is allocated a slot. Member functions are exported as generic functions.
<p>
Primitive symbols and functions (the interface that would be presented if
-proxy was not passed) are hidden and no longer accessible. If the -unhideprimitive
command line argument is passed to SWIG, then the primitive symbols will be
available, but each will be prefixed by the string "primitive:"
<p>
The exported symbol names can be controlled with the -closprefix and -useclassprefix arguments.
If -useclassprefix is passed to SWIG, every member function will be generated with the class name
as a prefix. If the -closprefix mymod: argument is passed to SWIG, then the exported functions will
be prefixed by the string "mymod:". If -useclassprefix is passed, -closprefix is ignored.
</p>
<H2><a name="Chicken_nn12">23.4 Linkage</a></H2>
<p>
Please refer to <em>CHICKEN - A practical and portable Scheme
system - User's manual</em> for detailed help on how to link
object files to create a CHICKEN Scheme program. Briefly, to
link object files, be sure to add <tt>`chicken-config
-extra-libs -libs`</tt> or <tt>`chicken-config -shared
-extra-libs -libs`</tt>to your linker options. Use the
<tt>-shared</tt> option if you want to create a dynamically
loadable module. You might also want to use the much simpler
<tt>csc</tt> or <tt>csc.bat</tt>.
</p>
<p>Each scheme file that is generated
by SWIG contains <code>(declare (uses <i>modname</i>))</code>. This means that to load the
module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>.
</p>
<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3>
<p>We can easily use csc to build a static binary.</p>
<div class="shell">
<pre>
$ swig -chicken example.i
$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
$ ./example
</pre>
</div>
<p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled
into a shared library, and then that shared library linked when compiling the
main application.</p>
<div class="shell">
<pre>
$ swig -chicken example.i
$ csc -sv example.scm example_wrap.c example_impl.c -o example.so
</pre>
</div>
<p>The <tt>example.so</tt> file can then linked with <tt>test_script.scm</tt> when it
is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>.
Multiple SWIG modules could have been linked into <tt>example.so</tt> and each
one accessed with a <code>(declare (uses ... ))</code>.
</p>
<div class="shell">
<pre>
$ csc -v test_script.scm -lexample
</pre>
</div>
<p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>,
in which case the test script does not need to be linked with example.so. The test_script.scm file can then
be run with <tt>csi</tt>.
</p>
<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3>
<p>Building a shared library like in the above section only works if the library
is linked at compile time with a script containing <code>(declare (uses ...))</code> or is
loaded explicitly with <code>(load-library 'example "example.so")</code>. It is
not the format that CHICKEN expects for extension libraries and eggs. The problem is the
<code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file. There are
two possible solutions to this.</p>
<p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code>
is not generated. Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into
their own shared library.</p>
<div class="shell">
<pre>
$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
</pre>
</div>
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
See the
Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p>
<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p>
<div class="targetlang">
<pre>
(declare (uses mod1))
(declare (uses mod2))
</pre>
</div>
<p>Which would then be compiled with</p>
<div class="shell">
<pre>
$ swig -chicken mod1.i
$ swig -chicken mod2.i
$ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
</pre>
</div>
<p>Then the extension library can be loaded with <code>(require 'mod)</code>. As we can see here,
<tt>mod_load.scm</tt> contains the code that gets executed when the module is loaded. All this code
does is load both mod1 and mod2. As we can see, this technique is more useful when you want to
combine a few SWIG modules into one chicken extension library, especially if modules are related by
<code>%import</code></p>
<p>In either method, the files that are compiled into the shared library could also be
packaged into an egg. The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> files that are created by SWIG
are stand alone and do not need SWIG to be installed to be compiled. Thus the egg could be
distributed and used by anyone, even if SWIG is not installed.</p>
<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
two eggs, one using the first method and one using the second method.</p>
<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3>
<p>Linking together multiple modules that share type information using the <code>%import</code>
directive while also using <tt>-proxy</tt> is more complicated. For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the
<tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>,
and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported
to the top of <tt>mod2.scm</tt>. By default, when SWIG encounters an <code>%import "modname.i"</code> directive,
it exports <code>(declare (uses <i>modname</i>))</code> into the scm file. This works fine unless mod1 was compiled with
the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p>
<p>One option is to override the automatic generation of <code>(declare (uses mod1))</code>
by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>.
SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive. Any scheme code inside that directive is inserted into the
generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>.
This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code>
(which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p>
<p>The other option is to use the second idea in the above section. Compile all the modules normally, without any
<code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>. Then the modules will import each other correctly
with <code>(declare (uses ...))</code>.
To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
all the modules.</p>
<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2>
<p>
The Chicken module handles all types via typemaps. This information is
read from <code>Lib/chicken/typemaps.i</code> and
<code>Lib/chicken/chicken.swg</code>.
</p>
<H2><a name="Chicken_nn17">23.6 Pointers</a></H2>
<p>
For pointer types, SWIG uses CHICKEN tagged pointers.
A tagged pointer is an ordinary CHICKEN pointer with an
extra slot for a void *. With SWIG
CHICKEN, this void * is a pointer to a type-info
structure. So each pointer used as input or output from
the SWIG-generated CHICKEN wrappers will have type
information attached to it. This will let the wrappers
correctly determine which method should be called
according to the object type hierarchy exposed in the SWIG
interface files.
</p>
<p>
To construct a Scheme object from a C pointer, the wrapper code
calls the function
<code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>,
The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared
<code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code>
It is ok to call <code>SWIG_NewPointerObj</code> more than once,
just make sure known_space has enough space for all the created pointers.
</p>
<p>
To get the pointer represented by a CHICKEN tagged pointer, the
wrapper code calls the function
<code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
passing a pointer to a struct representing the expected pointer
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3>
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
finalizer to the type which will call the destructor or delete method of
that type. The destructor and delete functions are no longer exported for
use in scheme code, instead SWIG and chicken manage pointers.
In situations where SWIG knows that a function is returning a type that should
be garbage collected, SWIG will automatically set the owner flag to 1. For other functions,
the <code>%newobject</code> directive must be specified for functions whose return values
should be garbage collected. See
<a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information.
</p>
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps),
any pointer that gets passed in will no longer be garbage collected.
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
get deleted while the scheme code still holds a pointer to it. Further use of this pointer
can lead to a crash.
</p>
<p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
does not work for chicken versions below 1.89. If you would like the SWIG generated code to work with
chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG. This will not export code
inside the _wrap.c file to register finalizers, and will then export destructor functions which
must be called manually.
</p>
<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2>
<ul>
<li>No director support.</li>
<li>No support for c++ standard types like std::vector.</li>
<li>The TinyCLOS wrappers for overloaded functions will not work correctly when using
<a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
</ul>
<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</a></H3>
<p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods
with different number of specializers: TinyCLOS assumes that every method added to a generic function
will have the same number of specializers. SWIG generates functions with different lengths of specializers
when C/C++ functions are overloaded. For example, the code</p>
<div class="code">
<pre>
class Foo {};
int foo(int a, Foo *b);
int foo(int a);
</pre></div>
<p>will produce scheme code</p>
<div class="targetlang">
<pre>
(define-method (foo (arg0 &lt;top&gt;) (arg1 &lt;Foo&gt;)) (<i>call primitive function</i>))
(define-method (foo (arg0 &lt;top&gt;)) (<i>call primitive function</i>))
</pre></div>
<p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one,
so calling <code>(foo 3 f)</code> will produce an error.</p>
<p>There are three solutions to this. The easist is to upgrade to the latest Chicken version. Otherwise, the
file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against
tinyclos.scm inside the 1.92 chicken source to add support into TinyCLOS for multi-argument generics. (This patch was accepted into Chicken)
This requires chicken to be rebuilt and custom install of chicken. An alternative is the <tt>Lib/chicken/multi-generic.scm</tt>
file in the SWIG source. This file can be loaded after TinyCLOS is loaded, and it will override some functions
inside TinyCLOS to correctly support multi-argument generics. Please see the comments at the top of both files for more information.</p>
</body>
</html>

18
Doc/Manual/Contents.html
View file

@ -91,16 +91,16 @@
</ul> </ul>
<li><a href="Windows.html#Windows_other_compilers">Instructions for using the Examples with other compilers</a> <li><a href="Windows.html#Windows_other_compilers">Instructions for using the Examples with other compilers</a>
</ul> </ul>
<li><a href="Windows.html#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</a>
<ul>
<li><a href="Windows.html#Windows_swig_exe">Building swig.exe on Windows</a> <li><a href="Windows.html#Windows_swig_exe">Building swig.exe on Windows</a>
<ul> <ul>
<li><a href="Windows.html#Windows_cmake">Building swig.exe using CMake</a>
<li><a href="Windows.html#Windows_msys2">Building swig.exe using MSYS2</a>
<li><a href="Windows.html#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a> <li><a href="Windows.html#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
<li><a href="Windows.html#Windows_cygwin">Building swig.exe using Cygwin</a> <li><a href="Windows.html#Windows_cygwin">Building swig.exe using Cygwin</a>
<li><a href="Windows.html#Windows_building_alternatives">Building swig.exe alternatives</a> <ul>
</ul>
<li><a href="Windows.html#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a> <li><a href="Windows.html#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul> </ul>
</ul>
<li><a href="Windows.html#Windows_interface_file">Microsoft extensions and other Windows quirks</a> <li><a href="Windows.html#Windows_interface_file">Microsoft extensions and other Windows quirks</a>
</ul> </ul>
</div> </div>
@ -171,6 +171,7 @@
<li><a href="SWIG.html#SWIG_rename_ignore">Renaming and ignoring declarations</a> <li><a href="SWIG.html#SWIG_rename_ignore">Renaming and ignoring declarations</a>
<ul> <ul>
<li><a href="SWIG.html#SWIG_nn29">Simple renaming of specific identifiers</a> <li><a href="SWIG.html#SWIG_nn29">Simple renaming of specific identifiers</a>
<li><a href="SWIG.html#SWIG_ignore">Ignoring identifiers</a>
<li><a href="SWIG.html#SWIG_advanced_renaming">Advanced renaming support</a> <li><a href="SWIG.html#SWIG_advanced_renaming">Advanced renaming support</a>
<li><a href="SWIG.html#SWIG_limiting_renaming">Limiting global renaming rules</a> <li><a href="SWIG.html#SWIG_limiting_renaming">Limiting global renaming rules</a>
<li><a href="SWIG.html#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a> <li><a href="SWIG.html#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a>
@ -250,6 +251,9 @@
</ul> </ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a> <li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a>
<li><a href="SWIGPlus.html#SWIGPlus_class_extension">Class extension</a> <li><a href="SWIGPlus.html#SWIGPlus_class_extension">Class extension</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_replacing_methods">Replacing class methods</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a> <li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a>
<ul> <ul>
<li><a href="SWIGPlus.html#SWIGPlus_template_directive">The %template directive</a> <li><a href="SWIGPlus.html#SWIGPlus_template_directive">The %template directive</a>
@ -445,6 +449,7 @@
<li><a href="Library.html#Library_nn16">Utility Libraries</a> <li><a href="Library.html#Library_nn16">Utility Libraries</a>
<ul> <ul>
<li><a href="Library.html#Library_nn17">exception.i</a> <li><a href="Library.html#Library_nn17">exception.i</a>
<li><a href="Library.html#Library_attributes">attribute.i</a>
</ul> </ul>
</ul> </ul>
</div> </div>
@ -1473,7 +1478,10 @@
</ul> </ul>
<li><a href="Python.html#Python_python3support">Python 3 Support</a> <li><a href="Python.html#Python_python3support">Python 3 Support</a>
<ul> <ul>
<li><a href="Python.html#Python_nn74">Function annotation</a> <li><a href="Python.html#Python_nn74">Function annotations</a>
<ul>
<li><a href="Python.html#Python_annotations_c">C/C++ annotation types</a>
</ul>
<li><a href="Python.html#Python_nn75">Buffer interface</a> <li><a href="Python.html#Python_nn75">Buffer interface</a>
<li><a href="Python.html#Python_nn76">Abstract base classes</a> <li><a href="Python.html#Python_nn76">Abstract base classes</a>
<li><a href="Python.html#Python_nn77">Byte string output conversion</a> <li><a href="Python.html#Python_nn77">Byte string output conversion</a>

4
Doc/Manual/Doxygen.html
View file

@ -181,7 +181,7 @@ or enum element comments:
<div class="code"><pre> <div class="code"><pre>
enum E_NUMBERS enum E_NUMBERS
{ {
EN_ZERO, ///&lt; The first enum item, gets zero as it's value EN_ZERO, ///&lt; The first enum item, gets zero as its value
EN_ONE, ///&lt; The second, EN_ONE=1 EN_ONE, ///&lt; The second, EN_ONE=1
EN_THREE EN_THREE
}; };
@ -1354,7 +1354,7 @@ Here is the list of all Doxygen tags and the description of how they are transla
</tr> </tr>
<tr> <tr>
<td>\throws</td> <td>\throws</td>
<td>replaced wih ':raises:'</td> <td>replaced with ':raises:'</td>
</tr> </tr>
<tr> <tr>
<td>\todo</td> <td>\todo</td>

17
Doc/Manual/Extending.html
View file

@ -1132,6 +1132,11 @@ DOH_REPLACE_FIRST - Replace first occurrence only.
Returns the number of replacements made (if any). Returns the number of replacements made (if any).
</p> </p>
<p>
At most one of <tt>DOH_REPLACE_ANY</tt> and <tt>DOH_REPLACE_FIRST</tt> should be specified.
<tt>DOH_REPLACE_ANY</tt> is the default if neither is specified.
</p>
</div> </div>
<H3><a name="Extending_nn16">40.5.2 Hashes</a></H3> <H3><a name="Extending_nn16">40.5.2 Hashes</a></H3>
@ -2986,7 +2991,7 @@ virtual int functionWrapper(Node *n) {
/* create the wrapper object */ /* create the wrapper object */
Wrapper *wrapper = NewWrapper(); Wrapper *wrapper = NewWrapper();
/* create the functions wrappered name */ /* create the wrapper function's name */
String *wname = Swig_name_wrapper(iname); String *wname = Swig_name_wrapper(iname);
/* deal with overloading */ /* deal with overloading */
@ -2995,7 +3000,7 @@ virtual int functionWrapper(Node *n) {
/* write the wrapper function definition */ /* write the wrapper function definition */
Printv(wrapper-&gt;def, "RETURN_TYPE ", wname, "(ARGS) {", NIL); Printv(wrapper-&gt;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 */ /* write the list of locals/arguments required */
@ -3613,7 +3618,7 @@ A target language is given the 'Supported' status when
Examples must be available and run successfully. Examples must be available and run successfully.
</li> </li>
<li> <li>
The examples and test-suite must be fully functioning on the Travis Continuous Integration platform. The examples and test-suite must be fully functioning on the Github Actions Continuous Integration platform.
</li> </li>
</ul> </ul>
@ -3660,9 +3665,9 @@ Some minimum requirements and notes about languages with the 'Experimental' stat
The number of tests in these lists should be no greater than half of the number of tests in the full test-suite. The number of tests in these lists should be no greater than half of the number of tests in the full test-suite.
</li> </li>
<li> <li>
The examples and test-suite must also be fully functioning on the Travis Continuous Integration platform. The examples and test-suite must also be fully functioning on the Github Actions Continuous Integration platform.
However, experimental languages will be set as 'allow_failures'. However, experimental languages will be flagged as 'continue-on-error'.
This means that pull requests and normal development commits will not break the entire Travis build should an experimental language fail. This means that pull requests and normal development commits will not break the entire Github Actions build should an experimental language fail.
</li> </li>
<li> <li>
Any new failed tests will be fixed on a 'best effort' basis by core developers with no promises made. Any new failed tests will be fixed on a 'best effort' basis by core developers with no promises made.

65
Doc/Manual/Go.html
View file

@ -71,6 +71,7 @@ code. SWIG fills this gap.
There are (at least) two different Go compilers. The first is the gc compiler There are (at least) two different Go compilers. The first is the gc compiler
of the <a href="https://golang.org/doc/install">Go distribution</a>, normally of the <a href="https://golang.org/doc/install">Go distribution</a>, normally
invoked via the <a href="https://golang.org/cmd/go/">go tool</a>. invoked via the <a href="https://golang.org/cmd/go/">go tool</a>.
SWIG supports the gc compiler version 1.2 or later.
The second Go compiler is the <a href="https://golang.org/doc/install/gccgo"> The second Go compiler is the <a href="https://golang.org/doc/install/gccgo">
gccgo compiler</a>, which is a frontend to the GCC compiler suite. gccgo compiler</a>, which is a frontend to the GCC compiler suite.
The interface to C/C++ code is completely different for the two Go compilers. The interface to C/C++ code is completely different for the two Go compilers.
@ -142,44 +143,6 @@ You will now have a Go package that you can import from other Go packages as
usual. usual.
</p> </p>
<p>
SWIG can be used without cgo, via the <tt>-no-cgo</tt> option, but
more steps are required. This only works with Go versions before 1.5.
When using Go version 1.2 or later, or when using gccgo, the code
generated by SWIG can be linked directly into the Go program. A
typical command sequence when using the Go compiler of the Go
distribution would look like this:
</p>
<div class="code"><pre>
% swig -go -no-cgo example.i
% gcc -c code.c # The C library being wrapped.
% gcc -c example_wrap.c
% go tool 6g example.go
% go tool 6c example_gc.c
% go tool pack grc example.a example.6 example_gc.6 code.o example_wrap.o
% go tool 6g main.go
% go tool 6l main.6
</pre></div>
<p>
You can also put the wrapped code into a shared library, and when using the Go
versions before 1.2 this is the only supported option. A typical command
sequence for this approach would look like this:
</p>
<div class="code"><pre>
% swig -go -no-cgo -use-shlib example.i
% gcc -c -fpic example.c
% gcc -c -fpic example_wrap.c
% gcc -shared example.o example_wrap.o -o example.so
% go tool 6g example.go
% go tool 6c example_gc.c
% go tool pack grc example.a example.6 example_gc.6
% go tool 6g main.go # your code, not generated by SWIG
% go tool 6l main.6
</pre></div>
<H3><a name="Go_commandline">25.3.1 Go-specific Commandline Options</a></H3> <H3><a name="Go_commandline">25.3.1 Go-specific Commandline Options</a></H3>
@ -206,9 +169,7 @@ swig -go -help
<tr> <tr>
<td>-no-cgo</td> <td>-no-cgo</td>
<td>Generate files that can be used directly, rather than via the Go <td>This option is no longer supported.</td>
cgo tool. This option does not work with Go 1.5 or later. It is
required for versions of Go before 1.2.</td>
</tr> </tr>
<tr> <tr>
@ -279,13 +240,10 @@ swig -go -help
<H3><a name="Go_outputs">25.3.2 Generated Wrapper Files</a></H3> <H3><a name="Go_outputs">25.3.2 Generated Wrapper Files</a></H3>
<p>There are two different approaches to generating wrapper files, <p>
controlled by SWIG's <tt>-no-cgo</tt> option. The <tt>-no-cgo</tt> SWIG will generate the following files when generating wrapper
option only works with version of Go before 1.5. It is required code:
when using versions of Go before 1.2.</p> </p>
<p>With or without the <tt>-no-cgo</tt> option, SWIG will generate the
following files when generating wrapper code:</p>
<ul> <ul>
<li> <li>
@ -308,17 +266,6 @@ or C++ compiler.
</li> </li>
</ul> </ul>
<p>When the <tt>-no-cgo</tt> option is used, and the <tt>-gccgo</tt>
option is not used, SWIG will also generate an additional file:</p>
<ul>
<li>
MODULE_gc.c will contain C code which should be compiled with the C
compiler distributed as part of the gc compiler. It should then be
combined with the compiled MODULE.go using go tool pack.
</li>
</ul>
<H2><a name="Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a></H2> <H2><a name="Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a></H2>

2
Doc/Manual/Guile.html
View file

@ -183,7 +183,7 @@ information by including a directive like this in the interface file:
</div> </div>
<p> <p>
(The <code>%scheme</code> directive allows to insert arbitrary Scheme (The <code>%scheme</code> directive allows inserting arbitrary Scheme
code into the generated file <code><var>module.scm</var></code>; it is code into the generated file <code><var>module.scm</var></code>; it is
placed between the <code>define-module</code> form and the placed between the <code>define-module</code> form and the
<code>export</code> form.) <code>export</code> form.)

24
Doc/Manual/Java.html
View file

@ -644,7 +644,7 @@ java::
<p> <p>
To build the DLL and compile the java code, run NMAKE (you may need to run <tt>vcvars32</tt> first). To build the DLL and compile the java code, run NMAKE (you may need to run <tt>vcvars32</tt> 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. 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.
</p> </p>
@ -4030,7 +4030,7 @@ repetitive duplication of the <code>director:except</code> feature code
for each director method. for each director method.
To mitigate this, a second approach is provided via typemaps in a To mitigate this, a second approach is provided via typemaps in a
fashion analogous to fashion analogous to
the <a href="Typemaps.html#throws_typemap">"throws" typemap</a>. the <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a>.
The "throws" typemap provides a way to map all the C++ The "throws" typemap provides a way to map all the C++
exceptions listed in a method's defined exceptions (either from exceptions listed in a method's defined exceptions (either from
a C++ <em>exception specification</em> or a <code>%catches</code> a C++ <em>exception specification</em> or a <code>%catches</code>
@ -4081,7 +4081,7 @@ has the <code>$directorthrowshandlers</code> special variable replaced with the
the relevant "directorthrows" typemaps, for each and every exception defined for the method. the relevant "directorthrows" typemaps, for each and every exception defined for the method.
The relevant exceptions can be defined either with a C++ exception The relevant exceptions can be defined either with a C++ exception
specification or <code>%catches</code> as described for the specification or <code>%catches</code> as described for the
<a href="Typemaps.html#throws_typemap">"throws" typemap</a>. <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a>.
</p> </p>
<p> <p>
@ -6610,6 +6610,15 @@ Below shows an example modifying the finalizer, assuming the <tt>delete</tt> met
</div> </div>
<p><tt>%typemap(javainterfacemodifiers)</tt></p>
<div class="indent">
Interface modifiers for the Java interface generated when using the <tt>interface</tt> feature, see <a href="Java.html#Java_interfaces">Java interfaces</a> section. The default is "public interface".
<p>
<b>Compatibility note:</b> This typemap was added in SWIG-4.1.0.
</p>
</div>
<p><tt>%typemap(javainterfacecode, declaration="...", cptrmethod="...")</tt></p> <p><tt>%typemap(javainterfacecode, declaration="...", cptrmethod="...")</tt></p>
<div class="indent"> <div class="indent">
<p> <p>
@ -6709,7 +6718,7 @@ The "javaimports" typemap is ignored if the enum class is wrapped by an inner Ja
<div class="code"> <div class="code">
<pre> <pre>
[ javaimports typemap ] [ javaimports typemap ]
public interface [ javainterfacename ] { [ javainterfacemodifiers typemap ] [ javainterfacename ] {
[ javainterfacecode:cptrmethod typemap attribute ] [ javainterfacecode:cptrmethod typemap attribute ]
... interface declarations ... ... interface declarations ...
} }
@ -9053,6 +9062,11 @@ You may have to add in some "jtype", "jstype", "javain" and "javaout" typemaps w
Here the default typemaps work for <tt>int</tt> and <tt>char *</tt>. Here the default typemaps work for <tt>int</tt> and <tt>char *</tt>.
</p> </p>
<p>
Note that if you're wanting to effectively <b>replace</b> the JNI code generated for a C/C++ function then you'll need to use <tt>%ignore</tt> as well
to tell SWIG not to automatically generate a JNI wrapper for it.
</p>
<p> <p>
In summary the <tt>%native</tt> directive is telling SWIG to generate the Java code to access the JNI C code, but not the JNI C function itself. In summary the <tt>%native</tt> 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. 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.
@ -9086,7 +9100,7 @@ This method normally calls the C++ destructor or <tt>free()</tt> for C code.
<p> <p>
The generated code can be debugged using both a Java debugger and a C++ debugger using the usual debugging techniques. The generated code can be debugged using both a Java debugger and a C++ debugger using the usual debugging techniques.
Breakpoints can be set in either Java or C++ code and so both can be debugged simultaneously. Breakpoints can be set in either Java or C++ code and so both can be debugged simultaneously.
Most debuggers do not understand both Java and C++, with one noteable exception of Sun Studio, Most debuggers do not understand both Java and C++, with one notable exception of Sun Studio,
where it is possible to step from Java code into a JNI method within one environment. where it is possible to step from Java code into a JNI method within one environment.
</p> </p>

19
Doc/Manual/Javascript.html
View file

@ -89,19 +89,10 @@ $ swig -javascript -jsc example.i</pre>
<pre> <pre>
$ swig -c++ -javascript -jsc example.i</pre> $ swig -c++ -javascript -jsc example.i</pre>
</div> </div>
<p>The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later.</p> <p>The V8 code that SWIG generates requires at least V8 5.0. Keep in mind
<p>The API headers for V8 &gt;= 4.3.0 define constants which SWIG can use to that this is theV8 version, not Node.js. To give some perspective, Node.js v6.0
determine the V8 version it is compiling for. For versions &lt; 4.3.0, you uses V8 5.0, v12.0 - 7.4, v14.0 - 8.1...</p>
need to specify the V8 version when running SWIG. This is specified as a hex <p>To generate code for V8, you would run swig like so:</p>
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 &gt; 99,
but this constant is only useful for V8 &lt; 4.3.0, and no V8 versions from
that era had a component &gt; 99. For example:</p>
<div class="shell">
<pre>
$ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre>
</div>
<p>If you're targeting V8 &gt;= 4.3.0, you would just run swig like so:</p>
<div class="shell"> <div class="shell">
<pre> <pre>
$ swig -c++ -javascript -v8 example.i</pre> $ swig -c++ -javascript -v8 example.i</pre>
@ -401,7 +392,7 @@ the main window.</p>
<p> <p>
As known from <code>node.js</code> one can use <code>require</code> to load javascript modules. As known from <code>node.js</code> one can use <code>require</code> to load javascript modules.
Additionally, <code>node-webkit</code> provides an API that allows to manipulate the window's menu, Additionally, <code>node-webkit</code> provides an API that allows manipulating the window's menu,
open new windows, and many more things. open new windows, and many more things.
</p> </p>

220
Doc/Manual/Library.html
View file

@ -44,6 +44,7 @@
<li><a href="#Library_nn16">Utility Libraries</a> <li><a href="#Library_nn16">Utility Libraries</a>
<ul> <ul>
<li><a href="#Library_nn17">exception.i</a> <li><a href="#Library_nn17">exception.i</a>
<li><a href="#Library_attributes">attribute.i</a>
</ul> </ul>
</ul> </ul>
</div> </div>
@ -2108,5 +2109,224 @@ For example:
</div> </div>
<H3><a name="Library_attributes">12.5.2 attribute.i</a></H3>
<p>
The attribute library contains a set of macros to convert a pair of set/get methods
into a "native" attribute/property.
</p>
<p>
Use <tt>%attribute</tt> when you have a pair of get/set methods to a
primitive type like:
</p>
<div class="code">
<pre>
%include "attribute.i"
%attribute(A, int, a, get_a, set_a);
struct A {
int get_a() const;
void set_a(int aa);
};
</pre>
</div>
<p>
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):
</p>
<div class="targetlang">
<pre>
x = A()
x.a = 3 # calls A::set_a(3)
print(x.a) # calls A::get_a() const
</pre>
</div>
<p>
If you don't provide a 'set' method, a 'read-only' attribute
is generated, ie, like:
</p>
<div class="code">
<pre>
%attribute(A, int, c, get_c);
</pre>
</div>
<p>
Use <tt>%attributeref</tt> when you have const/non-const reference
access methods for primitive types or class/structs, like:
</p>
<div class="code">
<pre>
%attributeref(A, int, b);
struct A {
const int &amp; b() const;
int &amp; b();
};
%attributeref(B, int, c);
struct B {
int &amp; c();
};
</pre>
</div>
<p>
Use the attributes like so (in Python):
</p>
<div class="targetlang">
<pre>
x = A()
x.b = 3 # calls A::b()
print(x.b) # calls A::b() const
</pre>
</div>
<p>
You can also use
</p>
<div class="code">
<pre>
%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
</pre>
</div>
<p>
if the internal C++ reference methods have a different name from the
attribute you want, so
</p>
<div class="code">
<pre>
%attributeref(B, int, d, c);
</pre>
</div>
<p>
is the same as the last example, but instead of the attribute 'c' being
called 'c', it is called 'd'.
</p>
<p>
Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> to indicate
that reference-pointer translation is required.
Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
this:
</p>
<div class="code">
<pre>
%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
%inline %{
struct MyFoo {
int x;
};
class MyClass {
MyFoo foo;
public:
MyFoo &amp; GetFoo() { return foo; }
void SetFoo(const MyFoo &amp;other) { foo = other; }
};
%}
</pre>
</div>
<p>
Here, the data type of the property is a wrapped type <tt>MyFoo</tt> 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 &amp;). Therefore, if you
use <tt>%attribute</tt>, you'll get an error from your C/C++
compiler. <tt>%attribute2</tt> translates between a pointer and a
reference to eliminate the error. In case you're confused, let's make
it simple: just use <tt>%attribute</tt> at first, but if the C/C++
compiler gives an error while compiling the wrapper,
try <tt>%attribute2</tt> instead.
</p>
<p>
NOTE: remember that if the type contains commas, such as
<tt>std::pair&lt;int, int&gt;</tt>, you need to use the macro like:
</p>
<div class="code">
<pre>
%attributeref(A, %arg(std::pair&lt;int, int&gt;), pval);
</pre>
</div>
<p>
where <tt>%arg()</tt> 'normalizes' the type to be understood as a single
argument, otherwise the macro will get confused by the comma.
</p>
<p>
The <tt>%attributeval</tt> is the same as <tt>%attribute</tt>, 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.
</p>
<div class="code">
<pre>
%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; }
};
%}
</pre>
</div>
<p>
The <tt>%attributestring</tt> is the same as <tt>%attributeval</tt>,
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 <tt>std::string</tt>:
</p>
<div class="code">
<pre>
%include &lt;std_string.i&gt;
%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
%inline %{
class MyStringyClass {
std::string str;
public:
MyStringyClass(const std::string &amp;val) : str(val) {}
std::string GetString() { return str; }
void SetString(std::string other) { str = other; }
};
%}
</pre>
</div>
<p>
The <tt>%attributestring</tt> also works for class types that
have <tt>%naturalvar</tt> turned on and so is also useful for
shared_ptr which has <tt>%naturalvar</tt> turned on in
<tt>%shared_ptr</tt>.
</p>
</body> </body>
</html> </html>

8
Doc/Manual/Lua.html
View file

@ -1520,7 +1520,7 @@ function
nil nil
&gt; &gt;
</pre></div> </pre></div>
<p> 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 <p> 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. then its bases are searched for it. Option -squash-bases will effectively return old behaviour.
</p> </p>
@ -1638,7 +1638,7 @@ More details can be found in the <a href="Library.html#Library_carrays">carrays.
<div class="code"><pre>// using the C-array <div class="code"><pre>// using the C-array
%include &lt;carrays.i&gt; %include &lt;carrays.i&gt;
// 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) %array_functions(int, int)
extern void sort_int(int* arr, int len); // the function to wrap 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 &amp; 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. In theory, you can play with this usertable &amp; 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.
</p> </p>
<p> <p>
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.
</p> </p>
<p> <p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__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' &amp; '__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.
</p> </p>
<H3><a name="Lua_nn38">29.7.3 Memory management</a></H3> <H3><a name="Lua_nn38">29.7.3 Memory management</a></H3>

942
Doc/Manual/Modula3.html
View file

@ -1,942 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Modula-3</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3">31 SWIG and Modula-3</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="#Modula3_motivation">Motivation</a>
</ul>
<li><a href="#Modula3_conception">Conception</a>
<ul>
<li><a href="#Modula3_cinterface">Interfaces to C libraries</a>
<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a>
</ul>
<li><a href="#Modula3_preliminaries">Preliminaries</a>
<ul>
<li><a href="#Modula3_compilers">Compilers</a>
<li><a href="#Modula3_commandline">Additional Commandline Options</a>
</ul>
<li><a href="#Modula3_typemaps">Modula-3 typemaps</a>
<ul>
<li><a href="#Modula3_inoutparam">Inputs and outputs</a>
<li><a href="#Modula3_ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#Modula3_class">Objects</a>
<li><a href="#Modula3_imports">Imports</a>
<li><a href="#Modula3_exceptions">Exceptions</a>
<li><a href="#Modula3_typemap_example">Example</a>
</ul>
<li><a href="#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="#Modula3_features">Features</a>
<li><a href="#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support for
<a href="http://modula3.org/">Modula-3</a>.
You should be familiar with the
<a href="SWIG.html#SWIG">basics</a>
of SWIG,
especially
<a href="Typemaps.html#Typemaps">typemaps</a>.
</p>
<H2><a name="Modula3_modula3_overview">31.1 Overview</a></H2>
<p>
Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor to Pascal.
</p>
<p>
SWIG's Modula-3 support is currently very basic and highly experimental!
Many features are still not designed satisfyingly
and I need more discussion about the odds and ends.
Don't rely on any feature, incompatible changes are likely in the future!
However, the Modula-3 generator was already useful for interfacing
to the libraries:
</p>
<ol>
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/">
PLPlot
</a>
</li>
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
FFTW
</a>
</li>
</ol>
<H3><a name="Modula3_motivation">31.1.1 Motivation</a></H3>
<p>
Although it is possible to write Modula-3 code that performs as well as C/C++
most existing libraries are not written in Modula-3 but in C or C++, and
even libraries in other languages may provide C header files.
</p>
<p>
Fortunately Modula-3 can call C functions, but you have to write Modula-3
interfaces to them, and to make things comfortable you will also need
wrappers that convert between high-level features of Modula-3 (garbage
collecting, exceptions) and the explicit tracking of allocated memory and
exception codes used by C APIs.
</p>
<p>
SWIG converts C headers to Modula-3 interfaces for you, and using typemaps
you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes
into exceptions.
</p>
<p>
If the library API is ill designed
writing appropriate typemaps can still be time-consuming.
E.g. C programmers are very creative to work-around
missing data types like (real) enumerations and sets.
You should turn such work-arounds back to the Modula-3 way
otherwise you lose static safety and consistency.
</p>
<p>
Without SWIG you would probably never consider trying to call C++ libraries
from Modula-3, but with SWIG this is becomes feasible.
SWIG can generate C wrappers to C++ functions and object methods
that may throw exceptions, and then wrap these C wrappers for Modula-3.
To make it complete you can then hide the C interface with Modula-3 classes and
exceptions.
</p>
<p>
SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
functions), but it doesn't allow you to easily integrate a Modula-3 module into
a C/C++ project.
</p>
<H2><a name="Modula3_conception">31.2 Conception</a></H2>
<H3><a name="Modula3_cinterface">31.2.1 Interfaces to C libraries</a></H3>
<p>
Modula-3 has integrated support for calling C functions.
This is also extensively used by the standard Modula-3 libraries
to call OS functions.
The Modula-3 part of SWIG and the corresponding SWIG library
modula3.swg
contain code that uses these features.
Because of the built-in support there is no need
for calling the SWIG kernel to generate wrappers written in C.
All conversion and argument checking can be done in Modula-3
and the interfacing is quite efficient.
All you have to do is to write pieces of Modula-3 code
that SWIG puts together.
</p>
<table border summary="Modula-3 C library support">
<tr><th colspan=2>C library support integrated in Modula-3<th></tr>
<tr>
<td>Pragma <tt>&lt;* EXTERNAL *&gt;</tt></td>
<td>Precedes a declaration of a PROCEDURE that is implemented
in an external library instead of a Modula-3 module.</td>
</tr>
<tr>
<td>Pragma <tt>&lt;* CALLBACK *&gt;</tt></td>
<td>Precedes a declaration of a PROCEDURE that should be called
by external library code.</td>
</tr>
<tr>
<td>Module <tt>Ctypes</tt></td>
<td>Contains Modula-3 types that match some basic C types.</td>
</tr>
<tr>
<td>Module <tt>M3toC</tt></td>
<td>Contains routines that convert between Modula-3's <tt>TEXT</tt> type
and C's <tt>char *</tt> type.</td>
</tr>
</table>
<p>
In each run of SWIG the Modula-3 part
generates several files:
</p>
<table border summary="Modula-3 generated files">
<tr>
<th>Module name scheme</th>
<th>Identifier for <tt>%insert</tt></th>
<th>Description</th>
</tr>
<tr>
<td>Module<tt>Raw.i3</tt></td>
<td><tt>m3rawintf</tt></td>
<td>Declaration of types that are equivalent to those of the C library,
<tt>EXTERNAL</tt> procedures as interface to the C library functions</td>
</tr>
<tr>
<td>Module<tt>Raw.m3</tt></td>
<td><tt>m3rawimpl</tt></td>
<td>Almost empty.</td>
</tr>
<tr>
<td>Module<tt>.i3</tt></td>
<td><tt>m3wrapintf</tt></td>
<td>Declaration of comfortable wrappers to the C library functions.</td>
</tr>
<tr>
<td>Module<tt>.m3</tt></td>
<td><tt>m3wrapimpl</tt></td>
<td>Implementation of the wrappers that
convert between Modula-3 and C types,
check for validity of values,
hand-over resource management to the garbage collector using <tt>WeakRef</tt>s
and raises exceptions.</td>
</tr>
<tr>
<td><tt>m3makefile</tt></td>
<td><tt>m3makefile</tt></td>
<td>Add the modules above to the Modula-3 project and
specify the name of the Modula-3 wrapper library
to be generated.
Today I'm not sure if it is a good idea
to create a <tt>m3makefile</tt> in each run,
because SWIG must be started for each Modula-3 module it creates.
Thus the m3makefile is overwritten each time. :-(
</td>
</tr>
</table>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions:
</p>
<table summary="Modula-3 C library">
<tr>
<td align=center>
Modula-3 wrapper<br>
Module<tt>.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td></td>
<td align=center></td>
</tr>
<tr>
<td align=center>
<!-- pre tag overrides centering -->
|<br>
v
</td>
<td></td>
<td align=center></td>
</tr>
<tr>
<td align=center>
Modula-3 interface to C<br>
Module<tt>Raw.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td>--&gt;</td>
<td align=center>
C library
</td>
</tr>
</table>
<p>
I have still no good conception how one can split C library interfaces
into type oriented interfaces.
A Module in Modula-3 represents an Abstract DataType
(or call it a static classes, i.e. a class without virtual methods).
E.g. if you have a principal type, say <tt>Database</tt>,
it is good Modula-3 style to set up one Module with the name <tt>Database</tt>
where the database type is declared with the name <tt>T</tt>
and where all functions are declared that operates on it.
</p>
<p>
The normal operation of SWIG is to generate a fixed set of files per call.
To generate multiple modules one has to write one SWIG interface
(different SWIG interfaces can share common data) per module.
Identifiers belonging to a different module may ignored (<tt>%ignore</tt>)
and the principal type must be renamed (<tt>%typemap</tt>).
</p>
<H3><a name="Modula3_cppinterface">31.2.2 Interfaces to C++ libraries</a></H3>
<p>
Interfaces to C++ files are much more complicated and
there are some more design decisions that are not made, yet.
Modula-3 has no support for C++ functions
but C++ compilers should support generating C++ functions
with a C interface.
</p>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
<tr>
<td align=center>
Modula-3 wrapper<br>
Module<tt>.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td></td>
<td align=center>C++ library</td>
</tr>
<tr>
<td align=center>
<!-- pre tag overrides centering -->
|<br>
v
</td>
<td></td>
<td align=center>
^<br>
|
</td>
</tr>
<tr>
<td align=center>
Modula-3 interface to C<br>
Module<tt>Raw.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td>--&gt;</td>
<td align=center>
C interface to C++<br>
module<tt>_wrap.cxx</tt><br>
generated by the SWIG core
</td>
</tr>
</table>
<p>
Wrapping C++ libraries arises additional problems:
</p>
<ul>
<li>
Is it sensible to wrap C++ classes with Modula-3 classes?
</li>
<li>
How to find the wrapping Modula-3 class
for a class pointer that is returned by a C++ routine?
</li>
<li>
How to deal with multiple inheritance
which was neglected for Modula-3 for good reasons?
</li>
<li>
Is it possible to sub-class C++ classes with Modula-3 code?
This issue is addressed by directors,
a feature that was experimentally added to some Language modules
like
<a href="Java.html#Java_directors">Java</a> and
<a href="Python.html#Python_directors">Python</a>.
</li>
<li>
How to manage storage with the garbage collector of Modula-3?
Support for
<a href="Customization.html#Customization_ownership">
<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a>
isn't implemented, yet.
What's about resources that are managed by the garbage collector
but shall be passed back to the storage management of the C++ library?
This is a general issue which is not solved in a satisfying fashion
as far as I know.
</li>
<li>
How to turn C++ exceptions into Modula-3 exceptions?
There's also no support for
<a href="Customization.html#Customization_exception">
<tt>%exception</tt></a>, yet.
</li>
</ul>
<p>
Be warned:
There is no C++ library I wrote a SWIG interface for,
so I'm not sure if this is possible or sensible, yet.
</p>
<H2><a name="Modula3_preliminaries">31.3 Preliminaries</a></H2>
<H3><a name="Modula3_compilers">31.3.1 Compilers</a></H3>
<p>
There are different Modula-3 compilers around:
cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
SWIG itself does not contain compiler specific code
but the modula3.swg library file
may do so.
For testing examples I use Critical Mass cm3.
</p>
<H3><a name="Modula3_commandline">31.3.2 Additional Commandline Options</a></H3>
<p>
There are some experimental command line options
that prevent SWIG from generating interface files.
Instead files are emitted that may assist you
when writing SWIG interface files.
</p>
<table border summary="Modula-3 specific options">
<tr>
<th>Modula-3 specific options</th>
<th>Description</th>
</tr>
<tr>
<td valign=top>-generateconst &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead write code for computing numeric values of constants
to the specified file.
<br>
C code may contain several constant definitions
written as preprocessor macros.
Other language modules of SWIG use
compute-once-use-readonly variables or
functions to wrap such definitions.
All of them can invoke C code dynamically
for computing the macro values.
But if one wants to turn them into Modula-3
integer constants, enumerations or set types,
the values of these expressions has to be known statically.
Although definitions like <tt>(1 &lt;&lt; FLAG_MAXIMIZEWINDOW)</tt>
must be considered as good C style
they are hard to convert to Modula-3
since the value computation can use every feature of C.
<br>
Thus I implemented these switch
to extract all constant definitions
and write a C program that output the values of them.
It works for numeric constants only
and treats all of them as <tt>double</tt>.
Future versions may generate a C++ program
that can detect the type of the macros
by overloaded output functions.
Then strings can also be processed.
</td>
</tr>
<tr>
<td valign=top>-generaterename &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate suggestions for <tt>%rename</tt>.
<br>
C libraries use a naming style
that is neither homogeneous nor similar to that of Modula-3.
C function names often contain a prefix denoting the library
and some name components separated by underscores
or capitalization changes.
To get library interfaces that are really Modula-3 like
you should rename the function names with the <tt>%rename</tt> directive.
This switch outputs a list of such directives
with a name suggestion generated by a simple heuristic.
</td>
</tr>
<tr>
<td valign=top>-generatetypemap &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate templates for some basic typemaps.
</td>
</tr>
</table>
<H2><a name="Modula3_typemaps">31.4 Modula-3 typemaps</a></H2>
<H3><a name="Modula3_inoutparam">31.4.1 Inputs and outputs</a></H3>
<p>
Each C procedure has a bunch of inputs and outputs.
Inputs are passed as function arguments,
outputs are updated referential arguments and
the function value.
</p>
<p>
Each C type can have several typemaps
that apply only in case if a type is used
for an input argument, for an output argument,
or for a return value.
A further typemap may specify
the direction that is used for certain parameters.
I have chosen this separation
in order to be able to write general typemaps for the modula3.swg typemap library.
In the library code the final usage of the type is not known.
Using separate typemaps for each possible use
allows appropriate definitions for each case.
If these pre-definitions are fine
then the direction of the function parameter
is the only hint the user must give.
</p>
<p>
The typemaps specific to Modula-3 have a common name scheme:
A typemap name starts with "m3",
followed by "raw" or "wrap"
depending on whether it controls the generation
of the Module<tt>Raw.i3</tt> or the Module<tt>.i3</tt>, respectively.
It follows an "in" for typemaps applied to input argument,
"out" for output arguments, "arg" for all kind of arguments,
"ret" for returned values.
</p>
<p>
The main task of SWIG is to build wrapper function,
i.e. functions that convert values between C and Modula-3
and call the corresponding C function.
Modula-3 wrapper functions generated by SWIG
consist of the following parts:
</p>
<ul>
<li>Generate <tt>PROCEDURE</tt> signature.</li>
<li>Declare local variables.</li>
<li>Convert input values from Modula-3 to C.</li>
<li>Check for input value integrity.</li>
<li>Call the C function.</li>
<li>Check returned values, e.g. error codes.</li>
<li>Convert and write back values into Modula-3 records.</li>
<li>Free temporary storage.</li>
<li>Return values.</li>
</ul>
<table border summary="Modula-3 typemaps">
<tr>
<th>Typemap</th>
<th>Example</th>
<th>Description</th>
</tr>
<tr>
<td>m3wrapargvar</td>
<td><tt>$1: INTEGER := $1_name;</tt></td>
<td>
Declaration of some variables needed for temporary results.
</td>
</tr>
<tr>
<td>m3wrapargconst</td>
<td><tt>$1 = "$1_name";</tt></td>
<td>
Declaration of some constant, maybe for debug purposes.
</td>
</tr>
<tr>
<td>m3wrapargraw</td>
<td><tt>ORD($1_name)</tt></td>
<td>
The expression that should be passed as argument to the raw Modula-3 interface function.
</td>
</tr>
<tr>
<td>m3wrapargdir</td>
<td><tt>out</tt></td>
<td>
Referential arguments can be used for input, output, update.
???
</td>
</tr>
<tr>
<td>m3wrapinmode</td>
<td><tt>READONLY</tt></td>
<td>
One of Modula-3 parameter modes
<tt>VALUE</tt> (or empty),
<tt>VAR</tt>,
<tt>READONLY</tt>
</td>
</tr>
<tr>
<td>m3wrapinname</td>
<td></td>
<td>
New name of the input argument.
</td>
</tr>
<tr>
<td>m3wrapintype</td>
<td></td>
<td>
Modula-3 type of the input argument.
</td>
</tr>
<tr>
<td>m3wrapindefault</td>
<td></td>
<td>
Default value of the input argument
</td>
</tr>
<tr>
<td>m3wrapinconv</td>
<td><tt>$1 := M3toC.SharedTtoS($1_name);</tt></td>
<td>
Statement for converting the Modula-3 input value to C compliant value.
</td>
</tr>
<tr>
<td>m3wrapincheck</td>
<td><tt>IF Text.Length($1_name) &gt; 10 THEN RAISE E("str too long"); END;</tt></td>
<td>
Check the integrity of the input value.
</td>
</tr>
<tr>
<td>m3wrapoutname</td>
<td></td>
<td>
Name of the <tt>RECORD</tt> field to be used for returning multiple values.
This applies to referential output arguments that shall be turned
into return values.
</td>
</tr>
<tr>
<td>m3wrapouttype</td>
<td></td>
<td>
Type of the value that is returned instead of a referential output argument.
</td>
</tr>
<tr>
<td>m3wrapoutconv</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapoutcheck</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretraw</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretname</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wraprettype</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretvar</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretconv</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretcheck</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapfreearg</td>
<td><tt>M3toC.FreeSharedS(str, arg1);</tt></td>
<td>
Free resources that were temporarily used in the wrapper.
Since this step should never be skipped,
SWIG will put it in the <tt>FINALLY</tt> branch
of a <tt>TRY .. FINALLY</tt> structure.
</td>
</tr>
</table>
<H3><a name="Modula3_ordinals">31.4.2 Subranges, Enumerations, Sets</a></H3>
<p>
Subranges, enumerations, and sets are machine oriented types
that make Modula very strong and expressive compared
with the type systems of many other languages.
</p>
<ul>
<li>
Subranges are used for statically restricted choices of integers.
</li>
<li>
Enumerations are used for named choices.
</li>
<li>
Sets are commonly used for flag (option) sets.
</li>
</ul>
<p>
Using them extensively makes Modula code very safe and readable.
</p>
<p>
C supports enumerations, too, but they are not as safe as the ones of Modula.
Thus they are abused for many things:
For named choices, for integer constant definitions, for sets.
To make it complete every way of defining a value in C
(<tt>#define</tt>, <tt>const int</tt>, <tt>enum</tt>)
is somewhere used for defining something
that must be handled completely different in Modula-3
(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>).
</p>
<p>
I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s
that split the task up into converting
the C bit patterns (integer or bit set)
into Modula-3 bit patterns (integer or bit set)
and change the type as requested.
See the corresponding example in the
Examples/modula3/enum/example.i file.
This is quite messy and not satisfying.
So the best what you can currently do is
to rewrite constant definitions manually.
Though this is a tedious work
that I'd like to automate.
</p>
<H3><a name="Modula3_class">31.4.3 Objects</a></H3>
<p>
Declarations of C++ classes are mapped to <tt>OBJECT</tt> types
while it is tried to retain the access hierarchy
"public - protected - private" using partial revelation.
Though the example in
Examples/modula3/class/example.i
is not really useful, yet.
</p>
<H3><a name="Modula3_imports">31.4.4 Imports</a></H3>
<p>
Pieces of Modula-3 code provided by typemaps
may contain identifiers from foreign modules.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code using the function <tt>M3toC.SharedTtoS</tt>
you may declare <tt>%typemap("m3wrapinconv:import") blah * %{M3toC%}</tt>.
Then the module <tt>M3toC</tt> is imported
if the <tt>m3wrapinconv</tt> typemap for <tt>blah *</tt>
is used at least once.
Use <tt>%typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%}</tt>
if you need module renaming.
Unqualified import is not supported.
</p>
<p>
It is cumbersome to add this typemap to each piece of Modula-3 code.
It is especially useful when writing general typemaps
for the modula3.swg typemap library.
For a monolithic module you might be better off
if you add the imports directly:
</p>
<div class="code">
<pre>
%insert(m3rawintf) %{
IMPORT M3toC;
%}
</pre></div>
<H3><a name="Modula3_exceptions">31.4.5 Exceptions</a></H3>
<p>
Modula-3 provides another possibility
of an output of a function: exceptions.
</p>
<p>
Any piece of Modula-3 code that SWIG inserts
due to a typemap can raise an exception.
This way you can also convert an error code
from a C function into a Modula-3 exception.
</p>
<p>
The <tt>RAISES</tt> clause is controlled
by typemaps with the <tt>throws</tt> extension.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code that may raise the exceptions <tt>OSError.E</tt>
you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="Modula3_typemap_example">31.4.6 Example</a></H3>
<p>
The generation of wrappers in Modula-3 needs very fine control
to take advantage of the language features.
Here is an example of a generated wrapper
where almost everything is generated by a typemap:
</p>
<div class="code"><pre>
<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I>
PROCEDURE Name (READONLY str : TEXT := "" )
<I> (* m3wrapoutcheck:throws *)</I>
: NameResult RAISES {E} =
CONST
arg1name = "str"; <I>(* m3wrapargconst *)</I>
VAR
arg0 : C.char_star; <I>(* m3wrapretvar *)</I>
arg1 : C.char_star; <I>(* m3wrapargvar *)</I>
arg2 : C.int;
result : RECORD
<I> (*m3wrapretname m3wraprettype*)</I>
unixPath : TEXT;
<I> (*m3wrapoutname m3wrapouttype*)</I>
checksum : CARDINAL;
END;
BEGIN
TRY
arg1 := M3toC.SharedTtoS(str); <I>(* m3wrapinconv *)</I>
IF Text.Length(arg1) &gt; 10 THEN <I>(* m3wrapincheck *)</I>
RAISE E("str too long");
END;
<I> (* m3wrapretraw m3wrapargraw *)</I>
arg0 := MessyToUnix (arg1, arg2);
result.unixPath := M3toC.CopyStoT(arg0); <I>(* m3wrapretconv *)</I>
result.checksum := arg2; <I>(* m3wrapoutconv *)</I>
IF result.checksum = 0 THEN <I>(* m3wrapoutcheck *)</I>
RAISE E("invalid checksum");
END;
FINALLY
M3toC.FreeSharedS(str, arg1); <I>(* m3wrapfreearg *)</I>
END;
END Name;
</pre></div>
<H2><a name="Modula3_hints">31.5 More hints to the generator</a></H2>
<H3><a name="Modula3_features">31.5.1 Features</a></H3>
<table border summary="Modula-3 features">
<tr>
<th>Feature</th>
<th>Example</th>
<th>Description</th>
</tr>
<tr>
<td>multiretval</td>
<td><tt>%m3multiretval get_box;</tt> or
<tt>%feature("modula3:multiretval") get_box;</tt></td>
<td>Let the denoted function return a <tt>RECORD</tt>
rather than a plain value.
This <tt>RECORD</tt> contains all arguments with "out" direction
including the return value of the C function (if there is one).
If more than one argument is "out"
then the function <b>must</b> have the <tt>multiretval</tt> feature activated,
but it is explicitly requested from the user to prevent mistakes.</td>
</tr>
<tr>
<td>constnumeric</td>
<td><tt>%constnumeric(12) twelve;</tt> or
<tt>%feature("constnumeric", "12") twelve;</tt></td>
<td>This feature can be used to tell Modula-3's back-end of SWIG
the value of an identifier.
This is necessary in the cases
where it was defined by a non-trivial C expression.
This feature is used by the
<tt>-generateconst</tt> <a href="#Modula3_commandline">option</a>.
In future it may be generalized to other kind of values
such as strings.
</td>
</tr>
</table>
<H3><a name="Modula3_pragmas">31.5.2 Pragmas</a></H3>
<table border summary="Modula-3 pragmas">
<tr>
<th>Pragma</th>
<th>Example</th>
<th>Description</th>
</tr>
<tr>
<td>unsafe</td>
<td><tt>%pragma(modula3) unsafe="true";</tt></td>
<td>Mark the raw interface modules as <tt>UNSAFE</tt>.
This will be necessary in many cases.</td>
</tr>
<tr>
<td>library</td>
<td><tt>%pragma(modula3) library="m3fftw";</tt></td>
<td>Specifies the library name for the wrapper library to be created.
It should be distinct from the name of the library to be wrapped.</td>
</tr>
</table>
<H2><a name="Modula3_remarks">31.6 Remarks</a></H2>
<ul>
<li>
The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
Modula files.
</li>
</ul>
</body>
</html>

20
Doc/Manual/Ocaml.html
View file

@ -720,7 +720,6 @@ Here's a simple example using Trolltech's Qt Library:
class QApplication { class QApplication {
public: public:
QApplication( int argc, char **argv ); QApplication( int argc, char **argv );
void setMainWidget( QWidget *widget );
void exec(); void exec();
}; };
@ -736,16 +735,15 @@ public:
<div class="code"><pre> <div class="code"><pre>
bash-2.05a$ QTPATH=/your/qt/path $ QTPATH=/your/qt/path
bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done $ 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 $ 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 $ 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 $ swig -ocaml -c++ -o qt_wrap.c qt.i
bash-2.05a$ mv qt_wrap.cxx qt_wrap.c $ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c $ ocamlc -c qt.mli
bash-2.05a$ ocamlc -c qt.mli $ ocamlc -c qt.ml
bash-2.05a$ ocamlc -c qt.ml $ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \ camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
-L$QTPATH/lib -cclib -lqt -L$QTPATH/lib -cclib -lqt
</pre></div> </pre></div>

26
Doc/Manual/Octave.html
View file

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

32
Doc/Manual/Perl5.html
View file

@ -91,10 +91,10 @@
<p> <p>
This chapter describes SWIG's support of Perl5. Although the Perl5 This chapter describes SWIG's support of Perl5. Although the Perl5
module is one of the earliest SWIG modules, it has continued to evolve 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 and has been improved greatly with the help of SWIG users. As of SWIG
best results, it is recommended that SWIG be used with Perl 5.8 or 4.1.0, the minimum version of Perl we aim to support is Perl 5.8.0.
later. We're no longer testing regularly with older versions, but We can no longer easily test with older versions, and they no longer
Perl 5.6 seems to mostly work, while older versions don't. seem to be in active use.
</p> </p>
<H2><a name="Perl5_nn2">31.1 Overview</a></H2> <H2><a name="Perl5_nn2">31.1 Overview</a></H2>
@ -680,7 +680,6 @@ files(s) field".
installation under "Additional include directories". installation under "Additional include directories".
<li>Define the symbols WIN32 and MSWIN32 under preprocessor options. <li>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 Note that all extensions to the ActiveWare port must be compiled with
the C++ compiler since Perl has been encapsulated in a C++ class. the C++ compiler since Perl has been encapsulated in a C++ class.
@ -1065,7 +1064,7 @@ int *Foo_x_get(Foo *self) {
<p> <p>
If you want to set an array member, you will need to supply a "memberin" typemap 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 described later in this chapter. As a special case, SWIG does generate
code to set array members of type <tt>char</tt> (allowing you to store a Python code to set array members of type <tt>char</tt> (allowing you to store a Perl
string in the structure). string in the structure).
</p> </p>
@ -1736,7 +1735,7 @@ See the chapter on "<a href="Customization.html#Customization">Customization fea
<div class="code"> <div class="code">
<pre> <pre>
%except(python) { %except(perl5) {
try { try {
$function $function
} }
@ -2243,7 +2242,7 @@ can be done using the <tt>EXTEND()</tt> macro as in:
EXTEND(sp, 1); /* Extend the stack by 1 object */ EXTEND(sp, 1); /* Extend the stack by 1 object */
} }
$result = sv_newmortal(); $result = sv_newmortal();
sv_setiv($target, (IV) *($1)); sv_setiv($result, (IV) *($1));
argvi++; argvi++;
} }
</pre></div> </pre></div>
@ -2320,7 +2319,7 @@ typedef struct {
<p> <p>
By default, SWIG doesn't know how to the handle the values structure 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. 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. To make the member writable, a "memberin" typemap can be used.
</p> </p>
@ -2651,8 +2650,8 @@ constructors and destructors for the package and are always named
"new" and "DESTROY". The constructor always returns a tied hash "new" and "DESTROY". The constructor always returns a tied hash
table. This hash table is used to access the member variables of a table. This hash table is used to access the member variables of a
structure in addition to being able to invoke member functions. The structure in addition to being able to invoke member functions. The
<tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are used <tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are
internally and described shortly. implementation details used internally and described shortly.
</p> </p>
<p> <p>
@ -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 corresponding Perl object (this situation turns out to come up
frequently when constructing objects like linked lists and trees). frequently when constructing objects like linked lists and trees).
When C takes possession of an object, you can change Perl's ownership When C takes possession of an object, you can change Perl's ownership
by simply deleting the object from the <tt>%OWNER</tt> hash. This is by calling the <tt>DISOWN</tt> method (which will delete the object
done using the <tt>DISOWN</tt> method. from the internal <tt>%OWNER</tt> hash).
</p>
<p>
The <tt>%OWNER</tt> hash is an implementation detail, discussed here
only to help clarify the operation of <tt>ACQUIRE</tt> and <tt>DISOWN</tt>.
You should not access <tt>%OWNER</tt> directly - the details of how it
works (and possibly even its existence) may change in future SWIG versions.
</p> </p>
<div class="targetlang"><pre> <div class="targetlang"><pre>

272
Doc/Manual/Php.html
View file

@ -50,18 +50,19 @@
<p> <p>
In this chapter, we discuss SWIG's support of PHP. SWIG currently supports In this chapter, we discuss SWIG's support of PHP. Currently any PHP7 or PHP8
generating wrappers for PHP7. Support for PHP5 was removed in SWIG 4.0.0 release should work.
and support for PHP4 was removed in SWIG 1.3.37.
</p> </p>
<p> <p>
Currently any PHP7 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.
</p> </p>
<p> <p>
In order to use this module, you will need to have a copy of the PHP 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" 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 package for these to be installed. You can find out where these files are
by running <tt>php-config --includes</tt>. To use the built PHP module you by running <tt>php-config --includes</tt>. To use the built PHP module you
@ -84,16 +85,21 @@ swig -php7 example.i
</pre></div> </pre></div>
<p> <p>
This will produce 3 files example_wrap.c, php_example.h and This will produce 2 files: example_wrap.c and php_example.h.
example.php. The first file, <tt>example_wrap.c</tt> contains all of The first file, <tt>example_wrap.c</tt> contains all of
the C code needed to build a PHP extension. The second file, the C code needed to build a PHP extension. The second file,
<tt>php_example.h</tt> contains the header information needed if <tt>php_example.h</tt> contains the header information needed if
you wish to statically link the extension into the php interpreter. you wish to statically link the extension into the php interpreter.
The third file, </p>
<tt>example.php</tt> can be included by PHP scripts. It attempts to
dynamically load the extension and contains extra php code specified <p>
in the interface file. If wrapping C++ code with PHP classes, it will If the interface file uses <tt>%pragma(php) include=</tt>... or
also contain PHP class wrappers. <tt>%pragma(php) code=</tt>... then SWIG will also generate a third file,
<tt>example.php</tt> to contain what these specify. In SWIG &lt; 4.1.0,
this third file was always generated as it defined the PHP classes, etc
(but this is now done via C code in <tt>example_wrap.c</tt>) and also
contained code to dynamically load the extension (but this used the
PHP <tt>dl()</tt> function, which isn't recommended nowadays).
</p> </p>
<p> <p>
@ -139,8 +145,20 @@ least work for Linux though):
<p> <p>
To test the extension from a PHP script, you first need to tell PHP to To test the extension from a PHP script, you first need to tell PHP to
load it. To do this, add a line like this to the <tt>[PHP]</tt> section of load it. Assuming you're using PHP 7.2 or higher, the recommended (and
<tt>php.ini</tt>: simplest!) way to do this is to copy it to PHP's default extension directory
and add a line like this to the <tt>[PHP]</tt> section of <tt>php.ini</tt>:
</p>
<div class="code"><pre>
extension=modulename
</pre></div>
<p>
PHP &lt; 7.2 doesn't support loading by just the module name, so you need
to specify the filename of the module to be specified, which varies
between platforms. And for any PHP version, if the module is not in PHP's
default extension directory, you also need to specify the path, for example:
</p> </p>
<div class="code"><pre> <div class="code"><pre>
@ -148,13 +166,9 @@ load it. To do this, add a line like this to the <tt>[PHP]</tt> section of
</pre></div> </pre></div>
<p> <p>
If the module is in PHP's default extension directory, you can omit the path. If you're using the PHP CLI SAPI it's possible (but not recommended) to use the
</p> <a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to
load an extension at run time, by adding a line like this to the start of each
<p>
For some SAPIs (for example, the CLI SAPI) you can instead use the
<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to load
an extension at run time, by adding a line like this to the start of each
PHP script which uses your extension: PHP script which uses your extension:
</p> </p>
@ -163,23 +177,11 @@ PHP script which uses your extension:
</pre></div> </pre></div>
<p> <p>
But note that <tt>dl()</tt> isn't supported when running PHP through a But to do this portably you need to take into account that pathnames and the
webserver - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as filename extension vary by platform, and for security reasons PHP no longer
described above. supports <tt>dl()</tt> when running PHP through a webserver. Overall it's
</p> better to instead use <tt>extension</tt> in <tt>php.ini</tt> as described
above.
<p>
The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt>
call for you if the extension isn't already loaded:
</p>
<div class="code"><pre>
include("example.php");
</pre></div>
<p>
This PHP module also defines the PHP classes for the wrapped API, so you'll
almost certainly want to include it anyway.
</p> </p>
<H2><a name="Php_nn2">32.2 Basic PHP interface</a></H2> <H2><a name="Php_nn2">32.2 Basic PHP interface</a></H2>
@ -219,24 +221,19 @@ you can access the constants in your PHP script like this,
</p> </p>
<div class="code"><pre> <div class="code"><pre>
include("example.php");
echo "PI = " . PI . "\n"; echo "PI = " . PI . "\n";
echo "E = " . E . "\n"; echo "E = " . E . "\n";
</pre> </pre>
</div> </div>
<p> <p>
There's one peculiarity of how constants work in PHP which it is useful There's one peculiarity of how constants work in PHP prior to PHP 8
to note (this is not specific to SWIG though) - if you try to use an undeclared which it is useful to note (this is not specific to SWIG though) - if you try
constant, PHP will emit a warning (or a notice in PHP 7.1 and earlier) and then to use an undeclared constant, PHP will emit a warning (or a notice in PHP 7.1
expand the constant to a string version of the constant's name. Unfortunately and earlier) and then expand the constant to a string version of the constant's
it is easy to miss the warning message if you're using PHP in a webserver as name. Unfortunately it is easy to miss the warning message if you're using PHP
it will probably end up in error.log or similar. Apparently this will throw in a webserver as it will probably end up in error.log or similar. PHP 8.0
an Error in a future version of PHP, but until then it's something to be made this an error.
aware of.
</p> </p>
<p> <p>
@ -256,8 +253,6 @@ accessed incorrectly in PHP,
<div class="code"> <div class="code">
<pre> <pre>
include("example.php");
if(EASY_TO_MISPEL) { if(EASY_TO_MISPEL) {
... ...
} else { } else {
@ -298,7 +293,6 @@ is accessed as follows:
</p> </p>
<div class="code"><pre> <div class="code"><pre>
include("example.php");
print seki_get(); print seki_get();
seki_set( seki_get() * 2); # The C variable is now 4. seki_set( seki_get() * 2); # The C variable is now 4.
print seki_get(); print seki_get();
@ -306,8 +300,10 @@ print seki_get();
<p> <p>
SWIG supports global variables of all C datatypes including pointers SWIG supports global variables of all C datatypes including pointers
and complex objects. Additional types can be supported by using the and complex objects. To support additional types, you just need to
<tt>varinit</tt> typemap. supply the standard <tt>in</tt> and <tt>out</tt> typemaps, which get
used because of the wrapping as <tt>_get()</tt> and <tt>_set()</tt>
functions.
</p> </p>
<p> <p>
@ -342,13 +338,86 @@ Will be accessed in PHP like this :
</p> </p>
<div class="code"><pre> <div class="code"><pre>
include("example.php");
$a = foo(2); $a = foo(2);
$b = bar(3.5, -1.5); $b = bar(3.5, -1.5);
$c = bar(3.5); # Use default argument for 2nd parameter $c = bar(3.5); # Use default argument for 2nd parameter
</pre></div> </pre></div>
<p>
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).
</p>
<p>
You can control the generation of PHP type declarations using
the "php:type" %feature. This has three settings:
</p>
<ul>
<li> <p>If unset or set to "0" then no type declarations are generated, e.g.: <tt>%feature("php:type", "0");</tt>
</p>
</li>
<li> <p>If set to "1" then type declarations are generated for both parameters and return types, e.g.: <tt>%feature("php:type", "1");</tt>
</p></li>
<li> <p>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.: <tt>%feature("php:type", "compat");</tt>
</p></li>
</ul>
<p>
If you have an existing PHP interface and are upgrading to SWIG &gt;= 4.1.0
then the default "compat" setting should work well.
</p>
<p>
If you're writing a new set of bindings and <b>only targeting PHP8 or newer</b>
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.
</p>
<p>
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.
</p>
<p>
Note that being a SWIG feature this can be specified globally (like above) or
per class, per method, etc. See the <a
href="Customization.html#Customization_features">%feature directives</a>
section for full details of how to control at a fine-grained level.
</p>
<p>
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.
</p>
<p>
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. <tt>%typemap(in, phptype="int|string|Foo")</tt> means the
typemap accepts a PHP int or string or an object of class Foo,
<tt>%typemap(in, phptype="?int")</tt> 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.
</p>
<!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality <!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
<p> <p>
Because PHP is a dynamically typed language, the default typemaps Because PHP is a dynamically typed language, the default typemaps
@ -434,8 +503,11 @@ taking the integer argument.
<p> <p>
Pointers to C/C++ objects are represented Since SWIG 4.1.0, SWIG wraps C/C++ classes directly with PHP objects.
as PHP resources, rather like MySQL connection handles. Pointers to other types are also wrapped as PHP objects - mostly this is an
implementation detail, but it's visible from PHP via <tt>is_object()</tt> and
similar. In earlier SWIG versions, PHP resources were used to wrap both
classes and pointers to other types.
</p> </p>
<p> <p>
@ -467,8 +539,6 @@ This will result in the following usage in PHP:
<div class="code"><pre> <div class="code"><pre>
&lt;?php &lt;?php
include("example.php");
$in1=copy_intp(3); $in1=copy_intp(3);
$in2=copy_intp(5); $in2=copy_intp(5);
$result=new_intp(); $result=new_intp();
@ -476,7 +546,6 @@ $result=new_intp();
add( $in1, $in2, $result ); add( $in1, $in2, $result );
echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n"; echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n";
?&gt;
</pre></div> </pre></div>
<p> <p>
@ -501,14 +570,11 @@ This will result in the following usage in PHP:
<div class="code"><pre> <div class="code"><pre>
&lt;?php &lt;?php
include("example.php");
$in1 = 3; $in1 = 3;
$in2 = 5; $in2 = 5;
$result= add($in1, $in2); # Note using variables for the input is unnecessary. $result= add($in1, $in2); # Note using variables for the input is unnecessary.
echo "The sum $in1 + $in2 = $result\n"; echo "The sum $in1 + $in2 = $result\n";
?&gt;
</pre></div> </pre></div>
<p> <p>
@ -539,15 +605,12 @@ This will result in the following usage in PHP:
<div class="code"><pre> <div class="code"><pre>
&lt;?php &lt;?php
include("example.php");
$in1 = 3; $in1 = 3;
$in2 = 5; $in2 = 5;
$result = 0; $result = 0;
add($in1, $in2, $result); add($in1, $in2, $result);
echo "The sum $in1 + $in2 = $result\n"; echo "The sum $in1 + $in2 = $result\n";
?&gt;
</pre></div> </pre></div>
<p> <p>
@ -572,11 +635,16 @@ variable, or assigning <tt>NULL</tt> to a variable.
<p> <p>
SWIG defaults to wrapping C++ structs and classes with PHP classes - this SWIG defaults to wrapping C++ structs and classes with PHP classes.
is done by generating a PHP wrapper script which defines proxy classes Since SWIG 4.1.0, this is done entirely via PHP's C API - earlier SWIG
which calls a set of flat functions which actually wrap the C++ class. versions generated a PHP wrapper script which defined proxy classes
You can disable this wrapper layer by passing the command-line option which called a set of flat functions which actually wrapped the C++ class.
"-noproxy" in which case you'll just get the flat functions. </p>
<p>
If you don't want the class wrappers, you can pass the command-line option
"-noproxy" in which case you'll get C++ classes wrapped as flat functions
as described below.
</p> </p>
<p> <p>
@ -605,7 +673,6 @@ Would be used in the following way from PHP:
<div class="code"><pre> <div class="code"><pre>
&lt;?php &lt;?php
require "vector.php";
$v = new Vector(); $v = new Vector();
$v-&gt;x = 3; $v-&gt;x = 3;
@ -622,7 +689,6 @@ Would be used in the following way from PHP:
$c-&gt;im = 0; $c-&gt;im = 0;
# $c destructor called when $c goes out of scope. # $c destructor called when $c goes out of scope.
?&gt;
</pre></div> </pre></div>
<p> <p>
@ -667,8 +733,8 @@ constructor to execute.
</p> </p>
<p> <p>
Because PHP uses reference counting to manage resources, simple Because PHP uses reference counting, simple assignment of one variable to
assignment of one variable to another such as: another such as:
</p> </p>
<div class="code"><pre> <div class="code"><pre>
@ -721,8 +787,6 @@ would be accessed in PHP as,
</p> </p>
<div class="code"><pre> <div class="code"><pre>
include("example.php");
echo "There have now been " . Ko::threats() . " threats\n"; echo "There have now been " . Ko::threats() . " threats\n";
</pre></div> </pre></div>
@ -754,9 +818,11 @@ class Ko {
}; };
</pre></div> </pre></div>
would be executed in PHP as, <p>
would be executed in PHP as
</p>
<div class="code"><pre> <div class="code"><pre>
include("example.php");
Ko::threats(); Ko::threats();
</pre></div> </pre></div>
@ -783,9 +849,8 @@ If there are multiple interfaces, just list them separated by commas.
<p> <p>
To place PHP code in the generated "example.php" file one can use the You can get SWIG to generate an "example.php" file by specifying
<b>code</b> pragma. The code is inserted after loading the shared the code to put in it using the <b>code</b> pragma.
object.
</p> </p>
<div class="code"><pre> <div class="code"><pre>
@ -883,7 +948,7 @@ into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_F
Proxy classes provide a more natural, object-oriented way to access Proxy classes provide a more natural, object-oriented way to access
extension classes. As described above, each proxy instance has an extension classes. As described above, each proxy instance has an
associated C++ instance, and method calls to the proxy are passed to the associated C++ instance, and method calls to the proxy are passed to the
C++ instance transparently via C wrapper functions. C++ instance transparently.
</p> </p>
<p> <p>
@ -989,8 +1054,6 @@ then at the PHP side you can define
<div class="targetlang"> <div class="targetlang">
<pre> <pre>
require("mymodule.php");
class MyFoo extends Foo { class MyFoo extends Foo {
function one() { function one() {
print "one from php\n"; print "one from php\n";
@ -1012,8 +1075,8 @@ that derives from both the class in question and a special
<tt>Swig::Director</tt> class. These new classes, referred to as director <tt>Swig::Director</tt> class. These new classes, referred to as director
classes, can be loosely thought of as the C++ equivalent of the PHP classes, can be loosely thought of as the C++ equivalent of the PHP
proxy classes. The director classes store a pointer to their underlying proxy classes. The director classes store a pointer to their underlying
PHP object. Indeed, this is quite similar to the "_cPtr" and "thisown" PHP object. Indeed, this is quite similar to <tt>struct swig_object_wrapper</tt>
members of the PHP proxy classes. which is used to implement the PHP proxy classes.
</p> </p>
<p> <p>
@ -1068,12 +1131,12 @@ infinite loop.
<p> <p>
One more point needs to be made about the relationship between director One more point needs to be made about the relationship between director
classes and proxy classes. When a proxy class instance is created in classes and proxy classes. When a proxy class instance is created in
PHP, SWIG creates an instance of the original C++ class and assigns it PHP, SWIG creates an instance of the original C++ class and stores it
to <tt>-&gt;_cPtr</tt>. This is exactly what happens without directors in the <tt>struct swig_object_wrapper</tt>. This is true whether or not
and is true even if directors are enabled for the particular class in directors are enabled for the particular class in question. However
question. When a class <i>derived</i> from a proxy class is created, when a class <i>derived</i> from a proxy class is created, SWIG instead
however, SWIG then creates an instance of the corresponding C++ director creates an instance of the corresponding C++ director class.
class. The reason for this difference is that user-defined subclasses The reason for this difference is that user-defined subclasses
may override or extend methods of the original class, so the director may override or extend methods of the original class, so the director
class is needed to route calls to these methods correctly. For class is needed to route calls to these methods correctly. For
unmodified proxy classes, all methods are ultimately implemented in C++ unmodified proxy classes, all methods are ultimately implemented in C++
@ -1161,13 +1224,32 @@ should suffice in most cases:
<div class="code"> <div class="code">
<pre> <pre>
%feature("director:except") { %feature("director:except") {
if ($error == FAILURE) { #if SWIG_VERSION &gt;= 0x040100
if ($error != NULL)
#else
if ($error == FAILURE)
#endif
{
throw Swig::DirectorMethodException(); throw Swig::DirectorMethodException();
} }
} }
</pre> </pre>
</div> </div>
<p>
If you only need to support SWIG &gt;= 4.1.0, you can just use the
<tt>($error != NULL)</tt> condition.
</p>
<p>
In SWIG 4.1.0, <tt>$error</tt> was changed in the SWIG/PHP director
implementation to make it work more like how it does for other languages.
Previously, <tt>$error</tt> didn't actually indicate an exception, but instead
was only set to <tt>FAILURE</tt> if there was a problem calling the PHP method.
Now <tt>$error</tt> indicates if the PHP method threw a PHP exception, and
directorout typemaps for PHP no longer need to be gated by <tt>if (EG(exception))</tt>.
</p>
<p> <p>
This code will check the PHP error state after each method call from a This code will check the PHP error state after each method call from a
director into PHP, and throw a C++ exception if an error occurred. This director into PHP, and throw a C++ exception if an error occurred. This

246
Doc/Manual/Pike.html
View file

@ -1,246 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Pike</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike">37 SWIG and Pike</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Pike_nn2">Preliminaries</a>
<ul>
<li><a href="#Pike_nn3">Running SWIG</a>
<li><a href="#Pike_nn4">Getting the right header files</a>
<li><a href="#Pike_nn5">Using your module</a>
</ul>
<li><a href="#Pike_nn6">Basic C/C++ Mapping</a>
<ul>
<li><a href="#Pike_nn7">Modules</a>
<li><a href="#Pike_nn8">Functions</a>
<li><a href="#Pike_nn9">Global variables</a>
<li><a href="#Pike_nn10">Constants and enumerated types</a>
<li><a href="#Pike_nn11">Constructors and Destructors</a>
<li><a href="#Pike_nn12">Static Members</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG support for Pike. As of this writing, the
SWIG Pike module is still under development and is not considered
ready for prime time. The Pike module is being developed against the
Pike 7.4.10 release and may not be compatible with previous versions
of Pike.
</p>
<p>
This chapter covers most SWIG features, but certain low-level details
are covered in less depth than in earlier chapters. At the very
least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2">37.1 Preliminaries</a></H2>
<H3><a name="Pike_nn3">37.1.1 Running SWIG</a></H3>
<p>
Suppose that you defined a SWIG module such as the following:
</p>
<div class="code">
<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
</div>
<p>
To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
</p>
<div class="code">
<pre>$ <b>swig -pike example.i</b><br></pre>
</div>
<p>
If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
</p>
<div class="code">
<pre>$ <b>swig -c++ -pike example.i</b><br></pre>
</div>
<p>
This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
ran SWIG with the <tt>-c++</tt> option).
The SWIG-generated source file contains the low-level wrappers that need
to be compiled and linked with the rest of your C/C++ application to
create an extension module.
</p>
<p>
The name of the wrapper file is derived from the name of the input
file. For example, if the input file is <tt>example.i</tt>, the name
of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
can use the <tt>-o</tt> option:
</p>
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</div>
<H3><a name="Pike_nn4">37.1.2 Getting the right header files</a></H3>
<p>
In order to compile the C/C++ wrappers, the compiler needs to know the
path to the Pike header files. These files are usually contained in a
directory such as
</p>
<div class="code">
<pre>/usr/local/pike/7.4.10/include/pike<br></pre>
</div>
<p>
There doesn't seem to be any way to get Pike itself to reveal the
location of these files, so you may need to hunt around for them.
You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
and so on.
</p>
<H3><a name="Pike_nn5">37.1.3 Using your module</a></H3>
<p>
To use your module, simply use Pike's <tt>import</tt> statement:
</p>
<div class="code"><pre>
$ <b>pike</b>
Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></div>
<H2><a name="Pike_nn6">37.2 Basic C/C++ Mapping</a></H2>
<H3><a name="Pike_nn7">37.2.1 Modules</a></H3>
<p>
All of the code for a given SWIG module is wrapped into a single Pike
module. Since the name of the shared library that implements your
module ultimately determines the module's name (as far as Pike is
concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8">37.2.2 Functions</a></H3>
<p>
Global functions are wrapped as new Pike built-in functions. For
example,
</p>
<div class="code"><pre>
%module example
int fact(int n);
</pre></div>
<p>
creates a new built-in function <tt>example.fact(n)</tt> that works
exactly as you'd expect it to:
</p>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></div>
<H3><a name="Pike_nn9">37.2.3 Global variables</a></H3>
<p>
Global variables are currently wrapped as a pair of functions, one to get
the current value of the variable and another to set it. For example, the
declaration
</p>
<div class="code"><pre>
%module example
double Foo;
</pre></div>
<p>
will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
</p>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>Foo_get();</b>
(1) Result: 3.000000
&gt; <b>Foo_set(3.14159);</b>
(2) Result: 0
&gt; <b>Foo_get();</b>
(3) Result: 3.141590
</pre></div>
<H3><a name="Pike_nn10">37.2.4 Constants and enumerated types</a></H3>
<p>
Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11">37.2.5 Constructors and Destructors</a></H3>
<p>
Constructors are wrapped as <tt>create()</tt> methods, and destructors are
wrapped as <tt>destroy()</tt> methods, for Pike classes.
</p>
<H3><a name="Pike_nn12">37.2.6 Static Members</a></H3>
<p>
Since Pike doesn't support static methods or data for Pike classes, static
member functions in your C++ classes are wrapped as regular functions and
static member variables are wrapped as pairs of functions (one to get the
value of the static member variable, and another to set it). The names of
these functions are prepended with the name of the class.
For example, given this C++ class declaration:
</p>
<div class="code"><pre>
class Shape
{
public:
static void print();
static int nshapes;
};
</pre></div>
<p>
SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
<tt>Shape::print()</tt> member function, as well as a pair of methods,
<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
the value of <tt>Shape::nshapes</tt>.
</p>
</body>
</html>

10
Doc/Manual/Preface.html
View file

@ -281,12 +281,12 @@ You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build a
</p> </p>
<p> <p>
<a href="http://www.pcre.org/">PCRE</a> <a href="http://www.pcre.org/">PCRE2</a>
needs to be installed on your system to build SWIG, in particular needs to be installed on your system to build SWIG, in particular
pcre-config must be available. If you have PCRE headers and libraries but not pcre2-config must be available. If you have PCRE2 headers and libraries but not
pcre-config itself or, alternatively, wish to override the compiler or linker pcre2-config itself or, alternatively, wish to override the compiler or linker
flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables flags returned by pcre2-config, you may set PCRE2_LIBS and PCRE2_CFLAGS variables
to be used instead. And if you don't have PCRE at all, the configure script to be used instead. And if you don't have PCRE2 at all, the configure script
will provide instructions for obtaining it. will provide instructions for obtaining it.
</p> </p>

21
Doc/Manual/Preprocessor.html
View file

@ -99,8 +99,23 @@ header files without generating any wrappers.
<p> <p>
SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>, SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>,
<tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally
include parts of an interface. The following symbols are predefined include parts of an interface.
by SWIG when it is parsing the interface: </p>
<p>
SWIG's preprocessor conditionals support the standard C/C++ preprocessor
integer expressions. As a SWIG-specific extension, string equality and
inequality tests are also supported, for example:
</p>
<div class="code">
<pre>
#if defined __cplusplus && (#__VA_ARGS__ != "" || #TYPE == "void")
</pre>
</div>
<p>
The following symbols are predefined by SWIG when it is parsing the interface:
</p> </p>
<div class="code"><pre> <div class="code"><pre>
@ -123,7 +138,7 @@ SWIGOCAML Defined when using OCaml
SWIGOCTAVE Defined when using Octave SWIGOCTAVE Defined when using Octave
SWIGPERL Defined when using Perl SWIGPERL Defined when using Perl
SWIGPHP Defined when using PHP (any version) SWIGPHP Defined when using PHP (any version)
SWIGPHP7 Defined when using PHP7 SWIGPHP7 Defined when using PHP 7 or later (with a compatible C API)
SWIGPYTHON Defined when using Python SWIGPYTHON Defined when using Python
SWIGR Defined when using R SWIGR Defined when using R
SWIGRUBY Defined when using Ruby SWIGRUBY Defined when using Ruby

123
Doc/Manual/Python.html
View file

@ -133,7 +133,10 @@
</ul> </ul>
<li><a href="#Python_python3support">Python 3 Support</a> <li><a href="#Python_python3support">Python 3 Support</a>
<ul> <ul>
<li><a href="#Python_nn74">Function annotation</a> <li><a href="#Python_annotations">Function annotations</a>
<ul>
<li><a href="#Python_annotations_c">C/C++ annotation types</a>
</ul>
<li><a href="#Python_nn75">Buffer interface</a> <li><a href="#Python_nn75">Buffer interface</a>
<li><a href="#Python_nn76">Abstract base classes</a> <li><a href="#Python_nn76">Abstract base classes</a>
<li><a href="#Python_nn77">Byte string output conversion</a> <li><a href="#Python_nn77">Byte string output conversion</a>
@ -1608,7 +1611,7 @@ public:
</div> </div>
<p> <p>
In Python, the static member can be access in three different ways: In Python, the static member can be accessed in three different ways:
</p> </p>
<div class="targetlang"> <div class="targetlang">
@ -1616,7 +1619,7 @@ In Python, the static member can be access in three different ways:
&gt;&gt;&gt; example.Spam_foo() # Spam::foo() &gt;&gt;&gt; example.Spam_foo() # Spam::foo()
&gt;&gt;&gt; s = example.Spam() &gt;&gt;&gt; s = example.Spam()
&gt;&gt;&gt; s.foo() # Spam::foo() via an instance &gt;&gt;&gt; s.foo() # Spam::foo() via an instance
&gt;&gt;&gt; example.Spam.foo() # Spam::foo(). Python-2.2 only &gt;&gt;&gt; example.Spam.foo() # Spam::foo() using Python-2.2 and later
</pre> </pre>
</div> </div>
@ -1627,16 +1630,31 @@ last technique is only available in Python-2.2 and later versions.
<p> <p>
Static member variables are currently accessed as global variables. This means, Static member variables are currently accessed as global variables. This means,
they are accessed through <tt>cvar</tt> like this: they are accessed through <tt>cvar</tt> or via an instance property:
</p> </p>
<div class="targetlang"> <div class="targetlang">
<pre> <pre>
&gt;&gt;&gt; print example.cvar.Spam_bar &gt;&gt;&gt; example.cvar.Spam_bar # Spam::bar
7
&gt;&gt;&gt; s = example.Spam()
&gt;&gt;&gt; s.bar # Spam::bar via an instance property
7 7
</pre> </pre>
</div> </div>
<p>
The <tt>-builtin</tt> option uses a metaclass to additionally provide access as follows:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; example.Spam.bar # Spam::bar using -builtin option only
7
</pre>
</div>
<H3><a name="Python_nn21">33.3.8 C++ inheritance</a></H3> <H3><a name="Python_nn21">33.3.8 C++ inheritance</a></H3>
@ -2516,6 +2534,12 @@ import A
assert(issubclass(B.Derived, A.Base)) assert(issubclass(B.Derived, A.Base))
</pre></div> </pre></div>
</li> </li>
<li><p><a href="#Python_annotations">Python function annotations</a> are not supported.
</p>
</li>
</ul> </ul>
<H4><a name="Python_builtin_overloads">33.4.2.2 Operator overloads and slots -- use them!</a></H4> <H4><a name="Python_builtin_overloads">33.4.2.2 Operator overloads and slots -- use them!</a></H4>
@ -2568,7 +2592,7 @@ but <b>the line that uses the '+' operator is much faster</b>.
(<tt>operator==, operator&lt;</tt>, etc.) are also converted to Python (<tt>operator==, operator&lt;</tt>, etc.) are also converted to Python
slot operators. For a complete list of C++ operators that are slot operators. For a complete list of C++ operators that are
automatically converted to Python slot operators, refer to the file automatically converted to Python slot operators, refer to the file
<tt>python/pyopers.swig</tt> in the SWIG library. <tt>python/pyopers.swg</tt> in the SWIG library.
</p> </p>
@ -2674,7 +2698,7 @@ the chosen closure function.
<p> <p>
There is further information on <tt>%feature("python:slot")</tt> There is further information on <tt>%feature("python:slot")</tt>
in the file <tt>python/pyopers.swig</tt> in the SWIG library. in the file <tt>python/pyopers.swg</tt> in the SWIG library.
</p> </p>
@ -4939,7 +4963,6 @@ object to be used as a <tt>char **</tt> object.
if (PyString_Check(o)) { if (PyString_Check(o)) {
$1[i] = PyString_AsString(PyList_GetItem($input, i)); $1[i] = PyString_AsString(PyList_GetItem($input, i));
} else { } else {
free($1);
PyErr_SetString(PyExc_TypeError, "list must contain strings"); PyErr_SetString(PyExc_TypeError, "list must contain strings");
SWIG_fail; SWIG_fail;
} }
@ -5038,7 +5061,6 @@ previous example:
if (PyString_Check(o)) { if (PyString_Check(o)) {
$2[i] = PyString_AsString(PyList_GetItem($input, i)); $2[i] = PyString_AsString(PyList_GetItem($input, i));
} else { } else {
free($2);
PyErr_SetString(PyExc_TypeError, "list must contain strings"); PyErr_SetString(PyExc_TypeError, "list must contain strings");
SWIG_fail; SWIG_fail;
} }
@ -6740,37 +6762,66 @@ The following are Python 3 new features that are currently supported by
SWIG. SWIG.
</p> </p>
<H3><a name="Python_nn74">33.12.1 Function annotation</a></H3> <H3><a name="Python_annotations">33.12.1 Function annotations</a></H3>
<p> <p>
The <tt>-py3</tt> option will enable function annotation support. When used Python 3 supports function annotations as defined in
SWIG is able to generate proxy method definitions like this:
</p>
<div class="code"><pre>
def foo(self, bar : "int"=0) -&gt; "void" : ...
</pre></div>
<p>
Also, even if without passing SWIG the <tt>-py3</tt> option, the parameter list
still could be generated:
</p>
<div class="code"><pre>
def foo(self, bar=0): ...
</pre></div>
<p>
But for overloaded function or method, the parameter list would fallback to
<tt>*args</tt> or <tt>self, *args</tt>, and <tt>**kwargs</tt> may be append
depend on whether you enabled the keyword argument. This fallback is due to
all overloaded functions share the same function in SWIG generated proxy class.
</p>
<p>
For detailed usage of function annotation, see
<a href="https://www.python.org/dev/peps/pep-3107/">PEP 3107</a>. <a href="https://www.python.org/dev/peps/pep-3107/">PEP 3107</a>.
Note that there is currently no annotations support for the <tt>-builtin</tt> nor
the <tt>-fastproxy</tt> option.
Annotations are added via the <tt>python:annotations</tt>
<a href="Customization.html#Customization_features">%feature directives</a>.
SWIG currently supports one type of function annotation.
</p>
<H4><a name="Python_annotations_c">33.12.1.1 C/C++ annotation types</a></H4>
<p>
The <tt>%feature("python:annotations", "c")</tt> directive generates function annotations
containing C/C++ types. For example:
</p>
<div class="code"><pre>
%feature("python:annotations", "c") global_ints;
int *global_ints(int &amp;ri);
</pre></div>
<p>
The generated code then contains function annotations containing the C types:
</p>
<div class="targetlang"><pre>
def global_ints(ri: "int &amp;") -&gt; "int *":
return _python_annotations_c.global_ints(ri)
</pre></div>
<p>
There are some limitations with annotations support, for example, overloaded functions use
<tt>*args</tt> or <tt>**kwargs</tt> when keyword arguments are enabled.
The parameter names and types are then not shown. For example, with input:
</p>
<div class="code"><pre>
int *global_overloaded(int &amp;ri);
int *global_overloaded();
</pre></div>
<p>
The generated Python function including annotations is shown below.
Only the return type is annotated.
</p>
<div class="targetlang"><pre>
def global_overloaded(*args) -&gt; "int *":
return _python_annotations_c.global_overloaded(*args)
</pre></div>
<p>
<b>Compatibility Note:</b> SWIG-4.1.0 changed the way that function annotations are generated.
Prior versions required the <tt>-py3</tt> option which enabled function annotation support
containing C/C++ types instead of supporting <tt>%feature("python:annotations", "c")</tt>.
</p> </p>
<H3><a name="Python_nn75">33.12.2 Buffer interface</a></H3> <H3><a name="Python_nn75">33.12.2 Buffer interface</a></H3>

4
Doc/Manual/R.html
View file

@ -196,7 +196,7 @@ slices)
<p> <p>
Wrapping of C++ classes for R works quite well. R has a special Wrapping of C++ classes for R works quite well. R has a special
type, known as an external reference, that can be used as a pointer type, known as an external reference, that can be used as a pointer
to arbitary things, including C++ classes. The proxy layers generated to arbitrary things, including C++ classes. The proxy layers generated
for other classes are not required. for other classes are not required.
</p> </p>
@ -265,7 +265,7 @@ v2$Axles
[1] 4 [1] 4
v1$Available v1$Available
[1] FALSE [1] FALSE
# Set availabilty # Set availability
v1$Available &lt;- TRUE v1$Available &lt;- TRUE
v1$Available v1$Available
[1] TRUE [1] TRUE

142
Doc/Manual/SWIG.html
View file

@ -47,6 +47,7 @@
<li><a href="#SWIG_rename_ignore">Renaming and ignoring declarations</a> <li><a href="#SWIG_rename_ignore">Renaming and ignoring declarations</a>
<ul> <ul>
<li><a href="#SWIG_nn29">Simple renaming of specific identifiers</a> <li><a href="#SWIG_nn29">Simple renaming of specific identifiers</a>
<li><a href="#SWIG_ignore">Ignoring identifiers</a>
<li><a href="#SWIG_advanced_renaming">Advanced renaming support</a> <li><a href="#SWIG_advanced_renaming">Advanced renaming support</a>
<li><a href="#SWIG_limiting_renaming">Limiting global renaming rules</a> <li><a href="#SWIG_limiting_renaming">Limiting global renaming rules</a>
<li><a href="#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a> <li><a href="#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a>
@ -127,7 +128,7 @@ Supported Target Language Options
-lua - Generate Lua wrappers -lua - Generate Lua wrappers
-octave - Generate Octave wrappers -octave - Generate Octave wrappers
-perl5 - Generate Perl 5 wrappers -perl5 - Generate Perl 5 wrappers
-php7 - Generate PHP 7 wrappers -php7 - Generate PHP 7 or later wrappers
-python - Generate Python wrappers -python - Generate Python wrappers
-r - Generate R (aka GNU S) wrappers -r - Generate R (aka GNU S) wrappers
-ruby - Generate Ruby wrappers -ruby - Generate Ruby wrappers
@ -208,7 +209,7 @@ General Options
-oh &lt;headfile&gt; - Set name of C++ output header file for directors to &lt;headfile&gt; -oh &lt;headfile&gt; - Set name of C++ output header file for directors to &lt;headfile&gt;
-outcurrentdir - Set default output dir to current dir instead of input file's path -outcurrentdir - Set default output dir to current dir instead of input file's path
-outdir &lt;dir&gt; - Set language specific files output directory to &lt;dir&gt; -outdir &lt;dir&gt; - Set language specific files output directory to &lt;dir&gt;
-pcreversion - Display PCRE version information -pcreversion - Display PCRE2 version information
-small - Compile in virtual elimination and compact mode -small - Compile in virtual elimination and compact mode
-swiglib - Report location of SWIG library and exit -swiglib - Report location of SWIG library and exit
-templatereduce - Reduce all the typedefs in templates -templatereduce - Reduce all the typedefs in templates
@ -1469,14 +1470,14 @@ SWIG generates the following code:
<pre> <pre>
/* C mode */ /* C mode */
void foo_set(char *value) { void foo_set(char *value) {
if (foo) free(foo); free(foo);
foo = (char *) malloc(strlen(value)+1); foo = (char *) malloc(strlen(value)+1);
strcpy(foo, value); strcpy(foo, value);
} }
/* C++ mode. When -c++ option is used */ /* C++ mode. When -c++ option is used */
void foo_set(char *value) { void foo_set(char *value) {
if (foo) delete [] foo; delete [] foo;
foo = new char[strlen(value)+1]; foo = new char[strlen(value)+1];
strcpy(foo, value); strcpy(foo, value);
} }
@ -1841,6 +1842,25 @@ all to `output' by specifying :</p>
%rename(output) print; // Rename all `print' functions to `output' %rename(output) print; // Rename all `print' functions to `output'
</pre></div> </pre></div>
<p>
A new <tt>%rename</tt> for the same name will replace the current
<tt>%rename</tt> for all uses after it in the file, and setting the
new name to "" will remove the rename. So, for instance, if you
wanted to rename some things in one file and not in another, you could
do:
</p>
<div class="code">
<pre>
%rename(print1) print;
%include "header1.h" //Anything "print" in here will become "print1"
%rename(print2) print;
%include "header2.h" //Anything "print" in here will become "print2"
%rename("") print;
%include "header3.h" //Anything "print" in here will remain "print"
</pre>
</div>
<p> <p>
SWIG does not normally perform any checks to see if the functions it wraps are SWIG does not normally perform any checks to see if the functions it wraps are
already defined in the target scripting language. However, if you are already defined in the target scripting language. However, if you are
@ -1857,6 +1877,9 @@ If you are using the <tt>%rename</tt> directive and C++, make sure you read the
for method overloading and default arguments. for method overloading and default arguments.
</p> </p>
<H4><a name="SWIG_ignore">5.4.7.2 Ignoring identifiers</a></H4>
<p> <p>
Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive. <tt>%ignore</tt> instructs SWIG Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive. <tt>%ignore</tt> instructs SWIG
to ignore declarations that match a given identifier. For example: to ignore declarations that match a given identifier. For example:
@ -1896,7 +1919,7 @@ This directive is still supported, but it is deprecated and should probably be a
directive is more powerful and better supports wrapping of raw header file information. directive is more powerful and better supports wrapping of raw header file information.
</p> </p>
<H4><a name="SWIG_advanced_renaming">5.4.7.2 Advanced renaming support</a></H4> <H4><a name="SWIG_advanced_renaming">5.4.7.3 Advanced renaming support</a></H4>
<p> <p>
@ -2020,10 +2043,10 @@ and a more descriptive one, but the two functions are otherwise equivalent:
<tr> <tr>
<td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td> <td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td>
<td>String after (Perl-like) regex substitution operation. This function <td>String after (Perl-like) regex substitution operation. This function
allows to apply arbitrary regular expressions to the identifier names. The allows applying arbitrary regular expressions to the identifier names. The
<i>pattern</i> part is a regular expression in Perl syntax (as supported <i>pattern</i> part is a regular expression in Perl syntax (as supported
by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions (PCRE)</a>) by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions</a>)
library and the <i>subst</i> string (PCRE2 library) and the <i>subst</i> string
can contain back-references of the form <tt>\N</tt> where <tt>N</tt> is a digit can contain back-references of the form <tt>\N</tt> where <tt>N</tt> is a digit
from 0 to 9, or one of the following escape sequences: <tt>\l</tt>, <tt>\L</tt>, from 0 to 9, or one of the following escape sequences: <tt>\l</tt>, <tt>\L</tt>,
<tt>\u</tt>, <tt>\U</tt> or <tt>\E</tt>. The back-references are replaced with the <tt>\u</tt>, <tt>\U</tt> or <tt>\E</tt>. The back-references are replaced with the
@ -2041,23 +2064,10 @@ and a more descriptive one, but the two functions are otherwise equivalent:
<tt>%rename("regex:/(\\w+)_(.*)/\\u\\2/")</tt></td> <tt>%rename("regex:/(\\w+)_(.*)/\\u\\2/")</tt></td>
<td><tt>prefix_print</tt></td><td><tt>Print</tt></td> <td><tt>prefix_print</tt></td><td><tt>Print</tt></td>
</tr> </tr>
<tr>
<td><tt>command:cmd</tt></td>
<td>Output of an external command <tt>cmd</tt> with the string passed to
it as input. Notice that this function is extremely slow compared to all
the other ones as it involves spawning a separate process and using it for
many declarations is not recommended. The <i>cmd</i> is not enclosed in
square brackets but must be terminated with a triple <tt>'&lt;'</tt> sign,
e.g. <tt>%rename("command:tr&nbsp;-d&nbsp;aeiou &lt;&lt;&lt;")</tt>
(nonsensical example removing all vowels)</td>
<td><tt>Print</tt></td><td><tt>Prnt</tt></td>
</tr>
</table> </table>
<p> <p>
The most general function of all of the above ones (not counting The most general function of all of the above ones is the
<tt>command</tt> which is even more powerful in principle but which should
generally be avoided because of performance considerations) is the
<tt>regex</tt> one. Here are some more examples of its use: <tt>regex</tt> one. Here are some more examples of its use:
</p> </p>
@ -2105,7 +2115,7 @@ are exactly equivalent and <tt>%rename</tt> can be used to selectively ignore
multiple declarations using the previously described matching possibilities. multiple declarations using the previously described matching possibilities.
</p> </p>
<H4><a name="SWIG_limiting_renaming">5.4.7.3 Limiting global renaming rules</a></H4> <H4><a name="SWIG_limiting_renaming">5.4.7.4 Limiting global renaming rules</a></H4>
<p> <p>
@ -2137,11 +2147,15 @@ the match to class declarations only (in C++) and <tt>match="enumitem"</tt>
restricts it to the enum elements. SWIG also provides convenience macros for restricts it to the enum elements. SWIG also provides convenience macros for
such match expressions, for example such match expressions, for example
</p> </p>
<div class="code"> <div class="code">
<pre> <pre>
%rename("%(title)s", %$isenumitem) ""; %rename("%(title)s", %$isenumitem) "";
// same as:
%rename("%(title)s", match="enumitem") "";
</pre> </pre>
</div> </div>
<p> <p>
will capitalize the names of all the enum elements but not change the case of will capitalize the names of all the enum elements but not change the case of
the other declarations. Similarly, <tt>%$isclass</tt>, <tt>%$isfunction</tt>, the other declarations. Similarly, <tt>%$isclass</tt>, <tt>%$isfunction</tt>,
@ -2151,6 +2165,55 @@ documentation is not exhaustive, see the "%rename predicates" section in
<tt>swig.swg</tt> for the full list of supported match expressions. <tt>swig.swg</tt> for the full list of supported match expressions.
</p> </p>
<p>
A logical not is also possible by using <tt>notmatch</tt>.
For example, <tt>notmatch="enumitem"</tt> will restrict the
match to all items that are not enum elements.
There is also a <tt>%$not</tt> macro which simply expands to "not".
Be careful using this as some of the other macros in <tt>swig.swg</tt>
are complex expressions and so it will only "notmatch" the first part
of the expression.
</p>
<div class="code">
<pre>
%rename("%(title)s", %$not %$isenumitem) "";
// same as:
%rename("%(title)s", notmatch="enumitem") "";
</pre>
</div>
<p>
For a comprehensive understanding of how the matching works, the internal
<a href="Extending.html#Extending_nn8">parse tree</a> needs to be examined using the
command line option: <tt>-debug-module 1</tt>.
A snippet of the resulting output might be:
</p>
<div class="shell">
<pre>
+++ destructor - 0x7fc10ea05af0 ----------------------------------------
| name - "~Shape"
| ismember - "1"
| sym:name - "~Shape"
| access - "public"
| storage - "virtual"
</pre>
</div>
<p>
Here the node type is a "destructor" and in order to match all destructor nodes, use
<tt>match="destructor"</tt>. To match one of the listed attributes in the node,
such as when the storage is virtual, use <tt>match$storage="virtual"</tt>.
This will match all nodes that have a storage attribute set to "virtual".
To match only virtual destructors, combine them and use <tt>match="destructor", match$storage="virtual"</tt>.
</p>
<p>
While the vast majority of these internal parse tree nodes are unlikely to change from one version of
SWIG to the next, <b>use these matching rules at your own risk</b> as there are no guarantees that they will not change.
</p>
<p> <p>
In addition to literally matching some string with <tt>match</tt> you can In addition to literally matching some string with <tt>match</tt> you can
also use <tt>regexmatch</tt> or <tt>notregexmatch</tt> to match a string also use <tt>regexmatch</tt> or <tt>notregexmatch</tt> to match a string
@ -2203,7 +2266,7 @@ wrap C++ overloaded functions and methods or C++ methods which use default argum
</p> </p>
<H4><a name="SWIG_chosen_unignore">5.4.7.4 Ignoring everything then wrapping a few selected symbols</a></H4> <H4><a name="SWIG_chosen_unignore">5.4.7.5 Ignoring everything then wrapping a few selected symbols</a></H4>
<p> <p>
@ -2227,6 +2290,23 @@ the following approach could be taken:
%rename("%s") Star::shine; // named method %rename("%s") Star::shine; // named method
%include "myheader.h" %include "myheader.h"
%rename("%s") ""; // Undo the %ignore
</pre>
</div>
<p>
If <tt>Star</tt> was in the <tt>Galaxy</tt> namespace, you would need
to unignore the namespace, too, and add the namespace to all the
renames:
</p>
<div class="code">
<pre>
%rename("%s") Galaxy;
%rename("%s") Galaxy::Star;
%rename("%s") Galaxy::Star::Star;
...
</pre> </pre>
</div> </div>
@ -2241,6 +2321,7 @@ members of the class, so when the chosen class is unignored, all of its methods
%rename($ignore, %$isclass) ""; // Only ignore all classes %rename($ignore, %$isclass) ""; // Only ignore all classes
%rename("%s") Star; // Unignore 'Star' %rename("%s") Star; // Unignore 'Star'
%include "myheader.h" %include "myheader.h"
%rename("%s", %$isclass) ""; // Stop ignoring all classes
</pre> </pre>
</div> </div>
@ -2594,8 +2675,7 @@ char *Foo_name_get(Foo *obj) {
} }
char *Foo_name_set(Foo *obj, char *c) { char *Foo_name_set(Foo *obj, char *c) {
if (obj-&gt;name) free(obj-&gt;name);
free(obj-&gt;name);
obj-&gt;name = (char *) malloc(strlen(c)+1); obj-&gt;name = (char *) malloc(strlen(c)+1);
strcpy(obj-&gt;name, c); strcpy(obj-&gt;name, c);
return obj-&gt;name; return obj-&gt;name;
@ -2733,6 +2813,11 @@ void Foo_w_set(FOO *f, WORD value) {
</pre> </pre>
</div> </div>
<p>
If you have accessor methods that you want to use as attributes in the
target language, you can make them appear as data members using
<a href="Library.html#Library_attributes">attributes.i</a>.
</p>
<p> <p>
<b>Compatibility Note:</b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes <b>Compatibility Note:</b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
@ -2976,6 +3061,11 @@ typedef struct Vector {
</pre> </pre>
</div> </div>
<p>
You'll also need to use these names if you want to directly call methods added
using <tt>%extend</tt> from other C/C++ code.
</p>
<p> <p>
The name used for %extend should be the name of the struct and not the name of any typedef to the struct. The name used for %extend should be the name of the struct and not the name of any typedef to the struct.
For example: For example:

205
Doc/Manual/SWIGPlus.html
View file

@ -48,6 +48,9 @@
</ul> </ul>
<li><a href="#SWIGPlus_nn28">Overloaded operators</a> <li><a href="#SWIGPlus_nn28">Overloaded operators</a>
<li><a href="#SWIGPlus_class_extension">Class extension</a> <li><a href="#SWIGPlus_class_extension">Class extension</a>
<ul>
<li><a href="#SWIGPlus_replacing_methods">Replacing class methods</a>
</ul>
<li><a href="#SWIGPlus_nn30">Templates</a> <li><a href="#SWIGPlus_nn30">Templates</a>
<ul> <ul>
<li><a href="#SWIGPlus_template_directive">The %template directive</a> <li><a href="#SWIGPlus_template_directive">The %template directive</a>
@ -1122,7 +1125,7 @@ customization features.
<p> <p>
SWIG wraps class members that are public following the C++ SWIG wraps class members that are public following the C++
conventions, i.e., by explicit public declaration or by the use of conventions, i.e., by explicit public declaration or by the use of
the <tt>using</tt> directive. In general, anything specified in a <tt>using</tt> declarations. In general, anything specified in a
private or protected section will be ignored, although the internal private or protected section will be ignored, although the internal
code generator sometimes looks at the contents of the private and code generator sometimes looks at the contents of the private and
protected sections so that it can properly generate code for default protected sections so that it can properly generate code for default
@ -2080,7 +2083,6 @@ or for statically typed languages like Java:
<pre> <pre>
example.i:4: Warning 516: Overloaded method foo(long) ignored, example.i:4: Warning 516: Overloaded method foo(long) ignored,
example.i:3: Warning 516: using foo(int) instead. example.i:3: Warning 516: using foo(int) instead.
at example.i:3 used.
</pre> </pre>
</div> </div>
@ -2327,8 +2329,8 @@ also apply to <tt>%ignore</tt>. For example:
<div class="code"> <div class="code">
<pre> <pre>
%ignore foo(double); // Ignore all foo(double) %ignore foo(double); // Ignore all foo(double)
%ignore Spam::foo; // Ignore foo in class Spam %ignore Spam::foo; // Ignore foo in class Spam (and foo in any derived classes)
%ignore Spam::foo(double); // Ignore foo(double) in class Spam %ignore Spam::foo(double); // Ignore foo(double) in class Spam (and foo in any derived classes)
%ignore *::foo(double); // Ignore foo(double) in all classes %ignore *::foo(double); // Ignore foo(double) in all classes
</pre> </pre>
</div> </div>
@ -2383,6 +2385,53 @@ global scope (e.g., a renaming of <tt>Spam::foo</tt> takes precedence
over a renaming of <tt>foo(int)</tt>).</p> over a renaming of <tt>foo(int)</tt>).</p>
</li> </li>
<li><p>
Renaming a class member, using an unparameterized but qualified name, such as <tt>Spam::foo</tt>, also applies to members in all derived classes
that have members with the same name.
This can be used to simply rename a method, across an entire class hierarchy for all overloaded and non-overloaded methods.
This also applies to methods introduced via <tt>using</tt> declarations, see
<a href="#SWIGPlus_nn35">Using declarations and inheritance</a>.
For example:
<div class="code">
<pre>
%rename(foo_new) Spam::foo;
class Spam {
public:
virtual void foo(int); // Renamed to foo_new
};
class Bar : public Spam {
public:
virtual void foo(int); // Renamed to foo_new
void foo(bool, short, int); // Renamed to foo_new
};
class Grok : public Bar {
public:
virtual void foo(int); // Renamed to foo_new
void foo(bool, int); // Renamed to foo_new
void foo(const char *); // Renamed to foo_new
void foo(Bar *); // Renamed to foo_new
};
class Spok : public Grok {
public:
void foo(); // Renamed to foo_new
};
class Knock : public Spok {
public:
using Grok::foo; // Introduced methods renamed to foo_new
};
</pre>
</div>
</p>
</li>
<li><p> <li><p>
The order in which <tt>%rename</tt> directives are defined does not matter The order in which <tt>%rename</tt> directives are defined does not matter
as long as they appear before the declarations to be renamed. Thus, there is no difference as long as they appear before the declarations to be renamed. Thus, there is no difference
@ -2944,6 +2993,59 @@ be used to extend a structure with more than just methods, a more suitable
directive name has been chosen. directive name has been chosen.
</p> </p>
<H3><a name="SWIGPlus_replacing_methods">6.17.1 Replacing class methods</a></H3>
<p>
Suppose there is a method in a class that you need to replace and keep the method name the same.
This can be achieved combining the <tt>%extend</tt> and <tt>%ignore</tt> directives covered earlier.
Here is an example to replace the <tt>MyClass::mymethod()</tt>:
<div class="code">
<pre>
%extend MyClass {
void mymethod() {
std::cout &lt;&lt; "swig mymethod" &lt;&lt; std::endl;
}
}
%ignore MyClass::mymethod;
%inline %{
class MyClass {
public:
void mymethod() {
std::cout &lt;&lt; "class mymethod" &lt;&lt; std::endl;
}
};
%}
</pre>
</div>
<p>
Or if your code organization makes more sense to put
the <tt>%extend</tt> after the class definition, you would need the following:
</p>
<div class="code">
<pre>
%rename("") MyClass::mymethod; // unignores the method
</pre>
</div>
<p>
before the <tt>%extend</tt> or SWIG will continue to ignore
<tt>mymethod()</tt>, even in an <tt>%extend</tt>.
</p>
<p>
Note that you can call the class method from the method
in <tt>%extend</tt>, just use <tt>self-&gt;mymethod()</tt> and it will call
the class method, not the one in <tt>%extend</tt>.
</p>
<H2><a name="SWIGPlus_nn30">6.18 Templates</a></H2> <H2><a name="SWIGPlus_nn30">6.18 Templates</a></H2>
@ -3632,7 +3734,7 @@ Alternatively, you could expand the constructor template in selected instantiati
// Create default and conversion constructors // Create default and conversion constructors
%extend pair&lt;double, double&gt; { %extend pair&lt;double, double&gt; {
%template(paird) pair&lt;double, dobule&gt;; // Default constructor %template(paird) pair&lt;double, double&gt;; // Default constructor
%template(pairc) pair&lt;int, int&gt;; // Conversion constructor %template(pairc) pair&lt;int, int&gt;; // Conversion constructor
}; };
</pre> </pre>
@ -3647,7 +3749,7 @@ instead:
<pre> <pre>
// Create default and conversion constructors // Create default and conversion constructors
%extend pair&lt;double, double&gt; { %extend pair&lt;double, double&gt; {
%template(pair) pair&lt;double, dobule&gt;; // Default constructor %template(pair) pair&lt;double, double&gt;; // Default constructor
%template(pair) pair&lt;int, int&gt;; // Conversion constructor %template(pair) pair&lt;int, int&gt;; // Conversion constructor
}; };
</pre> </pre>
@ -4017,23 +4119,23 @@ math::Complex c;
<p> <p>
At this level, namespaces are relatively easy to manage. However, things start to get At this level, namespaces are relatively easy to manage. However, things start to get
very ugly when you throw in the other ways a namespace can be used. For example, very ugly when you throw in the other ways a namespace can be used. For example,
selective symbols can be exported from a namespace with <tt>using</tt>. selective symbols can be exported from a namespace with a <tt>using</tt> declaration:
</p> </p>
<div class="code"> <div class="code">
<pre> <pre>
using math::Complex; using math::Complex; // Using declaration
double magnitude(Complex *c); // Namespace prefix stripped double magnitude(Complex *c); // Namespace prefix stripped
</pre> </pre>
</div> </div>
<p> <p>
Similarly, the contents of an entire namespace can be made available like this: Similarly, the contents of an entire namespace can be made available via a <tt>using</tt> directive:
</p> </p>
<div class="code"> <div class="code">
<pre> <pre>
using namespace math; using namespace math; // Using directive
double x = sin(1.0); double x = sin(1.0);
double magnitude(Complex *c); double magnitude(Complex *c);
</pre> </pre>
@ -4190,9 +4292,11 @@ Similarly, <tt>%ignore</tt> can be used to ignore declarations.
</p> </p>
<p> <p>
<tt>using</tt> declarations do not have any effect on the generated wrapper C++ <tt>using</tt> directives and <tt>using</tt> declarations
code. They are ignored by SWIG language modules and they do not result in any do not add any code to the generated wrapper code.
code. However, these declarations <em>are</em> used by the internal type However, there is an exception in one context, see <a href="#SWIGPlus_nn35">Using declarations and inheritance</a>
for introducing members of a base class into a derived class definition.
C++ <tt>using</tt> declarations and directives <em>are</em> used by the internal type
system to track type-names. Therefore, if you have code like this: system to track type-names. Therefore, if you have code like this:
</p> </p>
@ -5116,7 +5220,7 @@ exit # 'a' is released, SWIG unref 'a' called in the destructor wra
<p> <p>
<tt>using</tt> declarations are sometimes used to adjust access to members of C++ <tt>using</tt> declarations are sometimes used to introduce members of
base classes. For example: base classes. For example:
</p> </p>
@ -5124,7 +5228,7 @@ base classes. For example:
<pre> <pre>
class Foo { class Foo {
public: public:
int blah(int x); int blah(int x);
}; };
class Bar { class Bar {
@ -5172,7 +5276,8 @@ you wrap this code in Python, the module works just like you would expect:
</div> </div>
<p> <p>
<tt>using</tt> declarations can also be used to change access when applicable. For example: C++ <tt>using</tt> declarations can also be used to change access when applicable.
For example, protected methods in a base class can be made public in a derived class:
</p> </p>
<div class="code"> <div class="code">
@ -5205,15 +5310,15 @@ ignored in a base class, it will also be ignored by a <tt>using</tt> declaration
<p> <p>
Because a <tt>using</tt> declaration does not provide fine-grained Because a <tt>using</tt> declaration does not provide fine-grained
control over the declarations that get imported, it may be difficult control over the declarations that get imported, because a single <tt>using</tt> declaration
may introduce multiple methods, it may be difficult
to manage such declarations in applications that make heavy use of to manage such declarations in applications that make heavy use of
SWIG customization features. If you can't get <tt>using</tt> to work SWIG customization features. If you can't get <tt>using</tt> to work
correctly, you can always change the interface to the following: correctly, you can always modify the C++ code to handle SWIG differently such as:
</p> </p>
<div class="code"> <div class="code">
<pre> <pre>
class FooBar : public Foo, public Bar { class FooBar : public Foo, public Bar {
public: public:
#ifndef SWIG #ifndef SWIG
@ -5229,13 +5334,36 @@ public:
</pre> </pre>
</div> </div>
<p>
If the C++ code being wrapped cannot be changed, make judicious usage of <tt>%extend</tt> and <tt>%rename</tt>
to ignore and unignore declarations. The example below is effectively the same as above:
</p>
<div class="code">
<pre>
%extend FooBar {
int blah(int x) { return $self-&gt;Foo::blah(x); }
double blah(double x) { return $self-&gt;Bar::blah(x); }
}
%ignore FooBar::blah; // ignore all FooBar::blah below
%rename("") FooBar::blah(const char *x); // parameterized unignore
class FooBar : public Foo, public Bar {
public:
using Foo::blah;
using Bar::blah;
char *blah(const char *x);
};
</pre>
</div>
<p> <p>
<b>Notes:</b> <b>Notes:</b>
</p> </p>
<ul> <ul>
<li><p>If a derived class redefines a method defined in a base class, then a <tt>using</tt> declaration <li><p>If a derived class introduces a method defined in a base class via a <tt>using</tt> declaration,
won't cause a conflict. For example:</p> there won't be a conflict due to incorrect additional methods. For example:</p>
<div class="code"> <div class="code">
<pre> <pre>
@ -5247,14 +5375,14 @@ public:
class Bar : public Foo { class Bar : public Foo {
public: public:
using Foo::blah; // Only imports blah(double); using Foo::blah; // Only introduces blah(double);
int blah(int); int blah(int);
}; };
</pre> </pre>
</div> </div>
<li><p>Resolving ambiguity in overloading may prevent declarations from being <li><p>Renaming methods may prevent methods from being
imported by <tt>using</tt>. For example: introduced into the derived class via <tt>using</tt> declarations. For example:
</p> </p>
<div class="code"> <div class="code">
@ -5268,11 +5396,38 @@ public:
class Bar : public Foo { class Bar : public Foo {
public: public:
using Foo::blah; // Only imports blah(int) using Foo::blah; // Only introduces blah(int)
double blah(double x); double blah(double x);
}; };
</pre> </pre>
</div> </div>
<p>
The problem here is <tt>Foo::blah</tt> is renamed to <tt>blah_long</tt> in the target language, but
the <tt>using</tt> declaration in Bar is not renamed in the target language and thinks all introduced methods should simply
be called <tt>blah</tt>.
It is not clear what target language names should be used in Bar and so the conflicting names are effectively ignored
as they are not introduced into the derived class for the target language wrappers.
In such situations SWIG will emit a warning:
</p>
<div class="shell">
<pre>
example.i:15: Warning 526: Using declaration Foo::blah, with name 'blah', is not actually using
example.i:10: Warning 526: the method from Foo::blah(long), with name 'blah_long', as the names are different.
</pre>
</div>
<p>
<b>Compatibility Note:</b>
This warning message was introduced in SWIG-4.1.0.
Prior versions also effectively ignored the using declaration for the same reasons, but were silent about it.
</p>
<p>
If methods really need different names, please use of combinations of <tt>%rename</tt>, <tt>%ignore</tt> and <tt>%extend</tt> to achieve the desired outcome.
</p>
</ul> </ul>
<H2><a name="SWIGPlus_nested_classes">6.27 Nested classes</a></H2> <H2><a name="SWIGPlus_nested_classes">6.27 Nested classes</a></H2>

13
Doc/Manual/Scilab.html
View file

@ -304,11 +304,6 @@ The following table lists the Scilab specific command line options in addition t
<td>Generate the gateway XML with the given &lt;gateway_id&gt;</td> <td>Generate the gateway XML with the given &lt;gateway_id&gt;</td>
</tr> </tr>
<tr>
<td><tt>-targetversion</tt></td>
<td>Generate for Scilab target (major) version</td>
</tr>
</table> </table>
<p> <p>
@ -343,10 +338,6 @@ In Scilab 5.x, identifier names are composed of 24 characters maximum (this limi
In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a> can be used to choose a different Scilab name. In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a> can be used to choose a different Scilab name.
</p> </p>
<p>
Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>).
</p>
<H3><a name="Scilab_wrapping_functions">36.3.3 Functions</a></H3> <H3><a name="Scilab_wrapping_functions">36.3.3 Functions</a></H3>
@ -768,7 +759,7 @@ Pointers are supported by SWIG. A pointer can be returned from a wrapped C/C++ f
Also, thanks to the SWIG runtime which stores information about types, pointer types are tracked between exchanges Scilab and the native code. Indeed pointer types are stored alongside the pointer address. Also, thanks to the SWIG runtime which stores information about types, pointer types are tracked between exchanges Scilab and the native code. Indeed pointer types are stored alongside the pointer address.
A pointer is mapped to a Scilab structure (<a href="https://help.scilab.org/docs/5.5.2/en_US/tlist.html">tlist</a>), which contains as fields the pointer address and the pointer type (in fact a pointer to the type information structure in the SWIG runtime). A pointer is mapped to a Scilab structure (<a href="https://help.scilab.org/docs/5.5.2/en_US/tlist.html">tlist</a>), which contains as fields the pointer address and the pointer type (in fact a pointer to the type information structure in the SWIG runtime).
<br> <br>
Why a native pointer is not mapped to a Scilab pointer (type name: "pointer", type ID: 128) ? The big advantage of mapping to a <tt>tlist</tt> is that it exposes a new type for the pointer in Scilab, type which can be acessed in Scilab with the <a href="https://help.scilab.org/docs/5.5.2/en_US/typeof.html">typeof</a> function, and manipulated using the <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a> mechanism. Why a native pointer is not mapped to a Scilab pointer (type name: "pointer", type ID: 128) ? The big advantage of mapping to a <tt>tlist</tt> is that it exposes a new type for the pointer in Scilab, type which can be accessed in Scilab with the <a href="https://help.scilab.org/docs/5.5.2/en_US/typeof.html">typeof</a> function, and manipulated using the <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a> mechanism.
</p> </p>
<p> <p>
@ -776,7 +767,7 @@ Notes:
</p> </p>
<ul> <ul>
<li>type tracking needs the SWIG runtime to be first initialized with the appropriate function (see the <a href="#Scilab_module_initialization">Module initialization</a> section).</li> <li>type tracking needs the SWIG runtime to be first initialized with the appropriate function (see the <a href="#Scilab_module_initialization">Module initialization</a> section).</li>
<li>for any reason, if a wrapped pointer type is unknown (or if the SWIG runtime is not initialized), SWIG maps it to a Scilab pointer. Also, a Scilab pointer is always accepted as a pointer argument of a wrapped function. The drawaback is that pointer type is lost.</li> <li>for any reason, if a wrapped pointer type is unknown (or if the SWIG runtime is not initialized), SWIG maps it to a Scilab pointer. Also, a Scilab pointer is always accepted as a pointer argument of a wrapped function. The drawback is that pointer type is lost.</li>
</ul> </ul>
<p> <p>

16
Doc/Manual/Tcl.html
View file

@ -636,7 +636,7 @@ tcl:
<p> <p>
To build the extension, run NMAKE (you may need to run vcvars32 To build the extension, run NMAKE (you may need to run vcvars32
first). This is a pretty minimal Makefile, but hopefully its enough first). This is a pretty minimal Makefile, but hopefully it's enough
to get you started. With a little practice, you'll be making lots of to get you started. With a little practice, you'll be making lots of
Tcl extensions. Tcl extensions.
</p> </p>
@ -1227,7 +1227,15 @@ _108fea88_p_Bar
<p> <p>
Finally, to destroy objects created from Tcl, you can either let the object Finally, to destroy objects created from Tcl, you can either let the object
name go out of scope or you can explicitly delete the object. For example: name go out of scope or you can explicitly delete the object as shown below.
Objects won't get automatically destroyed when the Tcl program exits, so if
it's important that the C++ destructor is called for a class you'll need to
make sure that you explicitly do this for objects of that class before program
exit.
</p>
<p>
For example:
</p> </p>
<div class="code"> <div class="code">
@ -2811,9 +2819,7 @@ used as a <tt>char **</tt> object.
// This gives SWIG some cleanup code that will get called after the function call // This gives SWIG some cleanup code that will get called after the function call
%typemap(freearg) char ** { %typemap(freearg) char ** {
if ($1) { free($1);
free($1);
}
} }
// Now a test functions // Now a test functions

33
Doc/Manual/Typemaps.html
View file

@ -3103,7 +3103,7 @@ as shown. To work with heap allocated data, the following technique can be use
} }
} }
%typemap(freearg) float value[ANY] { %typemap(freearg) float value[ANY] {
if ($1) free($1); free($1);
} }
</pre> </pre>
</div> </div>
@ -3556,7 +3556,7 @@ maps perform the conversion described for the above example:
} }
%typemap(freearg) (int argc, char *argv[]) { %typemap(freearg) (int argc, char *argv[]) {
if ($2) free($2); free($2);
} }
/* Required for C++ method overloading */ /* Required for C++ method overloading */
@ -3835,7 +3835,7 @@ To eliminate this, define a fragment that includes the common marshalling code:
<p> <p>
When the "in" or "varin" typemaps for MyClass are required, the When the "in" or "varin" typemaps for MyClass are required, the
contents of the fragment called "AsMyClass" is added to the "header" section within the generated code, and then the contents of the fragment called "AsMyClass" are added to the "header" section within the generated code, and then the
typemap code is emitted. Hence, the method <tt>AsMyClass</tt> will be typemap code is emitted. Hence, the method <tt>AsMyClass</tt> will be
generated into the wrapper code before any typemap code that calls it. generated into the wrapper code before any typemap code that calls it.
</p> </p>
@ -3983,19 +3983,34 @@ inclusion of the other fragments.
<li> <li>
<p> <p>
A typemap can also use more than one fragment, but since the A typemap can also use more than one fragment:
syntax is different, you need to specify the dependent fragments in a comma separated
list. Consider:
</p> </p>
<div class="code"> <div class="code">
<pre> <pre>
%typemap(in, fragment="frag1, frag2, frag3") {...} %typemap("in", fragment="frag1", fragment="frag2", fragment="frag3") {...}
</pre> </pre>
</div> </div>
<p> <p>
which is equivalent to: <b>Compatibility note: </b> The ability to use multiple
<tt>fragment</tt> keys as shown above was introduced in SWIG-4.1.0.
</p>
<p>
Multiple fragments can alternatively be specified as a comma
separated list value in a single <tt>fragment</tt> key.
Note that no whitespace is allowed within this comma separated list.
The following is the equivalent to the above:
</p>
<div class="code">
<pre>
%typemap(in, fragment="frag1,frag2,frag3") {...}
</pre>
</div>
<p>
which in turn is functionally equivalent to:
</p> </p>
<div class="code"> <div class="code">

4
Doc/Manual/Warnings.html
View file

@ -428,6 +428,7 @@ example.i(4) : Syntax error in input(1).
<li>324. Named nested template instantiations not supported. Processing as if no name was given to %template(). <li>324. Named nested template instantiations not supported. Processing as if no name was given to %template().
<li>325. Nested <em>kind</em> not currently supported (<em>name</em> ignored). <li>325. Nested <em>kind</em> not currently supported (<em>name</em> ignored).
<li>326. Deprecated %extend name used - the <em>kind</em> name '<em>name</em>' should be used instead of the typedef name '<em>name</em>'. <li>326. Deprecated %extend name used - the <em>kind</em> name '<em>name</em>' should be used instead of the typedef name '<em>name</em>'.
<li>327. Extern template ignored.
<li>350. operator new ignored. <li>350. operator new ignored.
<li>351. operator delete ignored. <li>351. operator delete ignored.
<li>352. operator+ ignored. <li>352. operator+ ignored.
@ -483,7 +484,7 @@ example.i(4) : Syntax error in input(1).
<li>401. Nothing known about class 'name'. Ignored. <li>401. Nothing known about class 'name'. Ignored.
<li>402. Base class 'name' is incomplete. <li>402. Base class 'name' is incomplete.
<li>403. Class 'name' might be abstract. <li>403. Class 'name' might be abstract.
<li>450. Deprecated typemap feature ($source/$target). <li>450. Reserved
<li>451. Setting const char * variable may leak memory. <li>451. Setting const char * variable may leak memory.
<li>452. Reserved <li>452. Reserved
<li>453. Can't apply (pattern). No typemaps are defined. <li>453. Can't apply (pattern). No typemaps are defined.
@ -536,6 +537,7 @@ example.i(4) : Syntax error in input(1).
<li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'. <li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'.
<li>524. Experimental target language. Target language <em>language</em> specified by <em>lang</em> is an experimental language. Please read about SWIG experimental languages, <em>htmllink</em>. <li>524. Experimental target language. Target language <em>language</em> specified by <em>lang</em> is an experimental language. Please read about SWIG experimental languages, <em>htmllink</em>.
<li>525. Destructor <em>declaration</em> is final, <em>name</em> cannot be a director class. <li>525. Destructor <em>declaration</em> is final, <em>name</em> cannot be a director class.
<li>526. Using declaration <em>declaration</em>, with name '<em>name</em>', is not actually using the method from <em>declaration</em>, with name '<em>name</em>', as the names are different.
</ul> </ul>
<H3><a name="Warnings_doxygen">19.9.6 Doxygen comments (560-599)</a></H3> <H3><a name="Warnings_doxygen">19.9.6 Doxygen comments (560-599)</a></H3>

184
Doc/Manual/Windows.html
View file

@ -29,16 +29,16 @@
</ul> </ul>
<li><a href="#Windows_other_compilers">Instructions for using the Examples with other compilers</a> <li><a href="#Windows_other_compilers">Instructions for using the Examples with other compilers</a>
</ul> </ul>
<li><a href="#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</a>
<ul>
<li><a href="#Windows_swig_exe">Building swig.exe on Windows</a> <li><a href="#Windows_swig_exe">Building swig.exe on Windows</a>
<ul> <ul>
<li><a href="#Windows_cmake">Building swig.exe using CMake</a>
<li><a href="#Windows_msys2">Building swig.exe using MSYS2</a>
<li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a> <li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
<li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a> <li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a>
<li><a href="#Windows_building_alternatives">Building swig.exe alternatives</a> <ul>
</ul>
<li><a href="#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a> <li><a href="#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul> </ul>
</ul>
<li><a href="#Windows_interface_file">Microsoft extensions and other Windows quirks</a> <li><a href="#Windows_interface_file">Microsoft extensions and other Windows quirks</a>
</ul> </ul>
</div> </div>
@ -77,10 +77,10 @@ If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe
<p> <p>
Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output. Microsoft Visual C++ is the most commonly used compiler for compiling and linking SWIG's output on Windows.
The Examples directory has a few Visual C++ project files (.dsp files). The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6. These were produced by Visual C++ 6.
Newer versions of Visual Studio should be able to open and convert these project files. Newer versions of Visual Studio are able to open and convert these project files.
Each C# example comes with a Visual Studio 2005 solution and associated project files instead of Visual C++ 6 project files. Each C# example comes with a Visual Studio 2005 solution and associated project files instead of Visual C++ 6 project files.
The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file. The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file.
Alternatively run the <a href="#Windows_examples_cygwin">examples using Cygwin</a>. Alternatively run the <a href="#Windows_examples_cygwin">examples using Cygwin</a>.
@ -95,9 +95,11 @@ More information on each of the examples is available with the examples distribu
Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work. Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work.
Most languages require some environment variables to be set <b>before</b> running Visual C++. Most languages require some environment variables to be set <b>before</b> running Visual C++.
Note that Visual C++ must be re-started to pick up any changes in environment variables. Note that Visual C++ must be re-started to pick up any changes in environment variables.
Open up an example .dsp file, Visual C++ will create a workspace for you (.dsw file). Open up an example .dsp file, Visual C++ will prompt you to upgrade the project and convert
Ensure the Release build is selected then do a Rebuild All from the Build menu. it into an MSBuild project (.vcxproj file) and Solution (.sln file).
The required environment variables are displayed with their current values. Note that older versions of Visual C++ will simply create a workspace for you (.dsw file).
Ensure the Release build is selected then do a Rebuild Solution from the Build menu.
The required environment variables are displayed with their current values during the build.
</p> </p>
<p> <p>
The list of required environment variables for each module language is also listed below. The list of required environment variables for each module language is also listed below.
@ -111,7 +113,7 @@ If you are interested in how the project files are set up there is explanatory i
<p> <p>
The C# examples do not require any environment variables to be set as a C# project file is included. The C# examples do not require any environment variables to be set as a C# project file is included.
Just open up the .sln solution file in Visual Studio .NET 2003 or later, select Release Build, and do a Rebuild All from the Build menu. Just open up the .sln solution file in Visual Studio 2005 or later, select Release Build, and do a Rebuild Solution from the Build menu.
The accompanying C# and C++ project files are automatically used by the solution file. The accompanying C# and C++ project files are automatically used by the solution file.
</p> </p>
@ -207,24 +209,149 @@ RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section. If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section.
</p> </p>
<H2><a name="Windows_cygwin_mingw">3.3 SWIG on Cygwin and MinGW</a></H2> <H2><a name="Windows_swig_exe">3.3 Building swig.exe on Windows</a></H2>
<p> <p>
SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ISO C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. The SWIG distribution provides a pre-built swig.exe and so it is not necessary for users to build the SWIG executable.
However, this section is provided for those that want to modify the SWIG source code in a Windows environment.
Normally this is not needed, so most people will want to ignore this section.
</p> </p>
<H3><a name="Windows_swig_exe">3.3.1 Building swig.exe on Windows</a></H3> <p>
There are various ways to build the SWIG executable including <a href="https://cmake.org/">CMake</a> which is able to generate project files for building with Visual Studio.
SWIG can also be compiled and run using <a href="https://www.msys2.org/">MSYS2</a>, <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a>, all of which provide a Unix like front end to Windows and comes free with the gcc C/C++ compiler.
</p>
<H3><a name="Windows_cmake">3.3.1 Building swig.exe using CMake</a></H3>
<p> <p>
If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below. SWIG can be built using <a href="https://cmake.org/">CMake</a> and Visual Studio rather than autotools. As with the other approaches to
This is not necessary to use the supplied swig.exe. building SWIG the dependencies need to be installed. The steps below are one of a number of ways of installing the dependencies without requiring Cygwin or MinGW.
This information is provided for those that want to modify the SWIG source code in a Windows environment. For fully working build steps always check the Continuous Integration (CI) setups currently detailed in the <a href="https://github.com/swig/swig/blob/master/appveyor.yml">Appveyor YAML file</a>.
Normally this is not needed, so most people will want to ignore this section.
</p> </p>
<H4><a name="Windows_mingw_msys">3.3.1.1 Building swig.exe using MinGW and MSYS</a></H4> <ol>
<li>
Install Nuget from <a href="https://www.nuget.org/downloads">https://www.nuget.org/downloads</a> (v6.0.0 is used in this example, and installed to <tt>C:\Tools</tt>). Nuget is the package manager
for .NET, but allows us to easily install <a href="https://cmake.org/">CMake</a> and other dependencies required by SWIG.
</li>
<li>
Install <a href="https://www.nuget.org/packages/CMake-win64/">CMake-win64 Nuget package</a> using the following command: <pre>C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre>
Alternatively you can download CMake from <a href="https://cmake.org/download/">https://cmake.org/download/</a>.
</li>
<li>
Install the <a href="https://www.nuget.org/packages/bison/">Bison Nuget package</a> using the following command: <pre>C:\Tools\nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bison</pre>
Alternatively download Bison from <a href="https://sourceforge.net/projects/winflexbison/files/">https://sourceforge.net/projects/winflexbison/files/</a> (Bison 3.7.4 is used in this example)
and save to a folder e.g. <tt>C:\Tools\Bison</tt>
</li>
<li>
Unfortunately, PCRE2 is not yet available on Nuget. Instead we will use CMake to build and install <a href="https://www.pcre.org/">PCRE2</a> to <tt>C:\Tools\pcre2</tt> using the following commands:
<div class="shell"><pre>
cd C:\
SET PATH=C:\Tools\CMake\CMake-win64.3.15.5\bin;%PATH%
git clone https://github.com/PhilipHazel/pcre2.git
cd pcre2
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:/Tools/pcre2 -S . -B build
cmake --build build --config Release --target install
</pre></div>
Alternatively, set <tt>WITH_PCRE=OFF</tt> to disable PCRE2 support if you are sure you do not require it.
</li>
<li>
We will also need the SWIG source code. Either download a zipped archive from GitHub, or if git is installed clone the latest codebase
using <pre>git clone https://github.com/swig/swig.git</pre>
In this example we are assuming the source code is available at <tt>C:\swig</tt>
</li>
<li>
<p>
Now we have all the required dependencies we can build SWIG using the commands below. We are assuming Visual Studio 2019 is installed. For other versions of Visual Studio change <tt>"Visual Studio 16 2019 -A x64"</tt> to the relevant
<a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators">Visual Studio Generator</a> and
architecture. We add the required build tools to the system PATH, and then
build a Release version of SWIG. If all runs successfully a new swig.exe should be generated in the <tt>C:/swig/install2/bin</tt> folder.
</p>
<div class="shell"> <pre>
cd C:\swig
SET PATH=C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;%PATH%
SET PCRE_ROOT=C:/Tools/pcre2
SET PCRE_PLATFORM=x64
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX="%CD:\=/%/install2" -DCMAKE_C_FLAGS="/DPCRE2_STATIC" ^
-DCMAKE_CXX_FLAGS="/DPCRE2_STATIC" -DPCRE2_INCLUDE_DIR=%PCRE_ROOT%/include -DPCRE2_LIBRARY=%PCRE_ROOT%/lib/pcre2-8-static.lib -S . -B build
cmake --build build --config Release --target install
REM to test the exe
cd install2/bin
swig.exe -help
</pre></div>
</li>
</ol>
<p>
In addition to Release builds you can create a Debug build using:
</p>
<div class="shell">
<pre>cmake --build build --config Debug</pre>
</div>
<p>
A Visual Studio solution file should be generated named swig.sln. This can be opened and debugged by running the swig project and setting <tt>Properties &gt; Debugging &gt; Command Arguments</tt>. For example to debug one of the test-suite .i files included with the SWIG source use the following:
</p>
<div class="shell">
<pre>-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i</pre>
</div>
<H3><a name="Windows_msys2">3.3.2 Building swig.exe using MSYS2</a></H3>
<p>
Download and install MSYS2 from <a href="https://www.msys2.org/">www.msys2.org</a> (tested with version msys2-x86_64-20201109).
Launch the MSYS2 shell.
</p>
<p>
Install the packages needed to build swig:<br>
</p>
<div class="shell">
<pre>
pacman -S git autoconf automake bison gcc make pcre2-devel
</pre>
</div>
<p>
Clone the repository to /usr/src/:
</p>
<div class="shell">
<pre>
mkdir /usr/src/
cd /usr/src/
git clone https://github.com/swig/swig.git
</pre>
</div>
<p>
Configure and build:
</p>
<div class="shell">
<pre>
cd /usr/src/swig
./autogen.sh
./configure
make
</pre>
</div>
<p>
Finally you may also want to install SWIG:
</p>
<div class="shell">
<pre>
make install
</pre>
</div>
<H3><a name="Windows_mingw_msys">3.3.3 Building swig.exe using MinGW and MSYS</a></H3>
<p> <p>
@ -319,10 +446,10 @@ the autotools will fail miserably on those.
</li> </li>
<li> <li>
The PCRE third party library needs to be built next. The PCRE2 third party library needs to be built next.
Download the latest PCRE source tarball, such as <tt>pcre-8.10.tar.bz2</tt>, from Download the latest PCRE2 source tarball, such as <tt>pcre2-10.39.tar.bz2</tt>, from
<a href=http://www.pcre.org>PCRE</a> and place in the <tt>/usr/src/swig</tt> directory. <a href=http://www.pcre.org>www.pcre.org</a> and place in the <tt>/usr/src/swig</tt> directory.
Build PCRE as a static library using the Tools/pcre-build.sh script as follows: Build PCRE2 as a static library using the Tools/pcre-build.sh script as follows:
<div class="shell"><pre> <div class="shell"><pre>
cd /usr/src/swig cd /usr/src/swig
@ -342,7 +469,7 @@ make
</ol> </ol>
<H4><a name="Windows_cygwin">3.3.1.2 Building swig.exe using Cygwin</a></H4> <H3><a name="Windows_cygwin">3.3.4 Building swig.exe using Cygwin</a></H3>
<p> <p>
@ -353,17 +480,8 @@ Note that the Cygwin environment will also allow one to regenerate the autotool
These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system. These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
</p> </p>
<H4><a name="Windows_building_alternatives">3.3.1.3 Building swig.exe alternatives</a></H4>
<H4><a name="Windows_examples_cygwin">3.3.4.1 Running the examples on Windows using Cygwin</a></H4>
<p>
If you don't want to install Cygwin or MinGW, use a different compiler to build
SWIG. For example, all the source code files can be added to a Visual C++ project
file in order to build swig.exe from the Visual C++ IDE.
</p>
<H3><a name="Windows_examples_cygwin">3.3.2 Running the examples on Windows using Cygwin</a></H3>
<p> <p>

70
Examples/Makefile.in
View file

@ -165,6 +165,7 @@ TCL_SO = @TCL_SO@
TCLLDSHARED = @TCLLDSHARED@ TCLLDSHARED = @TCLLDSHARED@
TCLCXXSHARED = @TCLCXXSHARED@ TCLCXXSHARED = @TCLCXXSHARED@
TCL_SCRIPT = $(SRCDIR)$(RUNME).tcl TCL_SCRIPT = $(SRCDIR)$(RUNME).tcl
TCL_LINK = @TCLLINK@
# ----------------------------------------------------------- # -----------------------------------------------------------
# Build a new version of the tclsh shell # Build a new version of the tclsh shell
@ -187,7 +188,7 @@ tclsh_cpp: $(SRCDIR_SRCS)
tcl: $(SRCDIR_SRCS) tcl: $(SRCDIR_SRCS)
$(SWIG) -tcl8 $(SWIGOPT) $(TCL_SWIGOPTS) -o $(ISRCS) $(INTERFACEPATH) $(SWIG) -tcl8 $(SWIGOPT) $(TCL_SWIGOPTS) -o $(ISRCS) $(INTERFACEPATH)
$(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(ISRCS) $(INCLUDES) $(TCL_INCLUDE) $(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(ISRCS) $(INCLUDES) $(TCL_INCLUDE)
$(TCLLDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO) $(TCLLDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO) $(TCL_LINK)
# ----------------------------------------------------------- # -----------------------------------------------------------
# Build a Tcl7.5 dynamic loadable module for C++ # Build a Tcl7.5 dynamic loadable module for C++
@ -196,7 +197,7 @@ tcl: $(SRCDIR_SRCS)
tcl_cpp: $(SRCDIR_SRCS) tcl_cpp: $(SRCDIR_SRCS)
$(SWIG) -tcl8 -c++ $(SWIGOPT) $(TCL_SWIGOPTS) -o $(ICXXSRCS) $(INTERFACEPATH) $(SWIG) -tcl8 -c++ $(SWIGOPT) $(TCL_SWIGOPTS) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(ICXXSRCS) $(INCLUDES) $(TCL_INCLUDE) $(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(ICXXSRCS) $(INCLUDES) $(TCL_INCLUDE)
$(TCLCXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO) $(TCLCXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO) $(TCL_LINK)
# ----------------------------------------------------------------- # -----------------------------------------------------------------
# Run Tcl example # Run Tcl example
@ -381,13 +382,7 @@ python_static_cpp: $(SRCDIR_SRCS)
# Running a Python example # Running a Python example
# ----------------------------------------------------------------- # -----------------------------------------------------------------
ifeq (,$(PY3)) PYSCRIPT = $(RUNME).py
PYSCRIPT = $(RUNME).py
else
PYSCRIPT = $(RUNME)3.py
endif
PY2TO3 = @PY2TO3@ `@PY2TO3@ -l | grep -v -E "Available|import$$" | awk '{print "-f "$$0}'`
python_run: $(PYSCRIPT) python_run: $(PYSCRIPT)
ifneq (,$(PYCODESTYLE)) ifneq (,$(PYCODESTYLE))
@ -400,10 +395,6 @@ $(RUNME).py: $(SRCDIR)$(RUNME).py
cp $< $@ cp $< $@
endif endif
$(RUNME)3.py: $(SRCDIR)$(RUNME).py
cp $< $@
$(PY2TO3) -w $@ >/dev/null 2>&1
# ----------------------------------------------------------------- # -----------------------------------------------------------------
# Version display # Version display
# ----------------------------------------------------------------- # -----------------------------------------------------------------
@ -421,7 +412,6 @@ python_clean:
rm -f core @EXTRA_CLEAN@ rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *@SO@ *$(PYTHON_SO) rm -f *.@OBJEXT@ *@SO@ *$(PYTHON_SO)
rm -f $(TARGET).py rm -f $(TARGET).py
if test -f $(SRCDIR)$(RUNME).py; then rm -f $(RUNME)3.py $(RUNME)3.py.bak; fi
case "x$(SRCDIR)" in x|x./);; *) rm -f $(RUNME).py;; esac case "x$(SRCDIR)" in x|x./);; *) rm -f $(RUNME).py;; esac
@ -1056,20 +1046,21 @@ ruby_clean:
rm -f *.@OBJEXT@ *$(RUBY_SO) rm -f *.@OBJEXT@ *$(RUBY_SO)
################################################################## ##################################################################
##### PHP7 ###### ##### PHP ######
################################################################## ##################################################################
PHP = @PHP@ PHP = @PHP@
PHP_INCLUDE = @PHPINC@ PHP_INCLUDE = @PHPINC@
PHP_SO = @PHP_SO@ PHP_SO = @PHP_SO@
PHP_SCRIPT = $(SRCDIR)$(RUNME).php PHP_SCRIPT = $(SRCDIR)$(RUNME).php
PHP_EXTENSION = example$(PHP_SO)
# ------------------------------------------------------------------- # -------------------------------------------------------------------
# Build a PHP dynamically loadable module (C) # Build a PHP dynamically loadable module (C)
# ------------------------------------------------------------------- # -------------------------------------------------------------------
php: $(SRCDIR_SRCS) php: $(SRCDIR_SRCS)
$(SWIG) -php7 $(SWIGOPT) -o $(ISRCS) $(INTERFACEPATH) $(SWIG) -php $(SWIGOPT) -o $(ISRCS) $(INTERFACEPATH)
$(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(ISRCS) $(INCLUDES) $(PHP_INCLUDE) $(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(ISRCS) $(INCLUDES) $(PHP_INCLUDE)
$(LDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(PHP_SO) $(LDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(PHP_SO)
@ -1078,7 +1069,7 @@ php: $(SRCDIR_SRCS)
# -------------------------------------------------------------------- # --------------------------------------------------------------------
php_cpp: $(SRCDIR_SRCS) php_cpp: $(SRCDIR_SRCS)
$(SWIG) -php7 -c++ $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH) $(SWIG) -php -c++ $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(ICXXSRCS) $(INCLUDES) $(PHP_INCLUDE) $(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(ICXXSRCS) $(INCLUDES) $(PHP_INCLUDE)
$(CXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(PHP_SO) $(CXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(PHP_SO)
@ -1087,7 +1078,7 @@ php_cpp: $(SRCDIR_SRCS)
# ----------------------------------------------------------------- # -----------------------------------------------------------------
php_run: php_run:
$(RUNTOOL) $(PHP) -n -q -d extension_dir=. -d safe_mode=Off -d display_errors=stderr $(PHP_SCRIPT) $(RUNPIPE) $(RUNTOOL) $(PHP) -n -d extension_dir=. -d extension=$(PHP_EXTENSION) -d display_errors=stderr -r 'set_error_handler(function($$n,$$s,$$f,$$l){if($$f!==Null){print$$f;if($$l!==Null)print":$$l";print": ";}print"$$s\n";exit(1);});include($$argv[1]);' $(PHP_SCRIPT) $(RUNPIPE)
# ----------------------------------------------------------------- # -----------------------------------------------------------------
# Version display # Version display
@ -1259,46 +1250,6 @@ lua_clean:
rm -f core @EXTRA_CLEAN@ rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *$(LUA_SO) rm -f *.@OBJEXT@ *$(LUA_SO)
##################################################################
##### ALLEGRO CL ######
##################################################################
ALLEGROCL = @ALLEGROCLBIN@
ALLEGROCL_SCRIPT=$(RUNME).lisp
allegrocl: $(SRCDIR_SRCS)
$(SWIG) -allegrocl -cwrap $(SWIGOPT) -o $(ISRCS) $(INTERFACEPATH)
$(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(ISRCS) $(INCLUDES) $(SRCDIR_SRCS)
$(LDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(SO)
allegrocl_cpp: $(SRCDIR_SRCS)
$(SWIG) -c++ -allegrocl $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(ICXXSRCS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(INCLUDES)
$(CXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(SO)
# -----------------------------------------------------------------
# Run ALLEGRO CL example
# -----------------------------------------------------------------
allegrocl_run:
$(RUNTOOL) $(ALLEGROCL) -batch -s $(ALLEGROCL_SCRIPT) $(RUNPIPE)
# -----------------------------------------------------------------
# Version display
# -----------------------------------------------------------------
allegrocl_version:
$(ALLEGROCL) --version
# -----------------------------------------------------------------
# Cleaning the ALLEGRO CL examples
# -----------------------------------------------------------------
allegrocl_clean:
rm -f *_wrap* *~ .~*
rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *@SO@
################################################################## ##################################################################
##### CFFI ###### ##### CFFI ######
################################################################## ##################################################################
@ -1406,6 +1357,7 @@ r_clean:
SCILAB = @SCILAB@ SCILAB = @SCILAB@
SCILAB_INC= @SCILABINCLUDE@ SCILAB_INC= @SCILABINCLUDE@
SCILAB_OPT = @SCILABOPT@ SCILAB_OPT = @SCILABOPT@
SCILAB_VERSION = @SCILAB_VERSION@
SCILAB_LIBPREFIX = lib SCILAB_LIBPREFIX = lib
# ---------------------------------------------------------------- # ----------------------------------------------------------------
@ -1438,7 +1390,7 @@ scilab_run:
# ----------------------------------------------------------------- # -----------------------------------------------------------------
scilab_version: scilab_version:
echo `$(SCILAB) -version | head -1` echo `$(SCILAB) -nwni -version | head -1`
# ----------------------------------------------------------------- # -----------------------------------------------------------------
# Cleaning the scilab examples # Cleaning the scilab examples

12
Examples/chicken/README
View file

@ -1,12 +0,0 @@
This directory contains examples for CHICKEN.
class -- illustrates the proxy class C++ interface
constants -- handling #define and %constant literals
egg -- examples of building chicken extension libraries
multimap -- typemaps with multiple sub-types
overload -- C++ function overloading
simple -- the simple example from the user manual
zlib -- a wrapping of the zlib compression library
You should be able to run make in each of the examples. By default, a shared
library will be built. Run make check to execute the test.

6
Examples/chicken/check.list
View file

@ -1,6 +0,0 @@
# see top-level Makefile.in
class
constants
multimap
overload
simple

40
Examples/chicken/class/Makefile
View file

@ -1,40 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS =
CXXSRCS = example.cxx
TARGET = class
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following lines to build a static exe (only pick one of the CHICKEN_MAIN lines)
#CHICKEN_MAIN = runme-lowlevel.scm
#CHICKEN_MAIN = runme-tinyclos.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CHICKEN_SCRIPT='runme-lowlevel.scm' chicken_run
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CHICKEN_SCRIPT='runme-tinyclos.scm' chicken_run
build: $(TARGET) $(TARGET)_proxy
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
$(TARGET)_proxy: $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT) -proxy' TARGET='$(TARGET)_proxy' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

28
Examples/chicken/class/example.cxx
View file

@ -1,28 +0,0 @@
/* File : example.cxx */
#include "example.h"
#define M_PI 3.14159265358979323846
/* Move the shape to a new location */
void Shape::move(double dx, double dy) {
x += dx;
y += dy;
}
int Shape::nshapes = 0;
double Circle::area() {
return M_PI*radius*radius;
}
double Circle::perimeter() {
return 2*M_PI*radius;
}
double Square::area() {
return width*width;
}
double Square::perimeter() {
return 4*width;
}

41
Examples/chicken/class/example.h
View file

@ -1,41 +0,0 @@
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
}
double x, y;
void move(double dx, double dy);
virtual double area() = 0;
virtual double perimeter() = 0;
static int nshapes;
enum SomeEnum {
First = 0,
Second,
Third,
Last = 1000
};
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { }
virtual double area();
virtual double perimeter();
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { }
virtual double area();
virtual double perimeter();
};

9
Examples/chicken/class/example.i
View file

@ -1,9 +0,0 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"

76
Examples/chicken/class/runme-lowlevel.scm
View file

@ -1,76 +0,0 @@
;; This file illustrates the low-level C++ interface generated
;; by SWIG.
(load-library 'example "class.so")
(declare (uses example))
;; ----- Object creation -----
(display "Creating some objects:\n")
(define c (new-Circle 10.0))
(display " Created circle ")
(display c)
(display "\n")
(define s (new-Square 10.0))
(display " Created square ")
(display s)
(display "\n")
;; ----- Access a static member -----
(display "\nA total of ")
(display (Shape-nshapes))
(display " shapes were created\n")
;; ----- Member data access -----
;; Set the location of the object
(Shape-x-set c 20.0)
(Shape-y-set c 30.0)
(Shape-x-set s -10.0)
(Shape-y-set s 5.0)
(display "\nHere is their current position:\n")
(display " Circle = (")
(display (Shape-x-get c))
(display ", ")
(display (Shape-y-get c))
(display ")\n")
(display " Square = (")
(display (Shape-x-get s))
(display ", ")
(display (Shape-y-get s))
(display ")\n")
;; ----- Call some methods -----
(display "\nHere are some properties of the shapes:\n")
(let
((disp (lambda (o)
(display " ")
(display o)
(display "\n")
(display " area = ")
(display (Shape-area o))
(display "\n")
(display " perimeter = ")
(display (Shape-perimeter o))
(display "\n"))))
(disp c)
(disp s))
(display "\nGuess I'll clean up now\n")
;; Note: this invokes the virtual destructor
(set! c #f)
(set! s #f)
(gc #t)
(set! s 3)
(display (Shape-nshapes))
(display " shapes remain\n")
(display "Goodbye\n")
(exit)

76
Examples/chicken/class/runme-tinyclos.scm
View file

@ -1,76 +0,0 @@
;; This file illustrates the proxy C++ interface generated
;; by SWIG.
(load-library 'example "class_proxy.so")
(declare (uses example))
(declare (uses tinyclos))
;; ----- Object creation -----
(display "Creating some objects:\n")
(define c (make <Circle> 10.0))
(display " Created circle ")
(display c)
(display "\n")
(define s (make <Square> 10.0))
(display " Created square ")
(display s)
(display "\n")
;; ----- Access a static member -----
(display "\nA total of ")
(display (Shape-nshapes))
(display " shapes were created\n")
;; ----- Member data access -----
;; Set the location of the object
(slot-set! c 'x 20.0)
(slot-set! c 'y 30.0)
(slot-set! s 'x -10.0)
(slot-set! s 'y 5.0)
(display "\nHere is their current position:\n")
(display " Circle = (")
(display (slot-ref c 'x))
(display ", ")
(display (slot-ref c 'y))
(display ")\n")
(display " Square = (")
(display (slot-ref s 'x))
(display ", ")
(display (slot-ref s 'y))
(display ")\n")
;; ----- Call some methods -----
(display "\nHere are some properties of the shapes:\n")
(let
((disp (lambda (o)
(display " ")
(display o)
(display "\n")
(display " area = ")
(display (area o))
(display "\n")
(display " perimeter = ")
(display (perimeter o))
(display "\n"))))
(disp c)
(disp s))
(display "\nGuess I'll clean up now\n")
;; Note: Invoke the virtual destructors by forcing garbage collection
(set! c 77)
(set! s 88)
(gc #t)
(display (Shape-nshapes))
(display " shapes remain\n")
(display "Goodbye\n")
(exit)

31
Examples/chicken/constants/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS =
CXXSRCS =
TARGET = constants
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following two lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

27
Examples/chicken/constants/example.i
View file

@ -1,27 +0,0 @@
/* File : example.i */
%module example
/* A few preprocessor macros */
#define ICONST 42
#define FCONST 2.1828
#define CCONST 'x'
#define CCONST2 '\n'
#define SCONST "Hello World"
#define SCONST2 "\"Hello World\""
/* This should work just fine */
#define EXPR ICONST + 3*(FCONST)
/* This shouldn't do anything */
#define EXTERN extern
/* Neither should this (BAR isn't defined) */
#define FOO (ICONST + BAR)
/* The following directives also produce constants. Remember that
CHICKEN is normally case-insensitive, so don't rely on differing
case to differentiate variable names */
%constant int iconstX = 37;
%constant double fconstX = 3.14;

16
Examples/chicken/constants/runme.scm
View file

@ -1,16 +0,0 @@
;; feel free to uncomment and comment sections
(load-library 'example "./constants.so")
(display "starting test ... you will see 'finished' if successful.\n")
(or (= (ICONST) 42) (exit 1))
(or (< (abs (- (FCONST) 2.1828)) 0.00001) (exit 1))
(or (char=? (CCONST) #\x) (exit 1))
(or (char=? (CCONST2) #\newline) (exit 1))
(or (string=? (SCONST) "Hello World") (exit 1))
(or (string=? (SCONST2) "\"Hello World\"") (exit 1))
(or (< (abs (- (EXPR) (+ (ICONST) (* 3 (FCONST))))) 0.00001) (exit 1))
(or (= (iconstX) 37) (exit 1))
(or (< (abs (- (fconstX) 3.14)) 0.00001) (exit 1))
(display "finished test.\n")
(exit 0)

41
Examples/chicken/egg/Makefile
View file

@ -1,41 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
check: build
cd eggs/install && csi ../../test.scm
build: single multi
# This creates an egg which contains only the single module. Any additional implementation files
# that implement the interface being wrapped should also be added to this egg
single: single_wrap.cxx
mkdir -p eggs
tar czf eggs/single.egg single.setup single.scm single_wrap.cxx
rm -f single.scm single_wrap.cxx
# compile the single module with -nounit
single_wrap.cxx: single.i
$(SWIGEXE) -chicken -c++ -proxy -nounit single.i
# Now build both mod1 and mod2 into a single egg
multi: mod1_wrap.cxx mod2_wrap.cxx
mkdir -p eggs
tar czf eggs/multi.egg multi.setup multi_init.scm mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx
rm -f mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx
mod1_wrap.cxx: mod1.i
$(SWIGEXE) -chicken -c++ -proxy mod1.i
mod2_wrap.cxx: mod2.i
$(SWIGEXE) -chicken -c++ -proxy mod2.i
clean:
rm -rf eggs
# this part is for testing...
setup:
cd eggs && \
mkdir -p install && \
chicken-setup -repository `pwd`/install single.egg && \
chicken-setup -repository `pwd`/install multi.egg

19
Examples/chicken/egg/README
View file

@ -1,19 +0,0 @@
These examples show how to build a chicken extension module in the form of an
egg. There are two eggs that get built, single.egg which contains a single
module which is built with -nounit and multi.egg, which contains two modules
mod1 and mod2. These are built normally, and multi_init.scm loads them both.
Read section "17.4.2 Building chicken extension libraries" in the manual
for a description of these two techniques.
To build:
$ make
$ make setup
$ make run
$ make clean
The eggs are built into an eggs subdirectory, because chicken-setup has
problems installing eggs when there are other files named similar in
the same directory. The make setup step runs chicken-setup to install
the eggs into the eggs/install directory.

8
Examples/chicken/egg/mod1.i
View file

@ -1,8 +0,0 @@
%module mod1
%inline %{
class Bar {
public:
int b;
};
%}

17
Examples/chicken/egg/mod2.i
View file

@ -1,17 +0,0 @@
%module mod2
%import "mod1.i"
%{
class Bar {
public:
int b;
};
%}
%inline %{
class Bar2 : public Bar {
public:
int c;
};
%}

2
Examples/chicken/egg/multi.setup
View file

@ -1,2 +0,0 @@
(run (csc -s -o multi.so multi_init.scm mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx))
(install-extension 'multi '("multi.so"))

2
Examples/chicken/egg/multi_init.scm
View file

@ -1,2 +0,0 @@
(declare (uses mod1))
(declare (uses mod2))

8
Examples/chicken/egg/single.i
View file

@ -1,8 +0,0 @@
%module single
%inline %{
class Foo {
public:
int a;
};
%}

2
Examples/chicken/egg/single.setup
View file

@ -1,2 +0,0 @@
(run (csc -s -o single.so single.scm single_wrap.cxx))
(install-extension 'single '("single.so"))

18
Examples/chicken/egg/test.scm
View file

@ -1,18 +0,0 @@
(require-extension single)
(require-extension multi)
(define f (make <Foo>))
(slot-set! f 'a 3)
(print (slot-ref f 'a))
(define b (make <Bar>))
(slot-set! b 'b 2)
(print (slot-ref b 'b))
(define b2 (make <Bar2>))
(slot-set! b2 'b 4)
(slot-set! b2 'c 6)
(print (slot-ref b2 'b))
(print (slot-ref b2 'c))
(exit 0)

31
Examples/chicken/multimap/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS = example.c
CXXSRCS =
TARGET = multimap
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following two lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

53
Examples/chicken/multimap/example.c
View file

@ -1,53 +0,0 @@
/* File : example.c */
#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
/* Compute the greatest common divisor of positive integers */
int gcd(int x, int y) {
int g;
g = y;
while (x > 0) {
g = x;
x = y % x;
y = g;
}
return g;
}
int gcdmain(int argc, char *argv[]) {
int x,y;
if (argc != 3) {
printf("usage: gcd x y\n");
return -1;
}
x = atoi(argv[1]);
y = atoi(argv[2]);
printf("gcd(%d,%d) = %d\n", x,y,gcd(x,y));
return 0;
}
int count(char *bytes, int len, char c) {
int i;
int count = 0;
for (i = 0; i < len; i++) {
if (bytes[i] == c) count++;
}
return count;
}
void capitalize(char *str, int len) {
int i;
for (i = 0; i < len; i++) {
str[i] = (char)toupper(str[i]);
}
}
void circle(double x, double y) {
double a = x*x + y*y;
if (a > 1.0) {
printf("Bad points %g, %g\n", x,y);
} else {
printf("Good points %g, %g\n", x,y);
}
}

96
Examples/chicken/multimap/example.i
View file

@ -1,96 +0,0 @@
/* File : example.i */
%module example
%{
extern int gcd(int x, int y);
extern int gcdmain(int argc, char *argv[]);
extern int count(char *bytes, int len, char c);
extern void capitalize (char *str, int len);
extern void circle (double cx, double cy);
extern int squareCubed (int n, int *OUTPUT);
%}
%include exception.i
%include typemaps.i
extern int gcd(int x, int y);
%typemap(in) (int argc, char *argv[]) {
int i;
if (!C_swig_is_vector ($input)) {
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, "Argument $input is not a vector");
}
$1 = C_header_size ($input);
$2 = (char **) malloc(($1+1)*sizeof(char *));
for (i = 0; i < $1; i++) {
C_word o = C_block_item ($input, i);
if (!C_swig_is_string (o)) {
char err[50];
free($2);
sprintf (err, "$input[%d] is not a string", i);
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, err);
}
$2[i] = C_c_string (o);
}
$2[i] = 0;
}
%typemap(freearg) (int argc, char *argv[]) {
free($2);
}
extern int gcdmain(int argc, char *argv[]);
%typemap(in) (char *bytes, int len) {
if (!C_swig_is_string ($input)) {
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, "Argument $input is not a string");
}
$1 = C_c_string ($input);
$2 = C_header_size ($input);
}
extern int count(char *bytes, int len, char c);
/* This example shows how to wrap a function that mutates a string */
%typemap(in) (char *str, int len)
%{ if (!C_swig_is_string ($input)) {
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, "Argument $input is not a string");
}
$2 = C_header_size ($input);
$1 = (char *) malloc ($2+1);
memmove ($1, C_c_string ($input), $2);
%}
/* Return the mutated string as a new object. Notice the if MANY construct ... they must be at column 0. */
%typemap(argout) (char *str, int len) (C_word *scmstr)
%{ scmstr = C_alloc (C_SIZEOF_STRING ($2));
SWIG_APPEND_VALUE(C_string (&scmstr, $2, $1));
free ($1);
%}
extern void capitalize (char *str, int len);
/* A multi-valued constraint. Force two arguments to lie
inside the unit circle */
%typemap(check) (double cx, double cy) {
double a = $1*$1 + $2*$2;
if (a > 1.0) {
SWIG_exception (SWIG_ValueError, "cx and cy must be in unit circle");
}
}
extern void circle (double cx, double cy);
/* Test out multiple return values */
extern int squareCubed (int n, int *OUTPUT);
%{
/* Returns n^3 and set n2 to n^2 */
int squareCubed (int n, int *n2) {
*n2 = n * n;
return (*n2) * n;
};
%}

58
Examples/chicken/multimap/runme.scm
View file

@ -1,58 +0,0 @@
;; feel free to uncomment and comment sections
(load-library 'example "multimap.so")
(display "(gcd 90 12): ")
(display (gcd 90 12))
(display "\n")
(display "(circle 0.5 0.5): ")
(display (circle 0.5 0.5))
(display "\n")
(display "(circle 1.0 1.0): ")
(handle-exceptions exvar
(if (= (car exvar) 9)
(display "success: exception thrown")
(display "an incorrect exception was thrown"))
(begin
(circle 1.0 1.0)
(display "an exception was not thrown when it should have been")))
(display "\n")
(display "(circle 1 1): ")
(handle-exceptions exvar
(if (= (car exvar) 9)
(display "success: exception thrown")
(display "an incorrect exception was thrown"))
(begin
(circle 1 1)
(display "an exception was not thrown when it should have been")))
(display "\n")
(display "(capitalize \"will this be all capital letters?\"): ")
(display (capitalize "will this be all capital letters?"))
(display "\n")
(display "(count \"jumpity little spider\" #\\t): ")
(display (count "jumpity little spider" #\t))
(display "\n")
(display "(gcdmain '#(\"hi\" \"there\")): ")
(display (gcdmain '#("hi" "there")))
(display "\n")
(display "(gcdmain '#(\"gcd\" \"9\" \"28\")): ")
(gcdmain '#("gcd" "9" "28"))
(display "\n")
(display "(gcdmain '#(\"gcd\" \"12\" \"90\")): ")
(gcdmain '#("gcd" "12" "90"))
(display "\n")
(display "squarecubed 3: ")
(call-with-values (lambda() (squareCubed 3))
(lambda (a b) (printf "~A ~A" a b)))
(display "\n")
(exit)

31
Examples/chicken/overload/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS =
CXXSRCS = example.cxx
TARGET = overload
INCLUDE =
SWIGOPT = -proxy -unhideprimitive
VARIANT =
# uncomment the following lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

2
Examples/chicken/overload/README
View file

@ -1,2 +0,0 @@
Overloading example from Chapter 5.14 of SWIG Core Documentation for
version 1.3.

33
Examples/chicken/overload/example.cxx
View file

@ -1,33 +0,0 @@
/* File : example.c */
#include "example.h"
#include <stdio.h>
void foo(int x) {
printf("x is %d\n", x);
}
void foo(char *x) {
printf("x is '%s'\n", x);
}
Foo::Foo () {
myvar = 55;
printf ("Foo constructor called\n");
}
Foo::Foo (const Foo &) {
myvar = 66;
printf ("Foo copy constructor called\n");
}
void Foo::bar (int x) {
printf ("Foo::bar(x) method ... \n");
printf("x is %d\n", x);
}
void Foo::bar (char *s, int y) {
printf ("Foo::bar(s,y) method ... \n");
printf ("s is '%s'\n", s);
printf ("y is %d\n", y);
}

14
Examples/chicken/overload/example.h
View file

@ -1,14 +0,0 @@
/* File : example.h */
extern void foo (int x);
extern void foo (char *x);
class Foo {
private:
int myvar;
public:
Foo();
Foo(const Foo &); // Copy constructor
void bar(int x);
void bar(char *s, int y);
};

16
Examples/chicken/overload/example.i
View file

@ -1,16 +0,0 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let "Foo" objects be converted back and forth from TinyCLOS into
low-level CHICKEN SWIG procedures */
%typemap(clos_in) Foo * = SIMPLE_CLOS_OBJECT *;
%typemap(clos_out) Foo * = SIMPLE_CLOS_OBJECT *;
/* Let's just grab the original header file here */
%include "example.h"

45
Examples/chicken/overload/runme.scm
View file

@ -1,45 +0,0 @@
;; This file demonstrates the overloading capabilities of SWIG
(load-library 'example "overload.so")
;; Low level
;; ---------
(display "
Trying low level code ...
(foo 1)
(foo \"some string\")
(define A-FOO (new-Foo))
(define ANOTHER-FOO (new-Foo A-FOO)) ;; copy constructor
(Foo-bar A-FOO 2)
(Foo-bar ANOTHER-FOO \"another string\" 3)
")
(primitive:foo 1)
(primitive:foo "some string")
(define A-FOO (slot-ref (primitive:new-Foo) 'swig-this))
(define ANOTHER-FOO (slot-ref (primitive:new-Foo A-FOO) 'swig-this)) ;; copy constructor
(primitive:Foo-bar A-FOO 2)
(primitive:Foo-bar ANOTHER-FOO "another string" 3)
;; TinyCLOS
;; --------
(display "
Trying TinyCLOS code ...
(+foo+ 1)
(+foo+ \"some string\")
(define A-FOO (make <Foo>))
(define ANOTHER-FOO (make <Foo> A-FOO)) ;; copy constructor
(-bar- A-FOO 2)
(-bar- ANOTHER-FOO \"another string\" 3)
")
(foo 1)
(foo "some string")
(define A-FOO (make <Foo>))
(define ANOTHER-FOO (make <Foo> A-FOO)) ;; copy constructor
(bar A-FOO 2)
(bar ANOTHER-FOO "another string" 3)
(exit)

31
Examples/chicken/simple/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS = example.c
CXXSRCS =
TARGET = simple
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following two lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm example-generic.scm example-clos.scm
rm -f $(TARGET)

1
Examples/chicken/simple/README
View file

@ -1 +0,0 @@
Simple example from users manual.

24
Examples/chicken/simple/example.c
View file

@ -1,24 +0,0 @@
/* Simple example from documentation */
/* File : example.c */
#include <time.h>
double My_variable = 3.0;
/* Compute factorial of n */
int fact(int n) {
if (n <= 1) return 1;
else return n*fact(n-1);
}
/* Compute n mod m */
int my_mod(int n, int m) {
return (n % m);
}
char *get_time() {
long ltime;
time(&ltime);
return ctime(&ltime);
}

16
Examples/chicken/simple/example.i
View file

@ -1,16 +0,0 @@
/* File : example.i */
%module example
%{
/* Put headers and other declarations here */
%}
%include typemaps.i
%rename(mod) my_mod;
%inline %{
extern double My_variable;
extern int fact(int);
extern int my_mod(int n, int m);
extern char *get_time();
%}

28
Examples/chicken/simple/runme.scm
View file

@ -1,28 +0,0 @@
;; feel free to uncomment and comment sections
(load-library 'example "simple.so")
(display "(My-variable): ")
(display (My-variable))
(display "\n")
(display "(My-variable 3.141259): ")
(display (My-variable 3.141259))
(display "\n")
(display "(My-variable): ")
(display (My-variable))
(display "\n")
(display "(fact 5): ")
(display (fact 5))
(display "\n")
(display "(mod 75 7): ")
(display (mod 75 7))
(display "\n")
(display "(get-time): ")
(display (get-time))
(display "\n")
(exit)

11
Examples/contract/simple_c/example.c
View file

@ -1,11 +0,0 @@
#include <stdio.h>
int Circle (int x, int y, int radius) {
/* Draw Circle */
printf("Drawing the circle...\n");
/* Return -1 to test contract post assertion */
if (radius == 2)
return -1;
else
return 1;
}

19
Examples/contract/simple_c/example.i
View file

@ -1,19 +0,0 @@
/* File : example.i */
/* Basic C example for swig contract */
/* Tiger, University of Chicago, 2003 */
%module example
%contract Circle (int x, int y, int radius) {
require:
x >= 0;
y >= 0;
radius > x;
ensure:
Circle >= 0;
}
%inline %{
extern int Circle (int x, int y, int radius);
%}

17
Examples/contract/simple_c/runme1.py
View file

@ -1,17 +0,0 @@
import example
# Call the Circle() function correctly
x = 1;
y = 1;
r = 3;
c = example.Circle(x, y, r)
# test post-assertion
x = 1;
y = 1;
r = 2;
c = example.Circle(x, y, r)
print "The return value of Circle(%d, %d, %d) is %d" % (x,y,r,c)

20
Examples/contract/simple_c/runme2.py
View file

@ -1,20 +0,0 @@
import example
# Call the Circle() function correctly
x = 1;
y = 1;
r = 3;
c = example.Circle(x, y, r)
print "The return value of Circle(%d, %d, %d) is %d" % (x,y,r,c)
# test pre-assertion
x = 1;
y = -1;
r = 3;
c = example.Circle(x, y, r)
print "The return value of Circle(%d, %d, %d) is %d" % (x,y,r,c)

30
Examples/contract/simple_cxx/example.cxx
View file

@ -1,30 +0,0 @@
#include "example.h"
#define M_PI 3.14159265358979323846
/* Move the shape to a new location */
void Shape::move(double dx, double dy) {
x += dx;
y += dy;
}
int Shape::nshapes = 0;
double Circle::area(void) {
/* return -1 is to test post-assertion */
if (radius == 1)
return -1;
return M_PI*radius*radius;
}
double Circle::perimeter(void) {
return 2*M_PI*radius;
}
double Square::area(void) {
return width*width;
}
double Square::perimeter(void) {
return 4*width;
}

34
Examples/contract/simple_cxx/example.h
View file

@ -1,34 +0,0 @@
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
}
double x, y;
void move(double dx, double dy);
virtual double area(void) = 0;
virtual double perimeter(void) = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { }
virtual double area(void);
virtual double perimeter(void);
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { }
virtual double area(void);
virtual double perimeter(void);
};

28
Examples/contract/simple_cxx/example.i
View file

@ -1,28 +0,0 @@
%module example
%contract Circle::Circle(double radius) {
require:
radius > 0;
}
%contract Circle::area(void) {
ensure:
area > 0;
}
%contract Shape::move(double dx, double dy) {
require:
dx > 0;
}
/* should be no effect, since there is no move() for class Circle */
%contract Circle::move(double dx, double dy) {
require:
dy > 1;
}
# include must be after contracts
%{
#include "example.h"
%}
%include "example.h"

33
Examples/contract/simple_cxx/runme1.py
View file

@ -1,33 +0,0 @@
import example
# Create the Circle object
r = 2;
print " Creating circle (radium: %d) :" % r
c = example.Circle(r)
# Set the location of the object
c.x = 20
c.y = 30
print " Here is its current position:"
print " Circle = (%f, %f)" % (c.x,c.y)
# ----- Call some methods -----
print "\n Here are some properties of the Circle:"
print " area = ", c.area()
print " perimeter = ", c.perimeter()
dx = 1;
dy = 1;
print " Moving with (%d, %d)..." % (dx, dy)
c.move(dx, dy)
del c
print "==================================="
# test construction */
r = -1;
print " Creating circle (radium: %d) :" % r
c = example.Circle(r)

44
Examples/contract/simple_cxx/runme2.py
View file

@ -1,44 +0,0 @@
import example
# Create the Circle object
r = 2;
print " Creating circle (radium: %d) :" % r
c = example.Circle(r)
# Set the location of the object
c.x = 20
c.y = 30
print " Here is its current position:"
print " Circle = (%f, %f)" % (c.x,c.y)
# ----- Call some methods -----
print "\n Here are some properties of the Circle:"
print " area = ", c.area()
print " perimeter = ", c.perimeter()
dx = 1;
dy = 1;
print " Moving with (%d, %d)..." % (dx, dy)
c.move(dx, dy)
del c
print "==================================="
# test area function */
r = 1;
print " Creating circle (radium: %d) :" % r
c = example.Circle(r)
# Set the location of the object
c.x = 20
c.y = 30
print " Here is its current position:"
print " Circle = (%f, %f)" % (c.x,c.y)
# ----- Call some methods -----
print "\n Here are some properties of the Circle:"
print " area = ", c.area()

57
Examples/contract/simple_cxx/runme3.py
View file

@ -1,57 +0,0 @@
import example
# Create the Circle object
r = 2;
print " Creating circle (radium: %d) :" % r
c = example.Circle(r)
# Set the location of the object
c.x = 20
c.y = 30
print " Here is its current position:"
print " Circle = (%f, %f)" % (c.x,c.y)
# ----- Call some methods -----
print "\n Here are some properties of the Circle:"
print " area = ", c.area()
print " perimeter = ", c.perimeter()
dx = 1;
dy = 1;
print " Moving with (%d, %d)..." % (dx, dy)
c.move(dx, dy)
del c
print "==================================="
# test move function */
r = 2;
print " Creating circle (radium: %d) :" % r
c = example.Circle(r)
# Set the location of the object
c.x = 20
c.y = 30
print " Here is its current position:"
print " Circle = (%f, %f)" % (c.x,c.y)
# ----- Call some methods -----
print "\n Here are some properties of the Circle:"
print " area = ", c.area()
print " perimeter = ", c.perimeter()
# no error for Circle's pre-assertion
dx = 1;
dy = -1;
print " Moving with (%d, %d)..." % (dx, dy)
c.move(dx, dy)
# error with Shape's pre-assertion
dx = -1;
dy = 1;
print " Moving with (%d, %d)..." % (dx, dy)
c.move(dx, dy)

8
Examples/guile/check.list
View file

@ -1,9 +1,9 @@
# see top-level Makefile.in # see top-level Makefile.in
constants
class class
port constants
simple
std_vector
matrix matrix
multimap multimap
multivalue multivalue
port
simple
std_vector

6
Examples/guile/matrix/example.i
View file

@ -14,4 +14,8 @@
%include math.i %include math.i
extern double drand48(); %{
/* Add drand48 declaration as it is posix only and is not in stdlib.h when using strict c99 and later */
extern double drand48(void);
%}
extern double drand48(void);

2
Examples/guile/multimap/example.i
View file

@ -78,7 +78,7 @@ extern int count(char *bytes, int len, char c);
%typemap(argout) (char *str, int len) { %typemap(argout) (char *str, int len) {
SWIG_APPEND_VALUE(scm_from_locale_stringn($1,$2)); SWIG_APPEND_VALUE(scm_from_locale_stringn($1,$2));
if ($1) SWIG_free($1); SWIG_free($1);
} }
extern void capitalize(char *str, int len); extern void capitalize(char *str, int len);

2
Examples/javascript/exception/example.h
View file

@ -10,7 +10,7 @@ class Exc {
public: public:
Exc(int c, const char *m) { Exc(int c, const char *m) {
code = c; code = c;
strncpy(msg,m,256); strncpy(msg,m,255);
} }
int code; int code;
char msg[256]; char msg[256];

2
Examples/javascript/native/example.i
View file

@ -15,7 +15,7 @@ int placeholder() { return 0; }
static SwigV8ReturnValue JavaScript_do_work(const SwigV8Arguments &args) { static SwigV8ReturnValue JavaScript_do_work(const SwigV8Arguments &args) {
SWIGV8_HANDLESCOPE(); SWIGV8_HANDLESCOPE();
const int MY_MAGIC_NUMBER = 5; const int MY_MAGIC_NUMBER = 5;
v8::Handle<v8::Value> jsresult = SWIGV8_VALUE jsresult =
SWIG_From_int(static_cast< int >(MY_MAGIC_NUMBER)); SWIG_From_int(static_cast< int >(MY_MAGIC_NUMBER));
if (args.Length() != 0) if (args.Length() != 0)
SWIG_exception_fail(SWIG_ERROR, "Illegal number of arguments."); SWIG_exception_fail(SWIG_ERROR, "Illegal number of arguments.");

4
Examples/lua/arrays/example.i
View file

@ -9,12 +9,12 @@ See the lua code for how they are called
%include <carrays.i> // array helpers %include <carrays.i> // array helpers
// 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) %array_functions(int,int)
// this adds some lua code directly into the module // this adds some lua code directly into the module
// warning: you need the example. prefix if you want it added into the module // warning: you need the example. prefix if you want it added into the module
// admittedly this code is a bit tedious, but its a one off effort // admittedly this code is a bit tedious, but it's a one off effort
%luacode { %luacode {
function example.sort_int2(t) function example.sort_int2(t)
-- local len=table.maxn(t) -- the len - maxn deprecated in 5.3 -- local len=table.maxn(t) -- the len - maxn deprecated in 5.3

2
Examples/lua/constants/runme.lua
View file

@ -30,6 +30,6 @@ function checkfail(fn)
end end
-- these should fail -- these should fail
-- example.EXTERN is a nil value, so concatentatin will make it fail -- example.EXTERN is a nil value, so concatenation will make it fail
checkfail(function() print("EXTERN = "..example.EXTERN) end) checkfail(function() print("EXTERN = "..example.EXTERN) end)
checkfail(function() print("FOO = "..example.FOO) end) checkfail(function() print("FOO = "..example.FOO) end)

2
Examples/lua/embed/embed.c
View file

@ -23,7 +23,7 @@ We will be using the luaL_dostring()/lua_dostring() function to call into lua
#define lua_open luaL_newstate #define lua_open luaL_newstate
#endif #endif
/* the SWIG wrappered library */ /* the SWIG wrapped library */
extern int luaopen_example(lua_State*L); extern int luaopen_example(lua_State*L);
/* a really simple way of calling lua from C /* a really simple way of calling lua from C

10
Examples/lua/embed2/embed2.c
View file

@ -41,7 +41,7 @@ extern int luaopen_example(lua_State*L);
/* This is an example of how to call the Lua function /* This is an example of how to call the Lua function
int add(int,int) int add(int,int)
its very tedious, but gives you an idea of the issues involved. it's very tedious, but gives you an idea of the issues involved.
(look below for a better idea) (look below for a better idea)
*/ */
int call_add(lua_State *L,int a,int b,int* res) { int call_add(lua_State *L,int a,int b,int* res) {
@ -75,7 +75,7 @@ int call_add(lua_State *L,int a,int b,int* res) {
return 1; return 1;
} }
/* This is a variargs call function for calling from C into Lua. /* This is a varargs call function for calling from C into Lua.
Original Code from Programming in Lua (PIL) by Roberto Ierusalimschy Original Code from Programming in Lua (PIL) by Roberto Ierusalimschy
ISBN 85-903798-1-7 ISBN 85-903798-1-7
http://www.lua.org/pil/25.3.html http://www.lua.org/pil/25.3.html
@ -186,7 +186,7 @@ int main(int argc,char* argv[]) {
luaopen_base(L); luaopen_base(L);
luaopen_string(L); luaopen_string(L);
luaopen_math(L); luaopen_math(L);
printf("[C] now loading the SWIG wrappered library\n"); printf("[C] now loading the SWIG wrapped library\n");
luaopen_example(L); luaopen_example(L);
printf("[C] all looks ok\n"); printf("[C] all looks ok\n");
printf("\n"); printf("\n");
@ -226,8 +226,8 @@ int main(int argc,char* argv[]) {
printf("\n"); printf("\n");
printf("[C] Note: no protection if you mess up the va-args, this is C\n"); printf("[C] Note: no protection if you mess up the va-args, this is C\n");
printf("\n"); printf("\n");
printf("[C] Finally we will call the wrappered gcd function gdc(6,9):\n"); printf("[C] Finally we will call the wrapped gcd function gdc(6,9):\n");
printf("[C] This will pass the values to Lua, then call the wrappered function\n"); printf("[C] This will pass the values to Lua, then call the wrapped function\n");
printf(" Which will get the values from Lua, call the C code \n"); printf(" Which will get the values from Lua, call the C code \n");
printf(" and return the value to Lua and eventually back to C\n"); printf(" and return the value to Lua and eventually back to C\n");
printf("[C] Certainly not the best way to do it :-)\n"); printf("[C] Certainly not the best way to do it :-)\n");

4
Examples/lua/embed3/embed3.cpp
View file

@ -61,7 +61,7 @@ bool push_pointer(lua_State*L, void* ptr, const char* type_name, int owned = 0)
/* This is an example of how to call the Lua function /* This is an example of how to call the Lua function
void onEvent(Event e) void onEvent(Event e)
its very tedious, but gives you an idea of the issues involed. it's very tedious, but gives you an idea of the issues involved.
*/ */
int call_onEvent(lua_State *L, Event e) { int call_onEvent(lua_State *L, Event e) {
int top; int top;
@ -105,7 +105,7 @@ int main(int argc, char* argv[]) {
/* this code will pass a pointer into lua, but C++ still owns the object /* this code will pass a pointer into lua, but C++ still owns the object
this is a little tedious, to do, but let's do it this is a little tedious, to do, but let's do it
we need to pass the pointer (obviously), the type name we need to pass the pointer (obviously), the type name
and a flag which states if Lua should delete the pointer once its finished with it and a flag which states if Lua should delete the pointer once it's finished with it
The type name is a class name string which is registered with SWIG The type name is a class name string which is registered with SWIG
(normally, just look in the wrapper file to get this) (normally, just look in the wrapper file to get this)
in this case we don't want Lua to delete the pointer so the ownership flag is 0 in this case we don't want Lua to delete the pointer so the ownership flag is 0

2
Examples/lua/exception/example.h
View file

@ -10,7 +10,7 @@ class Exc {
public: public:
Exc(int c, const char *m) { Exc(int c, const char *m) {
code = c; code = c;
strncpy(msg,m,256); strncpy(msg,m,255);
} }
int code; int code;
char msg[256]; char msg[256];

Some files were not shown because too many files have changed in this diff Show more