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

Merge branch 'master' into C

This commit is contained in:
Olly Betts 2024-03-18 09:09:51 +13:00
parent b88df82c55 6682abab8d
commit 9a5dd880e8
1291 changed files with 45858 additions and 22350 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
.github/workflows/ci.yml vendored
View File

@ -27,13 +27,17 @@ jobs:
# By default, the name of the build is the language used and SWIG options, but matrix entries
# can define the additional "desc" field with any additional information to include in the name.
name: ${{ matrix.SWIGLANG || 'none' }}${{ matrix.PY2 }} ${{ matrix.ENGINE}} ${{ matrix.VER }} ${{ matrix.SWIG_FEATURES }} ${{ (matrix.compiler || 'gcc') }}${{ matrix.GCC }} ${{ matrix.CPPSTD }} ${{ matrix.CSTD }} ${{ matrix.desc }} ${{ matrix.continue-on-error && '(can fail)' }}
name: ${{ matrix.SWIGLANG || 'none' }}${{ matrix.PY2 }} ${{ matrix.ENGINE}} ${{ matrix.VER }} ${{ matrix.SWIG_FEATURES }} ${{ (matrix.compiler || 'gcc') }}${{ matrix.GCC }} ${{ matrix.CPPSTD }} ${{ matrix.CSTD }} ${{ matrix.EXTRA_CXXFLAGS }} ${{ matrix.desc }} ${{ matrix.continue-on-error && '(can fail)' }}
strategy:
matrix:
include:
- SWIGLANG: ""
CPPFLAGS: "-DDOH_POISON"
- SWIGLANG: ""
GCC: 7
CPPSTD: c++98
CSTD: c99
- SWIGLANG: ""
GCC: 7
- SWIGLANG: ""
@ -47,20 +51,24 @@ jobs:
- SWIGLANG: ""
GCC: 12
os: ubuntu-22.04
- SWIGLANG: ""
GCC: 13
os: ubuntu-22.04
- SWIGLANG: ""
compiler: clang
os: ubuntu-22.04
- SWIGLANG: c
CPPSTD: c++11
- 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: d
VER: 'ldc'
CPPSTD: c++14
- SWIGLANG: d
VER: 'gdmd'
CPPSTD: c++11
- SWIGLANG: d
VER: '2.103.1'
CPPSTD: c++17
- SWIGLANG: go
VER: '1.6'
CSTD: gnu11
@ -78,58 +86,56 @@ jobs:
VER: '3.0'
- SWIGLANG: java
- SWIGLANG: javascript
ENGINE: node
VER: '6'
CPPSTD: c++11
os: ubuntu-18.04
ENGINE: jsc
VER: '4.0'
- SWIGLANG: javascript
ENGINE: node
VER: '8'
ENGINE: napi
VER: '18'
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: '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: '18'
CPPSTD: c++14
- SWIGLANG: javascript
ENGINE: jsc
VER: '4.0'
- SWIGLANG: lua
- SWIGLANG: lua
VER: '5.3'
- SWIGLANG: octave
CPPSTD: c++11
- SWIGLANG: octave
os: ubuntu-22.04 # Octave 6.4.0
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
VER: '8.0'
- SWIGLANG: php
VER: '8.1'
- SWIGLANG: php
VER: '8.2'
- SWIGLANG: php
VER: '8.3'
- SWIGLANG: python
PY2: 2
- SWIGLANG: python
VER: '3.3'
os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
- SWIGLANG: python
VER: '3.4'
os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
#- SWIGLANG: python
# VER: '3.3'
# os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
#- SWIGLANG: python
# VER: '3.4'
# os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
- SWIGLANG: python
VER: '3.5'
- SWIGLANG: python
@ -144,6 +150,9 @@ jobs:
VER: '3.10'
- SWIGLANG: python
VER: '3.11'
- SWIGLANG: python
VER: '3.12'
CSTD: gnu99
- SWIGLANG: python
PY2: 2
SWIG_FEATURES: -builtin
@ -154,22 +163,20 @@ jobs:
SWIG_FEATURES: -builtin
- SWIGLANG: python
SWIG_FEATURES: -builtin -O
- SWIGLANG: python
EXTRA_CXXFLAGS: -DPy_LIMITED_API=0x03040000
CPPSTD: c++20
GCC: 13
os: ubuntu-22.04
- 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
@ -184,11 +191,17 @@ jobs:
- SWIGLANG: ruby
VER: '3.1'
CPPSTD: c++11
- SWIGLANG: ruby
CPPSTD: c++11
VER: '3.2.2' # import_fragments testcase started to fail on upgrade to 3.2.3, see https://github.com/swig/swig/issues/2800
- SWIGLANG: scilab
VER: '5.5.2'
- SWIGLANG: scilab
os: ubuntu-18.04 # scilab 6.0
VER: '6.0.2'
- SWIGLANG: scilab
os: ubuntu-22.04 # scilab 6.1.1
- SWIGLANG: scilab
VER: '2023.0.0'
- SWIGLANG: tcl
# c++11 testing
- SWIGLANG: csharp
@ -221,6 +234,9 @@ jobs:
CPPSTD: c++11
- SWIGLANG: r
CPPSTD: c++11
- SWIGLANG: ruby
CPPSTD: c++11
VER: '3.3'
- SWIGLANG: ruby
CPPSTD: c++11
- SWIGLANG: scilab
@ -261,68 +277,79 @@ jobs:
CPPSTD: c++14
- SWIGLANG: tcl
CPPSTD: c++14
# c++17 testing (using gcc11)
# c++17 testing (using gcc13)
- SWIGLANG: csharp
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++17
GCC: 11
GCC: 13
CSTD: gnu17
- SWIGLANG: guile
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: java
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: javascript
ENGINE: node
VER: '18'
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: lua
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: octave
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: perl5
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: php
CPPSTD: c++17
CSTD: gnu17
GCC: 11
GCC: 13
- SWIGLANG: python
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: r
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: ruby
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: scilab
CPPSTD: c++17
GCC: 11
GCC: 13
- SWIGLANG: tcl
CPPSTD: c++17
GCC: 11
# c++20 testing (using gcc12)
# ubuntu-22.04 is currently experimental on Github Actions, so limit to just one language for now
GCC: 13
# c++20 testing (using gcc13)
- SWIGLANG: python
CPPSTD: c++20
GCC: 12
GCC: 13
os: ubuntu-22.04
- SWIGLANG: javascript
ENGINE: napi
VER: '20'
CPPSTD: c++20
GCC: 13
os: ubuntu-22.04
- SWIGLANG: javascript
ENGINE: node
VER: '20'
CPPSTD: c++20
GCC: 13
os: ubuntu-22.04
# Experimental languages (these are allowed to fail)
- SWIGLANG: mzscheme
continue-on-error: true
- SWIGLANG: ocaml
CPPSTD: c++17
GCC: 11
GCC: 13
os: ubuntu-22.04 # ocaml-4.08 in ubuntu-20.04 doesn't work
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
@ -336,11 +363,24 @@ jobs:
CSTD: ${{ matrix.CSTD }}
CPPSTD: ${{ matrix.CPPSTD }}
CPPFLAGS: ${{ matrix.CPPFLAGS }}
EXTRA_CXXFLAGS: ${{ matrix.EXTRA_CXXFLAGS }}
steps:
- name: Machine Info
run: |
echo "nproc..."
nproc --all
echo "uname..."
uname --all
echo "meminfo..."
cat /proc/meminfo
echo "lsb-release..."
cat /etc/lsb-release
- name: Checkout
uses: actions/checkout@v2
uses: actions/checkout@v4
with:
show-progress: false
submodules: recursive
- name: Install CCache
@ -451,11 +491,21 @@ jobs:
unset SWIGJOBS
esac
;;
ocaml)
# `make check-ocaml-test-suite` fails with parallel make with:
#
# File "swig.ml", line 1:
# Error: Could not find the .cmi file for interface swig.mli.
#
# Apparently we ought to be using `ocamldep` to generate make
# dependencies.
unset SWIGJOBS
;;
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)
cflags="$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) $EXTRA_CFLAGS"
cxxflags="$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) $EXTRA_CXXFLAGS"
make check-$SWIGLANG-version
make check-$SWIGLANG-enabled
make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags"

63
.github/workflows/nuget.yml vendored Normal file
View File

@ -0,0 +1,63 @@
name: Windows Nuget Build
on:
push:
paths-ignore:
- 'CHANGES*'
- 'Doc/**'
- 'appveyor.yml'
pull_request:
branches: master
paths-ignore:
- 'CHANGES*'
- 'Doc/**'
- 'appveyor.yml'
permissions:
contents: read # to fetch code (actions/checkout)
jobs:
build:
runs-on: windows-2019
steps:
- name: Checkout
uses: actions/checkout@v4
with:
show-progress: false
submodules: recursive
- name: Install Dependencies
shell: powershell
run: |
nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake
nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bison
nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2
- name: Build
shell: powershell
run: |
$env:PATH="C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;" + $env:PATH
$PCRE_ROOT="C:\Tools\pcre2\PCRE2.10.39.0"
$PCRE_PLATFORM="x64"
$WORKING_DIR=(Get-Location).ToString() -replace "\\","/"
cmake -G "Visual Studio 16 2019" -A "x64" `
-DCMAKE_INSTALL_PREFIX="$WORKING_DIR/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
- name: Install
shell: powershell
run: |
cmake --install build --config Release
- name: Test
shell: powershell
working-directory: install2/bin
run: |
swig.exe -version

2
.gitignore vendored
View File

@ -68,7 +68,6 @@ CCache/config.log
CCache/config.status
CCache/config_win32.h
Examples/Makefile
Examples/d/example.mk
Examples/guile/Makefile
Examples/test-suite/*/Makefile
Examples/xml/Makefile
@ -81,7 +80,6 @@ Tools/javascript/Makefile
config.log
config.status
preinst-swig
swig.spec
# Build Artifacts
.dirstamp

14
ANNOUNCE
View File

@ -1,8 +1,8 @@
*** ANNOUNCE: SWIG 4.1.0 (in progress) ***
*** ANNOUNCE: SWIG 4.3.0 (in progress) ***
http://www.swig.org
https://www.swig.org
We're pleased to announce SWIG-4.1.0, the latest SWIG release.
We're pleased to announce SWIG-4.3.0, the latest SWIG release.
What is SWIG?
=============
@ -19,20 +19,20 @@ and user interface development for large C/C++ systems.
Release Notes
=============
Detailed release notes are available with the release and are also
published on the SWIG web site at http://swig.org/release.html.
published on the SWIG web site at https://swig.org/release.html.
Availability
============
The release is available for download on Sourceforge at
https://prdownloads.sourceforge.net/swig/swig-4.1.0.tar.gz
https://prdownloads.sourceforge.net/swig/swig-4.3.0.tar.gz
A Windows version is also available at
https://prdownloads.sourceforge.net/swig/swigwin-4.1.0.zip
https://prdownloads.sourceforge.net/swig/swigwin-4.3.0.zip
Please report problems with this release to the swig-devel mailing list,
details at http://www.swig.org/mail.html.
details at https://www.swig.org/mail.html.
--- The SWIG Developers

18
CCache/ccache.c
View File

@ -735,13 +735,15 @@ static void from_cache(int first)
}
/* send the cpp stderr, if applicable */
fd_cpp_stderr = open(cpp_stderr, O_RDONLY | O_BINARY);
if (fd_cpp_stderr != -1) {
copy_fd(fd_cpp_stderr, 2);
close(fd_cpp_stderr);
unlink(cpp_stderr);
free(cpp_stderr);
cpp_stderr = NULL;
if (cpp_stderr) {
fd_cpp_stderr = open(cpp_stderr, O_RDONLY | O_BINARY);
if (fd_cpp_stderr != -1) {
copy_fd(fd_cpp_stderr, 2);
close(fd_cpp_stderr);
unlink(cpp_stderr);
free(cpp_stderr);
cpp_stderr = NULL;
}
}
/* send the stderr */
@ -1089,7 +1091,7 @@ static void process_args(int argc, char **argv)
}
*p = 0;
}
else {
else {
int len = p - default_depfile_name;
p = x_malloc(len + 3);

2
CCache/ccache.yo
View File

@ -409,7 +409,7 @@ ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
If you wish to report a problem or make a suggestion then please email
the SWIG developers on the swig-devel mailing list, see
url(http://www.swig.org/mail.html)(http://www.swig.org/mail.html)
url(https://www.swig.org/mail.html)(https://www.swig.org/mail.html)
ccache is released under the GNU General Public License version 2 or
later. Please see the file COPYING for license details.

5
CCache/configure.ac
View File

@ -63,6 +63,9 @@ AC_CACHE_CHECK([for C99 vsnprintf],ccache_cv_HAVE_C99_VSNPRINTF,[
AC_RUN_IFELSE([AC_LANG_SOURCE([[
#include <sys/types.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
void foo(const char *format, ...) {
va_list ap;
int len;
@ -77,7 +80,7 @@ void foo(const char *format, ...) {
exit(0);
}
main() { foo("hello"); }
int main(void) { foo("hello"); }
]])],[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
AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ])

53
CCache/mdfour.c
View File

@ -24,8 +24,6 @@
It assumes that a int is at least 32 bits long
*/
static struct mdfour *m;
#define MASK32 (0xffffffff)
#define F(X,Y,Z) ((((X)&(Y)) | ((~(X))&(Z))))
@ -38,12 +36,12 @@ static struct mdfour *m;
#define ROUND3(a,b,c,d,k,s) a = lshift((a + H(b,c,d) + M[k] + 0x6ED9EBA1)&MASK32,s)
/* this applies md4 to 64 byte chunks */
static void mdfour64(uint32 *M)
static void mdfour64(struct mdfour *md, uint32 *M)
{
uint32 AA, BB, CC, DD;
uint32 A,B,C,D;
A = m->A; B = m->B; C = m->C; D = m->D;
A = md->A; B = md->B; C = md->C; D = md->D;
AA = A; BB = B; CC = C; DD = D;
ROUND1(A,B,C,D, 0, 3); ROUND1(D,A,B,C, 1, 7);
@ -80,7 +78,7 @@ static void mdfour64(uint32 *M)
A &= MASK32; B &= MASK32;
C &= MASK32; D &= MASK32;
m->A = A; m->B = B; m->C = C; m->D = D;
md->A = A; md->B = B; md->C = C; md->D = D;
}
static void copy64(uint32 *M, const unsigned char *in)
@ -88,8 +86,8 @@ static void copy64(uint32 *M, const unsigned char *in)
int i;
for (i=0;i<16;i++)
M[i] = (in[i*4+3]<<24) | (in[i*4+2]<<16) |
(in[i*4+1]<<8) | (in[i*4+0]<<0);
M[i] = ((uint32)in[i*4+3]<<24) | ((uint32)in[i*4+2]<<16) |
((uint32)in[i*4+1]<<8) | ((uint32)in[i*4+0]<<0);
}
static void copy4(unsigned char *out,uint32 x)
@ -111,15 +109,15 @@ void mdfour_begin(struct mdfour *md)
}
static void mdfour_tail(const unsigned char *in, int n)
static void mdfour_tail(struct mdfour *md, const unsigned char *in, int n)
{
unsigned char buf[128];
uint32 M[16];
uint32 b;
m->totalN += n;
md->totalN += n;
b = m->totalN * 8;
b = md->totalN * 8;
memset(buf, 0, 128);
if (n) memcpy(buf, in, n);
@ -128,13 +126,13 @@ static void mdfour_tail(const unsigned char *in, int n)
if (n <= 55) {
copy4(buf+56, b);
copy64(M, buf);
mdfour64(M);
mdfour64(md, M);
} else {
copy4(buf+120, b);
copy64(M, buf);
mdfour64(M);
mdfour64(md, M);
copy64(M, buf+64);
mdfour64(M);
mdfour64(md, M);
}
}
@ -142,10 +140,8 @@ void mdfour_update(struct mdfour *md, const unsigned char *in, int n)
{
uint32 M[16];
m = md;
if (in == NULL) {
mdfour_tail(md->tail, md->tail_len);
mdfour_tail(md, md->tail, md->tail_len);
return;
}
@ -158,18 +154,18 @@ void mdfour_update(struct mdfour *md, const unsigned char *in, int n)
in += len;
if (md->tail_len == 64) {
copy64(M, md->tail);
mdfour64(M);
m->totalN += 64;
mdfour64(md, M);
md->totalN += 64;
md->tail_len = 0;
}
}
while (n >= 64) {
copy64(M, in);
mdfour64(M);
mdfour64(md, M);
in += 64;
n -= 64;
m->totalN += 64;
md->totalN += 64;
}
if (n) {
@ -181,12 +177,10 @@ void mdfour_update(struct mdfour *md, const unsigned char *in, int n)
void mdfour_result(struct mdfour *md, unsigned char *out)
{
m = md;
copy4(out, m->A);
copy4(out+4, m->B);
copy4(out+8, m->C);
copy4(out+12, m->D);
copy4(out, md->A);
copy4(out+4, md->B);
copy4(out+8, md->C);
copy4(out+12, md->D);
}
@ -272,7 +266,12 @@ static void file_checksum2(char *fname)
printf("\n");
}
#endif
/*
* To test:
* gcc -DTEST_MDFOUR mdfour.c -o mdfourexe && ./mdfourexe <somefile>
* then compare against a reference, such as:
* openssl dgst -md4 <somefile>
*/
int main(int argc, char *argv[])
{
file_checksum1(argv[1]);

2641
CHANGES
View File

File diff suppressed because it is too large Load Diff

1143
CHANGES.current
View File

File diff suppressed because it is too large Load Diff

24
CMakeLists.txt
View File

@ -1,8 +1,6 @@
cmake_minimum_required (VERSION 3.2)
cmake_minimum_required (VERSION 3.13)
if (NOT DEFINED CMAKE_BUILD_TYPE)
set (CMAKE_BUILD_TYPE Release CACHE STRING "Build type")
endif ()
set (CMAKE_BUILD_TYPE Release CACHE STRING "Build type")
project (swig)
@ -20,8 +18,11 @@ endif ()
set (SWIG_ROOT ${PROJECT_SOURCE_DIR})
set (SWIG_LIB share/swig/${SWIG_VERSION})
if (WIN32)
set (SWIG_LIB bin/Lib)
else ()
set (SWIG_LIB share/swig/${SWIG_VERSION})
endif ()
# Project wide configuration variables
# ------------------------------------
@ -80,14 +81,14 @@ if (WITH_PCRE)
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 ()
#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)
find_package (BISON 3.5 REQUIRED)
# Compiler flags
@ -127,6 +128,7 @@ install (FILES ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg DESTINATION ${SWIG_LIB})
# ---------
file (GLOB DOH_SOURCES ${SWIG_SOURCE_DIR}/DOH/*.c)
file (GLOB CPARSE_SOURCES ${SWIG_SOURCE_DIR}/CParse/*.c)
list (REMOVE_ITEM CPARSE_SOURCES ${SWIG_SOURCE_DIR}/CParse/parser.c)
list (APPEND CPARSE_SOURCES)
file (GLOB PREPROCESSOR_SOURCES ${SWIG_SOURCE_DIR}/Preprocessor/*.c)
file (GLOB CORE_SOURCES ${SWIG_SOURCE_DIR}/Swig/*.c)

13
COPYRIGHT
View File

@ -1,7 +1,7 @@
SWIG Copyright and Authors
--------------------------
Copyright (c) 1995-2012 The SWIG Developers
Copyright (c) 1995-2023 The SWIG Developers
Copyright (c) 2005-2006 Arizona Board of Regents (University of Arizona).
Copyright (c) 1998-2005 University of Chicago.
Copyright (c) 1995-1998 The University of Utah and the Regents of the University of California
@ -14,11 +14,7 @@ Active SWIG Developers:
William Fulton (wsf@fultondesigns.co.uk) (SWIG core, Java, C#, Windows, Cygwin)
Olly Betts (olly@survex.com) (PHP)
Joseph Wang (joequant@gmail.com) (R)
Xavier Delacour (xavier.delacour@gmail.com) (Octave)
David Nadlinger (code@klickverbot.at) (D)
Leif Middelschulte (leif.middelschulte@gmail.com) (C)
Oliver Buchtala (oliver.buchtala@gmail.com) (Javascript)
Neha Narang (narangneha03@gmail.com) (Javascript)
Momtchil Momtchev (momtchil@momtchev.com) (Javascript Node-API)
Simon Marchetto (simon.marchetto@scilab-enterprises.com) (Scilab)
Zackery Spytz (zspytz@gmail.com) (OCaml, SWIG core)
@ -70,6 +66,11 @@ Past SWIG developers and major contributors include:
Vincent Couvert (Scilab)
Sylvestre Ledru (Scilab)
Wolfgang Frisch (Scilab)
Oliver Buchtala (oliver.buchtala@gmail.com) (Javascript)
Neha Narang (narangneha03@gmail.com) (Javascript)
Xavier Delacour (xavier.delacour@gmail.com) (Octave)
David Nadlinger (code@klickverbot.at) (D)
Leif Middelschulte (leif.middelschulte@gmail.com) (C)
Past contributors include:
James Michael DuPont, Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran

2
Doc/Devel/engineering.html
View File

@ -130,7 +130,7 @@ like this:
* terms also apply to certain portions of SWIG. The full details of the SWIG
* license and copyrights can be found in the LICENSE and COPYRIGHT files
* included with the SWIG source code as distributed by the SWIG developers
* and at http://www.swig.org/legal.html.
* and at https://www.swig.org/legal.html.
*
* xxx.c
*

4
Doc/Devel/internals.html
View File

@ -108,7 +108,7 @@ subdir tree.</td>
</tr>
<tr><td>CParse</td>
<td>Parser (lex / yacc) files and support</td>
<td>Parser (bison) files and support</td>
</tr>
<tr><td>Modules</td>
@ -555,7 +555,7 @@ manipulate datatypes.
<li><tt>SwigType_str(SwigType *t, char *name)</tt>.<br>
This function produces the exact string
representation of the datatype <tt>t</tt>. <tt>name</tt> is an optional parameter that
specifies a declaration name. This is used when dealing with more complicated datatypes
specifies a declaration name and can be <tt>NULL</tt>. This is used when dealing with more complicated datatypes
such as arrays and pointers to functions where the output might look something like
"<tt>int (*name)(int, double)</tt>".

10
Doc/Devel/migrate.txt
View File

@ -101,10 +101,10 @@ parameter values is as follows:
ParmList *l;
Parm *p;
for (p = l; p; p = Getnext(p)) {
SwigType *pt = Gettype(p); /* Get parameter type */
String *pn = Getname(p); /* Get parameter name */
String *value = Getvalue(p); /* Get parameter value */
for (p = l; p; p = nextSibling(p)) {
SwigType *pt = Getattr(p, "type"); /* Get parameter type */
String *pn = Getattr(p, "name"); /* Get parameter name */
String *value = Getattr(p, "value"); /* Get parameter value */
...
do whatever
...
@ -119,7 +119,7 @@ Typemaps more or less work. However, the interface has changed slightly. Inste
the function is
Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
Swig_typemap_lookup("in", node, pname, wrapper);
There are a variety of other changes to typemaps (see CHANGES).

23
Doc/Devel/scanner.html
View File

@ -19,7 +19,7 @@ January 11, 2007<br>
This document describes functions that can be used to tokenize C/C++
input text. These functions are relatively low-level and are meant to
be used in the implementation of scanners that can be plugged into yacc or used for
be used in the implementation of scanners that can be plugged into bison or used for
other purposes. For instance, the preprocessor uses these functions to evaluate and test
constant expressions.
@ -103,7 +103,7 @@ Skips to the end of the current line. The text skipped can be obtained using <
</blockquote>
<p>
<b><tt>void Scanner_skip_balanced(Scanner *s, int startchar, int endchar)</tt></b>
<b><tt>int Scanner_skip_balanced(Scanner *s, int startchar, int endchar)</tt></b>
<blockquote>
Skips to the end of a block of text denoted by starting and ending characters. For example, <tt>{</tt> and <tt>}</tt>. The
function is smart about how it skips text. String literals and comments are ignored. The function also is aware of nesting. The
@ -112,7 +112,7 @@ skipped text can be obtained using <tt>Scanner_text()</tt> afterwards. Returns 0
<p>
<b><tt>void Scanner_set_location(Scanner *s, int startchar, int endchar)</tt></b>
<b><tt>void Scanner_set_location(Scanner *s, String *file, int line)</tt></b>
<blockquote>
Changes the current filename and line number of the scanner.
</blockquote>
@ -136,7 +136,7 @@ Gets the starting line number of the last token returned by the scanner.
</blockquote>
<p>
<b><tt>void Scanner_idstart(Scanner *s, char *idchar)</tt></b>
<b><tt>void Scanner_idstart(Scanner *s, const char *idchar)</tt></b>
<blockquote>
Sets additional characters (other than the C default) that may be used to start C identifiers. <tt>idchar</tt> is a string
containing the characters (e.g., "%@"). The purpose of this function is to up special keywords such as "%module" or "@directive" as
@ -187,7 +187,6 @@ SWIG_TOKEN_RPAREN )
SWIG_TOKEN_SEMI ;
SWIG_TOKEN_COMMA ,
SWIG_TOKEN_STAR *
SWIG_TOKEN_TIMES *
SWIG_TOKEN_LBRACE {
SWIG_TOKEN_RBRACE }
SWIG_TOKEN_EQUAL =
@ -210,11 +209,9 @@ SWIG_TOKEN_LNOT !
SWIG_TOKEN_LBRACKET [
SWIG_TOKEN_RBRACKET ]
SWIG_TOKEN_SLASH /
SWIG_TOKEN_DIVIDE /
SWIG_TOKEN_BACKSLASH \
SWIG_TOKEN_POUND #
SWIG_TOKEN_PERCENT %
SWIG_TOKEN_MODULO %
SWIG_TOKEN_COLON :
SWIG_TOKEN_DCOLON ::
SWIG_TOKEN_DCOLONSTAR ::*
@ -238,21 +235,28 @@ SWIG_TOKEN_ARROWSTAR -&gt;*
SWIG_TOKEN_PERIOD .
SWIG_TOKEN_AT @
SWIG_TOKEN_DOLLAR $
SWIG_TOKEN_ELLIPSIS ...
SWIG_TOKEN_LLBRACKET [[
SWIG_TOKEN_RRBRACKET ]]
SWIG_TOKEN_ENDLINE Literal newline
SWIG_TOKEN_ID identifier
SWIG_TOKEN_FLOAT Floating point with F suffix (e.g., 3.1415F)
SWIG_TOKEN_DOUBLE Floating point (e.g., 3.1415 )
SWIG_TOKEN_LONGDOUBLE Floating point with L suffix (e.g., 3.1415L)
SWIG_TOKEN_INT Integer (e.g., 314)
SWIG_TOKEN_UINT Unsigned integer (e.g., 314U)
SWIG_TOKEN_LONG Long integer (e.g., 314L)
SWIG_TOKEN_ULONG Unsigned long integer (e.g., 314UL)
SWIG_TOKEN_LONGLONG Long long integer (e.g., 314LL )
SWIG_TOKEN_ULONGLONG Unsigned long long integer (e.g., 314ULL)
SWIG_TOKEN_BOOL Boolean literal (true or false)
SWIG_TOKEN_CHAR Character literal in single quotes ('c')
SWIG_TOKEN_WCHAR Wide character literal (L'c')
SWIG_TOKEN_STRING String literal in double quotes ("str")
SWIG_TOKEN_RSTRING Reverse quote string (`str`)
SWIG_TOKEN_CODEBLOCK SWIG code literal block %{ ... %}
SWIG_TOKEN_COMMENT C or C++ comment (// or /* ... */)
SWIG_TOKEN_WSTRING Wide string literal (L"str")
SWIG_TOKEN_ILLEGAL Illegal character
</pre>
</blockquote>
@ -260,9 +264,6 @@ SWIG_TOKEN_ILLEGAL Illegal character
<b>Notes</b>
<ul>
<li>When more than one token code exist for the same token text, those codes are identical (e.g., <tt>SWIG_TOKEN_STAR</tt> and <tt>SWIG_TOKEN_TIMES</tt>).
<p>
<li>
String literals are returned in their exact representation in which escape codes (if any) have been interpreted.
@ -277,7 +278,7 @@ add extra checking on the returned text.
<p>
<li>The maximum token integer value is found in the constant <tt>SWIG_MAXTOKENS</tt>. This can be used if you wanted to create
an array or table for the purposes of remapping tokens to a different set of codes. For instance, if you are
using these functions to write a yacc-compatible lexer.
using these functions to write a bison-compatible lexer.
</ul>
</body>

18
Doc/Devel/tree.html
View File

@ -241,17 +241,17 @@ This function is called by the <tt>-debug-tags</tt> option to SWIG.
<pre>
% swig -debug-tags -python example.i
. top (:1)
. top . include (/Users/beazley/Projects/share/swig/1.3.31/swig.swg:0)
. top . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarnings.swg:0)
. top . include . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarn.swg:0)
:1: . top
:1: . top . include
/usr/share/swig/swig.swg:320: . top . include . include
/usr/share/swig/swigwarnings.swg:39: . top . include . include . include
...
...
. top . include (example.i:0)
. top . include . module (example.i:2)
. top . include . insert (example.i:7)
. top . include . cdecl (example.i:5)
. top . include . cdecl (example.i:6)
:4: . top . include
example.i:2: . top . include . module
example.i:7: . top . include . insert
example.i:5: . top . include . cdecl
example.i:6: . top . include . cdecl
</pre>
Since many language modules include hundreds of typemaps and other information, the output of this can be significantly more complicated than you might expect.

7
Doc/Manual/Arguments.html
View File

@ -375,11 +375,6 @@ Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
rather than directly overwriting the value of the original input object.
</p>
<p>
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
SWIG. Backwards compatibility is preserved, but deprecated.
</p>
<H3><a name="Arguments_nn7">13.1.5 Using different names</a></H3>
@ -440,7 +435,7 @@ double exp(double x);
double log(double POSITIVE); // Allow only positive values
double sqrt(double NONNEGATIVE); // Non-negative values only
double inv(double NONZERO); // Non-zero values
void free(void *NONNULL); // Non-NULL pointers only
int fclose(FILE *NONNULL); // Non-NULL pointers only
</pre></div>

2
Doc/Manual/CCache.html
View File

@ -463,7 +463,7 @@ ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
<p>
If you wish to report a problem or make a suggestion then please email
the SWIG developers on the swig-devel mailing list, see
<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
<a href="https://www.swig.org/mail.html">https://www.swig.org/mail.html</a>
<p>
ccache is released under the GNU General Public License version 2 or
later. Please see the file COPYING for license details.

155
Doc/Manual/CPlusPlus11.html
View File

@ -73,8 +73,7 @@
<p>This chapter gives you a brief overview about the SWIG
implementation of the C++11 standard. This part of SWIG is still a work in
progress.
implementation of the C++11 standard.
</p>
<p>SWIG supports the new C++ syntax changes with some minor limitations
in some areas such as decltype expressions and variadic templates. Wrappers for the
@ -306,7 +305,7 @@ SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
</pre></div>
<p>
<tt>SwigValueWrapper</tt> is covered in <a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a>.
<tt>SwigValueWrapper</tt> is covered in <a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a> and is automatically generated in this case as <tt>MoveOnly</tt> is not assignable.
Note that the generated code could be optimised further using the <a href="Typemaps.html#Typemaps_optimal">"optimal" attribute</a>
in the "out" typemap, so if the above typemap is customised as follows (note that this is C# specific):
</p>
@ -720,22 +719,55 @@ AltStruct var2{2, 4.3}; // calls the constructor
<H3><a name="CPlusPlus11_type_inference">7.2.6 Type inference</a></H3>
<p>SWIG supports <tt>decltype()</tt> with some limitations. Single
variables are allowed, however, expressions are not supported yet. For
example, the following code will work:</p>
<p><tt>decltype()</tt> is supported with a few limitations. SWIG can parse
all uses, but can't deduce the type in every situation where a C++ compiler
can. The cases SWIG can deduce have expanded with time and hopefully will
continue to. For example, for the code</p>
<div class="code"><pre>
int i;
decltype(i) j;
decltype(i+j) k;
</pre></div>
<p>However, using an expression inside the decltype results in syntax error:</p>
<p>SWIG is able to deduce that the variable <tt>i</tt> and the expression
<tt>i+j</tt> both have type <tt>int</tt>.
</p>
<p>
Using an expression for the decltype which SWIG can't handle results in a warning:</p>
<div class="code"><pre>
int i; int j;
decltype(i+j) k; // syntax error
int foo(int);
decltype(foo(0)) k; // Warning 344: Unable to deduce decltype for 'foo(0)'.
</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>
<p>
This warning should be viewed as a prompt to add in a manual ignore of the variable/function as
in most cases the generated code will not compile.
For the example above, ignore the symbol that is declared using <tt>decltype</tt> and perhaps additionally
suppress the warning as follows:
</p>
<div class="code"><pre>
#pragma SWIG nowarn=SWIGWARN_CPP11_DECLTYPE
%ignore k;
</pre></div>
<p>
If an ignore is not acceptable, a workaround is to redefine the symbol with the actual type, for example:
</p>
<div class="code"><pre>
int k; // define k with the actual type
%ignore k; // ignore the real definition of k
</pre></div>
<p>You would typically put one of these workarounds in your interface file before
using <tt>%include</tt> to get SWIG to parse the header which defines <tt>k</tt>.
</p>
<p>SWIG supports <tt>auto</tt> as a type specifier for variables (with the same limitations
for actually deducing the type as for <tt>decltype()</tt>), and 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>
@ -833,12 +865,9 @@ where peer constructors can be called. SWIG handles this without any issue.
<p>
The second improvement is constructor inheritance via a <tt>using</tt> declaration.
This is parsed correctly, but the additional constructors are not currently added to the derived proxy class in the target language.
An example is shown below:
<!--
The extra constructors provided by the <tt>using</tt> syntax will add the appropriate constructors into the target language proxy derived classes.
In the example below a wrapper for the <tt>DerivedClass(int)</tt> is added to <tt>DerivedClass</tt>:
-->
The extra constructors provided by the <tt>using</tt> declaration will add the appropriate constructors into the target language proxy derived classes.
In the example below a wrapper for the <tt>DerivedClass(int)</tt> constructor is added to <tt>DerivedClass</tt>:
</p>
<div class="code"><pre>
@ -853,6 +882,10 @@ class DerivedClass: public BaseClass {
};
</pre></div>
<p>
<b>Compatibility note:</b> SWIG-4.2.0 was the first version to generate wrappers for constructors inherited via <tt>using</tt> declarations.
</p>
<p>
The final part is member initialization at the site of the declaration.
This kind of initialization is handled by SWIG.
@ -891,6 +924,19 @@ struct DerivedStruct : BaseStruct {
};
</pre></div>
<p>
Classes can also be marked as final, such as
</p>
<div class="code"><pre>
struct FinalDerivedStruct final : BaseStruct {
virtual void ab() const override;
};
</pre></div>
<p>
<b>Compatibility note:</b> Final methods were supported much earlier than final classes. SWIG-4.1.0 was the first version to support classes marked as final.
</p>
<H3><a name="CPlusPlus11_null_pointer_constant">7.2.12 Null pointer constant</a></H3>
@ -953,6 +999,22 @@ The equivalent in Java is:
System.out.println(Color.RainbowColors.Red.swigValue() + " " + Color.WarmColors.Red.swigValue() + " " + Color.PrimeColors.Red.swigValue());
</pre></div>
<p>
The C++11 enum base type, such as <tt>unsigned int</tt>, in the example above, is used by some language modules and is missing support in others. For example, in C#, the enum base type in the example above is used and converted into a C# <tt>uint</tt> to specify the underlying C# enumeration type as follows:
</p>
<div class="targetlang"><pre>
public enum RainbowColors : uint {
Red,
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet
}
</pre></div>
<H3><a name="CPlusPlus11_double_angle_brackets">7.2.14 Double angle brackets</a></H3>
@ -1085,38 +1147,71 @@ union P {
<H3><a name="CPlusPlus11_variadic_templates">7.2.18 Variadic templates</a></H3>
<p>SWIG supports the variadic templates syntax (inside the &lt;&gt;
block, variadic class inheritance and variadic constructor and
initializers) with some limitations. The following code is correctly parsed:</p>
<p>SWIG supports the variadic templates including the &lt;&gt;
variadic class inheritance, variadic methods, variadic constructors and
initializers. Example:</p>
<div class="code"><pre>
template &lt;typename... BaseClasses&gt; class ClassName : public BaseClasses... {
public:
ClassName (BaseClasses &amp;&amp;... baseClasses) : BaseClasses(baseClasses)... {}
}
ClassName(BaseClasses &amp;&amp;... baseClasses) : BaseClasses(baseClasses)... {}
void InstanceMethod(const BaseClasses&amp;... baseClasses) {}
};
</pre></div>
<p>
For now however, the <tt>%template</tt> directive only accepts one parameter substitution
for the variable template parameters.
The <tt>%template</tt> directive works as expected for variable template parameters.
</p>
<div class="code"><pre>
%template(MyVariant1) ClassName&lt;&gt; // zero argument not supported yet
%template(MyVariant2) ClassName&lt;int&gt; // ok
%template(MyVariant3) ClassName&lt;int, int&gt; // too many arguments not supported yet
struct A {
virtual void amethod();
virtual ~A();
};
struct B {
virtual void bmethod();
virtual ~B();
};
%template(ClassName0) ClassName&lt;&gt;
%template(ClassName1) ClassName&lt;A&gt;
%template(ClassName2) ClassName&lt;A, B&gt;
</pre></div>
<p>Support for the variadic <tt>sizeof()</tt> function is correctly parsed:</p>
<p>
Example usage from say Python:
</p>
<div class="targetlang"><pre>
cn0 = ClassName0()
cn0.InstanceMethod()
a = A()
cn1 = ClassName1(a)
cn1.amethod()
cn1.InstanceMethod(a)
b = B()
cn2 = ClassName2(a, b)
cn2.InstanceMethod(a, b)
cn2.amethod()
cn2.bmethod()
</pre></div>
<p>Support for the variadic <tt>sizeof()</tt> function also works:</p>
<div class="code"><pre>
const int SIZE = sizeof...(ClassName&lt;int, int&gt;);
const int SIZE = sizeof...(ClassName&lt;A, B&gt;);
</pre></div>
<p>
In the above example <tt>SIZE</tt> is of course wrapped as a constant.
</p>
<p>
<b>Compatibility note:</b> SWIG-4.2.0 was the first version to fully support variadic templates.
SWIG-3.0.0 provided initial support and was limited to only one variadic parameter.
</p>
<H3><a name="CPlusPlus11_new_char_literals">7.2.19 New character literals</a></H3>
@ -1541,7 +1636,7 @@ There is no special smart pointer handling available for <tt>std::weak_ptr</tt>.
<H3><a name="CPlusPlus11_extensible_random_number_facility">7.3.6 Extensible random number facility</a></H3>
<p>This feature extends and standardizes the standard library only and does not effect the C++ language nor SWIG.</p>
<p>This feature extends and standardizes the standard library only and does not affect the C++ language nor SWIG.</p>
<H3><a name="CPlusPlus11_wrapper_reference">7.3.7 Wrapper reference</a></H3>

62
Doc/Manual/CPlusPlus14.html
View File

@ -15,6 +15,7 @@
<li><a href="#CPlusPlus14_core_language_changes">Core language changes</a>
<ul>
<li><a href="#CPlusPlus14_binary_literals">Binary integer literals</a>
<li><a href="#CPlusPlus14_return_type_deduction">Return type deduction</a>
</ul>
<li><a href="#CPlusPlus14_standard_library_changes">Standard library changes</a>
</ul>
@ -53,6 +54,67 @@ int b = 0b101011;
</pre>
</div>
<H3><a name="CPlusPlus14_return_type_deduction">8.2.2 Return type deduction</a></H3>
<p>
C++14 added the ability to specify <tt>auto</tt> for the return type of a function
and have the compiler deduce it from the body of the function (in C++11 you had
to explicitly specify a trailing return type if you used <tt>auto</tt> for the
return type).
</p>
<p>
SWIG parses these types of functions, but with one significant limitation: SWIG
can't actually deduce the return type! If you want to wrap such a function
you will need to tell SWIG the return type explicitly.
</p>
<p>
The trick for specifying the return type is to use <tt>%ignore</tt> to tell
SWIG to ignore the function with the deduced return type, but first provide
SWIG with an alternative declaration of the function with an explicit return
type. The generated wrapper will wrap this alternative declaration, and the
call in the wrapper to the function will call the actual declaration. Here is
an actual example:
</p>
<div class="code"><pre>
std::tuple&lt;int, int&gt; va_static_cast();
%ignore va_static_cast();
#pragma SWIG nowarn=SWIGWARN_CPP14_AUTO
%inline %{
#include &lt;tuple&gt;
auto va_static_cast() {
return std::make_tuple(0, 0);
}
%}
</pre></div>
<p>
For member methods the trick is to use <tt>%extend</tt> to redeclare the method and call it as follows:
</p>
<div class="code"><pre>
%extend X {
const char * a() const { return $self-&gt;a(); }
}
%inline %{
struct X {
auto a() const {
return "a string";
}
};
%}
</pre></div>
<p>
<b>Compatibility note:</b> SWIG-4.2.0 first introduced support for functions declared with an auto return without a trailing return type.
</p>
<H2><a name="CPlusPlus14_standard_library_changes">8.3 Standard library changes</a></H2>

19
Doc/Manual/CPlusPlus20.html
View File

@ -16,6 +16,7 @@
<ul>
<li><a href="#CPlusPlus20_spaceship_operator">Spaceship operator</a>
<li><a href="#CPlusPlus20_lambda_templates">Lambda templates</a>
<li><a href="#CPlusPlus20_constexpr_destructors">Constexpr destructors</a>
</ul>
<li><a href="#CPlusPlus20_standard_library_changes">Standard library changes</a>
</ul>
@ -65,6 +66,24 @@ SWIG should parse lambda templates, but like
non-templated lambdas</a> they aren't currently wrapped.
</p>
<H3><a name="CPlusPlus20_constexpr_destructors">10.2.3 Constexpr destructors</a></H3>
<p>
Destructors that are declared <tt>constexpr</tt> are parsed and handled like any other constructor.
For example:
</p>
<div class="code">
<pre>
class DtorA {
public:
constexpr ~DtorA() {}
};
</pre>
</div>
<H2><a name="CPlusPlus20_standard_library_changes">10.3 Standard library changes</a></H2>

524
Doc/Manual/CSharp.html
View File

@ -16,7 +16,12 @@
<li><a href="#CSharp_commandline">Additional command line options</a>
</ul>
<li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_type_mapping">Type mapping</a>
<ul>
<li><a href="#CSharp_primitive_types">Primitive types</a>
<li><a href="#CSharp_other_type_mappings">Other types</a>
<li><a href="#CSharp_void_pointers">Void pointers</a>
</ul>
<li><a href="#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="#CSharp_arrays_swig_library">The SWIG C arrays library</a>
@ -37,6 +42,7 @@
<li><a href="#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="#CSharp_multiple_modules">Multiple modules</a>
<li><a href="#CSharp_named_arguments">C# named and optional arguments</a>
<li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
@ -520,7 +526,7 @@ The module directive attribute <tt>imclassname</tt> is used to achieve this:
<div class="code">
<pre>
%module (imclassname="name") modulename
%module(imclassname="name") modulename
</pre>
</div>
@ -530,6 +536,38 @@ from <tt>modulename</tt> to <tt>modulenameModule</tt>.
</p>
</li>
<li>
<a name="CSharp_begin"></a>
<p>
The <tt>%module</tt> directive supports the <tt>csbegin</tt> option for adding code to the start of every generated C# file.
This is useful for adding common comments, using statements and/or preprocessor statements into all generated .cs files. For example,
C# 8 nullable reference types can be enabled via a C# preprocessor directive by adding <tt>#nullable enable</tt> into C# files as follows:
</p>
<div class="code">
<pre>
%module(csbegin="#nullable enable\n") mymodule
</pre>
</div>
<p>
It might be easier to use a macro for multiple lines of code, for example:
</p>
<div class="code">
<pre>
%define CSBEGIN_CODE
"
/* Copyright statement */
using System.Text;
#nullable enable
"
%enddef
%module(csbegin=CSBEGIN_CODE) mymodule
</pre>
</div>
<li>
There is no additional 'premature garbage collection prevention parameter' as the marshalling of the <tt>HandleRef</tt> object
takes care of ensuring a reference to the proxy class is held until the unmanaged call completed.
@ -566,17 +604,313 @@ After SWIG has run and both the C# and C/C++ compilers have finished building,
the examples will be run, by either running <tt>runme.exe</tt> or by running
<tt>mono runme.exe</tt> (Mono C# compiler).
Windows users can also get the examples working using a
<a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles.
<a href="http://www.cygwin.com">Cygwin</a> or <a href="https://osdn.net/projects/mingw/">MinGW</a> environment for automatic configuration of the example makefiles.
Any one of the C# compilers (Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path.
<H2><a name="CSharp_void_pointers">23.3 Void pointers</a></H2>
<H2><a name="CSharp_type_mapping">23.3 Type mapping</a></H2>
<p>
By default SWIG treats <tt>void *</tt> as any other pointer and hence marshalls it as a type wrapper class called <tt>SWIGTYPE_p_void</tt>.
The marshalling of the types and typemaps used for marshalling across the managed/unmanaged layers are discussed in this section.
The interested reader will find the implementation in the csharp.swg file.
</p>
<H3><a name="CSharp_primitive_types">23.3.1 Primitive types</a></H3>
<p>
Primitive types are marshalled between the unmanaged and managed layers as blittable types.
</p>
<ul>
<li> The first column in the table below shows various C/C++ types that might be parsed by SWIG.
<li> The second column contains the default type provided by the 'ctype' typemap, that is, the type used for marshalling on the C side.
<li> The third column shows the default type provided by both the 'imtype' and the 'cstype' typemaps, that is, the equivalent type on the C# side.
<li> The fourth column shows the size or number of bytes of the 'imtype'/'cstype', which may or may not match the size of the C/C++ type and is discussed next.
</ul>
<table BORDER summary="Default primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>ctype</b></td>
<td><b>imtype/cstype</b></td>
<td><b>Size</b></td>
</tr>
<tr>
<td>bool<br> const bool &amp; </td>
<td>unsigned int</td>
<td>bool</td>
<td>1</td>
</tr>
<tr>
<td>char<br>const char &amp;</td>
<td>char</td>
<td>char</td>
<td>1</td>
</tr>
<tr>
<td>signed char<br>const signed char &amp;</td>
<td>signed char</td>
<td>sbyte</td>
<td>1</td>
</tr>
<tr>
<td>unsigned char<br>const unsigned char &amp;</td>
<td>unsigned char</td>
<td>byte</td>
<td>1</td>
</tr>
<tr>
<td>short<br>const short &amp;</td>
<td>short</td>
<td>short</td>
<td>2</td>
</tr>
<tr>
<td>unsigned short<br> const unsigned short &amp;</td>
<td>unsigned short</td>
<td>ushort</td>
<td>2</td>
</tr>
<tr>
<td>int<br> const int &amp;</td>
<td>int</td>
<td>int</td>
<td>4</td>
</tr>
<tr>
<td>unsigned int<br> const unsigned int &amp;</td>
<td>unsigned int</td>
<td>uint</td>
<td>4</td>
</tr>
<tr>
<td>long<br>const long &amp;</td>
<td>int</td>
<td>int</td>
<td>4</td>
</tr>
<tr>
<td>unsigned long<br>const unsigned long &amp;</td>
<td>unsigned int</td>
<td>uint</td>
<td>4</td>
</tr>
<tr>
<td>long long<br> const long long &amp;</td>
<td>long long</td>
<td>long</td>
<td>8</td>
</tr>
<tr>
<td>unsigned long long<br>const unsigned long long &amp;</td>
<td>unsigned long long</td>
<td>ulong</td>
<td>8</td>
</tr>
<tr>
<td>float<br>const float &amp;</td>
<td>float</td>
<td>float</td>
<td>4</td>
</tr>
<tr>
<td>double<br> const double &amp;</td>
<td>double</td>
<td>double</td>
<td>8</td>
</tr>
<tr>
<td>size_t<br> const size_t &amp;</td>
<td>unsigned int</td>
<td>uint</td>
<td>4</td>
</tr>
</table>
<p>
The size in bytes of the C type, 'ctype', should match the C# type, 'imtype' for blitting across the managed/unmanaged layers.
They do match across the common 32-bit and 64-bit operating systems, Unix, Windows and MacOS, except for the C long/unsigned long and size_t types.
From the table above the default is to handle C long and size_t as a 32-bit (4 byte) type, so large numbers could be truncated on some 64-bit operating systems.
If <tt>SWIGWORDSIZE64</tt> is defined the C long type is instead handled as a 64-bit (8 byte) type, as per the table below.
</p>
<table BORDER summary="SWIGWORDSIZE64 primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>ctype</b></td>
<td><b>imtype/cstype</b></td>
<td><b>Size</b></td>
</tr>
<tr>
<td>long<br>const long &amp;</td>
<td>long long</td>
<td>long</td>
<td>8</td>
</tr>
<tr>
<td>unsigned long<br>const unsigned long &amp;</td>
<td>unsigned long long</td>
<td>ulong</td>
<td>8</td>
</tr>
</table>
<p>
However, truncation may then occur when the C long type is actually 32-bits (4 bytes).
It's best to avoid using C long for portability across different operating systems!
</p>
<p>
If you need to support long on a range of systems where the size of long varies, then steps must be taken before invoking SWIG to determine whether or not to define <tt>SWIGWORDSIZE64</tt> when invoking SWIG.
</p>
<p>
In order to treat the C size_t type as a 64-bit (8 byte) type, apply the 64-bit typemaps as follows:
</p>
<div class="code">
<pre>
%apply unsigned long long { size_t };
%apply const unsigned long long &amp; { const size_t &amp; };
</pre>
</div>
<p>
The net effect then changes from the default shown earlier to:
</p>
<table BORDER summary="size_t long long mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>ctype</b></td>
<td><b>imtype/cstype</b></td>
<td><b>Size</b></td>
</tr>
<tr>
<td>size_t<br>const size_t &amp;</td>
<td>unsigned long long</td>
<td>ulong</td>
<td>8</td>
</tr>
</table>
<p>
If you need to support size_t on a range of systems where the size of size_t varies, then steps must be taken before invoking SWIG to determine whether or not to apply the typemaps.
Conditionally applying the typemaps using a macro is easily done. For example define <tt>MY_SIZET_WORDSIZE64</tt> to generate 64-bit (8 byte) handling using the following:
</p>
<div class="code">
<pre>
#if defined(MY_SIZET_WORDSIZE64)
%apply unsigned long long { size_t };
%apply const unsigned long long &amp; { const size_t &amp; };
#endif
</pre>
</div>
<H3><a name="CSharp_other_type_mappings">23.3.2 Other types</a></H3>
<p>
The table below shows the equivalent mappings for pointers and strings.
Classes and structs are marshalled using a pointer to the instance of the object.
Note the types in the 'imtype' and 'cstype' typemaps can be different.
</p>
<ul>
<li> The 'imtype' type is used for marshalling across the managed and unmanaged boundary.
<li> The 'cstype' is the final C# proxy or intermediary class type.
<li> In the table below, the 'imtype' type is used for marshalling from the managed to the unmanaged layer.
<li> The 'imtype out' type is used for marshalling from the unmanaged to the managed layer.
</ul>
<table BORDER summary="Other type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>ctype</b></td>
<td><b>imtype</b></td>
<td><b>imtype out</b></td>
<td><b>cstype</b></td>
</tr>
<tr>
<td>char *<br>char []</td>
<td>char *</td>
<td>string</td>
<td>string</td>
<td>string</td>
</tr>
<tr>
<td>void *</td>
<td>void *</td>
<td>System.Runtime.InteropServices.HandleRef</td>
<td>System.IntPtr</td>
<td>SWIGTYPE_p_void</td>
</tr>
</table>
<H3><a name="CSharp_void_pointers">23.3.3 Void pointers</a></H3>
<p>
By default SWIG treats <tt>void *</tt> as any other pointer and hence marshalls it as a type wrapper class called <tt>SWIGTYPE_p_void</tt>,
as shown in the table in the previous section.
If you want to marshall with the .NET <tt>System.IntPtr</tt> type instead, there is a simple set of named typemaps called
<tt>void *VOID_INT_PTR</tt> that can be used.
They can be applied like any other named typemaps:
The net effect is then:
</p>
<table BORDER summary="VOID_INT_PTR type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>ctype</b></td>
<td><b>imtype</b></td>
<td><b>imtype out</b></td>
<td><b>cstype</b></td>
</tr>
<tr>
<td>void *VOID_INT_PTR</td>
<td>void *</td>
<td>System.IntPtr</td>
<td>System.IntPtr</td>
<td>System.IntPtr</td>
</tr>
</table>
<p>
This is achieved by applying them like any other named typemaps:
</p>
@ -1473,7 +1807,7 @@ public class CSharpDerived : Base
{
public override uint UIntMethod(uint x)
{
Console.WriteLine("CSharpDerived - UIntMethod({0})", x);
global::System.Console.WriteLine("CSharpDerived - UIntMethod({0})", x);
return x;
}
}
@ -1817,7 +2151,96 @@ the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows
if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers.
</p>
<H2><a name="CSharp_typemap_examples">23.8 C# Typemap examples</a></H2>
<H2><a name="CSharp_named_arguments">23.8 C# named and optional arguments</a></H2>
<p>
In C++ you can specify default arguments for functions, methods, and constructors. C# offers named arguments. This feature, specific to C#, lets you bind default argument functions with default arguments in C#. SWIG also allows you to add default arguments to C# functions which don't have default arguments in C++.
</p>
<p>
The <tt>cs:defaultargs</tt> feature enables C# named arguments with C# default values.
Using this feature will turn off SWIG's default handling for default arguments, which would create an override for each defaulted argument.
</p>
<p>For this feature, you first specify the function/method/constructor you want it to impact. Inside the feature
call you specify each argument you want to override. If you specify none, it will take the literal text from c++
for each argument and apply that in C#. That often works fine, but when it doesn't you can supply a string literal
with a C# expression to be used as an override. Or you can supply an int literal, or a float literal. If you want to give a literal
string you need to include an escaped quote at the start and end of the literal such as <tt>"\"a string\""</tt>.
</p>
<p>
Let's consider an example:
</p>
<div class="code">
<pre>
%feature("cs:defaultargs") Foo::Foo;
%feature("cs:defaultargs", x=0, z=4) Foo::bar;
%feature("cs:defaultargs", x="\"five\"") Foo::zoo;
%inline %{
class Foo {
public:
Foo(int a, int b=1, int c=2)
{
}
int bar(int x, int y=2, int z=3)
{
return x+y+z;
}
int bat(int x=1, int y=2, int z=3)
{
return x+y+z;
}
int zoo(std::string x="four")
{
return (int)x.size();
}
};
%}
</pre>
</div>
<p>
The generated C# proxy class contains:
</p>
<div class="code">
<pre>
public class Foo : global::System.IDisposable {
...
public Foo(int a, int b=1, int c=2) ...
public int bar(int x=0, int y=2, int z=4) ...
public int bat(int x, int y, int z) ...
public int bat(int x, int y) ...
public int bat(int x) ...
public int bat() ...
public int zoo(string x="five") ...
}
</pre>
</div>
<p>
Note that:
</p>
<ol>
<li> The constructor uses the default arguments exactly as taken from C++. </li>
<li> The <tt>bar</tt> method uses the default arguments exactly as taken from C++ apart from <tt>z</tt> whose default value is changed to 4, and <tt>x</tt> did not have a default value in C++, but does in the generated C#.</li>
<li> The <tt>bat</tt> method does not use the <tt>cs:defaultargs</tt> feature and so the default handling of one overloaded C# method per defaulted C++ argument is generated.</li>
<li> The <tt>zoo</tt> method's string value is overridden by the new string value from the feature. </li>
</ol>
<p>
<b>Compatibility Note:</b> SWIG-4.2.0 added support for the <tt>cs:defaultargs</tt> feature.
</p>
<H2><a name="CSharp_typemap_examples">23.9 C# Typemap examples</a></H2>
This section includes a few examples of typemaps. For more examples, you
@ -1825,7 +2248,7 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<H3><a name="CSharp_memory_management_member_variables">23.8.1 Memory management when returning references to member variables</a></H3>
<H3><a name="CSharp_memory_management_member_variables">23.9.1 Memory management when returning references to member variables</a></H3>
<p>
@ -1861,7 +2284,7 @@ and the following usage from C# after running the code through SWIG:
<div class="code">
<pre>
Wheel wheel = new Bike(10).getWheel();
Console.WriteLine("wheel size: " + wheel.size);
global::System.Console.WriteLine("wheel size: " + wheel.size);
// Simulate a garbage collection
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
@ -1949,7 +2372,7 @@ public class Bike : global::System.IDisposable {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="CSharp_memory_management_objects">23.8.2 Memory management for objects passed to the C++ layer</a></H3>
<H3><a name="CSharp_memory_management_objects">23.9.2 Memory management for objects passed to the C++ layer</a></H3>
<p>
@ -2010,7 +2433,7 @@ In order to understand why, consider a garbage collection occurring...
Container container = new Container();
Element element = new Element(20);
container.setElement(element);
Console.WriteLine("element.value: " + container.getElement().value);
global::System.Console.WriteLine("element.value: " + container.getElement().value);
// Simulate a garbage collection
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
@ -2081,7 +2504,7 @@ as mentioned earlier, <tt>setElement</tt> is actually:
</div>
<H3><a name="CSharp_date_marshalling">23.8.3 Date marshalling using the csin typemap and associated attributes</a></H3>
<H3><a name="CSharp_date_marshalling">23.9.3 Date marshalling using the csin typemap and associated attributes</a></H3>
<p>
@ -2367,7 +2790,7 @@ public class example {
</pre>
</div>
<H3><a name="CSharp_date_properties">23.8.4 A date example demonstrating marshalling of C# properties</a></H3>
<H3><a name="CSharp_date_properties">23.9.4 A date example demonstrating marshalling of C# properties</a></H3>
<p>
@ -2467,7 +2890,7 @@ Some points to note:
<li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute.
</ul>
<H3><a name="CSharp_date_pre_post_directors">23.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
<H3><a name="CSharp_date_pre_post_directors">23.9.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
<p>
@ -2529,7 +2952,7 @@ Pay special attention to the memory management issues, using these attributes.
</p>
<H3><a name="CSharp_partial_classes">23.8.6 Turning proxy classes into partial classes</a></H3>
<H3><a name="CSharp_partial_classes">23.9.6 Turning proxy classes into partial classes</a></H3>
<p>
@ -2629,7 +3052,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt>
The following example is an alternative approach to adding managed code to the generated proxy class.
</p>
<H3><a name="CSharp_sealed_proxy_class">23.8.7 Turning proxy classes into sealed classes</a></H3>
<H3><a name="CSharp_sealed_proxy_class">23.9.7 Turning proxy classes into sealed classes</a></H3>
<p>
@ -2719,7 +3142,7 @@ Either suppress the warning or modify the generated code by copying and tweaking
'csbody' typemap code in csharp.swg by modifying swigCMemOwn to not be protected.
</p>
<H3><a name="CSharp_extending_proxy_class">23.8.8 Extending proxy classes with additional C# code</a></H3>
<H3><a name="CSharp_extending_proxy_class">23.9.8 Extending proxy classes with additional C# code</a></H3>
<p>
@ -2758,11 +3181,12 @@ public class ExtendMe : global::System.IDisposable {
</pre>
</div>
<H3><a name="CSharp_enum_underlying_type">23.8.9 Underlying type for enums</a></H3>
<H3><a name="CSharp_enum_underlying_type">23.9.9 Underlying type for enums</a></H3>
<P>
C# enums use int as the underlying type for each enum item.
C# enums use int as the underlying type for each enum item, unless there is a C++11 enum base specifying the underlying C++ enum type.
If there is a C++ base enum then this is automatically converted to the equivalent C# integral type.
If you wish to change the underlying type to something else, then use the <tt>csbase</tt> typemap.
For example when your C++ code uses a value larger than int, this is necessary as the C# compiler will not compile values which are too large to fit into an int.
Here is an example:
@ -2781,7 +3205,7 @@ Here is an example:
The generated enum will then use the given underlying type and compile correctly:
</p>
<div class="code">
<div class="targetlang">
<pre>
public enum BigNumbers : uint {
big = 0x80000000,
@ -2790,6 +3214,66 @@ public enum BigNumbers : uint {
</pre>
</div>
<p>
If a C++11 enum base is specified, such as <tt>unsigned short</tt> in the following:
</p>
<div class="code">
<pre>
%inline %{
enum SmallNumbers : unsigned short { tiny, small=1 };
%}
</pre>
</div>
<p>
The underlying type is automatically converted to the C# equivalent, <tt>ushort</tt>:
</p>
<div class="targetlang">
<pre>
public enum SmallNumbers : ushort {
tiny,
small = 1
}
</pre>
</div>
<p>
The underlying C# type can still be changed to something else using the csbase typemap but the <tt>replace</tt> attribute must be set to avoid an ignored warnings as there are effectively two specified bases, which of course is not possible. For example:
</p>
<div class="code">
<pre>
%typemap(csbase, replace="1") SmallNumbers "byte"
%inline %{
enum SmallNumbers : unsigned short { tiny, small=1 };
%}
</pre>
</div>
<p>
which generates the desired underlying enum type:
</p>
<div class="targetlang">
<pre>
public enum SmallNumbers : byte {
tiny,
small = 1
}
</pre>
</div>
<p>
If SWIG cannot find appropriate type information for the C++ enum base, then a type wrapper class (something like
SWIGTYPE_p_xxxx) is generated for the C# enum base.
This will not compile in C#, as a C# integral base is required.
To fix this, make sure the C++ enum base type information is parsed by SWIG; this is usually a typedef to an integral type.
Note that SWIG uses the cstype typemap to lookup the C# type for any given C++ type.
Using the csbase typemap, as described above, overrides the default cstype for looking up the C# integral base type.
</p>
</body>
</html>

28
Doc/Manual/Contents.html
View File

@ -237,6 +237,12 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn15">Protection</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn16">Enums and constants</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn17">Friends</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_friend_classes">Friend classes</a>
<li><a href="SWIGPlus.html#SWIGPlus_friend_function_definitions">Friend function definitions</a>
<li><a href="SWIGPlus.html#SWIGPlus_friend_function_declarations">Friend function declarations</a>
<li><a href="SWIGPlus.html#SWIGPlus_friends_unqualified">Unqualified friend functions</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn18">References and pointers</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn20">Inheritance</a>
@ -260,6 +266,7 @@
<li><a href="SWIGPlus.html#SWIGPlus_template_functions">Function templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_classes">Default template arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_class_inheritance">Template base classes</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_empty">Empty template instantiation</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_specialization">Template specialization</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_member">Member templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_scoping">Scoping and templates</a>
@ -358,6 +365,7 @@
<li><a href="CPlusPlus14.html#CPlusPlus14_core_language_changes">Core language changes</a>
<ul>
<li><a href="CPlusPlus14.html#CPlusPlus14_binary_literals">Binary integer literals</a>
<li><a href="CPlusPlus14.html#CPlusPlus14_return_type_deduction">Return type deduction</a>
</ul>
<li><a href="CPlusPlus14.html#CPlusPlus14_standard_library_changes">Standard library changes</a>
</ul>
@ -391,6 +399,7 @@
<ul>
<li><a href="CPlusPlus20.html#CPlusPlus20_spaceship_operator">Spaceship operator</a>
<li><a href="CPlusPlus20.html#CPlusPlus20_lambda_templates">Lambda templates</a>
<li><a href="CPlusPlus20.html#CPlusPlus20_constexpr_destructors">Constexpr destructors</a>
</ul>
<li><a href="CPlusPlus20.html#CPlusPlus20_standard_library_changes">Standard library changes</a>
</ul>
@ -444,6 +453,7 @@
<li><a href="Library.html#Library_stl_cpp_library">STL/C++ library</a>
<ul>
<li><a href="Library.html#Library_std_string">std::string</a>
<li><a href="Library.html#Library_std_string_view">std::string_view</a>
<li><a href="Library.html#Library_std_vector">std::vector</a>
<li><a href="Library.html#Library_stl_exceptions">STL exceptions</a>
<li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
@ -794,7 +804,12 @@
<li><a href="CSharp.html#CSharp_commandline">Additional command line options</a>
</ul>
<li><a href="CSharp.html#CSharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_type_mapping">Type mapping</a>
<ul>
<li><a href="CSharp.html#CSharp_primitive_types">Primitive types</a>
<li><a href="CSharp.html#CSharp_other_type_mappings">Other types</a>
<li><a href="CSharp.html#CSharp_void_pointers">Void pointers</a>
</ul>
<li><a href="CSharp.html#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="CSharp.html#CSharp_arrays_swig_library">The SWIG C arrays library</a>
@ -815,6 +830,7 @@
<li><a href="CSharp.html#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="CSharp.html#CSharp_multiple_modules">Multiple modules</a>
<li><a href="CSharp.html#CSharp_named_arguments">C# named and optional arguments</a>
<li><a href="CSharp.html#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="CSharp.html#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
@ -848,7 +864,11 @@
<li><a href="D.html#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="D.html#D_special_variables">Special variable macros</a>
</ul>
<li><a href="D.html#D_other_code_control">Other D code control features</a>
<ul>
<li><a href="D.html#D_module">D begin</a>
<li><a href="D.html#D_features">D and %feature</a>
</ul>
<li><a href="D.html#D_pragmas">Pragmas</a>
<li><a href="D.html#D_exceptions">D Exceptions</a>
<li><a href="D.html#D_directors">D Directors</a>
@ -1048,6 +1068,7 @@
<li><a href="Java.html#Java_proxycode">Class extension with %proxycode</a>
<li><a href="Java.html#Java_exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="Java.html#Java_method_access">Method access with %javamethodmodifiers</a>
<li><a href="Java.html#Java_begin">Java begin</a>
</ul>
<li><a href="Java.html#Java_tips_techniques">Tips and techniques</a>
<ul>
@ -1117,6 +1138,7 @@
<ul>
<li><a href="Javascript.html#Javascript_node_extensions">Creating node.js Extensions</a>
<ul>
<li><a href="Javascript.html#Javascript_using_yeoman">Using <code>yeoman</code> to generate a Node-API skeleton</a>
<li><a href="Javascript.html#Javascript_troubleshooting">Troubleshooting</a>
</ul>
<li><a href="Javascript.html#Javascript_embedded_webkit">Embedded Webkit</a>
@ -1138,6 +1160,7 @@
<li><a href="Javascript.html#Javascript_emitter">Emitter</a>
<li><a href="Javascript.html#Javascript_emitter_states">Emitter states</a>
<li><a href="Javascript.html#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a>
<li><a href="Javascript.html#Javascript_napi_exceptions">Handling Exceptions in Node-API</a>
</ul>
</ul>
</div>
@ -1351,6 +1374,7 @@
<li><a href="Php.html#Php_nn2_6_3">Static Member Variables</a>
<li><a href="Php.html#Php_nn2_6_4">Static Member Functions</a>
<li><a href="Php.html#Php_nn2_6_5">Specifying Implemented Interfaces</a>
<li><a href="Php.html#Php_nn2_6_6">Dynamic Properties</a>
</ul>
<li><a href="Php.html#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
@ -1427,6 +1451,7 @@
<li><a href="Python.html#Python_nn37">Overhead and code bloat</a>
<li><a href="Python.html#Python_nn38">Typemaps</a>
<li><a href="Python.html#Python_nn39">Miscellaneous</a>
<li><a href="Python.html#Python_stable_abi">Stable ABI</a>
</ul>
<li><a href="Python.html#Python_nn40">Common customization features</a>
<ul>
@ -1456,7 +1481,7 @@
</ul>
<li><a href="Python.html#Python_nn58">Typemap Examples</a>
<ul>
<li><a href="Python.html#Python_nn59">Converting Python list to a char ** </a>
<li><a href="Python.html#Python_nn59">Converting a Python list to a char ** </a>
<li><a href="Python.html#Python_nn60">Expanding a Python object into multiple arguments</a>
<li><a href="Python.html#Python_nn61">Using typemaps to return arguments</a>
<li><a href="Python.html#Python_nn62">Mapping Python tuples into small arrays</a>
@ -1734,6 +1759,7 @@
<ul>
<li><a href="Scilab.html#Scilab_generated_scripts_builder_script">Builder script</a>
<li><a href="Scilab.html#Scilab_generated_scripts_loader_script">Loader script</a>
<li><a href="Scilab.html#Scilab_generated_scripts_gateway">Gateway XML files</a>
</ul>
<li><a href="Scilab.html#Scilab_other_resources">Other resources</a>
</ul>

46
Doc/Manual/Customization.html
View File

@ -95,12 +95,6 @@ or <tt>%noexception</tt> with no code. For example:
%exception; // Deletes any previously defined handler
</pre></div>
<p>
<b>Compatibility note:</b> Previous versions of SWIG used a special directive <tt>%except</tt>
for exception handling. That directive is deprecated--<tt>%exception</tt>
provides the same functionality, but is substantially more flexible.
</p>
<H3><a name="Customization_nn3">15.1.1 Handling exceptions in C code</a></H3>
@ -432,16 +426,6 @@ to attach exceptions to specific parts of a header file. For example:
</pre>
</div>
<p>
<b>Compatibility note:</b> The <tt>%exception</tt> directive replaces
the functionality provided by the deprecated "except" typemap.
The typemap would allow exceptions to be thrown in the target
language based on the return type of a function and
was intended to be a mechanism for pinpointing specific
declarations. However, it never really worked that well and the new
%exception directive is much better.
</p>
<H3><a name="Customization_exception_special_variables">15.1.6 Special variables for %exception</a></H3>
@ -727,36 +711,6 @@ The use of <tt>%newobject</tt> is also integrated with reference counting and is
<a href="SWIGPlus.html#SWIGPlus_ref_unref">C++ reference counted objects</a> section.
</p>
<p>
<b>Compatibility note:</b> Previous versions of SWIG had a special <tt>%new</tt> directive. However, unlike <tt>%newobject</tt>,
it only applied to the next declaration. For example:
</p>
<div class="code">
<pre>
%new char *strdup(const char *s);
</pre>
</div>
<p>
For now this is still supported but is deprecated.
</p>
<p>
<b>How to shoot yourself in the foot:</b> The <tt>%newobject</tt> directive is not a declaration modifier like the old
<tt>%new</tt> directive. Don't write code like this:
</p>
<div class="code">
<pre>
%newobject
char *strdup(const char *s);
</pre>
</div>
<p>
The results might not be what you expect.
</p>
<H2><a name="Customization_features">15.3 Features and the %feature directive</a></H2>

42
Doc/Manual/D.html
View File

@ -22,7 +22,11 @@
<li><a href="#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="#D_special_variables">Special variable macros</a>
</ul>
<li><a href="#D_other_code_control">Other D code control features</a>
<ul>
<li><a href="#D_module">D begin</a>
<li><a href="#D_features">D and %feature</a>
</ul>
<li><a href="#D_pragmas">Pragmas</a>
<li><a href="#D_exceptions">D Exceptions</a>
<li><a href="#D_directors">D Directors</a>
@ -44,11 +48,11 @@
<H2><a name="D_introduction">24.1 Introduction</a></H2>
<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
<p>From the <a href="https://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="https://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
<p>Well, besides the obvious downside that the C header files have to be manually converted to D modules for this to work, there is one major inconvenience with this approach: D code usually is on a higher abstraction level than C, and many of the features that make D interesting are simply not available when dealing with C libraries, requiring you e.g. to manually convert strings between pointers to <tt>\0</tt>-terminated char arrays and D char arrays, making the algorithms from the D2 standard library unusable with C arrays and data structures, and so on.</p>
<p>While these issues can be worked around relatively easy by hand-coding a thin wrapper layer around the C library in question, there is another issue where writing wrapper code per hand is not feasible: C++ libraries. D did not support interfacing to C++ in version 1 at all, and even if <tt>extern(C++)</tt> has been added to D2, the support is still very limited, and a custom wrapper layer is still required in many cases. </p>
<p>While these issues can be worked around relatively easy by hand-coding a thin wrapper layer around the C library in question, there is another issue where writing wrapper code per hand is not feasible: C++ libraries. Support for C++ was added in D2 via <tt>extern(C++)</tt> but this support is still very limited, and a custom wrapper layer is still required in many cases. </p>
<p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html#CSharp">C#</a> (and also on <a href="Java.html#Java">Java</a>, since the C# module was in turn forked from it).</p>
@ -61,7 +65,7 @@
<dl>
<dt><tt>-d2</tt></dt>
<dd>
<p>By default, SWIG generates code for D1/Tango. Use the <tt>-d2</tt> flag to target D2/Phobos instead.</p>
<p>Prior to SWIG 4.2.0, SWIG generated wrappers for D1/Tango by default and <tt>-d2</tt> could be used to generate D2/Phobos wrappers instead. SWIG 4.2.0 dropped support for D1, and D2 wrappers are now produced by default. This option is still recognised to allow existing build systems calling SWIG to work, but is now a no-op.</p>
</dd>
<dt><a name="D_splitproxy"></a><tt>-splitproxy</tt></dt>
@ -305,7 +309,29 @@ $importtype(AnotherInterface)
</dl>
<H2><a name="D_features">24.4 D and %feature</a></H2>
<H2><a name="D_other_code_control">24.4 Other D code control features</a></H2>
<H3><a name="D_module">24.4.1 D begin</a></H3>
<p>
It is possible to add a common comment at the start of every generated D file.
The <tt>%module</tt> directive supports the <tt>dbegin</tt> option for this.
The provided text is generated at the very beginning of each generated D file.
As it is generated before the D module statement, is only really useful for adding in
a common comment into all generated D files. For example, copyright text for each file:
</p>
<div class="code">
<pre>
%module(dbegin="/* Common comment. Copyright (C) 2000 Mr Nobody. */\n") nobodymodule
</pre>
</div>
<H3><a name="D_features">24.4.2 D and %feature</a></H3>
<p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p>
@ -314,7 +340,7 @@ $importtype(AnotherInterface)
<dl>
<dt><tt>%dmanifestconst</tt> and <tt>%dconstvalue(value)</tt></dt>
<dd>
<p>Out of the box, SWIG generates accessor methods for C <tt>#defines</tt> and C++ constants. The <tt>%dmanifestconst</tt> directive enables wrapping these constants as D manifest constants (<tt>const</tt> in D1, <tt>enum</tt> in D2).</p>
<p>Out of the box, SWIG generates accessor methods for C <tt>#defines</tt> and C++ constants. The <tt>%dmanifestconst</tt> directive enables wrapping these constants as D manifest constants (<tt>enum</tt> in D2).</p>
<p>For this to work, the C/C++ code for the constant value must directly compile as D code, though. If this is not the case, you can manually override the expression written to the D proxy module using the <tt>%dconstvalue</tt> directive, passing the new value as parameter.</p>
<p>For <tt>enum</tt>s, again <tt>%dconstvalue</tt> can be used to override the value of an enum item if the initializer should not compile in D.</p>
</dd>
@ -417,11 +443,11 @@ struct A {
<H3><a name="D_operator_overloading">24.8.3 Operator overloading</a></H3>
<p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
<p>The D module comes with basic operator overloading support. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
<p>The first key difference is that C++ supports free functions as operators (along with argument-dependent lookup), while D requires operators to be member functions of the class they are operating on. SWIG can only automatically generate wrapping code for member function operators; if you want to use operators defined as free functions in D, you need to handle them manually.</p>
<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&amp;&amp;</tt> and <tt>||</tt>, but also <tt>!</tt>, and prefix increment/decrement operators in <a href="http://www.digitalmars.com/d/1.0/operatoroverloading.html">D1</a> resp. their postfix pendants in <a href="http://www.digitalmars.com/d/2.0/operatoroverloading.html">D2</a>.</p>
<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&amp;&amp;</tt> and <tt>||</tt>, but also <tt>!</tt>, and postfix increment/decrement operators (see the <a href="https://www.digitalmars.com/d/2.0/operatoroverloading.html">D documentation</a> for details).</p>
<p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p>
@ -429,7 +455,7 @@ struct A {
<H3><a name="D_test_suite">24.8.4 Running the test-suite</a></H3>
<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p>
<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile.</p>
<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib, ...)</tt> statement.</p>

14
Doc/Manual/Doxygen.html
View File

@ -67,7 +67,7 @@ supported.
<p>
The Doxygen Translation module of SWIG adds an extra layer of
functionality to SWIG, allowing automated translation of <a href=
"http://www.doxygen.nl/manual/">Doxygen</a> formatted comments
"https://www.doxygen.nl/manual/">Doxygen</a> formatted comments
from input files into a documentation language more suited for the
target language. Currently this module only translates into Javadoc
and Pydoc for the SWIG Java and Python modules.
@ -83,14 +83,14 @@ Code</a> proposal from Summer 2008.
<p>
To make use of the comment translation system, your documentation
comments must be in properly formatted <a href=
"http://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be
"https://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be
present in your main SWIG interface file or any header file that it
imports. You are advised to be validate that your comments compile
properly with Doxygen before you try to translate them. Doxygen
itself is a more comprehensive tool and can provide you better feedback for
correcting any syntax errors that may be present. Please look at
Doxygen's <a href=
"http://www.doxygen.nl/manual/docblocks.html"> Documenting the
"https://www.doxygen.nl/manual/docblocks.html"> Documenting the
code</a> for the full comment format specifications. However, SWIG's
Doxygen parser will still report many errors and warnings found
in comments (like unterminated strings or missing ending tags).
@ -98,7 +98,7 @@ in comments (like unterminated strings or missing ending tags).
<p>
Currently, the whole subset of Doxygen comment styles is supported
(See <a href="http://www.doxygen.nl/manual/docblocks.html">
(See <a href="https://www.doxygen.nl/manual/docblocks.html">
Documenting the code</a>). Here they are:
</p>
@ -298,7 +298,7 @@ make much sense for the other languages without explicit ownership management.
<p>
Doxygen syntax is rather rich and, in addition to simple commands such as
<tt>@transferfull</tt>, it is also possible to define commands with arguments.
As explained in <a href="http://www.doxygen.nl/manual/commands.html">Doxygen documentation</a>,
As explained in <a href="https://www.doxygen.nl/manual/commands.html">Doxygen documentation</a>,
the arguments can have a range of a single word, everything until the end of
line or everything until the end of the next paragraph. Currently, only the "end
of line" case is supported using the <tt>range="line"</tt> argument of the
@ -1079,7 +1079,7 @@ class Shape(_object):
<p>
If any parameters of a function or a method are documented in the Doxygen comment,
their description is copied into the generated output using
<a href="http://sphinx-doc.org/">Sphinx </a> documentation conventions. For example
<a href="https://www.sphinx-doc.org/">Sphinx </a> documentation conventions. For example
</p>
<div class="code"><pre>
/**
@ -1167,7 +1167,7 @@ completely (doxygen:notranslate feature). Then SWIG will just copy
the comments to the proxy file and reformat them if needed, but all
the comment content will be left as is. As Doxygen doesn't support
special commands in Python comments
(see <a href="http://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen
(see <a href="https://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen
docs</a>), you may want to use some tool like doxypy
(<a href="https://pypi.org/project/doxypy/">doxypy</a>)
to do the work.

14
Doc/Manual/Extending.html
View File

@ -1244,6 +1244,14 @@ if an object was removed, 0 otherwise.
Returns the list of hash table keys.
</div>
<p>
<b><tt>List *SortedKeys(Hash *h, int (*cmp) (const DOH *, const DOH *))</tt></b>
</p>
<div class="indent">
Returns the list of sorted hash table keys.
</div>
<H3><a name="Extending_nn17">40.5.3 Lists</a></H3>
@ -3141,7 +3149,7 @@ As you can see, most usages are direct.
<dd> This file is processed by
<p>
<A HREF="http://www.gnu.org/software/autoconf/">autoconf</A>
<A HREF="https://www.gnu.org/software/autoconf/">autoconf</A>
to generate the <TT>configure</TT> script. This is where you
need to add shell script fragments and autoconf macros to detect the
presence of whatever development support your language module requires,
@ -3489,7 +3497,7 @@ Advanced usage of the test-suite facilitates running tools on some of the five s
The make variables <tt>SWIGTOOL</tt> and <tt>RUNTOOL</tt> are used to specify a tool to respectively, invoke SWIG
and the execution of the runtime test.
You are advised to view the <tt>Examples/test-suite/common.mk</tt> file for details but for a short summary,
the classic usage is to use <a href="http://valgrind.org/">Valgrind</a> for memory checking.
the classic usage is to use <a href="https://valgrind.org/">Valgrind</a> for memory checking.
For example, checking for memory leaks when running the runtime test in the target language interpreter:
</p>
@ -3641,7 +3649,7 @@ A target language is given the 'Supported' status when
A major or minor version is the first or second digit in the three digit version.
</li>
<li>
Fixing unintended regressions in the Supported languages will be given higher priority over experimental languages by the core SWIG developers.
Fixing unintended regressions in the Supported languages will be given higher priority over the Experimental languages by the core SWIG developers.
</li>
<li>
Examples must be available and run successfully.

2
Doc/Manual/Go.html
View File

@ -56,7 +56,7 @@
<p>
This chapter describes SWIG's support of Go. For more information on
the Go programming language
see <a href="http://golang.org/">golang.org</a>.
see <a href="https://golang.org/">golang.org</a>.
</p>
<H2><a name="Go_overview">25.1 Overview</a></H2>

25
Doc/Manual/Guile.html
View File

@ -76,7 +76,7 @@ we explicitly prefix the context, e.g., "guile-module".
<p>Guile 1.8 and older could be interfaced using two different api's, the SCM
or the GH API. The GH interface to guile is deprecated. Read more about why in the
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
<a href="https://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
<p>Support for the guile GH wrapper code generation has been dropped from SWIG. The last
version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please
@ -250,26 +250,9 @@ Newer Guile versions have a shorthand procedure for this:
<p>Guile used to support an autoloading facility for object-code
modules. This support has been marked deprecated in version 1.4.1 and
is going to disappear sooner or later. SWIG still supports building
auto-loading modules if you pass it the <code>-Linkage ltdlmod</code>
command-line option.
<p>Auto-loading worked like this: Suppose a module with name <code>(my
lib foo)</code> is required and not loaded yet. Guile will then search
all directories in its search path
for a Scheme file <code>my/modules/foo.scm</code> or a shared library
<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.so</code> (or
<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.la</code>;
see the GNU libtool documentation). If a
shared library is found that contains the symbol
<code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>,
the library is loaded, and the function at that symbol is called with
no arguments in order to initialize the module.
<p>When invoked with the <code>-Linkage ltdlmod</code> command-line
option, SWIG generates an exported module initialization function with
an appropriate name.
modules, but this support was deprecated and removed in Guile version 1.4.1.
SWIG supported this via option <code>-Linkage ltdlmod</code>, but this
support is no longer useful and was removed in SWIG 4.2.0.
<H3><a name="Guile_nn9">26.4.5 Hobbit4D Linkage</a></H3>

12
Doc/Manual/Introduction.html
View File

@ -172,7 +172,7 @@ This status is provided to indicate the level of maturity to expect when using a
<p>
The second part of the SWIG documentation contains a chapter for each target level language.
Each chapter will state the status (Supported or Experimental) for that language.
The target language chapters are under one of two sections indicating the status (Supported or Experimental) for that language.
</p>
<H3><a name="Introduction_supported_status">2.3.1 Supported status</a></H3>
@ -453,14 +453,14 @@ Microsoft Visual Studio.
<p>
If you are using the GNU Autotools
(<a href="http://www.gnu.org/software/autoconf/">Autoconf</a>/
<a href="http://www.gnu.org/software/automake/">Automake</a>/
<a href="http://www.gnu.org/software/libtool/">Libtool</a>)
(<a href="https://www.gnu.org/software/autoconf/">Autoconf</a>/
<a href="https://www.gnu.org/software/automake/">Automake</a>/
<a href="https://www.gnu.org/software/libtool/">Libtool</a>)
to configure SWIG use in your project, the SWIG Autoconf macros can be used.
The primary macro is <tt>ax_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
<a href="https://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
The <tt>ax_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
<a href="https://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
for further information on this and other Autoconf macros.
</p>

101
Doc/Manual/Java.html
View File

@ -106,6 +106,7 @@
<li><a href="#Java_proxycode">Class extension with %proxycode</a>
<li><a href="#Java_exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="#Java_method_access">Method access with %javamethodmodifiers</a>
<li><a href="#Java_begin">Java begin</a>
</ul>
<li><a href="#Java_tips_techniques">Tips and techniques</a>
<ul>
@ -2226,7 +2227,7 @@ The module directive attribute <tt>jniclassname</tt> is used to achieve this:
<div class="code">
<pre>
%module (jniclassname="name") modulename
%module(jniclassname="name") modulename
</pre>
</div>
@ -5030,6 +5031,25 @@ protected static void protect_me() {
</pre>
</div>
<H3><a name="Java_begin">27.7.6 Java begin</a></H3>
<p>
It is possible to add a common comment at the start of every generated Java file.
The <tt>%module</tt> directive supports the <tt>javabegin</tt> option for this.
The provided text is generated at the very beginning of each generated .java file.
As it is generated before the package statement, is only really useful for adding in
a common comment into all generated .java files. For example, copyright text for each file:
</p>
<div class="code">
<pre>
%module(javabegin="/* Common comment. Copyright (C) 2000 Mr Nobody. */\n") nobodymodule
</pre>
</div>
<H2><a name="Java_tips_techniques">27.8 Tips and techniques</a></H2>
@ -5427,10 +5447,10 @@ destroy arrays and operate on elements. In this case, the functions are as foll
<div class="code">
<pre>
int *new_intArray(int nelements);
int *new_intArray(size_t nelements);
void delete_intArray(int *x);
int intArray_getitem(int *x, int index);
void intArray_setitem(int *x, int index, int value);
int intArray_getitem(int *x, size_t index);
void intArray_setitem(int *x, size_t index, int value);
</pre>
</div>
@ -5771,6 +5791,12 @@ The following table lists the default type mapping from Java to C/C++.</p>
<td>jdouble</td>
</tr>
<tr>
<td>size_t<br> const size_t &amp;</td>
<td>long</td>
<td>jlong</td>
</tr>
<tr>
<td>char *<br>char []</td>
<td>String</td>
@ -5779,6 +5805,62 @@ The following table lists the default type mapping from Java to C/C++.</p>
</table>
<p>
Note that default mappings for the C long type is more suitable for 32-bit systems.
If long is 64-bit, the full range can be obtained by defining <tt>SWIGWORDSIZE64</tt> when invoking SWIG.
The long type will instead be mapped as follows:
</p>
<table BORDER summary="SWIGWORDSIZE64 primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>Java type</b></td>
<td><b>JNI type</b></td>
</tr>
<tr>
<td>long<br> const long &amp;</td>
<td>long</td>
<td>jlong</td>
</tr>
<tr>
<td>unsigned long<br>const unsigned long &amp;</td>
<td>java.math.BigInteger</td>
<td>jobject</td>
</tr>
</table>
<p>
Note that when size_t is 64-bit in C, the full unsigned range is not available.
This can be fixed by applying the 64-bit unsigned long long typemaps as follows:
</p>
<div class="code"> <pre>
%apply unsigned long long { size_t };
%apply const unsigned long long &amp; { const size_t &amp; };
</pre> </div>
<p>
The net effect then changes from the default shown earlier to:
</p>
<table BORDER summary="64-bit size_t primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>Java type</b></td>
<td><b>JNI type</b></td>
</tr>
<tr>
<td>size_t<br> const size_t &amp;</td>
<td>java.math.BigInteger</td>
<td>jobject</td>
</tr>
</table>
<p>
Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers and arrays of this type are wrapped as strings.
The <tt>signed char</tt> type can be used if you want to treat <tt>char</tt> as a signed number rather than a character.
@ -8928,9 +9010,14 @@ public abstract class UserVisibleFoo extends Foo {
<p>
The SWIG documentation system is currently deprecated.
When it is resurrected JavaDoc comments will be fully supported.
If you can't wait for the full documentation system a couple of workarounds are available.
SWIG can translate <a href="https://doxygen.org/">Doxygen</a> comments in the
C/C++ headers being wrapped to JavaDoc. For details of this, see the
<a href="Doxygen.html#Doxygen_to_javadoc">Doxygen to Javadoc</a> section.
</p>
<p>
If you don't have Doxygen comments to translate then it's possible to add
JavaDoc comments from your interface file.
The <tt>%javamethodmodifiers</tt> feature can be used for adding proxy class method comments and module class method comments.
The "javaimports" typemap can be hijacked for adding in proxy class JavaDoc comments.
The <tt>jniclassimports</tt> or <tt>jniclassclassmodifiers</tt> pragmas can also be used for adding intermediary JNI class comments and likewise the <tt>moduleimports</tt> or <tt>moduleclassmodifiers</tt> pragmas for the module class.

83
Doc/Manual/Javascript.html
View File

@ -22,6 +22,7 @@
<ul>
<li><a href="#Javascript_node_extensions">Creating node.js Extensions</a>
<ul>
<li><a href="#Javascript_using_yeoman">Using <code>yeoman</code> to generate a Node-API skeleton</a>
<li><a href="#Javascript_troubleshooting">Troubleshooting</a>
</ul>
<li><a href="#Javascript_embedded_webkit">Embedded Webkit</a>
@ -43,6 +44,7 @@
<li><a href="#Javascript_emitter">Emitter</a>
<li><a href="#Javascript_emitter_states">Emitter states</a>
<li><a href="#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a>
<li><a href="#Javascript_napi_exceptions">Handling Exceptions in Node-API</a>
</ul>
</ul>
</div>
@ -79,7 +81,7 @@ With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is
int gcd(int x, int y);
extern double Foo;</pre>
</div>
<p>To build a Javascript module, run SWIG using the <code>-javascript</code> option and a desired target engine <code>-jsc</code>, <code>-v8</code>, or <code>-node</code>. The generator for <code>node</code> is essentially delegating to the <code>v8</code> generator and adds some necessary preprocessor definitions.</p>
<p>To build a Javascript module, run SWIG using the <code>-javascript</code> option and a desired target engine <code>-jsc</code>, <code>-v8</code>, <code>-node</code> or <code>-napi</code>. <code>-v8</code> allows for interfacing with a raw embedded version of V8. In this case, it is up to the user to implement a binary module loading protocol. There are two generators supporting Node.js. The older generator for <code>node</code> is essentially delegating to the <code>v8</code> generator and adds some necessary preprocessor definitions. The more recent <code>-napi</code> generator produces <code>node-addon-api</code> that interfaces to Node.js through Node-API. The V8 generator is more mature, while the Node-API generator offers a number of advantages such as binary stable ABI allowing for publishing of universal binary modules on npm, Electron support and automatic multi-threading.</p>
<div class="shell">
<pre>
$ swig -javascript -jsc example.i</pre>
@ -90,8 +92,12 @@ $ swig -javascript -jsc example.i</pre>
$ swig -c++ -javascript -jsc example.i</pre>
</div>
<p>The V8 code that SWIG generates requires at least V8 5.0. Keep in mind
that this is theV8 version, not Node.js. To give some perspective, Node.js v6.0
that this is the V8 version, not Node.js. To give some perspective, Node.js v6.0
uses V8 5.0, v12.0 - 7.4, v14.0 - 8.1...</p>
<p>The Node-API code that SWIG generates requires Node-API version 6.
This Node-API is available starting from Node.js v10.20 on the v10.x branch,
Node.js v12.17 on the v12.x branch and all versions starting from v14.0.
</p>
<p>To generate code for V8, you would run swig like so:</p>
<div class="shell">
<pre>
@ -125,14 +131,19 @@ $ sudo apt-get install libjavascriptcoregtk-1.0-dev</pre>
<p>Running with <code>V8</code> requires <code>libv8</code>:</p>
<div class="shell">
<pre>
$ sudo apt-get install libv8-dev</pre>
$ sudo apt-get install libnode-dev</pre>
</div>
<p>Running with Node-API requires <code>node-addon-api</code>:</p>
<div class="shell">
<pre>
$ sudo npm install -g node-addon-api</pre>
</div>
<p>Examples can be run using</p>
<div class="shell">
<pre>
$ make check-javascript-examples ENGINE=jsc</pre>
</div>
<p><code>ENGINE</code> can be <code>node</code>, <code>jsc</code>, or <code>v8</code>.</p>
<p><code>ENGINE</code> can be <code>node</code>, <code>jsc</code>, <code>v8</code>, or <code>napi</code>.</p>
<p>The test-suite can be run using</p>
<div class="shell">
<pre>
@ -150,15 +161,15 @@ $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre>
<p>At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.</p>
<ul>
<li><p>Default optional arguments do not work for all targeted interpreters</p></li>
<li><p>Default optional arguments do not work for all targeted interpreters except Node-API</p></li>
<li><p>Multiple output arguments do not work for JSC</p></li>
<li><p>C89 incompatibility: the JSC generator might still generate C89 violating code</p></li>
<li><p><code>long long</code> is not supported</p></li>
<li><p><code>long long</code> is not supported except with Node-API</p></li>
<li><p>Javascript callbacks are not supported</p></li>
<li><p><code>instanceOf</code> does not work under JSC</p></li>
</ul>
<p>The primary development environment has been Linux (Ubuntu 12.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p>
<p>The primary development environment has been Linux (Ubuntu 22.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p>
<H2><a name="Javascript_integration">28.3 Integration</a></H2>
@ -211,7 +222,27 @@ require("./build/Release/example")</pre>
</div>
<p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p>
<H4><a name="Javascript_troubleshooting">28.3.1.1 Troubleshooting</a></H4>
<H4><a name="Javascript_using_yeoman">28.3.1.1 Using <code>yeoman</code> to generate a Node-API skeleton</a></H4>
<p>If targeting Node-API, the easiest way to bootstrap a project is by using the <code>yeoman</code> generator: </p>
<div class="shell">
<pre>
$ sudo npm install -g yo
$ sudo npm install -g generator-napi-module
$ mkdir example
$ cd example
$ yo napi-module # the choice of template is irrelevant, SWIG will replace the C++ code
$ npm install node-addon-api@latest # the yeoman version is outdated
$ swig -javascript -napi -c++ -o src/example.cc example.i
$ node-gyp configure
$ node-gyp build
</pre>
</div>
<p>There is also the <a href="https://github.com/mmomtchev/node-magickwand"><code>node-magickwand</code></a> project that can be used as a tutorial for building and publishing a complex C++ library to
npm as a ready-to-use real-world binary module.</p>
<H4><a name="Javascript_troubleshooting">28.3.1.2 Troubleshooting</a></H4>
<ul>
@ -279,7 +310,7 @@ extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports)
<H4><a name="Javascript_gtk">28.3.2.2 GTK</a></H4>
<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial/">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial/">GTK tutorial</a>, and for Webkit there is a <a href="https://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
<p>An integration of a native extension 'example' would look like this:</p>
<div class="code">
<pre>
@ -310,7 +341,7 @@ int main(int argc, char* argv[])
...
// Load a web page into the browser instance
webkit_web_view_load_uri(webView, "http://www.webkitgtk.org/");
webkit_web_view_load_uri(webView, "https://www.webkitgtk.org/");
...
@ -465,7 +496,7 @@ example.Foo = 3.1415926;</pre>
</div>
<p>First the module <code>example</code> is loaded from the previously built extension. Global methods and variables are available in the scope of the module.</p>
<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p>
<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="https://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="https://browserify.org">Browserify</a>, for instance.</p>
<H3><a name="Javascript_class_example">28.4.2 Class</a></H3>
@ -605,7 +636,7 @@ at emitKey (readline.js:1095:12)</pre>
<H3><a name="Javascript_source_code">28.5.1 Source Code</a></H3>
<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code>, <code>JSCEmitter</code> or <code>NAPIEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
<div class="code">
<pre>
// module wide defines
@ -629,6 +660,7 @@ class JSEmitter { ... };
JSEmitter *swig_javascript_create_JSCEmitter();
JSEmitter *swig_javascript_create_V8Emitter();
JSEmitter *swig_javascript_create_NAPIEmitter();
// ###############################
// # Javascript module
@ -706,7 +738,7 @@ Template::Template(const String *code_) { ... }
<H3><a name="Javascript_code_templates">28.5.2 Code Templates</a></H3>
<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p>
<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code> and for <em>Node-API</em> in <code>Lib/javascript/napi/javascriptcode.swg</code>.</p>
<p>To track the originating code template for generated code you can run</p>
<div class="shell">
<pre>
@ -985,5 +1017,30 @@ if(js_exception)
}</pre>
</div>
<H3><a name="Javascript_napi_exceptions">28.5.6 Handling Exceptions in Node-API</a></H3>
<p>Node-API is the only generator that provides fully automatic conversion of C++ exceptions to JavaScript exceptions when building with C++ exceptions enabled in `binding.gyp`:</p>
<div class="code">
<pre>
'conditions': [
['OS=="mac"',
{
'xcode_settings': {
'GCC_ENABLE_CPP_RTTI': 'YES',
'GCC_ENABLE_CPP_EXCEPTIONS' : 'YES'
}
}
],
['OS=="linux" or OS=="freebsd" or OS=="openbsd" or OS=="solaris"',
{
'cflags!': [ '-fno-exceptions' ],
'cflags_cc!': [ '-fno-exceptions', '-fno-rtti' ]
}
]
]
</pre>
</div>
<p>In this case, nothing else is needed for the C++ exceptions to be passed to JavaScript.</p>
</body>
</html>

156
Doc/Manual/Library.html
View File

@ -30,6 +30,7 @@
<li><a href="#Library_stl_cpp_library">STL/C++ library</a>
<ul>
<li><a href="#Library_std_string">std::string</a>
<li><a href="#Library_std_string_view">std::string_view</a>
<li><a href="#Library_std_vector">std::vector</a>
<li><a href="#Library_stl_exceptions">STL exceptions</a>
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
@ -392,7 +393,7 @@ raw C array data.
<p>Creates four functions.</p>
<p>
<tt>type *new_name(int nelements)</tt>
<tt>type *new_name(size_t nelements)</tt>
</p>
<div class="indent"><p>
@ -409,7 +410,7 @@ Deletes an array. In C, <tt>free()</tt> is used. In C++, <tt>delete []</tt> is
</p></div>
<p>
<tt>type name_getitem(type *ary, int index)</tt>
<tt>type name_getitem(type *ary, size_t index)</tt>
</p>
<div class="indent"><p>
@ -417,7 +418,7 @@ Returns the value <tt>ary[index]</tt>.
</p></div>
<p>
<tt>void name_setitem(type *ary, int index, type value)</tt>
<tt>void name_setitem(type *ary, size_t index, type value)</tt>
</p>
<div class="indent"><p>
@ -490,10 +491,10 @@ interface is as follows:
<div class="code">
<pre>
struct name {
name(int nelements); // Create an array
name(size_t nelements); // Create an array
~name(); // Delete array
type getitem(int index); // Return item
void setitem(int index, type value); // Set item
type getitem(size_t index); // Return item
void setitem(size_t index, type value); // Set item
type *cast(); // Cast to original type
static name *frompointer(type *); // Create class wrapper from
// existing pointer
@ -1450,14 +1451,15 @@ The following table shows which C++ classes are supported and the equivalent SWI
<tr> <td>std::multiset (C++11)</td> <td>multiset</td> <td>std_multiset.i</td> </tr>
<tr> <td>std::pair</td> <td>utility</td> <td>std_pair.i</td> </tr>
<tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr>
<tr> <td>std::shared_ptr (C++11)</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
<tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
<tr> <td>std::string_view (C++17)</td> <td>string_view</td> <td>std_string_view.i</td> </tr>
<tr> <td>std::unordered_map (C++11)</td> <td>unordered_map</td> <td>std_unordered_map.i</td> </tr>
<tr> <td>std::unordered_multimap (C++11)</td> <td>unordered_multimap</td> <td>std_unordered_multimap.i</td> </tr>
<tr> <td>std::unordered_multiset (C++11)</td> <td>unordered_multiset</td> <td>std_unordered_multiset.i</td> </tr>
<tr> <td>std::unordered_set (C++11)</td> <td>unordered_set</td> <td>std_unordered_set.i</td> </tr>
<tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
<tr> <td>std::wstring</td> <td>wstring</td> <td>std_wstring.i</td> </tr>
<tr> <td>std::shared_ptr (C++11)</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
</table>
@ -1551,7 +1553,51 @@ void foo(string s, const String &amp;t); // std_string typemaps still applie
</pre>
</div>
<H3><a name="Library_std_vector">12.4.2 std::vector</a></H3>
<H3><a name="Library_std_string_view">12.4.2 std::string_view</a></H3>
<p>
The <tt>std_string_view.i</tt> library provides typemaps for converting C++17 <tt>std::string_view</tt>
objects to and from strings in the target scripting language. For example:
</p>
<div class="code">
<pre>
%module example
%include "std_string_view.i"
std::string_view foo();
void bar(std::string_view x);
</pre>
</div>
<p>
In the target language:
</p>
<div class="targetlang">
<pre>
x = foo(); # Returns a string object
bar("Hello World"); # Pass string as std::string_view
</pre>
</div>
<p>
For target languages for which SWIG supports directors, <tt>directorout</tt>
typemaps are provided for <tt>std::string_view</tt>, but these require extra
care to use safely. The issue is that returning <tt>std::string_view</tt>
effectively returns a pointer to string data but doesn't own the pointed to
data. For target languages where there isn't a native narrow string
representation (e.g. C#, Java) a <tt>static std::string</tt> is used to cache
the data, which works but isn't thread/reentrant safe. For target languages
where there is a native narrow string representation SWIG will return a
<tt>std::string_view</tt> pointing to that data, so you need to store the
string to return somewhere which will persist for the lifetime the caller
needs (e.g. put it in a member variable) - you can't return a temporary target
language string. In both cases SWIG will issue a warning by default.
</p>
<H3><a name="Library_std_vector">12.4.3 std::vector</a></H3>
<p>
@ -1730,7 +1776,7 @@ if you want to make their head explode.
details and the public API exposed to the interpreter vary.
</p>
<H3><a name="Library_stl_exceptions">12.4.3 STL exceptions</a></H3>
<H3><a name="Library_stl_exceptions">12.4.4 STL exceptions</a></H3>
<p>
@ -1780,10 +1826,10 @@ The <tt>%exception</tt> directive can be used by placing the following code befo
Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
</p>
<H3><a name="Library_std_shared_ptr">12.4.4 shared_ptr smart pointer</a></H3>
<H3><a name="Library_std_shared_ptr">12.4.5 shared_ptr smart pointer</a></H3>
<H4><a name="Library_shared_ptr_basics">12.4.4.1 shared_ptr basics</a></H4>
<H4><a name="Library_shared_ptr_basics">12.4.5.1 shared_ptr basics</a></H4>
<p>
@ -1826,7 +1872,7 @@ In order to use <tt>boost::shared_ptr</tt>, the <tt>boost_shared_ptr.i</tt> libr
<p>
You can only use one of these variants of shared_ptr in your interface file at a time.
and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
All three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr&lt;T&gt;</tt>.
The type <tt>T</tt> must be non-primitive.
A simple example demonstrates usage:
@ -1879,7 +1925,7 @@ System.out.println(val1 + " " + val2);
</pre>
</div>
<H4><a name="Library_shared_ptr_inheritance">12.4.4.2 shared_ptr and inheritance</a></H4>
<H4><a name="Library_shared_ptr_inheritance">12.4.5.2 shared_ptr and inheritance</a></H4>
<p>
@ -1970,7 +2016,7 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
</pre>
</div>
<H4><a name="Library_shared_ptr_overloading">12.4.4.3 shared_ptr and method overloading</a></H4>
<H4><a name="Library_shared_ptr_overloading">12.4.5.3 shared_ptr and method overloading</a></H4>
<p>
@ -1992,7 +2038,7 @@ SWIG will choose to wrap just the first method by default.
For the interested reader, SWIG detects that they are equivalent types via the <a href=Typemaps.html#Typemaps_typecheck_pointer>typecheck typemaps</a> in the shared_ptr library.
</p>
<H4><a name="Library_shared_ptr_templates">12.4.4.4 shared_ptr and templates</a></H4>
<H4><a name="Library_shared_ptr_templates">12.4.5.4 shared_ptr and templates</a></H4>
<p>
@ -2034,28 +2080,37 @@ The SWIG code below shows the required ordering:
</pre>
</div>
<H4><a name="Library_shared_ptr_directors">12.4.4.5 shared_ptr and directors</a></H4>
<H4><a name="Library_shared_ptr_directors">12.4.5.5 shared_ptr and directors</a></H4>
<p>
The languages that support shared_ptr also have support for using shared_ptr with directors.
</p>
<H3><a name="Library_std_unique_ptr">12.4.5 unique_ptr smart pointer</a></H3>
<H3><a name="Library_std_unique_ptr">12.4.6 unique_ptr smart pointer</a></H3>
<p>
The <tt>std_unique_ptr.i</tt> library file provides SWIG's unique_ptr support.
It defines typemaps and a macro, <tt>%unique_ptr(T)</tt>, to use for handling
It provides move semantics for the smart pointer's underlying object,
both from C++ to the target language and vice versa.
</p>
<p>
The library defines typemaps and a macro, <tt>%unique_ptr(T)</tt>, to use for handling
<tt>std::unique_ptr&lt;T&gt;</tt> for a type <tt>T</tt>.
The type <tt>T</tt> must be non-primitive.
This macro should be used before any code declaring or using type <tt>T</tt>.
Ordering requirements for using this smart pointer macro are the same as the
equivalent <tt>%shared_ptr(T)</tt> macro covered in the previous section.
The ownership and move semantics described here can of course be modified if not suitable
by copying and customising the typemaps in the appropriate <tt>std_unique_ptr.i</tt> library file.
</p>
<H4><a name="Library_std_unique_ptr_by_value">12.4.6 unique_ptr passed by value</a></H4>
<p>
Example usage of a <tt>std::unique_ptr</tt> being returned from a function is shown below.
Example usage of a <tt>std::unique_ptr</tt> being returned from a function by value is shown below.
</p>
<div class="code">
@ -2159,11 +2214,70 @@ Attempts to pass ownership from a proxy class to a <tt>std::unique</tt> paramete
in a "Cannot release ownership as memory is not owned" exception. For example, if <tt>example.take(k)</tt> in the example above is called twice.
</p>
<H4><a name="Library_std_unique_ptr_by_ref">12.4.6 unique_ptr passed by reference</a></H4>
<p>
<b>Compatibility note:</b> Support for <tt>std::unique_ptr</tt> was added in SWIG-4.1.0.
The effect of passing a <tt>std::unique_ptr</tt> by rvalue reference into a function is identical to passing it by value.
The ownership of the memory of the object being pointed to by the underyling pointer is transferred from the proxy class to the C++ function being called. Example:
</p>
<H3><a name="Library_std_auto_ptr">12.4.6 auto_ptr smart pointer</a></H3>
<div class="code">
<pre>
void grab(std::unique_ptr&lt;Klass&gt; &amp;&amp;);
</pre>
</div>
<p>
Passing non-const lvalue references into a function is a bit quirky and not perfect due to ambiguities as
to what the function may do.
The approach taken is the ownership is transferred out of the target language from the proxy class
into C++ space and the proxy class can then no longer be used after the wrapped function returns.
In summary it works much like passing a <tt>std::unique_ptr</tt> by value into a function.
The assumption is the function will not modify the <tt>std::unique_ptr</tt>.
If this is not true and the underlying pointer is changed, such as calling the member functions, <tt>swap</tt>, <tt>reset</tt> or <tt>release</tt>, then the modified <tt>std::unique_ptr</tt> will effectively be ignored.
It is destroyed when the function exits C++ space on return to the target language.
Example:
</p>
<div class="code">
<pre>
void process(std::unique_ptr&lt;Klass&gt; &amp;);
</pre>
</div>
<p>
Passing const lvalue references into a function works much like passing any wrapped class.
The proxy class owning the underling C++ object continues to own the underying C++ object
after calling the function, the function cannot modify the <tt>std::unique_ptr</tt> or take ownership.
Example:
</p>
<div class="code">
<pre>
void use(const std::unique_ptr&lt;Klass&gt; &amp;);
</pre>
</div>
<p>
Move semantics are not provided when wrapping a C++ function that returns a <tt>std::unique_ptr</tt> by reference.
The target language proxy class wrapper that is returned does not own the underlying C++ object.
This applies to all reference types, such as:
</p>
<div class="code">
<pre>
std::unique_ptr&lt;Klass&gt; &amp; LvalueRefReturn();
std::unique_ptr&lt;Klass&gt; &amp;&amp; RvalueRefReturn();
</pre>
</div>
<p>
<b>Compatibility note:</b> Support for <tt>std::unique_ptr</tt> was first added in SWIG-4.1.0.
This initial support contained the move semantics when passing a <tt>std::unique_ptr</tt> around by value. Support for passing a <tt>std::unique_ptr</tt> around by reference was added in SWIG-4.3.0.
</p>
<H3><a name="Library_std_auto_ptr">12.4.7 auto_ptr smart pointer</a></H3>
<p>

604
Doc/Manual/Lisp.html
View File

@ -1,604 +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 Common Lisp</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="Lisp">29 SWIG and Common Lisp</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Lisp_nn3">Common Foreign Function Interface(CFFI)</a>
<ul>
<li><a href="#Lisp_nn4">Additional Commandline Options </a>
<li><a href="#Lisp_nn5">Generating CFFI bindings</a>
<li><a href="#Lisp_nn6">Generating CFFI bindings for C++ code</a>
<li><a href="#Lisp_nn7">Inserting user code into generated files</a>
</ul>
<ul>
<li><a href="#Lisp_nn9">Additional Commandline Options </a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
Common Lisp is a high-level, all-purpose, object-oriented,
dynamic, functional programming language with long history.
Common Lisp is used in many fields, ranging from web development to
finance, and also common in computer science education.
There are more than 9 different implementations of common lisp which
are available, all have different foreign function
interfaces. SWIG currently supports the
Common Foreign Function Interface(CFFI).
</p>
<H2><a name="Lisp_nn3">29.2 Common Foreign Function Interface(CFFI)</a></H2>
<p>
CFFI, the Common Foreign Function Interface, is a portable foreign
function interface for ANSI Common Lisp systems.
CFFI requires only a small set of
low-level functionality from the Lisp implementation, such as
calling a foreign function by name, allocating foreign memory,
and dereferencing pointers.
</p>
<p>
To run the cffi module of SWIG requires very little effort, you
just need to run:
</p>
<div class="code"><pre>
swig -cffi -module <i>module-name</i> <i>file-name</i>
</pre></div>
<p>
But a better was of using all the power of SWIG is to write SWIG
interface files. Below we will explain how to write interface
files and the various things which you can do with them.
</p>
<H3><a name="Lisp_nn4">29.2.1 Additional Commandline Options </a></H3>
<table summary="CFFI specific options">
<tr>
<th> CFFI specific options</th>
</tr>
<tr>
<td>-generate-typedef</td>
<td>If this option is given then defctype will be used to generate<br/>
shortcuts according to the typedefs in the input.
</td>
</tr>
<tr>
<td>-[no]cwrap</td>
<td>Turn on or turn off generation of an intermediate C file when<br/>
creating a C interface. By default this is only done for C++ code.
</td>
</tr>
<tr>
<td>-[no]swig-lisp</td>
<td>Turns on or off generation of code for helper lisp macro, functions,
etc. which SWIG uses while generating wrappers. These macros, functions
may still be used by generated wrapper code.
</td>
</tr>
</table>
<H3><a name="Lisp_nn5">29.2.2 Generating CFFI bindings</a></H3>
<p>
As we mentioned earlier the ideal way to use SWIG is to use interface
files. To illustrate the use of it, let's assume that we have a
file named <i>test.h</i> with the following C code:
</p>
<div class="code"><pre>
#define y 5
#define x (y &gt;&gt; 1)
typedef int days;
struct bar {
short p, q;
char a, b;
int *z[1000];
struct bar * n;
};
struct bar * my_struct;
struct foo {
int a;
struct foo * b[100];
};
int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int p);
int func123(div_t * p, int **q[100], int r[][1000][10]);
void lispsort_double (int n, double * array);
enum color { RED, BLUE, GREEN};
</pre></div>
<p>
Corresponding to this we will write a simple interface file:
</p>
<div class="code"><pre>
%module test
%include "test.h"
</pre></div>
<p>
The generated SWIG Code will be:
</p>
<div class="targetlang"><pre>
;;;SWIG wrapper code starts here
(cl:defmacro defanonenum (&amp;body enums)
"Converts anonymous enums to defconstants."
`(cl:progn , @(cl:loop for value in enums
for index = 0 then (cl:1+ index)
when (cl:listp value) do (cl:setf index (cl:second value)
value (cl:first value))
collect `(cl:defconstant , value , index))))
(cl:eval-when (:compile-toplevel :load-toplevel)
(cl:unless (cl:fboundp 'swig-lispify)
(cl:defun swig-lispify (name flag cl:&amp;optional (package cl:*package*))
(cl:labels ((helper (lst last rest cl:&amp;aux (c (cl:car lst)))
(cl:cond
((cl:null lst)
rest)
((cl:upper-case-p c)
(helper (cl:cdr lst) 'upper
(cl:case last
((lower digit) (cl:list* c #\- rest))
(cl:t (cl:cons c rest)))))
((cl:lower-case-p c)
(helper (cl:cdr lst) 'lower (cl:cons (cl:char-upcase c) rest)))
((cl:digit-char-p c)
(helper (cl:cdr lst) 'digit
(cl:case last
((upper lower) (cl:list* c #\- rest))
(cl:t (cl:cons c rest)))))
((cl:char-equal c #\_)
(helper (cl:cdr lst) '_ (cl:cons #\- rest)))
(cl:t
(cl:error "Invalid character: ~A" c)))))
(cl:let ((fix (cl:case flag
((constant enumvalue) "+")
(variable "*")
(cl:t ""))))
(cl:intern
(cl:concatenate
'cl:string
fix
(cl:nreverse (helper (cl:concatenate 'cl:list name) cl:nil cl:nil))
fix)
package))))))
;;;SWIG wrapper code ends here
(cl:defconstant y 5)
(cl:defconstant x (cl:ash 5 -1))
(cffi:defcstruct bar
(p :short)
(q :short)
(a :char)
(b :char)
(z :pointer)
(n :pointer))
(cffi:defcvar ("my_struct" my_struct)
:pointer)
(cffi:defcstruct foo
(a :int)
(b :pointer))
(cffi:defcfun ("pointer_func" pointer_func) :int
(ClosureFun :pointer)
(p :int))
(cffi:defcfun ("func123" func123) :int
(p :pointer)
(q :pointer)
(r :pointer))
(cffi:defcfun ("lispsort_double" lispsort_double) :void
(n :int)
(array :pointer))
(cffi:defcenum color
:RED
:BLUE
:GREEN)
</pre></div>
<p>
The <i>SWIG wrapper</i> code refers to the special code which SWIG
may need to use while wrapping C code. You can turn on/off the
generation of this code by using the <i>-[no]swig-lisp</i>
option. You must have noticed that SWIG goes one extra step to
ensure that CFFI does not do automatic lispification of the C
function names. The reason SWIG does this is because quite often
developers want to build a nice CLOS based lispy API, and this one
to one correspondence between C function names and lisp function
name helps.
</p>
<p> Maybe you want to have your own convention for generating lisp
function names for corresponding C function names, or you just
want to lispify the names, also, before we forget you want to
export the generated lisp names. To do this, we will use the
SWIG <a
href="Customization.html#Customization_features">feature directive</a>.
Let's edit the interface file such that the C type "div_t*" is changed
to Lisp type ":my-pointer", we lispify all names,
export everything, and do some more stuff.
</p>
<div class="code"><pre>
%module test
%typemap(cin) div_t* ":my-pointer"
%feature("intern_function", "1");
%feature("export");
%feature("inline") lispsort_double;
%feature("intern_function", "my-lispify") lispsort_double;
%feature("export", package="'some-other-package") lispsort_double;
%rename func123 renamed_cool_func;
%ignore "pointer_func";
%include "test.h"
</pre></div>
<p>
The <i>typemap(cin)</i> ensures that for all arguments which are input
to C with the type "div_t*", the ":my-pointer" type be
used. Similarly <i>typemap(cout)</i> are used for all types which
are returned from C.
</p>
<p>
The feature <i>intern_function</i> ensures that all C names are
interned using the <b>swig-lispify</b> function. The "1" given
to the feature is optional. The use of feature like
<i>%feature("intern_function", "1");</i> globally enables
interning for everything. If you want to target a single
function, or declaration then use the targeted version of
feature, <i>%feature("intern_function", "my-lispify")
lispsort_double;</i>, here we are using an additional feature
which allows us to use our lispify function.
</p>
<p>The <i>export</i> feature allows us to export the symbols. If
the <i>package</i> argument is given, then the symbol will be exported to
the specified Lisp package. The <i>inline</i> feature declaims the
declared function as inline. The <i>rename</i> directive allows us to
change the name(it is useful when generating C wrapper code for handling
overloaded functions). The <i>ignore</i> directive ignores a certain
declaration.
</p>
<p>There are several other things which are possible, to see some
example of usage of SWIG look at the Lispbuilder and wxCL
projects. The generated code with 'noswig-lisp' option is:
</p>
<div class="targetlang"><pre>
(cl:defconstant #.(swig-lispify "y" 'constant) 5)
(cl:export '#.(swig-lispify "y" 'constant))
(cl:defconstant #.(swig-lispify "x" 'constant) (cl:ash 5 -1))
(cl:export '#.(swig-lispify "x" 'constant))
(cffi:defcstruct #.(swig-lispify "bar" 'classname)
(#.(swig-lispify "p" 'slotname) :short)
(#.(swig-lispify "q" 'slotname) :short)
(#.(swig-lispify "a" 'slotname) :char)
(#.(swig-lispify "b" 'slotname) :char)
(#.(swig-lispify "z" 'slotname) :pointer)
(#.(swig-lispify "n" 'slotname) :pointer))
(cl:export '#.(swig-lispify "bar" 'classname))
(cl:export '#.(swig-lispify "p" 'slotname))
(cl:export '#.(swig-lispify "q" 'slotname))
(cl:export '#.(swig-lispify "a" 'slotname))
(cl:export '#.(swig-lispify "b" 'slotname))
(cl:export '#.(swig-lispify "z" 'slotname))
(cl:export '#.(swig-lispify "n" 'slotname))
(cffi:defcvar ("my_struct" #.(swig-lispify "my_struct" 'variable))
:pointer)
(cl:export '#.(swig-lispify "my_struct" 'variable))
(cffi:defcstruct #.(swig-lispify "foo" 'classname)
(#.(swig-lispify "a" 'slotname) :int)
(#.(swig-lispify "b" 'slotname) :pointer))
(cl:export '#.(swig-lispify "foo" 'classname))
(cl:export '#.(swig-lispify "a" 'slotname))
(cl:export '#.(swig-lispify "b" 'slotname))
(cffi:defcfun ("renamed_cool_func" #.(swig-lispify "renamed_cool_func" 'function)) :int
(p :my-pointer)
(q :pointer)
(r :pointer))
(cl:export '#.(swig-lispify "renamed_cool_func" 'function))
(cl:declaim (cl:inline #.(my-lispify "lispsort_double" 'function)))
(cffi:defcfun ("lispsort_double" #.(my-lispify "lispsort_double" 'function)) :void
(n :int)
(array :pointer))
(cl:export '#.(my-lispify "lispsort_double" 'function) 'some-other-package)
(cffi:defcenum #.(swig-lispify "color" 'enumname)
#.(swig-lispify "RED" 'enumvalue :keyword)
#.(swig-lispify "BLUE" 'enumvalue :keyword)
#.(swig-lispify "GREEN" 'enumvalue :keyword))
(cl:export '#.(swig-lispify "color" 'enumname))
</pre></div>
<H3><a name="Lisp_nn6">29.2.3 Generating CFFI bindings for C++ code</a></H3>
<p>This feature to SWIG (for CFFI) is very new and still far from
complete. Pitch in with your patches, bug reports and feature
requests to improve it.
</p>
<p> Generating bindings for C++ code, requires <i>-c++</i> option to be
present and it first generates C binding which will wrap the C++
code, and then generates the
corresponding CFFI wrapper code. In the generated C wrapper
code, you will often want to put your own C code, such as the
code to include various files. This can be done by making use of
"%{" and "%}" as shown below.
</p>
<div class="code"><pre>
%{
#include "Test/test.h"
%}
</pre></div>
<p>
Also, while parsing the C++ file and generating C wrapper code SWIG
may need to be able to understand various symbols used in other
header files. To help SWIG in doing this while ensuring that
wrapper code is generated for the target file, use the "import"
directive. The "include" directive specifies the target file for
which wrapper code will be generated.
</p>
<div class="code"><pre>
%import "ancillary/header.h"
%include "target/header.h"
</pre></div>
<p>
Various features which were available for C headers can also be used
here. The target header which we are going to use here is:
</p>
<div class="code"><pre>
namespace OpenDemo {
class Test
{
public:
float x;
// constructors
Test (void) {x = 0;}
Test (float X) {x = X;}
// vector addition
Test operator+ (const Test&amp; v) const {return Test (x+v.x);}
// length squared
float lengthSquared (void) const {return this-&gt;dot (*this);}
static float distance (const Test&amp; a, const Test&amp; b){return(a-b).length();}
inline Test parallelComponent (const Test&amp; unitBasis) const {
return unitBasis * projection;
}
Test setYtoZero (void) const {return Test (this-&gt;x);}
static const Test zero;
};
inline Test operator* (float s, const Test&amp; v) {return v*s;}
inline std::ostream&amp; operator&lt;&lt; (std::ostream&amp; o, const Test&amp; v)
{
return o &lt;&lt; "(" &lt;&lt; v.x &lt;&lt; ")";
}
inline Test RandomUnitVectorOnXZPlane (void)
{
return RandomVectorInUnitRadiusSphere().setYtoZero().normalize();
}
}
</pre></div>
<p>The interface used is: </p>
<div class="code"><pre>
%module test
%include "test.cpp"
</pre></div>
<p>
SWIG generates 3 files, the first one is a C wrap which we don't show,
the second is the plain CFFI wrapper which is as shown below:
</p>
<div class="targetlang"><pre>
(cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
(self :pointer)
(x :float))
(cffi:defcfun ("_wrap_Test_x_get" Test_x_get) :float
(self :pointer))
(cffi:defcfun ("_wrap_new_Test__SWIG_0" new_Test) :pointer)
(cffi:defcfun ("_wrap_new_Test__SWIG_1" new_Test) :pointer
(X :float))
(cffi:defcfun ("_wrap_Test___add__" Test___add__) :pointer
(self :pointer)
(v :pointer))
(cffi:defcfun ("_wrap_Test_lengthSquared" Test_lengthSquared) :float
(self :pointer))
(cffi:defcfun ("_wrap_Test_distance" Test_distance) :float
(a :pointer)
(b :pointer))
(cffi:defcfun ("_wrap_Test_parallelComponent" Test_parallelComponent) :pointer
(self :pointer)
(unitBasis :pointer))
(cffi:defcfun ("_wrap_Test_setYtoZero" Test_setYtoZero) :pointer
(self :pointer))
(cffi:defcvar ("Test_zero" Test_zero)
:pointer)
(cffi:defcfun ("_wrap_delete_Test" delete_Test) :void
(self :pointer))
(cffi:defcfun ("_wrap___mul__" __mul__) :pointer
(s :float)
(v :pointer))
(cffi:defcfun ("_wrap___lshift__" __lshift__) :pointer
(o :pointer)
(v :pointer))
(cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
</pre></div>
<p>
The output is pretty good but it fails in disambiguating overloaded
functions such as the constructor, in this case. One way of
resolving this problem is to make the interface use the rename
directiv, but hopefully there are better solutions.
In addition SWIG also generates, a CLOS file
</p>
<div class="targetlang"><pre>
(clos:defclass test()
((ff :reader ff-pointer)))
(clos:defmethod (cl:setf x) (arg0 (obj test))
(Test_x_set (ff-pointer obj) arg0))
(clos:defmethod x ((obj test))
(Test_x_get (ff-pointer obj)))
(cl:shadow "+")
(clos:defmethod + ((obj test) (self test) (v test))
(Test___add__ (ff-pointer obj) (ff-pointer self) (ff-pointer v)))
(clos:defmethod length-squared ((obj test) (self test))
(Test_lengthSquared (ff-pointer obj) (ff-pointer self)))
(clos:defmethod parallel-component ((obj test) (self test) (unitBasis test))
(Test_parallelComponent (ff-pointer obj) (ff-pointer self) (ff-pointer unitBasis)))
(clos:defmethod set-yto-zero ((obj test) (self test))
(Test_setYtoZero (ff-pointer obj) (ff-pointer self)))
</pre></div>
<p>I agree that the CFFI C++ module needs lot more work. But I hope it
provides a starting point, on which you can base your work of
importing C++ libraries to Lisp.
</p>
<p>
If you have any questions, suggestions, patches, etc., related to CFFI
module feel free to contact us on the SWIG mailing list, and
also please add a "[CFFI]" tag in the subject line.
<H3><a name="Lisp_nn7">29.2.4 Inserting user code into generated files</a></H3>
<p>
It is often necessary to <a href="SWIG.html#SWIG_nn40">include user-defined code</a>
into the automatically generated interface files. For example, when building
a C++ interface, example_wrap.cxx will likely not compile unless
you add a <tt>#include "header.h"</tt> directive. This can be done
using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
</p>
<div class="code">
<pre>
%module example
%{
#include "header.h"
%}
%include "header.h"
int fact(int n);
</pre>
</div>
<p>
Additional sections have been added for inserting into the
generated lisp interface file:
</p>
<ul>
<li><tt>lisphead</tt> - inserts before type declarations</li>
<li><tt>swiglisp</tt> - inserts after type declarations according to
where it appears in the .i file</li>
</ul>
<p>
Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
<tt>%insert("header") %{ ... %}</tt>.
</p>
</body>
</html>

20
Doc/Manual/Lua.html
View File

@ -77,7 +77,7 @@
<p>
Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ISO C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to &lt;100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a>
Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ISO C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to &lt;100 kilobytes of binary code. It can be found at <a href="https://www.lua.org">https://www.lua.org</a>
</p>
<p>
eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a>
@ -171,7 +171,8 @@ swig -lua -help
<tr>
<td>-no-old-metatable-bindings</td>
<td>Disable backward compatibility: old-style binding names generations and a few other things. Explanations are included in appropriate later sections.</td>
<td>Disable backward compatibility: old-style binding names generations and a few other things. Explanations are included in appropriate later sections.
This option is considered deprecated and will be removed in the near future.</td>
</tr>
<tr>
<td>-squash-bases</td>
@ -370,7 +371,6 @@ creates a built-in function <tt>example.fact(n)</tt> that works exactly like you
To avoid name collisions, SWIG create a Lua table which keeps all the functions, constants, classes and global variables in.
It is possible to copy the functions, constants and classes (but not variables) out of this and into the global environment with the following code.
This can easily overwrite existing functions, so this must be used with care.
This option is considered deprecated and will be removed in the near future.
</p>
<div class="targetlang"><pre>
&gt; for k, v in pairs(example) do _G[k]=v end
@ -410,7 +410,7 @@ SWIG will effectively generate two functions <tt>example.Foo_set()</tt> and <tt>
&gt; example.Foo=4
&gt; print(c)
3
&gt; c=5 -- this will not effect the original example.Foo
&gt; c=5 -- this will not affect the original example.Foo
&gt; print(example.Foo, c)
4 5
</pre></div>
@ -566,7 +566,7 @@ If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style
</p>
<p>
It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other.
Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues.
Given the fact that these are constants and they are not supposed to be changed, it is up to you to avoid such issues.
</p>
<H3><a name="Lua_nn12">29.3.5 Pointers</a></H3>
@ -1624,8 +1624,8 @@ does SWIG have any indication of how large an array should be. However with the
arrays for convenient usage.</p>
<p>Given the functions:</p>
<div class="code"><pre>extern void sort_int(int* arr, int len);
extern void sort_double(double* arr, int len);
<div class="code"><pre>extern void sort_int(int* arr, size_t len);
extern void sort_double(double* arr, size_t len);
</pre></div>
<p>There are basically two ways that SWIG can deal with this. The first way, uses the <tt>&lt;carrays.i&gt;</tt> library
@ -1641,13 +1641,13 @@ More details can be found in the <a href="Library.html#Library_carrays">carrays.
// this declares a batch of functions for manipulating C integer arrays
%array_functions(int, int)
extern void sort_int(int* arr, int len); // the function to wrap
extern void sort_int(int* arr, size_t len); // the function to wrap
// using typemaps
%include &lt;typemaps.i&gt;
%apply (double *INOUT, int) {(double* arr, int len)};
%apply (double *INOUT, int) {(double* arr, size_t len)};
extern void sort_double(double* arr, int len); // the function to wrap
extern void sort_double(double* arr, size_t len); // the function to wrap
</pre></div>
<p>Once wrapped, the functions can both be called, though with different ease of use:</p>

6
Doc/Manual/Makefile
View File

@ -1,7 +1,7 @@
# Makefile for generating the SWIG documentation
#
# Note that the htmldoc package needs to be installed. wkhtmltopdf patched with qt is also required
# and can be installed from http://wkhtmltopdf.org/downloads.html.
# and the prebuilt binaries can be installed from https://wkhtmltopdf.org/downloads.html.
#
# The .html files are first processed and updated with chapter numbering and anchor names
# are added to the HTML headings using the python scripts. The htmldoc program is then
@ -43,8 +43,8 @@ check:
# 3) <pre> <tt> <code> elements do not always select a fixed-width font - try installing the
# Courier font to fix - these have been added to style.css.
generate: SWIGDocumentation.html
wkhtmltopdf --version | grep "with patched qt" || (echo "wkhtmltopdf is not the patched qt version and so cannot be used - download it from http://wkhtmltopdf.org/downloads.html" && false)
wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 10mm --margin-right 10mm --header-font-size 6 --footer-font-size 6 --header-spacing 6 --footer-spacing 6 --header-center '[doctitle]' --footer-left '[subsection]' --footer-right '[page]' SWIGDocumentation.html SWIGDocumentation.pdf
wkhtmltopdf --version | grep "with patched qt" || (echo "wkhtmltopdf is not the patched qt version and so cannot be used - download it from https://wkhtmltopdf.org/downloads.html" && false)
wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 10mm --margin-right 10mm --header-font-size 6 --footer-font-size 6 --header-spacing 6 --footer-spacing 6 --header-center '[doctitle]' --footer-left '[subsection]' --footer-right '[page]' --allow . SWIGDocumentation.html SWIGDocumentation.pdf
SWIGDocumentation.html: swightml.book
htmldoc --batch swightml.book || true

3
Doc/Manual/Mzscheme.html
View File

@ -22,7 +22,8 @@
<p>
This section contains information on SWIG's support of Racket, formally known as MzScheme.
This section contains information on SWIG's support of Racket, formally known as MzScheme. SWIG works with Racket versions &lt; 8 (Racket 8 switched to be based on a different scheme interpreter and SWIG hasn't been updated for this change).
</p>
<H2><a name="MzScheme_nn2">38.1 Creating native structures</a></H2>

21
Doc/Manual/Ocaml.html
View File

@ -68,10 +68,8 @@ This chapter describes SWIG's support of Ocaml.
</p>
<p>
Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
language to be added. Ocaml has widely acknowledged benefits for engineers,
mostly derived from a sophisticated type system, compile-time checking
Ocaml was the second compiled, typed language to be added to SWIG.
Ocaml has a sophisticated type system, compile-time checking
which eliminates several classes of common programming errors, and good
native performance. While all of this is wonderful, there are well-written
C and C++ libraries that Ocaml users will want to take advantage of as
@ -85,14 +83,15 @@ variants, functions, classes, etc.
<p>
If you're not familiar with the Objective Caml language, you can visit
<a href="http://ocaml.org/">The Ocaml Website</a>.
<a href="https://ocaml.org/">The Ocaml Website</a>.
</p>
<H2><a name="Ocaml_nn2">39.1 Preliminaries</a></H2>
<p>
SWIG is compatible with OCaml 3.12.0 and above. Given the choice,
SWIG is known to be compatible with OCaml 4.13.1 and above - older versions
are not regularly tested. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86, PPC, Sparc) and Cygwin on Windows. The
best way to determine whether your system will work is to compile the
@ -258,9 +257,17 @@ option is not needed when you build native code.
<H3><a name="Ocaml_nn7">39.1.5 Compilation problems and compiling with C++</a></H3>
<p>
Ocaml's C extension API unfortunately defines a <tt>value</tt> typedef - this
overly-generic name can collide with the C or C++ API being wrapped if it
defines a variable, function, member or type also called <tt>value</tt>.
Prior to SWIG 4.2.1, SWIG attempted to work around this but the hack used
itself caused problems so we've removed it. The problem is not one SWIG
created, nor one SWIG can really solve.
</p>
<p>
As mentioned above, .cxx files need special
As mentioned earlier, C++ files need special
handling to be compiled with <tt>ocamlc</tt>. Other than that, C code
that uses <tt>class</tt> as a non-keyword, and C code that is too
liberal with pointer types may not compile under the C++ compiler.

21
Doc/Manual/Octave.html
View File

@ -51,8 +51,8 @@
<p>
Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
More information can be found at <a href="http://www.gnu.org/software/octave/">Octave web site</a>.
Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
More information can be found at <a href="https://octave.org/">Octave web site</a>.
</p>
<p>
@ -64,7 +64,8 @@ Also, there are a dozen or so examples in the Examples/octave directory, and hun
<p>
SWIG is regularly tested against the following versions of Octave: 3.8, 4.0, 4.2.
SWIG is regularly tested against the following versions of Octave: 5.2, 6.4.
SWIG 4.2.1 has also been manually tested with 7.3, 8.4 and 9.0.
</p>
<p>
@ -104,9 +105,6 @@ The <tt>-c++</tt> option is also required when wrapping C++ code:
<div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
<p>
This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
</p>
<H3><a name="Octave_nn4">30.2.1 Command-line options</a></H3>
@ -625,6 +623,16 @@ On the C++ side, the default mappings are as follows:
Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
</p>
<p>
Octave has several operators for which no corresponding C++ operators exist. For example, the Octave code
</p>
<div class="targetlang"><pre>
x=[a,b,c];
</pre></div>
<p>
calls the Octave operator <tt>horzcat</tt> of the class of <tt>a</tt>. Hence, if <tt>a</tt> is of type <tt>swig_ref</tt> you can write an overload for this operator for your wrapped C++ class by placing a file <tt>@swig_ref/horzcat.m</tt> in the Octave load path (like for every Octave class, see <a href="https://docs.octave.org/latest/Creating-a-Class.html">Creating a Class</a>). This Octave function file is then called whenever the above Octave code is executed for a variable of type <tt>swig_ref</tt>.
</p>
<H3><a name="Octave_nn19">30.3.10 Class extension with %extend</a></H3>
@ -855,6 +863,7 @@ The use of threads in wrapped Director code is not supported; i.e., an Octave-si
<p>
As noted above, <tt>swig_ref</tt> represents a reference counted pointer to a C/C++-side object. It also contains a flag indicating whether Octave or the C/C++ code owns the object. If Octave owns it, any destructors will be called when the reference count reaches zero. If the C/C++ side owns the object, then destructors will not be called when the reference count goes to zero.
As noted above, <tt>swig_ref</tt> represents a reference counted pointer to a C/C++-side object. It also contains a flag indicating whether Octave or the C/C++ code owns the object. If Octave owns it, any destructors will be called when the reference count reaches zero. If the C/C++ side owns the object, then destructors will not be called when the reference count goes to zero.
</p>
<p>
For example,

32
Doc/Manual/Perl5.html
View File

@ -604,7 +604,7 @@ source has a list of macros that are known to conflict with either standard head
other headers. But if you get macro type conflicts from other macros not included
in Lib/perl5/noembed.h while compiling the wrapper, you will
have to find the macro that conflicts and add an #undef into the .i file. Please report
any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>.
any conflicting macros you find to <a href="https://www.swig.org/mail.html">swig-user mailing list</a>.
</p>
<H3><a name="Perl5_nn10">31.2.7 Compiling for 64-bit platforms</a></H3>
@ -1729,28 +1729,6 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
See the chapter on "<a href="Customization.html#Customization">Customization features</a>" for more examples.
</p>
<p>
<b>Compatibility note:</b> In SWIG1.1, exceptions were defined using the older <tt>%except</tt> directive:
</p>
<div class="code">
<pre>
%except(perl5) {
try {
$function
}
catch (RangeError) {
croak("Array index out-of-bounds");
}
}
</pre>
</div>
<p>
This is still supported, but it is deprecated. The newer <tt>%exception</tt> directive provides the same
functionality, but it has additional capabilities that make it more powerful.
</p>
<H2><a name="Perl5_nn27">31.7 Remapping datatypes with typemaps</a></H2>
@ -1961,14 +1939,6 @@ Clean up return value from a function.
Setting of C++ member data (all languages).
</div>
<p>
<tt>%typemap(memberout)</tt>
</p>
<div class="indent">
Return of C++ member data (all languages).
</div>
<p>
<tt>%typemap(check)</tt>
</p>

182
Doc/Manual/Php.html
View File

@ -30,6 +30,7 @@
<li><a href="#Php_nn2_6_3">Static Member Variables</a>
<li><a href="#Php_nn2_6_4">Static Member Functions</a>
<li><a href="#Php_nn2_6_5">Specifying Implemented Interfaces</a>
<li><a href="#Php_nn2_6_6">Dynamic Properties</a>
</ul>
<li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
@ -50,12 +51,13 @@
<p>
In this chapter, we discuss SWIG's support of PHP. Currently any PHP7 or PHP8
In this chapter, we discuss SWIG's support of PHP. Currently any PHP8
release should work.
</p>
<p>
Support for PHP7 was added in SWIG 3.0.11 and for PHP8 in 4.1.0.
Support for PHP8 was added in SWIG 4.1.0.
Support for PHP7 was added in SWIG 3.0.11 and removed in 4.2.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>
@ -75,13 +77,14 @@ available.
<p>
To build a PHP extension, run swig using the <tt>-php7</tt> option as follows
(<tt>-php</tt> is also supported and currently is an alias for <tt>-php7</tt>
but prior to SWIG 4.0.0 it was an alias for <tt>-php5</tt>):
To build a PHP extension, run swig using the <tt>-php</tt> option
(you can also use <tt>-php7</tt> - PHP7 and PHP8 have a largely compatible C
extension API, hence the same option name has been used for both). For
example:
</p>
<div class="code"><pre>
swig -php7 example.i
swig -php example.i
</pre></div>
<p>
@ -145,9 +148,9 @@ least work for Linux though):
<p>
To test the extension from a PHP script, you first need to tell PHP to
load it. Assuming you're using PHP 7.2 or higher, the recommended (and
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>:
load it. The recommended (and 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>
@ -155,16 +158,23 @@ and add a line like this to the <tt>[PHP]</tt> section of <tt>php.ini</tt>:
</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:
If the module is not in PHP's default extension directory, you also need to
specify the path, in which case you'll also need to deal with platform-specific
naming - for example, on Linux:
</p>
<div class="code"><pre>
extension=/path/to/modulename.so
</pre></div>
<p>
but on Microsoft Windows you'd need to use:
</p>
<div class="code"><pre>
extension=/path/to/php_modulename.dll
</pre></div>
<p>
If you're using the PHP CLI SAPI it's possible (but not recommended) to use the
<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to
@ -173,15 +183,17 @@ PHP script which uses your extension:
</p>
<div class="code"><pre>
dl("/path/to/modulename.so"); // Load the module
dl("modulename"); // Load the module
</pre></div>
<p>
But to do this portably you need to take into account that pathnames and the
filename extension vary by platform, and for security reasons PHP no longer
supports <tt>dl()</tt> when running PHP through a webserver. Overall it's
better to instead use <tt>extension</tt> in <tt>php.ini</tt> as described
above.
Again, if the module isn't in PHP's default extension directory you'll also
need to specify the path and deal with that varying by platform.
</p>
<p>
For security reasons PHP no longer supports <tt>dl()</tt> when running PHP
through a webserver, so this isn't an option there.
</p>
<H2><a name="Php_nn2">32.2 Basic PHP interface</a></H2>
@ -226,47 +238,6 @@ echo "E = " . E . "\n";
</pre>
</div>
<p>
There's one peculiarity of how constants work in PHP prior to PHP 8
which it is useful to note (this is not specific to SWIG though) - if you try
to use an undeclared constant, PHP will emit a warning (or a notice in PHP 7.1
and earlier) and then expand the constant to a string version of the constant's
name. Unfortunately it is easy to miss the warning message if you're using PHP
in a webserver as it will probably end up in error.log or similar. PHP 8.0
made this an error.
</p>
<p>
For example,
</p>
<div class="code"><pre>
%module example
#define EASY_TO_MISPELL 0
</pre>
</div>
<p>
accessed incorrectly in PHP,
</p>
<div class="code">
<pre>
if(EASY_TO_MISPEL) {
...
} else {
...
}
</pre>
</div>
<p>
The mis-spelled constant will become the string 'EASY_TO_MISPEL', which
is treated as true by the if test, when the value of the intended constant
would be treated as false!
</p>
<H3><a name="Php_nn2_2">32.2.2 Global Variables</a></H3>
@ -345,9 +316,7 @@ $c = bar(3.5); # Use default argument for 2nd parameter
<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).
types for PHP 8 and later.
</p>
<p>
@ -634,18 +603,12 @@ variable, or assigning <tt>NULL</tt> to a variable.
<p>
SWIG defaults to wrapping C++ structs and classes with PHP classes.
SWIG wraps C++ structs and classes with PHP classes.
Since SWIG 4.1.0, this is done entirely via PHP's C API - earlier SWIG
versions generated a PHP wrapper script which defined proxy classes
which called a set of flat functions which actually wrapped the C++ class.
</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>
This interface file
</p>
@ -698,33 +661,16 @@ Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
<p>
The <tt>-noproxy</tt> option flattens the object structure and
generates collections of named functions. The above example results
in the following PHP functions:
SWIG/PHP used to support a <tt>-noproxy</tt> option to flatten the class
structure and generate collections of named flat functions. This is no
longer supported as of SWIG 4.1.0.
</p>
<div class="code"><pre>
new_Vector();
Vector_x_set($obj, $d);
Vector_x_get($obj);
Vector_y_set($obj, $d);
Vector_y_get($obj);
Vector_z_set($obj, $d);
Vector_z_get($obj);
Vector_magnitude($obj);
new_Complex();
Complex_re_set($obj, $d);
Complex_re_get($obj);
Complex_im_set($obj, $d);
Complex_im_get($obj);
</pre></div>
<H4><a name="Php_nn2_6_2">32.2.6.2 Constructors and Destructors</a></H4>
<p>
The constructor is called when <tt>new Object()</tt> (or
<tt>new_Object()</tt> if using <tt>-noproxy</tt>) is used to create an
The constructor is called when <tt>new Object()</tt> is used to create an
instance of the object. If multiple constructors are defined for an
object, function overloading will be used to determine which
constructor to execute.
@ -843,6 +789,60 @@ so:
If there are multiple interfaces, just list them separated by commas.
</p>
<H4><a name="Php_nn2_6_6">32.2.6.6 Dynamic Properties</a></H4>
<p>
Historically PHP has supported dynamic class properties and SWIG
has implemented them too (because we implement the magic <tt>__get()</tt>,
<tt>__set()</tt> and <tt>__isset()</tt> methods we need to include explicit
handling).
</p>
<p>
PHP 8.2 <a
href="https://wiki.php.net/rfc/deprecate_dynamic_properties">deprecates
dynamic class properties</a> - initially they'll warn, and apparently they'll
not work by default in PHP 9.0.
</p>
<p>
In PHP code dynamic properties can be enabled for a class by
marking that class with the attribute <tt>#[AllowDynamicProperties]</tt>.
</p>
<p>
To follow this PHP change, as of SWIG 4.1.0 you now need enable dynamic
properties for any classes you want to support them. To enable for class
<tt>Foo</tt>:
</p>
<div class="code"><pre>
%feature("php:allowdynamicproperties", 1) Foo;
</pre></div>
<p>
or to enable them for all wrapped classes:
</p>
<div class="code"><pre>
%feature("php:allowdynamicproperties", 1);
</pre></div>
<p>
Note that unknown features are ignored, so you can add use these
unconditionally in your interface file and it'll work with older SWIG too.
</p>
<p>
There was a bug in SWIG 4.1.0 where setting this feature to any value enabled
it - SWIG 4.2.0 fixed this and you can now set it to 0 to turn it off (for
example, you might want to enabled it for everything and then selectively turn
it off for specific classes).
</p>
<H3><a name="Php_nn2_7">32.2.7 PHP Pragmas, Startup and Shutdown code</a></H3>

22
Doc/Manual/Preface.html
View File

@ -80,7 +80,7 @@ Some target languages were disabled as part of a clean up and others were given
<p>
The LICENSE file shipped with SWIG in the top level directory contains the SWIG license.
For further insight into the license including the license of SWIG's output code, please visit
the SWIG legal page - <a href="http://www.swig.org/legal.html">http://www.swig.org/legal.html</a>.
the SWIG legal page - <a href="https://www.swig.org/legal.html">https://www.swig.org/legal.html</a>.
</p>
<p>
@ -98,7 +98,7 @@ The official location of SWIG related material is
</p>
<div class="shell"><pre>
<a href="http://www.swig.org">http://www.swig.org</a>
<a href="https://www.swig.org">https://www.swig.org</a>
</pre></div>
<p>
@ -111,7 +111,7 @@ You can also subscribe to the swig-user mailing list by visiting the page
</p>
<div class="shell"><pre>
<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
<a href="https://www.swig.org/mail.html">https://www.swig.org/mail.html</a>
</pre></div>
<p>
@ -125,7 +125,7 @@ about this can be obtained at:
</p>
<div class="shell"><pre>
<a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>
<a href="https://www.swig.org/svn.html">SWIG Bleeding Edge</a>
</pre></div>
@ -231,7 +231,7 @@ detailed release notes for previous releases and summary release notes from SWIG
SWIG is an unfunded project that would not be possible without the
contributions of many people working in their spare time.
If you have benefitted from using SWIG, please consider
<a href="http://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
<a href="https://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
There have been a large varied number of people
who have made contributions at all levels over time. Contributors
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
@ -244,8 +244,8 @@ are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or
Although every attempt has been made to make SWIG bug-free, we are also trying
to make feature improvements that may introduce bugs.
To report a bug, either send mail to the SWIG developer
list at the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a> or report a bug
at the <a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as
list at the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a> or report a bug
at the <a href="https://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as
possible, including (if applicable), error messages, tracebacks (if a
core dump occurred), corresponding portions of the SWIG interface file
used, and any important pieces of the SWIG generated wrapper code. We
@ -273,15 +273,15 @@ the main SWIG distribution. There is no need to download anything else.
These installation instructions are for using the distributed tarball,
for example, <tt>swig-3.0.8.tar.gz</tt>.
If you wish to build and install from source on Github, extra steps are required.
Please see the <a href="http://swig.org/svn.html">Bleeding Edge</a> page on the SWIG website.
Please see the <a href="https://swig.org/svn.html">Bleeding Edge</a> page on the SWIG website.
</p>
<p>
You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
You must use <a href="https://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
</p>
<p>
<a href="http://www.pcre.org/">PCRE2</a>
<a href="https://www.pcre.org/">PCRE2</a>
needs to be installed on your system to build SWIG, in particular
pcre2-config must be available. If you have PCRE2 headers and libraries but not
pcre2-config itself or, alternatively, wish to override the compiler or linker
@ -357,7 +357,7 @@ Note:
If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt>
before <tt>./configure</tt>. In addition, a full build of SWIG requires
a number of packages to be installed. Full instructions at
<a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>.
<a href="https://www.swig.org/svn.html">SWIG bleeding edge</a>.
</li>
</ul>

48
Doc/Manual/Preprocessor.html
View File

@ -48,7 +48,7 @@ like this:
<div class="code">
<pre>
%include "pointer.i"
%include "cpointer.i"
</pre>
</div>
@ -132,6 +132,7 @@ SWIGJAVA Defined when using Java
SWIGJAVASCRIPT Defined when using Javascript
SWIG_JAVASCRIPT_JSC Defined when using Javascript with -jsc
SWIG_JAVASCRIPT_V8 Defined when using Javascript with -v8 or -node
SWIG_JAVASCRIPT_NAPI Defined when using Javascript with -napi
SWIGLUA Defined when using Lua
SWIGMZSCHEME Defined when using Mzscheme
SWIGOCAML Defined when using OCaml
@ -147,6 +148,14 @@ SWIGTCL Defined when using Tcl
SWIGXML Defined when using XML
</pre></div>
<p>
SWIG also defines <tt>SWIG_VERSION</tt> and a target language macro in
the generated wrapper file (since SWIG 4.1.0 - in older versions these
were defined for some target languages but this wasn't consistent). Best
practice is to use SWIG-time conditional checks because that results in smaller
generated wrapper sources.
</p>
<p>
In addition, SWIG defines the following set of standard C/C++ macros:
</p>
@ -155,11 +164,44 @@ In addition, SWIG defines the following set of standard C/C++ macros:
<pre>
__LINE__ Current line number
__FILE__ Current file name
__STDC__ Defined to indicate ISO C
__cplusplus Defined when -c++ option used
__STDC__ Defined to indicate ISO C/C++
__cplusplus Defined when -c++ option used, value controlled by <tt>-std=c++NN</tt>
__STDC_VERSION__ May be defined when -c++ option is not used, value controlled by <tt>-std=cNN</tt>
</pre>
</div>
<p>
Since SWIG 4.2.0, <tt>__STDC__</tt> is defined to <tt>1</tt> to match
the behaviour of ISO C/C++ compilers. Before this SWIG defined it to
have an empty value.
</p>
<p>
Since SWIG 4.2.0, <tt>__cplusplus</tt> is defined to <tt>199711L</tt>
(the value for C++98) by default. Before this SWIG always defined it to have
the <b>value</b> <tt>__cplusplus</tt>.
</p>
<p>
Since SWIG 4.2.0, SWIG supports command line options <tt>-std=cNN</tt> and
<tt>-std=c++NN</tt> to specify the C/C++ standards version. The only effect of
these options is to set appropriate values for <tt>__STDC_VERSION__</tt> and
<tt>__cplusplus</tt> respectively, which is useful if you're wrapping
headers which have preprocessor checks based on their values.
</p>
<p>
If your code requires these macros to be set to a version of the standard
that is not a final official version, or one that SWIG is not yet aware of,
you can simply redefine the appropriate macro to an alternative value at the
top of your interface file, for example:
</p>
<div class="code"><pre>
#undef __cplusplus
#define __cplusplus 202211L
</pre></div>
<p>
The following are language specific symbols that might be defined:
</p>

138
Doc/Manual/Python.html
View File

@ -65,6 +65,7 @@
<li><a href="#Python_nn37">Overhead and code bloat</a>
<li><a href="#Python_nn38">Typemaps</a>
<li><a href="#Python_nn39">Miscellaneous</a>
<li><a href="#Python_stable_abi">Stable ABI</a>
</ul>
<li><a href="#Python_nn40">Common customization features</a>
<ul>
@ -94,7 +95,7 @@
</ul>
<li><a href="#Python_nn58">Typemap Examples</a>
<ul>
<li><a href="#Python_nn59">Converting Python list to a char ** </a>
<li><a href="#Python_nn59">Converting a Python list to a char ** </a>
<li><a href="#Python_nn60">Expanding a Python object into multiple arguments</a>
<li><a href="#Python_nn61">Using typemaps to return arguments</a>
<li><a href="#Python_nn62">Mapping Python tuples into small arrays</a>
@ -1983,8 +1984,8 @@ overloaded assignment operators don't map to Python semantics and will be ignore
<p>
Operator overloading is implemented in the <tt>pyopers.swg</tt> library file.
In particular overloaded operators are marked with the <tt>python:maybecall</tt> feature, also known as <tt>%pythonmaybecall</tt>.
This feature forces SWIG to generate code that return an instance of Python's <tt>NotImplemented</tt>
instead of raising an exception when the comparison fails, that is, on any kind of error.
This feature forces SWIG to generate code that returns an instance of Python's <tt>NotImplemented</tt>
instead of raising the usual <tt>TypeError</tt> exception when an incorrect type is passed to a SWIG wrapped method.
This follows the guidelines in <a href="https://www.python.org/dev/peps/pep-0207/">PEP 207 - Rich Comparisons</a> and <a href="https://docs.python.org/3/library/constants.html#NotImplemented">NotImplemented Python constant</a>.
</p>
@ -3128,9 +3129,7 @@ likely cause your program to segfault.
<p>
To help ensure that no references to the Python object remain after
calling <tt>__disown__()</tt>, this method returns a weak reference to
the Python object. Weak references are only available in Python versions
2.1 and higher, so for older versions you must explicitly delete all
references. Here is an example:
the Python object. Here is an example:
</p>
<div class="code">
@ -3320,6 +3319,40 @@ director feature for reentrant, recursive or threaded member
methods that return const references.
</p>
<H3><a name="Python_stable_abi">33.5.8 Stable ABI</a></H3>
<p>
By default, the version of Python used to compile the wrappers needs to be the same as that used during runtime.
Alternatvely, the <a href="https://docs.python.org/3/c-api/stable.html">Python Stable ABI</a> enables a single compiled binary to be used by different versions of Python.
This is enabled by defining <tt>Py_LIMITED_API</tt> during the compilation of the C/C++ wrapper code and setting this macro to a particular minimum version of Python that one wants to support.
</p>
<p>
SWIG supports the stable ABI, but only version 3.4 of Python and later is supported.
There are two recommended approaches for using SWIG and the stable ABI and both require setting the <tt>Py_LIMITED_API</tt> macro to be set to <tt>0x03040000</tt> as a minimum value (Python 3.4).
Either set this using <tt>%begin</tt> by adding the following into your interface file so that this macro appears at the beginning of the generated C/C++ code:
</p>
<div class="code"><pre>
%begin %{
#define Py_LIMITED_API 0x03040000
%}
</pre></div>
<p>
or simply define the macro using your C/C++ compiler's <tt>-D</tt> command line option, for example, <tt>-DPy_LIMITED_API=0x03040000</tt>.
</p>
<p>
The default SWIG command line options generate code that enable the limited API/stable ABI.
Some options, such as <tt>-builtin</tt>, <tt>-fast</tt> (used by <tt>-O</tt>) do not use the limited API and hence when <tt>Py_LIMITED_API</tt> is defined there will be missing symbols during compilation.
Compatibility of user's custom typemaps is of course dependent on the Python APIs used in the typemaps.
</p>
<p>
<b>Compatibility Note:</b> Support for the stable ABI was added in SWIG-4.2.0.
</p>
<H2><a name="Python_nn40">33.6 Common customization features</a></H2>
@ -3427,9 +3460,15 @@ For example:
<div class="code">
<pre>
/* Rename the SWIG-generated wrapper. */
%rename _set_transform set_transform;
...
void set_transform(Image *im, double x[4][4]);
...
/* Rewrite the high level interface to set_transform */
%pythoncode %{
def set_transform(im, x):
@ -3437,7 +3476,7 @@ def set_transform(im, x):
for i in range(4):
for j in range(4):
mat44_set(a, i, j, x[i][j])
_example.set_transform(im, a)
_example._set_transform(im, a)
free_mat44(a)
%}
</pre>
@ -3504,7 +3543,7 @@ The insert code can be seen at the start of the generated <tt>.py</tt> file:
<div class="code">
<pre>
# This file was automatically generated by SWIG (http://www.swig.org).
# This file was automatically generated by SWIG (https://www.swig.org).
# Version 4.0.0
#
# Do not make changes to this file unless you know what you are doing--modify
@ -3570,6 +3609,7 @@ public:
<p> where <tt>$action</tt> will be replaced by the call to
the C/C++ proper method.
Note that this does not include the arguments to the C/C++ method.
</p>
<p>
@ -4935,84 +4975,17 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Python_nn59">33.9.1 Converting Python list to a char ** </a></H3>
<H3><a name="Python_nn59">33.9.1 Converting a Python list to a char ** </a></H3>
<p>
A common problem in many C programs is the processing of command line
arguments, which are usually passed in an array of NULL terminated
strings. The following SWIG interface file allows a Python list
object to be used as a <tt>char **</tt> object.
strings. SWIG provides typemaps which allow passing a Python list
or tuple - see
<a href="Library.html#Library_argcargv">argcargv.i</a>.
</p>
<div class="code"><pre>
%module argv
// This tells SWIG to treat char ** as a special case
%typemap(in) char ** {
/* Check if is a list */
if (PyList_Check($input)) {
int size = PyList_Size($input);
int i = 0;
$1 = (char **) malloc((size+1)*sizeof(char *));
for (i = 0; i &lt; size; i++) {
PyObject *o = PyList_GetItem($input, i);
if (PyString_Check(o)) {
$1[i] = PyString_AsString(PyList_GetItem($input, i));
} else {
PyErr_SetString(PyExc_TypeError, "list must contain strings");
SWIG_fail;
}
}
$1[i] = 0;
} else {
PyErr_SetString(PyExc_TypeError, "not a list");
SWIG_fail;
}
}
// This cleans up the char ** array we malloc'd before the function call
%typemap(freearg) char ** {
free((char *) $1);
}
// Now a test function
%inline %{
int print_args(char **argv) {
int i = 0;
while (argv[i]) {
printf("argv[%d] = %s\n", i, argv[i]);
i++;
}
return i;
}
%}
</pre></div>
<p>
When this module is compiled, the wrapped C function now operates as
follows :
</p>
<div class="targetlang"><pre>
&gt;&gt;&gt; from argv import *
&gt;&gt;&gt; print_args(["Dave", "Mike", "Mary", "Jane", "John"])
argv[0] = Dave
argv[1] = Mike
argv[2] = Mary
argv[3] = Jane
argv[4] = John
5
</pre></div>
<p>
In the example, two different typemaps are used. The "in" typemap is
used to receive an input argument and convert it to a C array. Since dynamic
memory allocation is used to allocate memory for the array, the
"freearg" typemap is used to later release this memory after the execution of
the C function.
</p>
<H3><a name="Python_nn60">33.9.2 Expanding a Python object into multiple arguments</a></H3>
@ -5377,10 +5350,9 @@ int SWIG_ConvertPtr(PyObject *obj, void **ptr, swig_type_info *ty, int flags)</t
Converts a Python object <tt>obj</tt> to a C pointer. The result of the conversion is placed
into the pointer located at <tt>ptr</tt>. <tt>ty</tt> is a SWIG type descriptor structure.
<tt>flags</tt> is used to handle error checking and other aspects of conversion. It is the
bitwise-or of several flag values including <tt>SWIG_POINTER_EXCEPTION</tt> and
<tt>SWIG_POINTER_DISOWN</tt>. The first flag makes the function raise an exception on type
error. The second flag additionally
steals ownership of an object. Returns 0 on success and -1 on error.
bitwise-or of several flag values including <tt>SWIG_POINTER_DISOWN</tt> (which steals
ownership of the object) and <tt>SWIG_POINTER_NO_NULL</tt> (which makes the conversion fail
if the C pointer would be <tt>NULL</tt>). Returns 0 on success and -1 on error.
</div>
<p>

6
Doc/Manual/R.html
View File

@ -30,7 +30,7 @@
<p>
R is a GPL'ed open source statistical and plotting environment.
Information about R can be found at <a
href="http://www.r-project.org/">www.r-project.org</a>.
href="https://www.r-project.org/">www.r-project.org</a>.
</p>
<p>
@ -39,7 +39,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. They are also used to create the SimpleITK R package, which
runs on Linux and MacOS. SWIG is used to create all wrapper
interfaces
to <a href="http://http://www.simpleitk.org/">SimpleITK</a>. The R
to <a href="https://www.simpleitk.org/">SimpleITK</a>. The R
bindings also work on Microsoft Windows using Visual C++.
</p>
@ -321,7 +321,7 @@ and forth between integers.
<p>
The details of enumeration names and contents are stored in hidden R
environments, which are named according the the enumeration name - for
environments, which are named according to the enumeration name - for
example, an enumeration colour:
</p>

4
Doc/Manual/Ruby.html
View File

@ -152,7 +152,7 @@
<H2><a name="Ruby_nn2">35.1 Preliminaries</a></H2>
<p> SWIG 4.0 is known to work with Ruby versions 1.9 and later.
<p> SWIG 4.2 is known to work with Ruby versions 2.0 and later.
Given the choice, you should use the latest stable version of Ruby. You
should also determine if your system supports shared libraries and
dynamic loading. SWIG will work with or without dynamic loading, but
@ -3411,7 +3411,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
</tr>
<tr>
<td>char * StringValuePtr(String)</td>
<td>SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</td>
<td>SWIG_AsCharPtrAndSize(VALUE, char**, size_t*, int* alloc)</td>
</tr>
<tr>
<td>char * rb_str2cstr(String, int*length)</td>

59
Doc/Manual/SWIG.html
View File

@ -128,17 +128,17 @@ Supported Target Language Options
-lua - Generate Lua wrappers
-octave - Generate Octave wrappers
-perl5 - Generate Perl 5 wrappers
-php7 - Generate PHP 7 or later wrappers
-php7 - Generate PHP 8 or later wrappers
-python - Generate Python wrappers
-r - Generate R (aka GNU S) wrappers
-ruby - Generate Ruby wrappers
-scilab - Generate Scilab wrappers
-tcl8 - Generate Tcl 8 wrappers
-xml - Generate XML wrappers
Experimental Target Language Options
-mzscheme - Generate MzScheme/Racket wrappers
-ocaml - Generate OCaml wrappers
-xml - Generate XML wrappers
General Options
-addextern - Add extra extern declarations
@ -165,7 +165,7 @@ General Options
-debug-tmused - Display typemaps used debugging information
-directors - Turn on director mode for all the classes, mainly for testing
-dirprot - Turn on wrapping of protected members for director classes (default)
-D&lt;symbol&gt; - Define a symbol &lt;symbol&gt; (for conditional compilation)
-D&lt;symbol&gt;[=&lt;value&gt;] - Define symbol &lt;symbol&gt; (for conditional compilation)
-E - Preprocess only, does not generate wrapper code
-external-runtime [file] - Export the SWIG runtime stack
-fakeversion &lt;v&gt;- Make SWIG fake the program version number to &lt;v&gt;
@ -185,7 +185,6 @@ General Options
-includeall - Follow all #include statements
-l&lt;ifile&gt; - Include SWIG library file &lt;ifile&gt;
-macroerrors - Report errors inside macros
-makedefault - Create default constructors/destructors (the default)
-M - List all dependencies
-MD - Is equivalent to `-M -MF &lt;file&gt;', except `-E' is not implied
-MF &lt;file&gt; - Generate dependencies into &lt;file&gt; and continue generating wrappers
@ -196,7 +195,6 @@ General Options
-MT &lt;target&gt; - Set the target of the rule emitted by dependency generation
-nocontract - Turn off contract checking
-nocpperraswarn - Do not treat the preprocessor #error statement as #warning
-nodefault - Do not generate default constructors nor default destructors
-nodefaultctor - Do not generate implicit default constructors
-nodefaultdtor - Do not generate implicit default destructors
-nodirprot - Do not wrap director protected members
@ -212,14 +210,16 @@ General Options
-outdir &lt;dir&gt; - Set language specific files output directory to &lt;dir&gt;
-pcreversion - Display PCRE2 version information
-small - Compile in virtual elimination and compact mode
-std=&lt;standard&gt; - Set the C or C++ language &lt;standard&gt; for inputs
-swiglib - Report location of SWIG library and exit
-templatereduce - Reduce all the typedefs in templates
-U&lt;symbol&gt; - Undefine symbol &lt;symbol&gt;
-v - Run in verbose mode
-version - Display SWIG version number
-Wall - Remove all warning suppression, also implies -Wextra
-Wallkw - Enable keyword warnings for all the supported languages
-Werror - Treat warnings as errors
-Wextra - Adds the following additional warnings: 202,309,403,405,512,321,322
-Wextra - Adds the following additional warnings: 309,403,405,512,321,322
-w&lt;list&gt; - Suppress/add warning messages, eg -w401,+321 - see Warnings.html
-xmlout &lt;file&gt; - Write XML version of the parse tree to &lt;file&gt; after normal processing
</pre></div>
@ -1780,13 +1780,6 @@ const int foo; /* Read only variable */
char * const version="1.0"; /* Read only variable */
</pre></div>
<p>
<b>Compatibility note:</b> Read-only access used to be controlled by a pair of directives
<tt>%readonly</tt> and <tt>%readwrite</tt>. Although these directives still work, they
generate a warning message. Simply change the directives to <tt>%immutable;</tt> and
<tt>%mutable;</tt> to silence the warning. Don't forget the extra semicolon!
</p>
<H3><a name="SWIG_rename_ignore">5.4.7 Renaming and ignoring declarations</a></H3>
@ -1904,22 +1897,6 @@ to add conditional compilation to the header. However, it should be stressed t
declarations. If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead.
</p>
<p>
<b>Compatibility note: </b> Older versions of SWIG provided a special <tt>%name</tt> directive for renaming declarations.
For example:
</p>
<div class="code">
<pre>
%name(output) extern void print(const char *);
</pre>
</div>
<p>
This directive is still supported, but it is deprecated and should probably be avoided. The <tt>%rename</tt>
directive is more powerful and better supports wrapping of raw header file information.
</p>
<H4><a name="SWIG_advanced_renaming">5.4.7.3 Advanced renaming support</a></H4>
@ -2046,7 +2023,7 @@ and a more descriptive one, but the two functions are otherwise equivalent:
<td>String after (Perl-like) regex substitution operation. This function
allows applying arbitrary regular expressions to the identifier names. The
<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</a>)
by the <a href="https://www.pcre.org/">Perl Compatible Regular Expressions</a>)
(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
from 0 to 9, or one of the following escape sequences: <tt>\l</tt>, <tt>\L</tt>,
@ -2551,8 +2528,9 @@ for the above example you'll get:
</p>
<div class="code"><pre>
foo.i:5: Warning 302: Identifier 'Foo' redefined (ignored),
foo.i:5: Warning 302: Redefinition of identifier 'Foo' as Foo(void) ignored,
foo.i:1: Warning 302: previous definition of 'Foo'.
</pre></div>
<p>
@ -2942,14 +2920,14 @@ struct Bar { // Default destructor generated.
<p>
<b>Compatibility note:</b> Prior to SWIG-1.3.7, SWIG did not generate default constructors
or destructors unless you explicitly turned them on using <tt>-make_default</tt>.
or destructors unless you explicitly turned them on.
However, it appears that most users want to have constructor and destructor functions so it
has now been enabled as the default behavior.
</p>
<p>
<b>Note:</b> There are also the <tt>-nodefault</tt> option and
<tt>%nodefault</tt> directive, which disable both the default or
<b>Note:</b> There is also the
<tt>%nodefault</tt> directive, which disables both the default or
implicit destructor generation. This could lead to memory leaks across
the target languages, and it is highly recommended you don't use them.
</p>
@ -3226,13 +3204,6 @@ the allocation of additional storage in the object (e.g., their values must
be entirely synthesized from existing attributes of the structure or obtained elsewhere).
</p>
<p>
<b>Compatibility note:</b> The <tt>%extend</tt> directive is a new
name for the <tt>%addmethods</tt> directive. Since <tt>%addmethods</tt> could
be used to extend a structure with more than just methods, a more suitable
directive name has been chosen.
</p>
<H3><a name="SWIG_nested_structs">5.5.7 Nested structures</a></H3>
@ -3353,7 +3324,7 @@ the following function is generated instead:
<pre>
static int
_wrap_Vector_x_get(ClientData clientData, Tcl_Interp *interp,
int objc, Tcl_Obj *CONST objv[]) {
int objc, Tcl_Obj *const objv[]) {
struct Vector *arg1 ;
double result ;
@ -3664,8 +3635,8 @@ In the process of building an interface, SWIG may encounter syntax errors or
other problems. The best way to deal with this is to simply copy the offending
code into a separate interface file and edit it. However, the SWIG developers
have worked very hard to improve the SWIG parser--you should report parsing errors
to the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a> or to the
<a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>.
to the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a> or to the
<a href="https://www.swig.org/bugs.html">SWIG bug tracker</a>.
</p>
<H3><a name="SWIG_nn47">5.7.2 The SWIG interface file</a></H3>

391
Doc/Manual/SWIGPlus.html
View File

@ -34,6 +34,12 @@
<li><a href="#SWIGPlus_nn15">Protection</a>
<li><a href="#SWIGPlus_nn16">Enums and constants</a>
<li><a href="#SWIGPlus_nn17">Friends</a>
<ul>
<li><a href="#SWIGPlus_friend_classes">Friend classes</a>
<li><a href="#SWIGPlus_friend_function_definitions">Friend function definitions</a>
<li><a href="#SWIGPlus_friend_function_declarations">Friend function declarations</a>
<li><a href="#SWIGPlus_friends_unqualified">Unqualified friend functions</a>
</ul>
<li><a href="#SWIGPlus_nn18">References and pointers</a>
<li><a href="#SWIGPlus_nn19">Pass and return by value</a>
<li><a href="#SWIGPlus_nn20">Inheritance</a>
@ -57,6 +63,7 @@
<li><a href="#SWIGPlus_template_functions">Function templates</a>
<li><a href="#SWIGPlus_template_classes">Default template arguments</a>
<li><a href="#SWIGPlus_template_class_inheritance">Template base classes</a>
<li><a href="#SWIGPlus_template_empty">Empty template instantiation</a>
<li><a href="#SWIGPlus_template_specialization">Template specialization</a>
<li><a href="#SWIGPlus_template_member">Member templates</a>
<li><a href="#SWIGPlus_template_scoping">Scoping and templates</a>
@ -92,8 +99,8 @@ This chapter describes SWIG's support for wrapping C++.
It is mostly concerned about C++ as defined by the C++ 98 and 03 standards.
For additions to the original C++ standard, please read the
<a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a>,
<a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a> and
<a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> chapters.
<a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a>,
<a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> and
<a href="CPlusPlus20.html#CPlusPlus20">SWIG and C++20</a> chapters.
As a prerequisite,
you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see
@ -254,7 +261,7 @@ details. The SWIG Wiki also has further details.
</p>
<b>Compatibility Note:</b> Early versions of SWIG generated just a flattened low-level C style API to C++ classes by default.
The <tt>-noproxy</tt> commandline option is recognised by many target languages and will generate just this
The <tt>-noproxy</tt> commandline option is recognised by some target languages and will generate just this
interface as in earlier versions.
<H2><a name="SWIGPlus_nn38">6.5 Proxy classes</a></H2>
@ -691,8 +698,7 @@ class Foo { // No destructor is generated, unless one is declared
<b>Compatibility Note:</b> The generation of default
constructors/implicit destructors was made the default behavior in SWIG
1.3.7. This may break certain older modules, but the old behavior can
be easily restored using <tt>%nodefault</tt> or the
<tt>-nodefault</tt> command line option. Furthermore, in order for
be easily restored using <tt>%nodefault</tt>. Furthermore, in order for
SWIG to properly generate (or not generate) default constructors, it
must be able to gather information from both the <tt>private</tt> and
<tt>protected</tt> sections (specifically, it needs to know if a private or
@ -706,9 +712,9 @@ those sections in the interface or using <tt>%nodefault</tt> to fix the problem.
<p>
<b>Note:</b> The <tt>%nodefault</tt>
directive/<tt>-nodefault</tt> options described above, which disable both the default
directive described above, which disables both the default
constructor and the implicit destructors, could lead to memory
leaks, and so it is strongly recommended to not use them.
leaks, and so it is strongly recommended to not use it.
</p>
@ -874,10 +880,12 @@ could be wrapped, but they had to be renamed. For example:
<div class="code">
<pre>
%rename(CopyFoo) Foo::Foo(const Foo &amp;);
class Foo {
public:
Foo();
%name(CopyFoo) Foo(const Foo &amp;);
Foo(const Foo &amp;);
...
};
</pre>
@ -1087,13 +1095,6 @@ However, any use of <tt>%feature("naturalvar")</tt> will override the global set
typemaps, eg <tt>%apply const std::string &amp; { std::string * }</tt>, but this example would also apply the typemaps to methods taking a <tt>std::string</tt> pointer.
</p>
<p>
<b>Compatibility note:</b> Read-only access used to be controlled by a pair of directives
<tt>%readonly</tt> and <tt>%readwrite</tt>. Although these directives still work, they
generate a warning message. Simply change the directives to <tt>%immutable;</tt> and
<tt>%mutable;</tt> to silence the warning. Don't forget the extra semicolon!
</p>
<p>
<b>Compatibility note:</b> Prior to SWIG-1.3.12, all members of unknown type were
wrapped into accessor functions using pointers. For example, if you had a structure
@ -1172,64 +1173,218 @@ Members declared as <tt>const</tt> are wrapped as read-only members and do not c
<H2><a name="SWIGPlus_nn17">6.9 Friends</a></H2>
<H3><a name="SWIGPlus_friend_classes">6.9.1 Friend classes</a></H3>
<p>
Friend declarations are recognised by SWIG. For example, if
you have this code:
Friend classes are a C++ feature that do not affect SWIG wrappers.
SWIG simply parses the friend class declarations, but they are effectively ignored
as they have no meaningful effect for wrappers.
An example of friend classes:
</p>
<div class="code">
<pre>
class Foo {
public:
class X;
class Y;
class C {
// Friend classes have no effect on generated wrappers
friend class X;
friend Y;
...
friend void blah(Foo *f);
};
</pre>
</div>
<H3><a name="SWIGPlus_friend_function_definitions">6.9.2 Friend function definitions</a></H3>
<p>
A friend function definition in a C++ class defines a non-member function of the class
and simultaneously makes it a friend of the class.
For example, if you have this code:
</p>
<div class="code">
<pre>
class Buddy {
int val;
friend int blah(Buddy *b) { return b-&gt;val; }
public:
...
};
</pre>
</div>
<p>
then the <tt>friend</tt> declaration does result in a wrapper code
equivalent to one generated for the following declaration
then the <tt>friend</tt> function definition results in wrapper code
equivalent to one generated for the following:
</p>
<div class="code">
<pre>
class Foo {
class Buddy {
int val;
friend int blah(Buddy *b);
public:
...
};
void blah(Foo *f);
int blah(Buddy *b) { return b-&gt;val; }
</pre>
</div>
<p>
A friend declaration, as in C++, is understood to be in the same scope
where the class is declared, hence, you can have
Access from target languages is thus as if <tt>blah</tt> was wrapped as a non-member function.
The function is available and wrapped even if the friend is defined with private or protected access.
</p>
<p>
A friend definition, as in C++, is understood to be in the same scope
that the class is defined in, hence the scoping required for SWIG directives, such as <tt>%ignore</tt>, is as follows:
</p>
<div class="code">
<pre>
%ignore bar::blah(Foo *f);
%ignore bar::blah(Buddy *b);
// Not: %ignore bar::Buddy::blah(Buddy *b);
namespace bar {
class Foo {
class Buddy {
int val;
friend int blah(Buddy *b) { return b-&gt;val; }
public:
...
friend void blah(Foo *f);
...
};
}
</pre>
</div>
<p>
and a wrapper for the method 'blah' will not be generated.
and a wrapper for <tt>blah</tt> will not be generated.
</p>
<H3><a name="SWIGPlus_friend_function_declarations">6.9.3 Friend function declarations</a></H3>
<p>
A C++ class can specify friends via friend function declarations.
These functions are allowed access to the private and protected members of a class.
This is pure C++ functionality and these friend function declarations are hence quietly ignored by SWIG and do not result in any wrappers.
Well, not always! The C++ rules for friends that SWIG needs to follow are not that simple.
Technically, only qualified function declarations are silently ignored by SWIG.
Below are some examples of qualified friend declarations in <tt>A</tt> that are quietly ignored:
</p>
<div class="code">
<pre>
struct B {
int f();
B();
~B();
...
};
int g();
class A {
public:
// The following friend function-declarations are silently ignored (including constructor and destructor friends)
friend B::B();
friend B::~B();
friend int B::f();
friend int ::g();
...
};
</pre>
</div>
<p>
In the example above, if SWIG parses the struct <tt>B</tt> and global function <tt>g()</tt>,
then they are of course wrapped as normal.
</p>
<H3><a name="SWIGPlus_friends_unqualified">6.9.4 Unqualified friend functions</a></H3>
<p>
Further clarification is required regarding both friend function definitions and declarations.
In C++, friend function definitions can only be unqualified, whereas, friend function declarations can be either unqualified or qualified. Qualified friend function declarations are silently ignored by SWIG as covered in the previous section. SWIG does generate wrappers for any unqualified friend functions that it parses. This section goes through some of the complexities of wrapping unqualified friend functions.
</p>
<p>
Consider an unqualified friend function definition:
</p>
<div class="code">
<pre>
class Chum {
int val;
friend int blah() { Chum c; c.private_function(); return c.val; }
void private_function();
public:
...
};
</pre>
</div>
<p>
The <tt>Chum::blah()</tt> friend is very similar to the <tt>Buddy::blah(Buddy *)</tt> friend presented earlier.
However, the generated code to call <tt>blah()</tt> may not compile unlike the code to call <tt>blah(Buddy *)</tt>.
The compiler error will be something like:
<div class="shell">
<pre>
error: 'blah' was not declared in this scope
</pre>
</div>
<p>
The reason one works and the other doesn't is due to the rules around unqualified friend definitions/declarations. Broadly, friends are not visible for lookup except via argument dependent lookup that considers the class that the friend is defined/declared in, unless there is a <i>matching declaration</i> at namespace scope.
This will probably only make sense if you are conversant with this C++ concept, which is covered quite well at <a href="https://en.cppreference.com/w/cpp/language/adl">Argument-dependent lookup</a>.
In our examples, <tt>blah(Buddy *)</tt> is visible via argument dependent lookup, but <tt>blah()</tt> is not. The solution is thus to provide a <i>matching declaration</i> in order to make the function visible to the compiler. Simply add:
</p>
<div class="code">
<pre>
int blah();
</pre>
</div>
<p>
SWIG does <b>not</b> have to parse it. In all likelihood, your code already has the <i>matching declaration</i> as it is required in order for the friend function definition to be usable from pure C++ code.
</p>
<p>
The same potential problem applies to unqualified friend function declarations, such as:
</p>
<div class="code">
<pre>
class Mate {
int val;
friend int blah(); // Unqualified friend function declaration
void private_function();
public:
...
};
</pre>
</div>
<p>
Again, the actual function declaration needs to be visible to the compiler.
Or just the actual function definition as shown below.
This must be defined in the same scope as <tt>Mate</tt>.
Of course the function definition is necessary in order to avoid linking issues too.
</p>
<div class="code">
<pre>
int blah() { Mate m; m.private_function(); return m.val; }
</pre>
</div>
<H2><a name="SWIGPlus_nn18">6.10 References and pointers</a></H2>
@ -1363,13 +1518,13 @@ Vector *wrap_cross_product(Vector *a, Vector *b) {
</div>
<p>
In order for the wrapper code to compile, <tt>Vector</tt> must define a default constructor, copy assignment operator (and/or a move assignment operator for C++11 and later).
In order for the wrapper code to compile, <tt>Vector</tt> must define a default constructor and a copy assignment operator (and/or a move assignment operator for C++11 and later).
The <a href="CPlusPlus11.html#CPlusPlus11_move_only">Movable and move-only types</a> section should be read regarding C++11 move semantics and return by value.
</p>
<p>
If <tt>Vector</tt> is defined as a class in the interface, but it does not
support a default constructor, SWIG changes the wrapper code by encapsulating
support a default constructor and an assignment operator, SWIG changes the wrapper code by encapsulating
the arguments inside a special C++ template wrapper class, through a process
called the "Fulton Transform". This produces a wrapper that looks like this:
</p>
@ -1390,7 +1545,7 @@ Vector cross_product(Vector *a, Vector *b) {
<p>
This transformation is a little sneaky, but it provides support for
pass-by-value even when a class does not provide a default constructor
pass-by-value even when a class is not default constructible nor assignable
and it makes it possible to properly support a number of SWIG's
customization options. The definition of <tt>SwigValueWrapper</tt>
can be found by reading the SWIG wrapper code. This class is really nothing more than a thin
@ -1808,6 +1963,11 @@ See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a
use the <tt>compactdefaultargs</tt> feature flag as mentioned below.
</p>
<p>
For C# please see the <a href="CSharp.html#CSharp_named_arguments">C# named and optional arguments</a> section for information on special
handling of default arguments available specifically for C#.
</p>
<p>
<b>Compatibility note:</b> Versions of SWIG prior to SWIG-1.3.23 wrapped default arguments slightly differently.
Instead a single wrapper method was generated and the default values were copied into the C++ wrappers
@ -1834,6 +1994,7 @@ such as C# and Java,
which don't have optional arguments in the language,
Another restriction of this feature is that it cannot handle default arguments that are not public.
The following example illustrates this:
</p>
<div class="code">
@ -2147,7 +2308,7 @@ This error means that the target language module supports overloading,
but for some reason there is no type-checking rule that can be used to
generate a working dispatch function. The resulting behavior is then
undefined. You should report this as a bug to the
<a href="http://www.swig.org/bugs.html">SWIG bug tracking database</a>
<a href="https://www.swig.org/bugs.html">SWIG bug tracking database</a>
if this is due to one of the typemaps supplied with SWIG.
</p>
@ -2324,7 +2485,7 @@ members (of all classes):
Note: the <tt>*::</tt> syntax is non-standard C++, but the '*' is meant to be a
wildcard that matches any class name (we couldn't think of a better
alternative so if you have a better idea, send email to
the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a>.
the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a>.
</p>
<p>
@ -2992,13 +3153,6 @@ as its use with C structures. Please refer to the <a href="SWIG.html#SWIG_adding
section for further details.
</p>
<p>
<b>Compatibility note:</b> The <tt>%extend</tt> directive is a new
name for the <tt>%addmethods</tt> directive in SWIG1.1. Since <tt>%addmethods</tt> could
be used to extend a structure with more than just methods, a more suitable
directive name has been chosen.
</p>
<H3><a name="SWIGPlus_replacing_methods">6.17.1 Replacing class methods</a></H3>
@ -3261,10 +3415,28 @@ void foo(List&lt;Integer&gt; *x);
In this case, <tt>List&lt;Integer&gt;</tt> is exactly the same type as
<tt>List&lt;int&gt;</tt>. Any use of <tt>List&lt;Integer&gt;</tt> is mapped back to the
instantiation of <tt>List&lt;int&gt;</tt> created earlier. Therefore, it is
not necessary to instantiate a new class for the type <tt>Integer</tt> (doing so is
redundant and will simply result in code bloat).
not correct to instantiate a new class for the type <tt>Integer</tt>.
An attempt to do so such as:
</p>
<div class="code">
<pre>
%template(intList) List&lt;int&gt;;
%template(IntegerList) List&lt;Integer&gt;; // Ignored
</pre>
</div>
<p>
will result in the duplicate instantiation being ignored with a warning:
</p>
<div class="shell">
<pre>
example.i:48: Warning 404: Duplicate template instantiation of 'List&lt; Integer &gt;' with name 'IntegerList' ignored,
example.i:47: Warning 404: previous instantiation of 'List&lt; int &gt;' with name 'intList'.
</pre>
</div>
<p>
The template provided to <tt>%template</tt> for instantiation must be the actual template and not a typedef to a template.
</p>
@ -3333,36 +3505,49 @@ original template definition. Template default arguments are supported. For ex
<div class="code">
<pre>
template vector&lt;typename T, int max=100&gt; class vector {
template &lt;typename T, int max=100&gt; class vector {
...
};
%template(intvec) vector&lt;int&gt;; // OK
%template(intvec) vector&lt;int&gt;; // OK
%template(vec1000) vector&lt;int, 1000&gt;; // OK
</pre>
</div>
<p>
The <tt>%template</tt> directive should not be used to wrap the same
template instantiation more than once in the same scope. This will
generate an error. For example:
template instantiation more than once. This also applies to default parameters
where a template parameter specified in the instantiation is the same as the default parameter.
For example:
</p>
<div class="code">
<pre>
%template(intList) List&lt;int&gt;;
%template(Listint) List&lt;int&gt;; // Error. Template already wrapped.
%template(vec) vector&lt;double&gt;; // OK
%template(vec100) vector&lt;double, 100&gt;; // Ignored
</pre>
</div>
<p>
This error is caused because the template expansion results in two
identical classes with the same name. This generates a symbol table
conflict. Besides, it probably more efficient to only wrap a specific
instantiation only once in order to reduce the potential for code
bloat.
will warn:
</p>
<div class="shell">
<pre>
example.i:59: Warning 404: Duplicate template instantiation of 'vector&lt; double,100 &gt;' with name 'vec100' ignored,
example.i:58: Warning 404: previous instantiation of 'vector&lt; double &gt;' with name 'vec'.
</pre>
</div>
<p>
If this was not ignored, the template expansion would result in two identical classes.
An identical instantiation is only wrapped once in order to reduce code bloat.
</p>
<p>
<b>Compatibility Note</b>: Versions prior to SWIG-4.2.0 would sometimes not detect and prevent duplicate
instantiations, such as when the wrapped name was different.
</p>
<H3><a name="SWIGPlus_template_class_inheritance">6.18.4 Template base classes</a></H3>
@ -3429,20 +3614,6 @@ code (and base classes need to be wrapped before derived classes).
Don't worry--if you get the order wrong, SWIG should generate a warning message.
</p>
<p>
Occasionally, you may need to tell SWIG about base classes that are defined by templates,
but which aren't supposed to be wrapped. Since SWIG is not able to automatically
instantiate templates for this purpose, you must do it manually. To do this, simply
use the empty template instantiation, that is, <tt>%template</tt> with no name. For example:
</p>
<div class="code">
<pre>
// Instantiate traits&lt;double, double&gt;, but don't wrap it.
%template() traits&lt;double, double&gt;;
</pre>
</div>
<p>
If you have to instantiate a lot of different classes for many different types,
you might consider writing a SWIG macro. For example:
@ -3468,7 +3639,66 @@ TEMPLATE_WRAP(PairStringInt, std::pair&lt;string, int&gt;)
Note the use of a vararg macro for the type T. If this wasn't used, the comma in the templated type in the last example would not be possible.
</p>
<H3><a name="SWIGPlus_template_specialization">6.18.5 Template specialization</a></H3>
<H3><a name="SWIGPlus_template_empty">6.18.5 Empty template instantiation</a></H3>
<p>
Occasionally, you may need to tell SWIG about classes that are defined by templates,
but which aren't supposed to be wrapped. Since SWIG is not able to automatically
instantiate templates for this purpose, you must do it manually. To do this, simply
use <tt>%template()</tt>, that is the empty template instantiation that omits providing a name. For example:
</p>
<div class="code">
<pre>
template&lt;typename T&gt; struct Traits {
typedef T type;
};
%}
%template() Traits&lt;int&gt;; // instantiate Traits&lt;int&gt;, but don't wrap it
void traitor(Traits&lt;int&gt;::type val);
</pre>
</div>
<p>
Without a template instantiation, SWIG does not know that the first parameter to the <tt>traitor</tt>
function is type int and passing an integer to this function from any target language won't work.
The empty template instantiation adds the appropriate type information into SWIG's type system, without
forcing one to wrap the <tt>Traits</tt> class.
</p>
<p>
Duplicate template instantiation are not allowed, as described in the
<a href="#SWIGPlus_template_classes">Default template arguments</a> section above.
There is one exception where a named template instantiation can be followed by an empty template instantiation.
Duplicate empty template instantiations are silently ignored, unlike duplicate named template instantiations.
</p>
<p>
Unlike template class instantiations, template function instantiations must have a name.
Consider the following:
</p>
<div class="code">
<pre>
template&lt;class T&gt; T tfunc(T x) { };
%template() tfunc&lt;double&gt;;
</pre>
</div>
<p>
The empty template instantiation will be ignored with:
</p>
<div class="shell">
<pre>
example.i:9: Warning 519: %template() contains no name. Template method ignored: tfunc&lt; double &gt;(double)
</pre>
</div>
<H3><a name="SWIGPlus_template_specialization">6.18.6 Template specialization</a></H3>
<p>
@ -3558,7 +3788,7 @@ SWIG implements template argument deduction so that the following partial specia
</pre>
</div>
<H3><a name="SWIGPlus_template_member">6.18.6 Member templates</a></H3>
<H3><a name="SWIGPlus_template_member">6.18.7 Member templates</a></H3>
<p>
@ -3770,7 +4000,7 @@ constructor, that will dispatch the proper call depending on the argument
type.
</p>
<H3><a name="SWIGPlus_template_scoping">6.18.7 Scoping and templates</a></H3>
<H3><a name="SWIGPlus_template_scoping">6.18.8 Scoping and templates</a></H3>
<p>
@ -3871,7 +4101,7 @@ template class C&lt;int&gt;;
</p>
<H3><a name="SWIGPlus_template_more">6.18.8 More on templates</a></H3>
<H3><a name="SWIGPlus_template_more">6.18.9 More on templates</a></H3>
<p>
@ -4273,8 +4503,8 @@ When this conflict occurs, you will get an error message that resembles this:
<div class="shell">
<pre>
example.i:26. Error. 'foo' is multiply defined in the generated target language module.
example.i:23. Previous declaration of 'foo'
example.i:26: Error: 'foo' is multiply defined in the generated target language module.
example.i:23: Error: Previous declaration of 'foo'
</pre>
</div>
@ -5283,6 +5513,11 @@ you wrap this code in Python, the module works just like you would expect:
</pre>
</div>
<p>
The C++11 standard supports using declarations for inheriting constructors and this is covered in
<a href="CPlusPlus11_object_construction_improvement">Object construction improvement</a>.
</p>
<p>
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:

30
Doc/Manual/Scilab.html
View File

@ -71,6 +71,7 @@
<ul>
<li><a href="#Scilab_generated_scripts_builder_script">Builder script</a>
<li><a href="#Scilab_generated_scripts_loader_script">Loader script</a>
<li><a href="#Scilab_generated_scripts_gateway">Gateway XML files</a>
</ul>
<li><a href="#Scilab_other_resources">Other resources</a>
</ul>
@ -80,7 +81,7 @@
<p>
Scilab is a scientific software package for numerical computations providing a powerful open computing environment for engineering and scientific applications that is mostly compatible with MATLAB. More information can be found at <a href="http://www.scilab.org">www.scilab.org</a>.
Scilab is a scientific software package for numerical computations providing a powerful open computing environment for engineering and scientific applications that is mostly compatible with MATLAB. More information can be found at <a href="https://www.scilab.org">www.scilab.org</a>.
</p>
<p>
@ -96,8 +97,7 @@ SWIG for Scilab supports Linux. Other operating systems haven't been tested.
</p>
<p>
Scilab is supported from version 5.3.3 onwards.
The forthcoming version 6, as of January 2015, is also supported.
Scilab is supported from version 5.3.3 onwards, the SWIG generated code is supported on both Scilab 5, Scilab 6 and more recent versions.
</p>
<p>
@ -304,6 +304,11 @@ 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>
</tr>
<tr>
<td><tt>-gatewayxml6</tt></td>
<td>Generate a gateway XML file compatible with Scilab 6</td>
</tr>
</table>
<p>
@ -2135,6 +2140,21 @@ clear get_file_path;
<li><tt><b>fcts</b></tt>: vector of character strings. The name of new Scilab function.</li>
</ul>
<H3><a name="Scilab_generated_scripts_gateway">36.7.3 Gateway XML files</a></H3>
<p>If you need to post-process the entry points, Scilab gateway files are XML files that can be used to retrieve all SWIG-generated entry points. With these XML files you can write your own <tt>builder_swig.sce</tt> file to add custom Scilab for building or linking the generated code. Documentation stubs can also be generated thanks to these function listings.</p>
<p>As an example, for a SWIG <a href="Modules.html">module</a> named <tt>fmuswig</tt> the Scilab code below can be used to store all SWIG-generated functions in a variable named <tt>funs</tt>.</p>
<div class="code"><pre>
// src_swig_path is a path to the directory containing the fmuswig.i file
doc = xmlRead(src_swig_path + "/fmuswig_gateway.xml");
names = xmlAsText(xmlXPath(doc, "//gateway/@name"));
funs = xmlAsText(xmlXPath(doc, "//gateway/@function"));
xmlDelete(doc);
</pre></div>
<H2><a name="Scilab_other_resources">36.8 Other resources</a></H2>
@ -2142,7 +2162,7 @@ clear get_file_path;
<ul>
<li>Example use cases can be found in the <tt>Examples/scilab</tt> directory.</li>
<li>The test suite in the <tt>Examples/test-suite/scilab</tt> can be another source of useful use cases.</li>
<li>The <a href="http://help.scilab.org/docs/5.5.0/en_US/api_scilab.html">Scilab API</a> is used in the generated code and is a useful reference when examining the output.</li>
<li>This <a href="http://wiki.scilab.org/howto/Create%20a%20toolbox">guide</a> describes the Scilab external modules structure and files, in particular the files that are generated by SWIG for Scilab.</li>
<li>The <a href="https://help.scilab.org/api_scilab.html">Scilab API</a> is used in the generated code and is a useful reference when examining the output.</li>
<li>This <a href="https://wiki.scilab.org/howto/Create%20a%20toolbox">guide</a> describes the Scilab external modules structure and files, in particular the files that are generated by SWIG for Scilab.</li>
</ul>

6
Doc/Manual/Sections.html
View File

@ -1,14 +1,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG-4.0 Documentation</title>
<title>SWIG-4.3 Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Sections">SWIG-4.0 Documentation</a></H1>
<H1><a name="Sections">SWIG-4.3 Documentation</a></H1>
<p>
Last update : SWIG-4.1.0 (in progress)
Last update : SWIG-4.3.0 (in progress)
</p>
<H2><a name="Sections_Sections">Sections</a></H2>

38
Doc/Manual/Tcl.html
View File

@ -81,7 +81,7 @@
<p>
This chapter discusses SWIG's support of Tcl. Since SWIG 4.1.0, Tcl 8.4 or a
later release is required. Prior to that earlier Tcl 8.x releases were also
supported.
supported. Tcl 9.0 is supported since SWIG 4.2.1.
</p>
<H2><a name="Tcl_nn2">37.1 Preliminaries</a></H2>
@ -826,7 +826,7 @@ are not wrapped as constants. For further discussion about this, see the <a hr
<p>
Constants are not guaranteed to remain constant in Tcl---the value
of the constant could be accidentally reassigned.You will just have to be careful.
of the constant could be accidentally reassigned. You will just have to be careful.
</p>
<p>
@ -843,38 +843,6 @@ proc blah {} {
</pre>
</div>
<p>
If a program relies on a lot of constants, this can be extremely annoying. To fix the problem, consider using the
following typemap rule:
</p>
<div class="code">
<pre>
%apply int CONSTANT { int x };
#define FOO 42
...
void bar(int x);
</pre>
</div>
<p>
When applied to an input argument, the <tt>CONSTANT</tt> rule allows a constant to be passed to a function using
its actual value or a symbolic identifier name. For example:
</p>
<div class="code">
<pre>
proc blah {} {
bar FOO
}
</pre>
</div>
<p>
When an identifier name is given, it is used to perform an implicit hash-table lookup of the value during argument
conversion. This allows the <tt>global</tt> statement to be omitted.
</p>
<H3><a name="Tcl_nn19">37.3.5 Pointers</a></H3>
@ -2812,7 +2780,7 @@ used as a <tt>char **</tt> object.
}
$1 = (char **) malloc((nitems+1)*sizeof(char *));
for (i = 0; i &lt; nitems; i++) {
$1[i] = Tcl_GetStringFromObj(listobjv[i], 0);
$1[i] = Tcl_GetString(listobjv[i]);
}
$1[i] = 0;
}

5
Doc/Manual/Typemaps.html
View File

@ -2626,11 +2626,6 @@ Usually <tt>numinputs</tt> is not specified, whereupon the default value is 1, t
<a href="#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a> provide a similar concept where the number of arguments mapped from the target language to C/C++ can be changed for multiple adjacent C/C++ arguments.
</p>
<p>
<b>Compatibility note: </b> Specifying <tt>numinputs=0</tt>
is the same as the old "ignore" typemap.
</p>
<H3><a name="Typemaps_nn27">14.5.2 "typecheck" typemap</a></H3>

2
Doc/Manual/Varargs.html
View File

@ -613,7 +613,7 @@ you need to bring out some bigger guns.
<p>
One way to do this is to use a special purpose library such as libffi
(<a
href="http://www.sourceware.org/libffi/">http://www.sourceware.org/libffi/</a>).
href="https://www.sourceware.org/libffi/">https://www.sourceware.org/libffi/</a>).
libffi is a library that allows you to dynamically construct
call-stacks and invoke procedures in a relatively platform independent
manner. Details about the library can be found in the libffi

55
Doc/Manual/Warnings.html
View File

@ -164,6 +164,15 @@ to provide additional diagnostics. These warnings can be turned on using the
</pre>
</div>
<p>
Preprocessor warning 202 ("Could not evaluate expression <em>expr</em>.") was
formally off by default and enabled by <tt>-Wextra</tt>, but since SWIG 4.1.0
this warning is on by default because suppressing it tends to hide genuine
problems. If you really don't want to see it, you can suppress it with
<tt>-w202</tt> or using <tt>%warnfilter</tt> as described below. Both will work
with older versions of SWIG too.
</p>
<p>
To selectively turn on extra warning messages, you can use the directives and options in the
previous section--simply add a "+" to all warning numbers. For example:
@ -211,7 +220,7 @@ You can of course also enable all warnings and suppress a select few, for exampl
</div>
<p>
The warnings on the right take precedence over the warnings on the left, so in the above example <tt>-Wextra</tt> adds numerous warnings including 452, but then <tt>-w309,452</tt> overrides this and so 452 is suppressesed.
The warnings on the right take precedence over the warnings on the left, so in the above example <tt>-Wextra</tt> adds numerous warnings including 452, but then <tt>-w309,452</tt> overrides this and so 452 is suppressed.
</p>
<p>
@ -363,27 +372,6 @@ example.i(4) : Syntax error in input(1).
<ul>
<li>101. Deprecated <tt>%extern</tt> directive.
<li>102. Deprecated <tt>%val</tt> directive.
<li>103. Deprecated <tt>%out</tt> directive.
<li>104. Deprecated <tt>%disabledoc</tt> directive.
<li>105. Deprecated <tt>%enabledoc</tt> directive.
<li>106. Deprecated <tt>%doconly</tt> directive.
<li>107. Deprecated <tt>%style</tt> directive.
<li>108. Deprecated <tt>%localstyle</tt> directive.
<li>109. Deprecated <tt>%title</tt> directive.
<li>110. Deprecated <tt>%section</tt> directive.
<li>111. Deprecated <tt>%subsection</tt> directive.
<li>112. Deprecated <tt>%subsubsection</tt> directive.
<li>113. Deprecated <tt>%addmethods</tt> directive.
<li>114. Deprecated <tt>%readonly</tt> directive.
<li>115. Deprecated <tt>%readwrite</tt> directive.
<li>116. Deprecated <tt>%except</tt> directive.
<li>117. Deprecated <tt>%new</tt> directive.
<li>118. Deprecated <tt>%typemap(except)</tt>.
<li>119. Deprecated <tt>%typemap(ignore)</tt>.
<li>120. Deprecated command line option (-runtime, -noruntime).
<li>121. Deprecated <tt>%name</tt> directive.
<li>126. The 'nestedworkaround' feature is deprecated.
</ul>
@ -404,31 +392,33 @@ example.i(4) : Syntax error in input(1).
<ul>
<li>301. <tt>class</tt> keyword used, but not in C++ mode.
<li>302. Identifier '<em>name</em>' redefined (ignored).
<li>302. Redefinition of identifier '<em>name</em>' as <em>decl</em> ignored.
<li>303. <tt>%extend</tt> defined for an undeclared class '<em>name</em>'.
<li>304. Unsupported constant value (ignored).
<li>305. Bad constant value (ignored).
<li>306. '<em>identifier</em>' is private in this context.
<li>307. Can't set default argument value (ignored)
<li>308. Namespace alias '<em>name</em>' not allowed here. Assuming '<em>name</em>'
<li>309. [private | protected] inheritance ignored.
<li>310. Template '<em>name</em>' was already wrapped as '<em>name</em>' (ignored)
<li>312. Unnamed nested class not currently supported (ignored).
<li>313. Unrecognized extern type "<em>name</em>" (ignored).
<li>314. '<em>identifier</em>' is a <em>lang</em> keyword.
<li>315. Nothing known about '<em>identifier</em>'.
<li>316. Repeated %module directive.
<li>317. Specialization of non-template '<em>name</em>'.
<li>318. Instantiation of template '<em>name</em>' is ambiguous, instantiation <em>templ</em> used, instantiation <em>templ</em> ignored.
<li>319. No access specifier given for base class <em>name</em> (ignored).
<li>320. Explicit template instantiation ignored.
<li>321. <em>identifier</em> conflicts with a built-in name.
<li>322. Redundant redeclaration of '<em>name</em>'.
<li>322. Redundant redeclaration of identifier '<em>name</em>' as <em>decl</em> ignored.
<li>323. Recursive scope inheritance of '<em>name</em>'.
<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>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>328. Value assigned to <em>name</em> not used due to limited parsing implementation.
<li>329. Using declaration '<em>name</em>' for inheriting constructors uses base '<em>name</em>' which is not an immediate base of '<em>name</em>'.
<li>340. Lambda expressions and closures are not fully supported yet.
<li>344. Unable to deduce decltype for '<em>expr</em>'.
<li>345. Unable to deduce auto return type for '<em>name</em>' (ignored).
<li>346. Unable to deduce auto type for variable '<em>name</em>' (ignored).
<li>350. operator new ignored.
<li>351. operator delete ignored.
<li>352. operator+ ignored.
@ -475,6 +465,8 @@ example.i(4) : Syntax error in input(1).
<li>393. operator&amp; ignored (unary).
<li>394. operator new[] ignored.
<li>395. operator delete[] ignored.
<li>396. operator*() ignored.
<li>397. operator&lt;=&gt; delete[] ignored.
</ul>
<H3><a name="Warnings_nn13">19.9.4 Types and typemaps (400-499) </a></H3>
@ -484,10 +476,14 @@ example.i(4) : Syntax error in input(1).
<li>401. Nothing known about class 'name'. Ignored.
<li>402. Base class 'name' is incomplete.
<li>403. Class 'name' might be abstract.
<li>404. Duplicate template instantiation of '<em>type</em>' with name '<em>name</em>' ignored, previous instantiation of '<em>type</em>' with name '<em>name</em>'.
<li>405. Method with rvalue ref-qualifier <em>name</em> ignored.
<li>450. Reserved
<li>451. Setting const char * variable may leak memory.
<li>452. Reserved
<li>453. Can't apply (pattern). No typemaps are defined.
<li>454. Setting a pointer/reference variable may leak memory
<li>455. Setting a const wchar_t * variable may leak memory.
<li>460. Unable to use type <em>type</em> as a function argument.
<li>461. Unable to use return type <em>type</em> in function <em>name</em>.
<li>462. Unable to set variable of type <em>type</em>.
@ -500,10 +496,13 @@ example.i(4) : Syntax error in input(1).
<li>469. No or improper directorin typemap defined for <em>type</em>
<li>470. Thread/reentrant unsafe wrapping, consider returning by value instead.
<li>471. Unable to use return type <em>type</em> in director method
<li>472. Overloaded method <em>method</em> with no explicit typecheck typemap for arg <em>number</em> of type '<em>type</em>'
<li>473. Returning a reference, pointer or pointer wrapper in a director method is not recommended.
<li>474. Method <em>method</em> usage of the optimal attribute ignored in the out typemap as the following cannot be used to generate optimal code: <em>code</em>
<li>475. Multiple calls to <em>method</em> might be generated due to optimal attribute usage in the out typemap.
<li>476. Initialization using std::initializer_list.
<li>477. No directorthrows typemap defined for <em>type</em>
<li>490. Fragment '<em>name</em>' not found.
</ul>

73
Doc/Manual/Windows.html
View File

@ -60,7 +60,7 @@ Usage within the Unix like environments MinGW and Cygwin is also detailed.
SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:
</p>
<ul>
<li>Download the swigwin zip package from the <a href="http://www.swig.org">SWIG website</a> and unzip into a directory. This is all that needs downloading for the Windows platform.
<li>Download the swigwin zip package from the <a href="https://www.swig.org">SWIG website</a> and unzip into a directory. This is all that needs downloading for the Windows platform.
<li>Set environment variables as described in the <a href="#Windows_examples">SWIG Windows Examples</a> section in order to run examples using Visual C++.
</ul>
@ -220,7 +220,7 @@ Normally this is not needed, so most people will want to ignore this section.
<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.
SWIG can also be compiled and run using <a href="https://www.msys2.org/">MSYS2</a>, <a href="https://www.cygwin.com">Cygwin</a> or <a href="https://osdn.net/projects/mingw/">MinGW</a>, all of which provide a Unix like front end to Windows and comes free with the gcc C/C++ compiler.
</p>
@ -230,7 +230,7 @@ SWIG can also be compiled and run using <a href="https://www.msys2.org/">MSYS2</
<p>
SWIG can be built using <a href="https://cmake.org/">CMake</a> and Visual Studio rather than autotools. As with the other approaches to
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.
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>.
For fully working build steps always check the Continuous Integration (CI) setups currently detailed in the <a href="https://github.com/swig/swig/tree/master/.github/workflows/nuget.yml">GitHub Actions YAML file</a>.
</p>
<ol>
@ -240,6 +240,7 @@ For fully working build steps always check the Continuous Integration (CI) setup
</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>
Using PowerShell the equivalent syntax is: <pre>&amp; "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>
@ -248,44 +249,48 @@ For fully working build steps always check the Continuous Integration (CI) setup
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.
Install the <a href="https://www.nuget.org/packages/pcre2/">PCRE2 Nuget package</a> using the following command: <pre>C:\Tools\nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2</pre>
Note this is a x64 build, if this is not suitable PCRE2 can be built from source using <a href="https://github.com/PhilipHazel/pcre2/">https://github.com/PhilipHazel/pcre2/</a>.
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>
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
Now we have all the required dependencies we can build SWIG using PowerShell and 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>
<div class="shell"><pre>
cd C:\swig
$env:PATH="C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;" + $env:PATH
$PCRE_ROOT="C:\Tools\pcre2\PCRE2.10.39.0"
$PCRE_PLATFORM="x64"
cmake -G "Visual Studio 16 2019" -A "x64" `
-DCMAKE_INSTALL_PREFIX="C:/swig/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
cmake --install build --config Release
# to test the exe built correctly
cd install2/bin
./swig.exe -version
./swig.exe -help
</pre></div>
<p>
In addition to Release builds you can create a Debug build using:
</p>
@ -354,18 +359,21 @@ make install
<H3><a name="Windows_mingw_msys">3.3.3 Building swig.exe using MinGW and MSYS</a></H3>
<p>Warning: These instructions were added in 2006 and have barely changed since
so are unlikely to work exactly as written.</p>
<p>
The short abbreviated instructions follow...
</p>
<ul>
<li>Install MinGW and MSYS from the <a href="http://www.mingw.org">MinGW</a> site. This provides a Unix environment on Windows.
<li>Install MinGW and MSYS from the <a href="https://osdn.net/projects/mingw/">MinGW</a> site. This provides a Unix environment on Windows.
<li>Follow the usual Unix instructions in the README file in the SWIG root directory to build swig.exe from the MinGW command prompt.
</ul>
<p>
The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from Github follow...
Note that the instructions for obtaining SWIG from Github are also online at <a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>.
Note that the instructions for obtaining SWIG from Github are also online at <a href="https://www.swig.org/svn.html">SWIG Bleeding Edge</a>.
</p>
<p>
@ -375,8 +383,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
<ol>
<li>
Download the following packages from the <a href="http://www.mingw.org/download.shtml">MinGW download page</a>
or <a href="https://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>.
Download the following packages from the <a href="https://osdn.net/projects/mingw/releases/">MinGW download page</a>.
Note that at the time of writing, the majority of these are in the Current
release list and some are in the Snapshot or Previous release list.
<ul>
@ -448,7 +455,7 @@ the autotools will fail miserably on those.
<li>
The PCRE2 third party library needs to be built next.
Download the latest PCRE2 source tarball, such as <tt>pcre2-10.39.tar.bz2</tt>, from
<a href=http://www.pcre.org>www.pcre.org</a> and place in the <tt>/usr/src/swig</tt> directory.
<a href=https://www.pcre.org>www.pcre.org</a> and place in the <tt>/usr/src/swig</tt> directory.
Build PCRE2 as a static library using the Tools/pcre-build.sh script as follows:
<div class="shell"><pre>

4
Doc/Manual/index.html
View File

@ -1,11 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG-4.0 Documentation</title>
<title>SWIG Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="index">SWIG-4.0 Documentation</a></H1>
<H1><a name="index">SWIG Documentation</a></H1>
The SWIG documentation is available in one of the following formats.
<ul>

2353
Examples/Makefile.in
View File

File diff suppressed because it is too large Load Diff

2
Examples/d/callback/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

36
Examples/d/callback/d1/runme.d
View File

@ -1,36 +0,0 @@
module runme;
import tango.io.Stdout;
import example;
public class DCallback : Callback {
public override void run() {
Stdout( "DCallback.run()" ).newline;
}
}
void main() {
auto caller = new Caller();
Stdout( "Adding and calling a normal C++ callback" ).newline;
Stdout( "----------------------------------------" ).newline;
{
scope auto callback = new Callback();
caller.setCallback(callback);
caller.call();
caller.resetCallback();
}
Stdout.newline;
Stdout( "Adding and calling a D callback" ).newline;
Stdout( "-------------------------------" ).newline;
{
scope auto callback = new DCallback();
caller.setCallback(callback);
caller.call();
caller.resetCallback();
}
Stdout.newline;
Stdout( "D exit" ).newline;
}

2
Examples/d/class/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

58
Examples/d/class/d1/runme.d
View File

@ -1,58 +0,0 @@
// This example illustrates how C++ classes can be used from D using SWIG.
// The D class gets mapped onto the C++ class and behaves as if it is a D class.
module runme;
import tango.io.Stdout;
import example;
void main() {
// ----- Object creation -----
Stdout( "Creating some objects:" ).newline;
{
scope Square s = new Square(10);
scope Circle c = new Circle(10);
// ----- Access a static member -----
Stdout.format( "{} shapes were created.", Shape.nshapes ).newline;
// ----- Member data access -----
// Notice how we can do this using functions specific to
// the 'Circle' class.
c.x = 20;
c.y = 30;
// Now use the same functions in the base class
Shape shape = s;
shape.x = -10;
shape.y = 5;
Stdout( "\nHere is their current position:" ).newline;
Stdout.format( " Circle = ( {}, {} )", c.x, c.y ).newline;
Stdout.format( " Square = ( {}, {} )", s.x, s.y ).newline;
// ----- Call some methods -----
Stdout( "\nHere are some properties of the shapes:" ).newline;
Shape[] shapes = [ cast(Shape) c, cast(Shape) s ];
foreach ( currentShape; shapes )
{
Stdout.format( " {}", currentShape.classinfo.name ).newline;
Stdout.format( " area = {}", currentShape.area() ).newline;
Stdout.format( " perimeter = {}", currentShape.perimeter() ).newline;
}
// Notice how the area() and perimeter() functions really
// invoke the appropriate virtual method on each object.
// ----- Delete everything -----
Stdout( "\nGuess I'll clean up now:" ).newline;
// Note: when this using scope is exited the D destructors are called which
// in turn call the C++ destructors.
}
Stdout.format( "{} shapes remain", Shape.nshapes ).newline;
Stdout( "\nGoodbye!" ).newline;
}

2
Examples/d/constants/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

28
Examples/d/constants/d1/runme.d
View File

@ -1,28 +0,0 @@
module runme;
import tango.io.Stdout;
static import example;
void main() {
Stdout.formatln("ICONST = {} (should be 42)", example.ICONST);
Stdout.formatln("FCONST = {} (should be 2.18)", example.FCONST);
Stdout.formatln("CCONST = {} (should be 'x')", example.CCONST);
Stdout.formatln("CCONST2 = {} (this should be on a new line)", example.CCONST2);
Stdout.formatln("SCONST = {} (should be 'Hello World')", example.SCONST);
Stdout.formatln("SCONST2 = {} (should be '\"Hello World\"')", example.SCONST2);
Stdout.formatln("EXPR = {} (should be 48.55)", example.EXPR);
Stdout.formatln("iconst = {} (should be 37)", example.iconst);
Stdout.formatln("fconst = {} (should be 3.14)", example.fconst);
static if (is(typeof(example.EXTERN))) {
Stdout.formatln("EXTERN should not be defined, but is: {}.", example.EXTERN );
} else {
Stdout.formatln("EXTERN isn't defined (good)");
}
static if (is(typeof(example.FOO))) {
Stdout.formatln("FOO should not be defined, but is: {}.", example.FOO);
} else {
Stdout.formatln("FOO isn't defined (good)");
}
}

2
Examples/d/enum/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

28
Examples/d/enum/d1/runme.d
View File

@ -1,28 +0,0 @@
module runme;
import tango.io.Stdout;
import example;
void main() {
Stdout( "Printing out some enum values:" ).newline;
Stdout(" color:").newline;
Stdout.formatln(" {} = {}", color.RED, cast(int)color.RED);
Stdout.formatln(" {} = {}", color.BLUE, cast(int)color.BLUE);
Stdout.formatln(" {} = {}", color.GREEN, cast(int)color.GREEN);
Stdout("\n Foo.speed:").newline;
Stdout.formatln(" Foo.{} = {}", Foo.speed.IMPULSE, cast(int)Foo.speed.IMPULSE);
Stdout.formatln(" Foo.{} = {}", Foo.speed.WARP, cast(int)Foo.speed.WARP);
Stdout.formatln(" Foo.{} = {}", Foo.speed.LUDICROUS , cast(int)Foo.speed.LUDICROUS);
Stdout("\nTesting use of enums with functions:").newline;
example.enum_test(color.RED, Foo.speed.IMPULSE);
example.enum_test(color.BLUE, Foo.speed.WARP);
example.enum_test(color.GREEN, Foo.speed.LUDICROUS);
Stdout( "\nTesting use of enum with class method:" ).newline;
scope f = new Foo();
f.enum_test(Foo.speed.IMPULSE);
f.enum_test(Foo.speed.WARP);
f.enum_test(Foo.speed.LUDICROUS);
}

50
Examples/d/example.mk Normal file
View File

@ -0,0 +1,50 @@
#
# Common Makefile code for building D examples.
#
# This file is supposed to be included from a Makefile in the subdirectory
# corresponding to a specific example.
#
EXAMPLES_TOP = ../../..
SWIG_TOP = ../../../..
SWIGEXE = $(SWIG_TOP)/swig
SWIG_LIB_DIR = $(SWIG_TOP)/$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
EXTRA_CFLAGS =
EXTRA_CXXFLAGS =
EXTRA_LDFLAGS =
TARGET = example_wrap
SWIGOPT = -outcurrentdir
DFLAGS = -ofrunme
ifeq (,$(SRCDIR))
DSRCS = *.d
else
DSRCS = *.d $(addprefix ../$(SRCDIR)d2/,runme.d)
endif
check: build
$(MAKE) -C d2/ -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' d_run
build:
mkdir -p d2/
if [ -f $(SRCDIR)example.cxx ]; then \
$(MAKE) -C d2/ -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' EXTRA_CXXFLAGS='$(EXTRA_CXXFLAGS)' EXTRA_LDFLAGS='$(EXTRA_LDFLAGS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='example.i' CXXSRCS='example.cxx' d_cpp; \
elif [ -f $(SRCDIR)example.c ]; then \
$(MAKE) -C d2/ -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' EXTRA_CFLAGS='$(EXTRA_CFLAGS)' EXTRA_LDFLAGS='$(EXTRA_LDFLAGS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='example.i' SRCS='example.c' d; \
else \
$(MAKE) -C d2/ -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' EXTRA_CFLAGS='$(EXTRA_CFLAGS)' EXTRA_LDFLAGS='$(EXTRA_LDFLAGS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='example.i' SRCS='' d; \
fi
$(MAKE) -C d2/ -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' DSRCS='$(DSRCS)' DFLAGS='$(DFLAGS)' d_compile
clean:
if [ -d d2/ ]; then \
$(MAKE) -C d2/ -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' d_clean; \
fi
test -f d2/runme.d || rm -rf d2/ # Only delete dir if out of source

66
Examples/d/example.mk.in
View File

@ -1,66 +0,0 @@
#
# Common Makefile code for building D examples.
#
# We actually need to configure this to gain access to the default D version to
# use when D_VERSION is not set. Using Examples/Makefile.in is not enough, as
# the location of the source files (d1/ or d2/) depends on it. The alternative
# would be to add the functionality specific to Examples/d (as opposed to the
# test suite) directly to Examples/Makefile.in.
#
# This file is supposed to be included from a Makefile in the subdirectory
# corresponding to a specific example.
#
ifeq (,$(D_VERSION))
D_VERSION = @DDEFAULTVERSION@
endif
ifeq (1,$(D_VERSION))
VERSION_DIR = d1/
else
VERSION_DIR = d2/
endif
EXAMPLES_TOP = ../../..
SWIG_TOP = ../../../..
SWIGEXE = $(SWIG_TOP)/swig
SWIG_LIB_DIR = $(SWIG_TOP)/$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
EXTRA_CFLAGS =
EXTRA_CXXFLAGS =
EXTRA_LDFLAGS =
TARGET = example_wrap
SWIGOPT = -outcurrentdir
DFLAGS = -ofrunme
ifeq (,$(SRCDIR))
DSRCS = *.d
else
DSRCS = *.d $(addprefix ../$(SRCDIR)$(VERSION_DIR),runme.d)
endif
check: build
$(MAKE) -C $(VERSION_DIR) -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' d_run
build:
mkdir -p $(VERSION_DIR)
if [ -f $(SRCDIR)example.cxx ]; then \
$(MAKE) -C $(VERSION_DIR) -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' EXTRA_CXXFLAGS='$(EXTRA_CXXFLAGS)' EXTRA_LDFLAGS='$(EXTRA_LDFLAGS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='example.i' CXXSRCS='example.cxx' d_cpp; \
elif [ -f $(SRCDIR)example.c ]; then \
$(MAKE) -C $(VERSION_DIR) -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' EXTRA_CFLAGS='$(EXTRA_CFLAGS)' EXTRA_LDFLAGS='$(EXTRA_LDFLAGS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='example.i' SRCS='example.c' d; \
else \
$(MAKE) -C $(VERSION_DIR) -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' EXTRA_CFLAGS='$(EXTRA_CFLAGS)' EXTRA_LDFLAGS='$(EXTRA_LDFLAGS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='example.i' SRCS='' d; \
fi
$(MAKE) -C $(VERSION_DIR) -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' DSRCS='$(DSRCS)' DFLAGS='$(DFLAGS)' d_compile
clean:
if [ -d $(VERSION_DIR) ]; then \
$(MAKE) -C $(VERSION_DIR) -f $(EXAMPLES_TOP)/Makefile SRCDIR='../$(SRCDIR)' d_clean; \
fi
test -f $(VERSION_DIR)runme.d || rm -rf $(VERSION_DIR) # Only delete dir if out of source

2
Examples/d/extend/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

75
Examples/d/extend/d1/runme.d
View File

@ -1,75 +0,0 @@
/// This file illustrates the cross language polymorphism using directors.
module runme;
import example;
import tango.io.Stdout;
// CEO class, which overrides Employee.getPosition().
class CEO : Manager {
public:
this( char[] name ) {
super( name );
}
override char[] getPosition() {
return "CEO";
}
// Public method to stop the SWIG proxy base class from thinking it owns the underlying C++ memory.
void disownMemory() {
swigCMemOwn = false;
}
}
void main() {
// Create an instance of CEO, a class derived from the D proxy of the
// underlying C++ class. The calls to getName() and getPosition() are standard,
// the call to getTitle() uses the director wrappers to call CEO.getPosition().
auto e = new CEO( "Alice" );
Stdout.formatln( "{} is a {}.", e.getName(), e.getPosition() );
Stdout.formatln( "Just call her '{}'.", e.getTitle() );
Stdout( "----------------------" ).newline;
{
// Create a new EmployeeList instance. This class does not have a C++
// director wrapper, but can be used freely with other classes that do.
scope auto list = new EmployeeList();
// EmployeeList owns its items, so we must surrender ownership of objects we add.
e.disownMemory();
list.addEmployee(e);
Stdout( "----------------------" ).newline;
// Now we access the first four items in list (three are C++ objects that
// EmployeeList's constructor adds, the last is our CEO). The virtual
// methods of all these instances are treated the same. For items 0, 1, and
// 2, all methods resolve in C++. For item 3, our CEO, getTitle calls
// getPosition which resolves in D. The call to getPosition is
// slightly different, however, because of the overridden getPosition() call, since
// now the object reference has been "laundered" by passing through
// EmployeeList as an Employee*. Previously, D resolved the call
// immediately in CEO, but now D thinks the object is an instance of
// class Employee. So the call passes through the
// Employee proxy class and on to the C wrappers and C++ director,
// eventually ending up back at the D CEO implementation of getPosition().
// The call to getTitle() for item 3 runs the C++ Employee::getTitle()
// method, which in turn calls getPosition(). This virtual method call
// passes down through the C++ director class to the D implementation
// in CEO. All this routing takes place transparently.
Stdout( "(position, title) for items 0-3:" ).newline;
Stdout.formatln( " {}, '{}'", list.getItem(0).getPosition(), list.getItem(0).getTitle() );
Stdout.formatln( " {}, '{}'", list.getItem(1).getPosition(), list.getItem(1).getTitle() );
Stdout.formatln( " {}, '{}'", list.getItem(2).getPosition(), list.getItem(2).getTitle() );
Stdout.formatln( " {}, '{}'", list.getItem(3).getPosition(), list.getItem(3).getTitle() );
Stdout( "----------------------" ).newline;
// All Employees will be destroyed when the EmployeeList goes out of scope,
// including the CEO instance.
}
Stdout( "----------------------" ).newline;
// All done.
Stdout( "Exiting cleanly from D code." ).newline;
}

2
Examples/d/funcptr/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

42
Examples/d/funcptr/d1/runme.d
View File

@ -1,42 +0,0 @@
module runme;
import tango.io.Stdout;
static import example;
extern(C) int add(int a, int b) {
return a + b;
}
extern(C) int sub(int a, int b) {
return a - b;
}
extern(C) int mul(int a, int b) {
return a * b;
}
void main() {
int a = 37;
int b = 42;
Stdout( "a = " )( a ).newline;
Stdout( "b = " )( b ).newline;
Stdout( "Trying some C callback functions:" ).newline;
Stdout( " ADD(a,b) = " )( example.do_op( a, b, example.ADD ) ).newline;
Stdout( " SUB(a,b) = " )( example.do_op( a, b, example.SUB ) ).newline;
Stdout( " MUL(a,b) = " )( example.do_op( a, b, example.MUL ) ).newline;
version (LDC) {
// Currently, there is no way to specify the calling convention for
// function pointer parameters in D, but LDC does strict typechecking for
// them (which is reasonable, but not covered by the language spec yet).
// As a result, there is no way to make the code below compile with LDC at
// the moment, so just skip it.
} else {
Stdout( "Now the same with callback functions defined in D:" ).newline;
Stdout( " add(a,b) = " )( example.do_op( a, b, &add ) ).newline;
Stdout( " sub(a,b) = " )( example.do_op( a, b, &sub ) ).newline;
Stdout( " mul(a,b) = " )( example.do_op( a, b, &mul ) ).newline;
}
}

2
Examples/d/simple/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

27
Examples/d/simple/d1/runme.d
View File

@ -1,27 +0,0 @@
module runme;
import tango.io.Stdout;
static import example;
void main() {
/*
* Call our gcd() function.
*/
int x = 42;
int y = 105;
int g = example.gcd( x, y );
Stdout.format( "The gcd of {} and {} is {}.", x, y, g ).newline;
/*
* Manipulate the Foo global variable.
*/
// Output its current value
Stdout.format( "Foo = {}", example.Foo ).newline;
// Change its value
example.Foo = 3.1415926;
// See if the change took effect
Stdout.format( "Foo = {}", example.Foo ).newline;
}

2
Examples/d/variables/Makefile
View File

@ -1 +1 @@
include ../example.mk
include $(SRCDIR)../example.mk

71
Examples/d/variables/d1/runme.d
View File

@ -1,71 +0,0 @@
// This example illustrates global variable access from C#.
module runme;
import tango.io.Stdout;
static import example;
void main() {
// Try to set the values of some global variables
example.ivar = 42;
example.svar = -31000;
example.lvar = 65537;
example.uivar = 123456;
example.usvar = 61000;
example.ulvar = 654321;
example.scvar = -13;
example.ucvar = 251;
example.cvar = 'S';
example.fvar = 3.14159f;
example.dvar = 2.1828;
example.strvar = "Hello World";
example.iptrvar = example.new_int(37);
example.ptptr = example.new_Point(37,42);
example.name = "Bill";
// Now print out the values of the variables
Stdout.formatln( "Variables (printed from D):" );
Stdout.formatln( "ivar = {}", example.ivar );
Stdout.formatln( "svar = {}", example.svar );
Stdout.formatln( "lvar = {}", example.lvar );
Stdout.formatln( "uivar = {}", example.uivar );
Stdout.formatln( "usvar = {}", example.usvar );
Stdout.formatln( "ulvar = {}", example.ulvar );
Stdout.formatln( "scvar = {}", example.scvar );
Stdout.formatln( "ucvar = {}", example.ucvar );
Stdout.formatln( "fvar = {}", example.fvar );
Stdout.formatln( "dvar = {}", example.dvar );
Stdout.formatln( "cvar = {}", example.cvar );
Stdout.formatln( "strvar = {}", example.strvar );
Stdout.formatln( "cstrvar = {}", example.cstrvar );
Stdout.formatln( "iptrvar = {}", example.iptrvar );
Stdout.formatln( "name = {}", example.name );
Stdout.formatln( "ptptr = {} {}", example.ptptr, example.Point_print(example.ptptr) );
Stdout.formatln( "pt = {} {}", example.pt, example.Point_print(example.pt) );
Stdout.formatln( "status = {}", example.status );
Stdout.formatln( "\nVariables (printed from the C library):" );
example.print_vars();
Stdout.formatln( "\nNow I'm going to try and modify some read only variables:" );
Stdout.formatln( "Checking that the read only variables are readonly..." );
Stdout( " 'path'..." );
static if ( is( typeof( example.path = "a" ) ) )
Stdout.formatln("Oh dear, this variable is not read only!");
else
Stdout.formatln("Good.");
Stdout( " 'status'..." );
static if ( is( typeof( example.status = 2 ) ) )
Stdout.formatln("Oh dear, this variable is not read only!");
else
Stdout.formatln("Good.");
Stdout.formatln( "\nI'm going to try and update a structure variable:" );
example.pt = example.ptptr;
Stdout( "The new value is " ).flush;
example.pt_print();
Stdout.formatln( "You should see the value {}", example.Point_print(example.ptptr) );
}

2
Examples/go/index.html
View File

@ -94,6 +94,6 @@ All of the examples were last tested with the following configuration
</ul>
Your mileage may vary. If you experience a problem, please let us know by
contacting us on the <a href="http://www.swig.org/mail.html">mailing lists</a>.
contacting us on the <a href="https://www.swig.org/mail.html">mailing lists</a>.
</body>
</html>

2
Examples/go/reference/index.html
View File

@ -99,7 +99,7 @@ functions like this:
class VectorArray {
public:
...
%addmethods {
%extend {
Vector &amp;get(int index) {
return (*self)[index];
}

4
Examples/go/template/index.html
View File

@ -42,7 +42,7 @@ template<class T> class vector {
v[index] = val;
}
#ifdef SWIG
%addmethods {
%extend {
T getitem(int index) {
return self-&gt;get(index);
}
@ -54,7 +54,7 @@ template<class T> class vector {
};
</pre>
</blockquote>
The %addmethods is used for a neater interface from Go as the
The %extend is used for a neater interface from Go as the
functions <tt>get</tt> and <tt>set</tt> use C++ references to
primitive types. These are tricky to use from Go as they end up as
pointers, which only work when the C++ and Go types correspond

4
Examples/java/doxygen/runme.java
View File

@ -33,8 +33,8 @@ public class runme {
System.out.println(" perimeter = " + shapes[i].perimeter());
}
String command = "javadoc -quiet -public -d javadocs example.java Shape.java Circle.java Square.java RectangleInt.java";
System.out.println("\nRunning: " + command);
String[] command = {"javadoc", "-quiet", "-public", "-d", "javadocs", "example.java", "Shape.java", "Circle.java", "Square.java", "RectangleInt.java"};
System.out.println("\nRunning: " + String.join(" ", command));
Process p = Runtime.getRuntime().exec(command);
int exitCode = p.waitFor();
System.out.println("javadoc exited with code " + exitCode);

2
Examples/java/index.html
View File

@ -58,7 +58,7 @@ The examples have been extensively tested on the following platforms:
</ul>
Your mileage may vary. If you experience a problem, please let us know by
contacting us on the <a href="http://www.swig.org/mail.html">mailing lists</a>.
contacting us on the <a href="https://www.swig.org/mail.html">mailing lists</a>.
</body>
</html>

2
Examples/java/reference/index.html
View File

@ -104,7 +104,7 @@ with a pair of set/get functions like this:
class VectorArray {
public:
...
%addmethods {
%extend {
Vector &amp;get(int index) {
return (*self)[index];
}

4
Examples/java/template/index.html
View File

@ -41,7 +41,7 @@ template<class T> class vector {
v[index] = val;
}
#ifdef SWIG
%addmethods {
%extend {
T getitem(int index) {
return self-&gt;get(index);
}
@ -53,7 +53,7 @@ template<class T> class vector {
};
</pre>
</blockquote>
The %addmethods is used for a neater interface from Java as the functions <tt>get</tt> and <tt>set</tt> use C++ references to primitive types. These are tricky to use from Java as they end up as a pointer in Java (Java long).
The %extend is used for a neater interface from Java as the functions <tt>get</tt> and <tt>set</tt> use C++ references to primitive types. These are tricky to use from Java as they end up as a pointer in Java (Java long).
<h2>The SWIG interface</h2>

3
Examples/javascript/class/Makefile
View File

@ -1,3 +1,4 @@
SRCS = example.cxx
CXXSRCS = example.cxx
_CPP = _cpp
include $(SRCDIR)../example.mk

15
Examples/javascript/class/runme.js
View File

@ -7,6 +7,12 @@ c = new example.Circle(10);
console.log("Created circle " + c);
s = new example.Square(10);
console.log("Created square " + s);
try {
new example.Shape();
console.error("Should have thrown");
} catch {
console.log("Instantiating abstract class Shape failed");
}
// ----- Access a static member -----
console.log("\nA total of " + example.Shape.nshapes + " shapes were created"); // access static member as properties of the class object
@ -21,6 +27,15 @@ c.y = 30;
s.x = -10;
s.y = 5;
// ----- Check inheritance -----
console.log("Square instanceof Shape: ", s instanceof example.Shape);
console.log("Square instanceof Circle: ", s instanceof example.Circle);
console.log("Square instanceof Square: ", s instanceof example.Square);
// ----- Use an inherited method -----
s.move(1, 1);
c.move(-1, -1);
console.log("\nHere is their new position:");
console.log("Circle = (" + c.x + "," + c.y + ")");
console.log("Square = (" + s.x + "," + s.y + ")");

2
Examples/javascript/constant/Makefile
View File

@ -1,3 +1 @@
SRCS =
include $(SRCDIR)../example.mk

3
Examples/javascript/enum/Makefile
View File

@ -1,3 +1,4 @@
SRCS = example.cxx
CXXSRCS = example.cxx
_CPP = _cpp
include $(SRCDIR)../example.mk

26
Examples/javascript/example.mk
View File

@ -1,12 +1,6 @@
# Note: as a convention an example must be in a child directory of this.
# These paths are relative to such an example directory
ifneq (, $(ENGINE))
JSENGINE=$(ENGINE)
else
JSENGINE=node
endif
ifneq (, $(V8_VERSION))
JSV8_VERSION=$(V8_VERSION)
else
@ -19,18 +13,22 @@ SWIGEXE = $(SWIG_TOP)/swig
SWIG_LIB_DIR = $(SWIG_TOP)/$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
TARGET = example
INTERFACE = example.i
SWIGOPT = -$(JSENGINE) -DV8_VERSION=$(JSV8_VERSION)
SWIGOPT =
ifneq (jsc, $(ENGINE))
SWIGOPT += -DV8_VERSION=$(JSV8_VERSION)
endif
check: build
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' JSENGINE='$(JSENGINE)' TARGET='$(TARGET)' javascript_run
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' TARGET='$(TARGET)' javascript_run
build:
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(SRCS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' javascript_wrapper_cpp
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(SRCS)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' JSENGINE='$(JSENGINE)' javascript_build_cpp
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
SRCS='$(SRCS)' SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' javascript_wrapper$(_CPP)
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
SRCS='$(SRCS)' SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' javascript_build$(_CPP)
clean:
$(MAKE) -f $(EXAMPLES_TOP)/Makefile SRCDIR='$(SRCDIR)' javascript_clean

3
Examples/javascript/exception/Makefile
View File

@ -1,3 +1,4 @@
SRCS = example.cxx
CXXSRCS = example.cxx
_CPP = _cpp
include $(SRCDIR)../example.mk

12
Examples/javascript/exception/runme.js
View File

@ -10,7 +10,7 @@ try{
if(error == -1) {
console.log("t.unknown() didn't throw");
} else {
console.log("successfully caught throw in Test::unknown().");
console.log("successfully caught throw in Test::unknown() :" + error);
}
}
@ -22,7 +22,7 @@ catch(error){
if(error == -1) {
console.log("t.simple() did not throw");
} else {
console.log("successfully caught throw in Test::simple().");
console.log("successfully caught throw in Test::simple() :" + error);
}
}
@ -33,7 +33,7 @@ try{
if(error == -1) {
console.log("t.message() did not throw");
} else {
console.log("successfully caught throw in Test::message().");
console.log("successfully caught throw in Test::message() :" + error);
}
}
@ -45,7 +45,7 @@ catch(error){
if(error == -1) {
console.log("t.hosed() did not throw");
} else {
console.log("successfully caught throw in Test::hosed().");
console.log("successfully caught throw in Test::hosed() :" + error);
}
}
@ -58,7 +58,7 @@ for (var i=1; i<4; i++) {
if(error == -1) {
console.log("t.multi(" + i + ") did not throw");
} else {
console.log("successfully caught throw in Test::multi().");
console.log("successfully caught throw in Test::multi() :" + error);
}
}
}
}

2
Examples/javascript/functor/Makefile
View File

@ -1,3 +1,3 @@
SRCS =
_CPP = _cpp
include $(SRCDIR)../example.mk

8
Examples/javascript/functor/runme.js
View File

@ -1,15 +1,19 @@
var example = require("example");
a = new example.intSum(0);
a = new example.intSum(1);
b = new example.doubleSum(100.0);
c = new example.intSum();
// Use the objects. They should be callable just like a normal
// javascript function.
for (i=1;i<=100;i++)
for (i=1;i<=100;i++) {
a.call(i); // Note: function call
b.call(Math.sqrt(i)); // Note: function call
c.call(i);
}
console.log(a.result());
console.log(b.result());
console.log(c.result());

2
Examples/javascript/native/Makefile
View File

@ -1,3 +1,3 @@
SRCS =
_CPP = _cpp
include $(SRCDIR)../example.mk

17
Examples/javascript/native/example.i
View File

@ -10,7 +10,7 @@ int placeholder() { return 0; }
// actual demo code
%wrapper
%{
#ifdef SWIG_V8_VERSION /* Engine: Node || V8 */
#if defined(SWIG_V8_VERSION) /* Engine: Node || V8 */
static SwigV8ReturnValue JavaScript_do_work(const SwigV8Arguments &args) {
SWIGV8_HANDLESCOPE();
@ -24,6 +24,21 @@ int placeholder() { return 0; }
SWIGV8_RETURN(SWIGV8_UNDEFINED());
}
#elif defined(NAPI_VERSION) /* Engine: NAPI */
static Napi::Value JavaScript_do_work(const Napi::CallbackInfo &args) {
Napi::Env env = args.Env();
Napi::EscapableHandleScope scope(env);
const int MY_MAGIC_NUMBER = 5;
Napi::Value jsresult =
SWIG_From_int(env, static_cast< int >(MY_MAGIC_NUMBER));
if (args.Length() != 0)
SWIG_exception_fail(SWIG_ERROR, "Illegal number of arguments.");
return scope.Escape(jsresult);
fail:
return Napi::Value();
}
#else /* Engine: JavaScriptCore */
static JSValueRef JavaScript_do_work(JSContextRef context,

2
Examples/javascript/nspace/Makefile
View File

@ -1,3 +1,3 @@
SRCS =
_CPP = _cpp
include $(SRCDIR)../example.mk

2
Examples/javascript/operator/Makefile
View File

@ -1,3 +1,3 @@
SRCS =
_CPP = _cpp
include $(SRCDIR)../example.mk

2
Examples/javascript/overload/Makefile
View File

@ -1,3 +1,3 @@
SRCS =
_CPP = _cpp
include $(SRCDIR)../example.mk

2
Examples/javascript/pointer/Makefile
View File

@ -1,3 +1,3 @@
SRCS = example.cxx
SRCS = example.c
include $(SRCDIR)../example.mk

2
Examples/javascript/pointer/binding.gyp.in
View File

@ -2,7 +2,7 @@
"targets": [
{
"target_name": "example",
"sources": [ "<!(cp $srcdir/example.cxx example-gypcopy.cxx && echo example-gypcopy.cxx)", "example_wrap.cxx" ],
"sources": [ "<!(cp $srcdir/example.c example-gypcopy.cxx && echo example-gypcopy.cxx)", "example_wrap.cxx" ],
"include_dirs": ["$srcdir"]
}
]

0
Examples/javascript/pointer/example.cxx → Examples/javascript/pointer/example.c
View File

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