diff options
| author | William S Fulton <wsf@fultondesigns.co.uk> | 2020-10-11 14:02:27 +0100 |
|---|---|---|
| committer | William S Fulton <wsf@fultondesigns.co.uk> | 2020-10-11 14:02:27 +0100 |
| commit | 0f07c9dc13a6d98b3ef046cb1d0ecaefa913000a (patch) | |
| tree | 4307138ba856e25d48b9080720235806a703807d | |
| parent | 1d1b3c714a234a60aa80ae5133023cf289a7abe6 (diff) | |
| parent | c1e0f9369efe096bef6041d276a8c06f566e795c (diff) | |
| download | swig-0f07c9dc13a6d98b3ef046cb1d0ecaefa913000a.tar.gz | |
Merge branch 'chsasank-master' into sphinxdocs
* chsasank-master:
Removed helper script file [skip-ci]
Updating conf.py path in .readthedocs.yml
Updating requirements.txt [skip-ci]
Sphinx doc corrections - SWIG.rst [skip-ci]
Sphinx doc corrections - Warnings.rst [skip-ci]
Sphinx doc corrections - Go.rst [skip-ci]
Sphinx doc corrections - Javascript.rst [skip-ci]
Sphinx doc corrections - Library.rst [skip-ci]
Sphinx doc corrections - Lisp.rst [skip-ci]
Sphinx doc corrections - Lua.rst [skip-ci]
Sphinx doc corrections - Modula3.rst [skip-ci]
Sphinx doc corrections - Ocaml.rst [skip-ci]
Sphinx doc corrections - Octave.rst [skip-ci]
Sphinx doc corrections - Pike.rst [skip-ci]
Sphinx doc corrections - Preface.rst [skip-ci]
Sphinx doc corrections - Preprocessor.rst [skip-ci]
Sphinx doc corrections - Python.rst [skip-ci]
Sphinx doc corrections - Ruby.rst [skip-ci]
Sphinx doc corrections - Scilab.rst [skip-ci]
Sphinx doc corrections - SWIG.rst [skip-ci]
Sphinx doc corrections - SWIGPlus.rst [skip-ci]
Sphinx doc corrections - Typemaps.rst [skip-ci]
Sphinx doc corrections - Windows.rst [skip-ci]
| -rw-r--r-- | .readthedocs.yml | 2 | ||||
| -rw-r--r-- | SphinxDocs/requirements.txt | 28 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Go.rst | 185 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Javascript.rst | 2 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Library.rst | 169 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Lisp.rst | 28 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Lua.rst | 47 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Modula3.rst | 592 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Ocaml.rst | 329 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Octave.rst | 2 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Pike.rst | 2 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Preface.rst | 4 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Preprocessor.rst | 12 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Python.rst | 177 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Ruby.rst | 530 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/SWIG.rst | 281 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/SWIGPlus.rst | 14 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Scilab.rst | 64 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Typemaps.rst | 116 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Warnings.rst | 366 | ||||
| -rw-r--r-- | SphinxDocs/source/Manual/Windows.rst | 51 |
21 files changed, 1584 insertions, 1417 deletions
diff --git a/.readthedocs.yml b/.readthedocs.yml index 694aadf12..dceb2607e 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -7,4 +7,4 @@ version: 2 # Build documentation in the docs/ directory with Sphinx sphinx: - configuration: SphinxDocs/conf.py + configuration: SphinxDocs/source/conf.py diff --git a/SphinxDocs/requirements.txt b/SphinxDocs/requirements.txt index cbf1e3658..1ba63194e 100644 --- a/SphinxDocs/requirements.txt +++ b/SphinxDocs/requirements.txt @@ -1,2 +1,26 @@ -sphinx -sphinx-rtd-theme +alabaster==0.7.12 +Babel==2.8.0 +certifi==2020.6.20 +chardet==3.0.4 +docutils==0.16 +idna==2.10 +imagesize==1.2.0 +Jinja2==2.11.2 +MarkupSafe==1.1.1 +packaging==20.4 +pkg-resources==0.0.0 +Pygments==2.7.1 +pyparsing==2.4.7 +pytz==2020.1 +requests==2.24.0 +six==1.15.0 +snowballstemmer==2.0.0 +Sphinx==3.2.1 +sphinx-rtd-theme==0.5.0 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==1.0.3 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.4 +urllib3==1.25.10 diff --git a/SphinxDocs/source/Manual/Go.rst b/SphinxDocs/source/Manual/Go.rst index 32ea3e0bf..22864f55e 100644 --- a/SphinxDocs/source/Manual/Go.rst +++ b/SphinxDocs/source/Manual/Go.rst @@ -31,7 +31,7 @@ Examples ------------- Working examples can be found in the `SWIG source -tree <https://github.com/swig/swig/tree/master/Examples/go>`__ . +tree <https://github.com/swig/swig/tree/master/Examples/go>`__. Please note that the examples in the SWIG source tree use makefiles with the .i SWIG interface file extension for backwards compatibility with Go @@ -122,29 +122,73 @@ be seen by using: swig -go -help -+-------------------------+ -| Go-specific options | -+=========================+ -| -cgo | -+-------------------------+ -| -no-cgo | -+-------------------------+ -| -intgosize <s> | -+-------------------------+ -| -gccgo | -+-------------------------+ -| -package <name> | -+-------------------------+ -| -use-shlib | -+-------------------------+ -| -soname <name> | -+-------------------------+ -| -go-pkgpath <pkgpath> | -+-------------------------+ -| -go-prefix <prefix> | -+-------------------------+ -| -import-prefix <prefix> | -+-------------------------+ +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * + - Go-specific options + - + * + - -cgo + - Generate files to be used as input for the Go cgo tool. + This is the default. + * + - -no-cgo + - Generate files that can be used directly, rather than + via the Go cgo tool. This option does not work with Go + 1.5 or later. It is required for versions of Go before 1.2. + * + - -intgosize <s> + - Set the size for the Go type int. This controls the + size that the C/C++ code expects to see. The <s> + argument should be 32 or 64. This option is currently + required during the transition from Go 1.0 to Go 1.1, + as the size of int on 64-bit x86 systems changes + between those releases (from 32 bits to 64 bits). In + the future the option may become optional, and SWIG + will assume that the size of int is the size of a C + pointer. + * + - -gccgo + - Generate code for gccgo. The default is to generate + code for the Go compiler of the Go distribution. + * + - -package <name> + - Set the name of the Go package to <name>. The default + package name is the SWIG module name. + * + - -use-shlib + - Tell SWIG to emit code that uses a shared library. This + is only meaningful for the Go compiler of the Go + distribution, which needs to know at compile time + whether a shared library will be used. + * + - -soname <name> + - Set the runtime name of the shared library that the + dynamic linker should include at runtime. The default + is the package name with ".so" appended. This is only + used when generating code for the Go compiler of the Go + distribution; when using gccgo, the equivalent name + will be taken from the -soname option passed to the + linker. Using this option implies the -use-shlib + option. + * + - -go-pkgpath <pkgpath> + - When generating code for gccgo, set the pkgpath to use. + This corresponds to the -fgo-pkgpath option to gccgo. + * + - -go-prefix <prefix> + - When generating code for gccgo, set the prefix to use. + This corresponds to the -fgo-prefix option to gccgo. If + -go-pkgpath is used, -go-prefix will be ignored. + * + - -import-prefix <prefix> + - A prefix to add when turning a %import prefix in the + SWIG interface file into an import statement in the Go + file. For example, with -import-prefix mymodule, a SWIG + interface file %import mypackage will become a Go + import statement import "mymodule/mypackage". Generated Wrapper Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -207,8 +251,8 @@ First the first letter of the variable name will be forced to uppercase, and then ``Get`` or ``Set`` will be prepended. For example, if the C/C++ variable is called ``var``, then SWIG will define the functions ``GetVar`` and ``SetVar``. If a variable is declared as ``const``, or if -SWIG's ```%immutable`` directive <SWIG.html#SWIG_readonly_variables>`__ -is used for the variable, then only the getter will be defined. +SWIG's `%immutable directive <SWIG.html#SWIG_readonly_variables>`__ is used for the variable, +then only the getter will be defined. C++ classes will be discussed further below. Here we'll note that the first letter of the class name will be forced to uppercase to give the @@ -909,40 +953,61 @@ The following table lists the default type mapping from C/C++ to Go. This table will tell you which Go type to expect for a function which uses a given C/C++ type. -+-----------------------------------+-----------------------------------+ -| **C/C++ type** | **Go type** | -+-----------------------------------+-----------------------------------+ -| bool | bool | -+-----------------------------------+-----------------------------------+ -| char | byte | -+-----------------------------------+-----------------------------------+ -| signed char | int8 | -+-----------------------------------+-----------------------------------+ -| unsigned char | byte | -+-----------------------------------+-----------------------------------+ -| short | int16 | -+-----------------------------------+-----------------------------------+ -| unsigned short | uint16 | -+-----------------------------------+-----------------------------------+ -| int | int | -+-----------------------------------+-----------------------------------+ -| unsigned int | uint | -+-----------------------------------+-----------------------------------+ -| long | int64 | -+-----------------------------------+-----------------------------------+ -| unsigned long | uint64 | -+-----------------------------------+-----------------------------------+ -| long long | int64 | -+-----------------------------------+-----------------------------------+ -| unsigned long long | uint64 | -+-----------------------------------+-----------------------------------+ -| float | float32 | -+-----------------------------------+-----------------------------------+ -| double | float64 | -+-----------------------------------+-----------------------------------+ -| char \* | string | -| char [] | | -+-----------------------------------+-----------------------------------+ +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + + * + - **C/C++ type** + - **Go type** + * + - bool + - bool + * + - char + - byte + * + - signed char + - int8 + * + - unsigned char + - byte + * + - short + - int16 + * + - unsigned short + - uint16 + * + - int + - int + * + - unsigned int + - uint + * + - long + - int64 + * + - unsigned long + - uint64 + * + - long long + - int64 + * + - unsigned long long + - uint64 + * + - float + - float32 + * + - double + - float64 + * + - char \* + + char [] + - string Note that SWIG wraps the C ``char`` type as a character. Pointers and arrays of this type are wrapped as strings. The ``signed char`` type can diff --git a/SphinxDocs/source/Manual/Javascript.rst b/SphinxDocs/source/Manual/Javascript.rst index 72aff3eee..fafeb05e2 100644 --- a/SphinxDocs/source/Manual/Javascript.rst +++ b/SphinxDocs/source/Manual/Javascript.rst @@ -67,7 +67,7 @@ If building a C++ extension, add the -c++ option: $ swig -c++ -javascript -jsc example.i -The V8 code that SWIG generates should work with most versions from +The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later. The API headers for V8 >= 4.3.0 define constants which SWIG can use to diff --git a/SphinxDocs/source/Manual/Library.rst b/SphinxDocs/source/Manual/Library.rst index b8de38f2b..bb14e6bc3 100644 --- a/SphinxDocs/source/Manual/Library.rst +++ b/SphinxDocs/source/Manual/Library.rst @@ -60,7 +60,7 @@ generate wrappers around simple C pointers. The primary use of this module is in generating pointers to primitive datatypes such as ``int`` and ``double``. -**``%pointer_functions(type, name)``** +**%pointer_functions(type, name)** .. container:: indent @@ -133,7 +133,7 @@ and ``double``. 7 >>> example.delete_intp(c) # Delete -**``%pointer_class(type, name)``** +**%pointer_class(type, name)** .. container:: indent @@ -200,7 +200,7 @@ and ``double``. access like objects and they can be easily garbage collected (destruction of the pointer object destroys the underlying object). -**``%pointer_cast(type1, type2, name)``** +**%pointer_cast(type1, type2, name)** .. container:: indent @@ -230,7 +230,7 @@ as arrays. The module does not provide any safety or an extra layer of wrapping--it merely provides functionality for creating, destroying, and modifying the contents of raw C array data. -**``%array_functions(type, name)``** +**%array_functions(type, name)** .. container:: indent @@ -305,7 +305,7 @@ modifying the contents of raw C array data. print_array(a) # Pass to C delete_doubleArray(a) # Destroy array -**``%array_class(type, name)``** +**%array_class(type, name)** .. container:: indent @@ -374,7 +374,7 @@ This module defines macros for wrapping the low-level C memory allocation functions ``malloc()``, ``calloc()``, ``realloc()``, and ``free()``. -**``%malloc(type [, name=type])``** +**%malloc(type [, name=type])** .. container:: indent @@ -391,7 +391,7 @@ allocation functions ``malloc()``, ``calloc()``, ``realloc()``, and wrapping a type that is not a valid identifier (e.g., "``int *``", "``double **``", etc.). -**``%calloc(type [, name=type])``** +**%calloc(type [, name=type])** .. container:: indent @@ -405,7 +405,7 @@ allocation functions ``malloc()``, ``calloc()``, ``realloc()``, and If ``type`` is ``void``, then the size parameter ``sz`` is required. -**``%realloc(type [, name=type])``** +**%realloc(type [, name=type])** .. container:: indent @@ -422,7 +422,7 @@ allocation functions ``malloc()``, ``calloc()``, ``realloc()``, and ``realloc_int(p, 100)`` reallocates ``p`` so that it holds 100 integers. -**``%free(type [, name=type])``** +**%free(type [, name=type])** .. container:: indent @@ -434,7 +434,7 @@ allocation functions ``malloc()``, ``calloc()``, ``realloc()``, and void free_name(type *ptr); -**``%sizeof(type [, name=type])``** +**%sizeof(type [, name=type])** .. container:: indent @@ -446,7 +446,7 @@ allocation functions ``malloc()``, ``calloc()``, ``realloc()``, and %constant int sizeof_name = sizeof(type); -**``%allocators(type [, name=type])``** +**%allocators(type [, name=type])** .. container:: indent @@ -504,14 +504,14 @@ instance, if you needed to extract data from a buffer. The target language must support strings with embedded binary data in order for this to work. -**``const char *cdata(void *ptr, size_t nbytes)``** +**const char *cdata(void *ptr, size_t nbytes)** .. container:: indent Converts ``nbytes`` of data at ``ptr`` into a string. ``ptr`` can be any pointer. -**``void memmove(void *ptr, const char *s)``** +**void memmove(void *ptr, const char *s)** .. container:: indent @@ -519,7 +519,7 @@ this to work. ``ptr``. The string may contain embedded NULL bytes. This is actually a wrapper to the standard C library ``memmove`` function, which is declared as - **``void memmove(void *ptr, const void *src, size_t n)``**. The + **void memmove(void *ptr, const void *src, size_t n)**. The ``src`` and length ``n`` parameters are extracted from the language specific string ``s`` in the underlying wrapper code. @@ -559,7 +559,7 @@ Python example: Since the size of data is not always known, the following macro is also defined: -**``%cdata(type [, name=type])``** +**%cdata(type [, name=type])** .. container:: indent @@ -759,7 +759,7 @@ typemaps. Therefore, the same pattern matching rules and ideas apply. stored in the buffer is then returned as a function return value. If the function already returns a value, then the return value and the output string are returned together (multiple return values). **If - more than ``maxsize`` bytes are written, your program will crash with + more than maxsize bytes are written, your program will crash with a buffer overflow!** **%cstring_chunk_output(parm, chunksize)** @@ -790,7 +790,7 @@ typemaps. Therefore, the same pattern matching rules and ideas apply. This macro is essentially identical to ``%cstring_bounded_output``. The only difference is that the result is always ``chunksize`` characters. Furthermore, the result can contain binary data. **If - more than ``maxsize`` bytes are written, your program will crash with + more than maxsize bytes are written, your program will crash with a buffer overflow!** **%cstring_bounded_mutable(parm, maxsize)** @@ -826,7 +826,7 @@ typemaps. Therefore, the same pattern matching rules and ideas apply. internal buffer. It is important to emphasize that this function does not mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. **If more than - ``maxsize`` bytes are written, your program will crash with a buffer + maxsize bytes are written, your program will crash with a buffer overflow!** **%cstring_mutable(parm [, expansion])** @@ -871,7 +871,7 @@ typemaps. Therefore, the same pattern matching rules and ideas apply. important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. **If the function expands the - result by more than ``expansion`` extra bytes, then the program will + result by more than expansion extra bytes, then the program will crash with a buffer overflow!** **%cstring_output_maxsize(parm, maxparm)** @@ -1068,55 +1068,86 @@ code written. The following table shows which C++ classes are supported and the equivalent SWIG interface library file for the C++ library. -+----------------------+----------------------+----------------------+ -| **C++ class** | **C++ Library file** | **SWIG Interface | -| | | library file** | -+----------------------+----------------------+----------------------+ -| std::array (C++11) | array | std_array.i | -+----------------------+----------------------+----------------------+ -| std::auto_ptr | memory | std_auto_ptr.i | -+----------------------+----------------------+----------------------+ -| std::complex | complex | std_complex.i | -+----------------------+----------------------+----------------------+ -| std::deque | deque | std_deque.i | -+----------------------+----------------------+----------------------+ -| std::list | list | std_list.i | -+----------------------+----------------------+----------------------+ -| std::map | map | std_map.i | -+----------------------+----------------------+----------------------+ -| std::multimap | multimap | std_multimap.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ -| std::multiset | multiset | std_multiset.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ -| std::pair | utility | std_pair.i | -+----------------------+----------------------+----------------------+ -| std::set | set | std_set.i | -+----------------------+----------------------+----------------------+ -| std::string | string | std_string.i | -+----------------------+----------------------+----------------------+ -| std::unordered_map | unordered_map | std_unordered_map.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ -| std | unordered_multimap | std_ | -| ::unordered_multimap | | unordered_multimap.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ -| std | unordered_multiset | std_ | -| ::unordered_multiset | | unordered_multiset.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ -| std::unordered_set | unordered_set | std_unordered_set.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ -| std::vector | vector | std_vector.i | -+----------------------+----------------------+----------------------+ -| std::wstring | wstring | std_wstring.i | -+----------------------+----------------------+----------------------+ -| std::shared_ptr | shared_ptr | std_shared_ptr.i | -| (C++11) | | | -+----------------------+----------------------+----------------------+ +.. list-table:: + :widths: 25 25 25 + :header-rows: 1 + + * + - **C++ class** + - **C++ Library file** + - **SWIG Interface library file** + * + - std::array (C++11) + - array + - std_array.i + * + - std::auto_ptr + - memory + - std_auto_ptr.i + * + - std::complex + - complex + - std_complex.i + * + - std::deque + - deque + - std_deque.i + * + - std::list + - list + - std_list.i + * + - std::map + - map + - std_map.i + * + - std::multimap (C++11) + - multimap + - std_multimap.i + * + - std::multiset (C++11) + - multiset + - std_multiset.i + * + - std::pair + - utility + - std_pair.i + * + - std::set + - set + - std_set.i + * + - std::string + - string + - std_string.i + * + - std::unordered_map (C++11) + - unordered_map + - std_unordered_map.i + * + - std::unordered_multimap (C++11) + - unordered_multimap + - std_unordered_multimap.i + * + - std::unordered_multiset (C++11) + - unordered_multiset + - std_unordered_multiset.i + * + - std::unordered_set (C++11) + - unordered_set + - std_unordered_set.i + * + - std::vector + - vector + - std_vector.i + * + - std::wstring + - wstring + - std_wstring.i + * + - std::shared_ptr (C++11) + - shared_ptr + - std_shared_ptr.i The list is by no means complete; some language modules support a subset of the above and some support additional STL classes. Please look for @@ -1710,7 +1741,7 @@ largely used by the SWIG library writers. If possible, use the error handling scheme available to your target language as there is greater flexibility in what errors/exceptions can be thrown. -**``SWIG_exception(int code, const char *message)``** +**SWIG_exception(int code, const char *message)** .. container:: indent diff --git a/SphinxDocs/source/Manual/Lisp.rst b/SphinxDocs/source/Manual/Lisp.rst index 7121a2d31..7a437b035 100644 --- a/SphinxDocs/source/Manual/Lisp.rst +++ b/SphinxDocs/source/Manual/Lisp.rst @@ -34,15 +34,25 @@ the various things which you can do with them. Additional Commandline Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+-----------------------------------------------------------------------+ -| CFFI specific options | -+=======================================================================+ -| -generate-typedef | -+-----------------------------------------------------------------------+ -| -[no]cwrap | -+-----------------------------------------------------------------------+ -| -[no]swig-lisp | -+-----------------------------------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - CFFI specific options + - + * + - -generate-typedef + - If this option is given then defctype will be used to generate shortcuts according to the typedefs + in the input. + * + - -[no]cwrap + - Turn on or turn off generation of an intermediate C file when creating a C interface. By default + this is only done for C++ code. + * + - -[no]swig-lisp + - 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. Generating CFFI bindings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/SphinxDocs/source/Manual/Lua.rst b/SphinxDocs/source/Manual/Lua.rst index 4101955dd..5f30e2efa 100644 --- a/SphinxDocs/source/Manual/Lua.rst +++ b/SphinxDocs/source/Manual/Lua.rst @@ -8,7 +8,7 @@ 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 *really* tiny language, less than -lines of code, which compiles to <100 kilobytes of binary code. It +6000 lines of code, which compiles to <100 kilobytes of binary code. It can be found at http://www.lua.org eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and @@ -117,19 +117,30 @@ for the Lua module. They can also be seen by using: swig -lua -help -+----------------------------+ -| Lua specific options | -+============================+ -| -elua | -+----------------------------+ -| -eluac | -+----------------------------+ -| -nomoduleglobal | -+----------------------------+ -| -no-old-metatable-bindings | -+----------------------------+ -| -squash-bases | -+----------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - Lua specific options + - + * + - -elua + - Generates LTR compatible wrappers for smaller devices running elua. + * + - -eluac + - LTR compatible wrappers in "crass compress" mode for elua. + * + - -nomoduleglobal + - Do not register the module name as a global variable but return the module table from calls to require. + * + - -no-old-metatable-bindings + - Disable backward compatibility: old-style binding names generations and a few other things. + Explanations are included in appropriate later sections. + * + - -squash-bases + - Squashes symbols from all inheritance tree of a given class into itself. + Emulates pre-SWIG3.0 inheritance. Insignificantly speeds things up, but increases memory consumption. Compiling and Linking and Interpreter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2102,7 +2113,7 @@ ease of use: Obviously the first version could be made less tedious by writing a Lua function to perform the conversion from a table to a C-array. The -``%luacode`` directive is good for this. See SWIG\Examples\lua\arrays +``%luacode`` directive is good for this. See ``SWIG\Examples\lua\arrays`` for an example of this. **Warning:** in C indexes start at ZERO, in Lua indexes start at ONE. @@ -2213,12 +2224,13 @@ main Lua-C api, as this is well documented and not worth covering. .. container:: indent This is the standard function used for converting a Lua userdata to a - void*. It takes the value at the given index in the Lua state and + ``void*``. It takes the value at the given index in the Lua state and converts it to a userdata. It will then provide the necessary type checks, confirming that the pointer is compatible with the type given - in 'type'. Then finally setting '*ptr' to the pointer. If flags is + in 'type'. Then finally setting ``'*ptr'`` to the pointer. If flags is set to SWIG_POINTER_DISOWN, this is will clear any ownership flag set on the object. + This returns a value which can be checked with the macro SWIG_IsOK() ``void SWIG_NewPointerObj(lua_State* L, void* ptr, swig_type_info *type, int own);`` @@ -2247,6 +2259,7 @@ main Lua-C api, as this is well documented and not worth covering. function, will jump to the error handler code. This will call any cleanup code (freeing any temp variables) and then triggers a lua_error. + A common use for this code is: :: diff --git a/SphinxDocs/source/Manual/Modula3.rst b/SphinxDocs/source/Manual/Modula3.rst index 75b365a05..f0d353a5f 100644 --- a/SphinxDocs/source/Manual/Modula3.rst +++ b/SphinxDocs/source/Manual/Modula3.rst @@ -70,97 +70,92 @@ generate wrappers written in C. All conversion and argument checking can be done in Modula-3 and the interfacing is quite efficient. All you have to do is to write pieces of Modula-3 code that SWIG puts together. -C library support integrated in Modula-3 - -Pragma ``<* EXTERNAL *>`` - -Precedes a declaration of a PROCEDURE that is implemented in an external -library instead of a Modula-3 module. - -Pragma ``<* CALLBACK *>`` - -Precedes a declaration of a PROCEDURE that should be called by external -library code. - -Module ``Ctypes`` - -Contains Modula-3 types that match some basic C types. - -Module ``M3toC`` - -Contains routines that convert between Modula-3's ``TEXT`` type and C's -``char *`` type. +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - C library support integrated in Modula-3 + - + * + - Pragma <\* EXTERNAL \*> + - Precedes a declaration of a PROCEDURE that is implemented in an external library instead of a + Modula-3 module. + * + - Pragma <\* CALLBACK \*> + - Precedes a declaration of a PROCEDURE that should be called by external library code. + * + - Module Ctypes + - Contains Modula-3 types that match some basic C types. + * + - Module M3toC + - Contains routines that convert between Modula-3's TEXT type and C's char * type. In each run of SWIG the Modula-3 part generates several files: -+--------------------+-----------------------+-----------------------+ -| Module name scheme | Identifier for | Description | -| | ``%insert`` | | -+====================+=======================+=======================+ -| Module\ ``Raw.i3`` | ``m3rawintf`` | Declaration of types | -| | | that are equivalent | -| | | to those of the C | -| | | library, ``EXTERNAL`` | -| | | procedures as | -| | | interface to the C | -| | | library functions | -+--------------------+-----------------------+-----------------------+ -| Module\ ``Raw.m3`` | ``m3rawimpl`` | Almost empty. | -+--------------------+-----------------------+-----------------------+ -| Module\ ``.i3`` | ``m3wrapintf`` | Declaration of | -| | | comfortable wrappers | -| | | to the C library | -| | | functions. | -+--------------------+-----------------------+-----------------------+ -| Module\ ``.m3`` | ``m3wrapimpl`` | Implementation of the | -| | | wrappers that convert | -| | | between Modula-3 and | -| | | C types, check for | -| | | validity of values, | -| | | hand-over resource | -| | | management to the | -| | | garbage collector | -| | | using ``WeakRef``\ s | -| | | and raises | -| | | exceptions. | -+--------------------+-----------------------+-----------------------+ -| ``m3makefile`` | ``m3makefile`` | Add the modules above | -| | | to the Modula-3 | -| | | project and specify | -| | | the name of the | -| | | Modula-3 wrapper | -| | | library to be | -| | | generated. Today I'm | -| | | not sure if it is a | -| | | good idea to create a | -| | | ``m3makefile`` in | -| | | each run, because | -| | | SWIG must be started | -| | | for each Modula-3 | -| | | module it creates. | -| | | Thus the m3makefile | -| | | is overwritten each | -| | | time. :-( | -+--------------------+-----------------------+-----------------------+ +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * + - Module name scheme + - Identifier for ``%insert`` + - Description + * + - Module\ ``Raw.i3`` + - ``m3rawintf`` + - Declaration of types that are equivalent to those of the C library, ``EXTERNAL`` + procedures as interface to the C library functions. + * + - Module\ ``Raw.m3`` + - ``m3rawimpl`` + - Almost empty. + * + - Module\ ``.i3`` + - ``m3wrapintf`` + - Declaration of comfortable wrappers to the C library functions. + * + - Module\ ``.m3`` + - ``m3wrapimpl`` + - Implementation of the wrappers that convert between Modula-3 and C types, check for + validity of values, hand-over resource management to the garbage collector using ``WeakRef``\ s + and raises exceptions. + * + - ``m3makefile`` + - ``m3makefile`` + - Add the modules above to the Modula-3 project and specify the name of the Modula-3 wrapper + library to be generated. Today I'm not sure if it is a good idea to create a ``m3makefile`` in + each run, because SWIG must be started for each Modula-3 module it creates. Thus the m3makefile + is overwritten each time. :-( Here's a scheme of how the function calls to Modula-3 wrappers are redirected to C library functions: -+-----------------------+-----------------------+-----------------------+ -| Modula-3 wrapper | | | -| Module\ ``.i3`` | | | -| generated by Modula-3 | | | -| part of SWIG | | | -+-----------------------+-----------------------+-----------------------+ -| \| | | | -| v | | | -+-----------------------+-----------------------+-----------------------+ -| Modula-3 interface to | --> | C library | -| C | | | -| Module\ ``Raw.i3`` | | | -| generated by Modula-3 | | | -| part of SWIG | | | -+-----------------------+-----------------------+-----------------------+ +.. list-table:: + :widths: 40 20 40 + :header-rows: 0 + :align: center + + * + - | Modula-3 wrapper + | Module\ ``.i3`` + | generated by Modula-3 + | part of SWIG + - + - + * + - | | + | v + - + - + * + - | Modula-3 interface to + | C + | Module\ ``Raw.i3`` + | generated by Modula-3 + | part of SWIG + - --> + - C library I have still no good conception how one can split C library interfaces into type oriented interfaces. A Module in Modula-3 represents an @@ -189,21 +184,36 @@ functions with a C interface. Here's a scheme of how the function calls to Modula-3 wrappers are redirected to C library functions: -+-----------------------+-----------------------+-----------------------+ -| Modula-3 wrapper | | C++ library | -| Module\ ``.i3`` | | | -| generated by Modula-3 | | | -| part of SWIG | | | -+-----------------------+-----------------------+-----------------------+ -| \| | | ^ | -| v | | \| | -+-----------------------+-----------------------+-----------------------+ -| Modula-3 interface to | --> | C interface to C++ | -| C | | module\ ``_wrap.cxx`` | -| Module\ ``Raw.i3`` | | generated by the SWIG | -| generated by Modula-3 | | core | -| part of SWIG | | | -+-----------------------+-----------------------+-----------------------+ +.. list-table:: + :widths: 40 20 40 + :header-rows: 0 + :align: center + + * + - | Modula-3 wrapper + | Module ``.i3`` + | generated by Modula-3 + | part of SWIG + - + - C++ library + * + - | \| + | v + - + - | ^ + | \| + * + - | Modula-3 interface to + | C + | Module ``Raw.i3`` + | generated by Modula-3 + | part of SWIG + - --> + - | C interface to C++ + | module ``_wrap.cxx`` + | generated by the + | SWIG core + Wrapping C++ libraries arises additional problems: @@ -218,15 +228,15 @@ Wrapping C++ libraries arises additional problems: `Java <Java.html#Java_directors>`__ and `Python <Python.html#Python_directors>`__. - How to manage storage with the garbage collector of Modula-3? Support - for ```%newobject`` and - ``%typemap(newfree)`` <Customization.html#Customization_ownership>`__ + for `%newobject and \ + %typemap(newfree) <Customization.html#Customization_ownership>`__ isn't implemented, yet. What's about resources that are managed by the garbage collector but shall be passed back to the storage management of the C++ library? This is a general issue which is not solved in a satisfying fashion as far as I know. - How to turn C++ exceptions into Modula-3 exceptions? There's also no support for - ```%exception`` <Customization.html#Customization_exception>`__, yet. + `%exception <Customization.html#Customization_exception>`__, yet. Be warned: There is no C++ library I wrote a SWIG interface for, so I'm not sure if this is possible or sensible, yet. @@ -249,70 +259,44 @@ There are some experimental command line options that prevent SWIG from generating interface files. Instead files are emitted that may assist you when writing SWIG interface files. -+-----------------------------------+-----------------------------------+ -| Modula-3 specific options | Description | -+===================================+===================================+ -| -generateconst <file> | Disable generation of interfaces | -| | and wrappers. Instead write code | -| | for computing numeric values of | -| | constants to the specified file. | -| | C code may contain several | -| | constant definitions written as | -| | preprocessor macros. Other | -| | language modules of SWIG use | -| | compute-once-use-readonly | -| | variables or functions to wrap | -| | such definitions. All of them can | -| | invoke C code dynamically for | -| | computing the macro values. But | -| | if one wants to turn them into | -| | Modula-3 integer constants, | -| | enumerations or set types, the | -| | values of these expressions has | -| | to be known statically. Although | -| | definitions like | -| | ``(1 << FLAG_MAXIMIZEWINDOW)`` | -| | must be considered as good C | -| | style they are hard to convert to | -| | Modula-3 since the value | -| | computation can use every feature | -| | of C. | -| | Thus I implemented these switch | -| | to extract all constant | -| | definitions and write a C program | -| | that output the values of them. | -| | It works for numeric constants | -| | only and treats all of them as | -| | ``double``. Future versions may | -| | generate a C++ program that can | -| | detect the type of the macros by | -| | overloaded output functions. Then | -| | strings can also be processed. | -+-----------------------------------+-----------------------------------+ -| -generaterename <file> | Disable generation of interfaces | -| | and wrappers. Instead generate | -| | suggestions for ``%rename``. | -| | C libraries use a naming style | -| | that is neither homogeneous nor | -| | similar to that of Modula-3. C | -| | function names often contain a | -| | prefix denoting the library and | -| | some name components separated by | -| | underscores or capitalization | -| | changes. To get library | -| | interfaces that are really | -| | Modula-3 like you should rename | -| | the function names with the | -| | ``%rename`` directive. This | -| | switch outputs a list of such | -| | directives with a name suggestion | -| | generated by a simple heuristic. | -+-----------------------------------+-----------------------------------+ -| -generatetypemap <file> | Disable generation of interfaces | -| | and wrappers. Instead generate | -| | templates for some basic | -| | typemaps. | -+-----------------------------------+-----------------------------------+ +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * + - Modula-3 specific options + - Description + * + - -generateconst <file> + - Disable generation of interfaces and wrappers. Instead write code for + computing numeric values of constants to the specified file. + C code may contain several constant definitions written as preprocessor macros. + Other language modules of SWIG use compute-once-use-readonly variables or functions to wrap + such definitions. + All of them can invoke C code dynamically for computing the macro values. + But if one wants to turn them into Modula-3 integer constants, enumerations or set + types, the values of these expressions has to be known statically. + Although definitions like ``(1 << FLAG_MAXIMIZEWINDOW)`` must be considered as good + C style they are hard to convert to Modula-3 since the value computation can use every feature of C. + Thus I implemented these switch to extract all constant definitions and write + a C program that output the values of them. + It works for numeric constants only and treats all of them as ``double``. + Future versions may generate a C++ program that can detect the type of the macros by output functions. + Then strings can also be processed. + * + - -generaterename <file> + - Disable generation of interfaces and wrappers. Instead generate suggestions for ``%rename``. + C libraries use a naming style that is neither homogeneous nor similar to that of Modula-3. + C function names often contain a prefix denoting the library and some name components + separated by underscores or capitalization changes. + To get library interfaces that are really Modula-3 like you should rename + the function names with the ``%rename``directive. + This switch outputs a list of such directives with a name suggestion generated by a simple heuristic. + * + - -generatetypemap <file> + - Disable generation of interfaces and wrappers. Instead generate templates for + some basic typemaps. + Modula-3 typemaps ---------------------- @@ -356,91 +340,101 @@ following parts: - Free temporary storage. - Return values. -+-----------------+------------------------+------------------------+ -| Typemap | Example | Description | -+=================+========================+========================+ -| m3wrapargvar | ``$1: | Declaration of some | -| | INTEGER := $1_name;`` | variables needed for | -| | | temporary results. | -+-----------------+------------------------+------------------------+ -| m3wrapargconst | ``$1 = "$1_name";`` | Declaration of some | -| | | constant, maybe for | -| | | debug purposes. | -+-----------------+------------------------+------------------------+ -| m3wrapargraw | ``ORD($1_name)`` | The expression that | -| | | should be passed as | -| | | argument to the raw | -| | | Modula-3 interface | -| | | function. | -+-----------------+------------------------+------------------------+ -| m3wrapargdir | ``out`` | Referential arguments | -| | | can be used for input, | -| | | output, update. ??? | -+-----------------+------------------------+------------------------+ -| m3wrapinmode | ``READONLY`` | One of Modula-3 | -| | | parameter modes | -| | | ``VALUE`` (or empty), | -| | | ``VAR``, ``READONLY`` | -+-----------------+------------------------+------------------------+ -| m3wrapinname | | New name of the input | -| | | argument. | -+-----------------+------------------------+------------------------+ -| m3wrapintype | | Modula-3 type of the | -| | | input argument. | -+-----------------+------------------------+------------------------+ -| m3wrapindefault | | Default value of the | -| | | input argument | -+-----------------+------------------------+------------------------+ -| m3wrapinconv | ``$1 := M3toC. | Statement for | -| | SharedTtoS($1_name);`` | converting the | -| | | Modula-3 input value | -| | | to C compliant value. | -+-----------------+------------------------+------------------------+ -| m3wrapincheck | ` | Check the integrity of | -| | `IF Text.Length($1_nam | the input value. | -| | e) > 10 THEN RAISE E(" | | -| | str too long"); END;`` | | -+-----------------+------------------------+------------------------+ -| m3wrapoutname | | Name of the ``RECORD`` | -| | | field to be used for | -| | | returning multiple | -| | | values. This applies | -| | | to referential output | -| | | arguments that shall | -| | | be turned into return | -| | | values. | -+-----------------+------------------------+------------------------+ -| m3wrapouttype | | Type of the value that | -| | | is returned instead of | -| | | a referential output | -| | | argument. | -+-----------------+------------------------+------------------------+ -| m3wrapoutconv | | | -+-----------------+------------------------+------------------------+ -| m3wrapoutcheck | | | -+-----------------+------------------------+------------------------+ -| m3wrapretraw | | | -+-----------------+------------------------+------------------------+ -| m3wrapretname | | | -+-----------------+------------------------+------------------------+ -| m3wraprettype | | | -+-----------------+------------------------+------------------------+ -| m3wrapretvar | | | -+-----------------+------------------------+------------------------+ -| m3wrapretconv | | | -+-----------------+------------------------+------------------------+ -| m3wrapretcheck | | | -+-----------------+------------------------+------------------------+ -| m3wrapfreearg | ``M3toC.Fre | Free resources that | -| | eSharedS(str, arg1);`` | were temporarily used | -| | | in the wrapper. Since | -| | | this step should never | -| | | be skipped, SWIG will | -| | | put it in the | -| | | ``FINALLY`` branch of | -| | | a ``TRY .. FINALLY`` | -| | | structure. | -+-----------------+------------------------+------------------------+ +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * + - Typemap + - Example + - Description + * + - m3wrapargvar + - ``$1: INTEGER := $1_name;`` + - Declaration of some variables needed for temporary results. + * + - m3wrapargconst + - ``$1 = "$1_name";`` + - Declaration of some constant, maybe for debug purposes. + * + - m3wrapargraw + - ``ORD($1_name)`` + - The expression that should be passed as argument to the raw Modula-3 interface function. + * + - m3wrapargdir + - ``out`` + - Referential arguments can be used for input, output, update. ??? + * + - m3wrapinmode + - ``READONLY`` + - One of Modula-3 parameter modes ``VALUE`` (or empty), ``VAR``, ``READONLY`` + * + - m3wrapinname + - + - New name of the input argument. + * + - m3wrapintype + - + - Modula-3 type of the input argument. + * + - m3wrapindefault + - + - Default value of the input argument. + * + - m3wrapinconv + - $1 := M3toC.SharedTtoS($1_name); + - Statement for converting the Modula-3 input value to C compliant value. + * + - m3wrapincheck + - IF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END; + - Check the integrity of the input value. + * + - m3wrapoutname + - + - Name of the ``RECORD`` field to be used for returning multiple values. + This applies to referential output arguments that shall be turned into return values. + * + - m3wrapouttype + - + - Type of the value that is returned instead of a referential output argument. + * + - m3wrapoutconv + - + - + * + - m3wrapoutcheck + - + - + * + - m3wrapretraw + - + - + * + - m3wrapretname + - + - + * + - m3wraprettype + - + - + * + - m3wrapretvar + - + - + * + - m3wrapretconv + - + - + * + - m3wrapretcheck + - + - + * + - m3wrapfreearg + - M3toC.FreeSharedS(str, arg1); + - Free resources that were temporarily used in the wrapper. + Since this step should never be skipped, SWIG will put it in the ``FINALLY`` branch of + a ``TRY .. FINALLY`` structure. Subranges, Enumerations, Sets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -570,62 +564,54 @@ More hints to the generator Features ~~~~~~~~~~~~~~~ -+--------------+--------------------------+--------------------------+ -| Feature | Example | Description | -+==============+==========================+==========================+ -| multiretval | ``% | Let the denoted function | -| | m3multiretval get_box;`` | return a ``RECORD`` | -| | or | rather than a plain | -| | ``%feature("modula3: | value. This ``RECORD`` | -| | multiretval") get_box;`` | contains all arguments | -| | | with "out" direction | -| | | including the return | -| | | value of the C function | -| | | (if there is one). If | -| | | more than one argument | -| | | is "out" then the | -| | | function **must** have | -| | | the ``multiretval`` | -| | | feature activated, but | -| | | it is explicitly | -| | | requested from the user | -| | | to prevent mistakes. | -+--------------+--------------------------+--------------------------+ -| constnumeric | ``%co | This feature can be used | -| | nstnumeric(12) twelve;`` | to tell Modula-3's | -| | or | back-end of SWIG the | -| | ``%feature("constn | value of an identifier. | -| | umeric", "12") twelve;`` | This is necessary in the | -| | | cases where it was | -| | | defined by a non-trivial | -| | | C expression. This | -| | | feature is used by the | -| | | ``-generateconst`` | -| | | `option <# | -| | | Modula3_commandline>`__. | -| | | In future it may be | -| | | generalized to other | -| | | kind of values such as | -| | | strings. | -+--------------+--------------------------+--------------------------+ +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * + - Feature + - Example + - Description + * + - multiretval + - %m3multiretval get_box; or + %feature("modula3:multiretval") + get_box; + - Let the denoted function return a ``RECORD`` rather than a plain value. + This ``RECORD`` contains all arguments with "out" direction including the return value of the C function + (if there is one). + If more than one argument is "out" then the function **must** have the ``multiretval`` feature activated, but it is explicitly requested from the user to prevent mistakes. + * + - constnumeric + - %constnumeric(12) twelve; + or + %feature("constnumeric", "12") twelve; + - This feature can be used to tell Modula-3's back-end of SWIG the value of an identifier. + This is necessary in the cases where it was defined by a non-trivial C expression. + This feature is used by the ``-generateconst`` `option <#Modula3_commandline>`__. + In future it may be generalized to other kind of values such as strings. Pragmas ~~~~~~~~~~~~~~ -+---------+----------------------------+----------------------------+ -| Pragma | Example | Description | -+=========+============================+============================+ -| unsafe | ``%pragma | Mark the raw interface | -| | (modula3) unsafe="true";`` | modules as ``UNSAFE``. | -| | | This will be necessary in | -| | | many cases. | -+---------+----------------------------+----------------------------+ -| library | ``%pragma(mo | Specifies the library name | -| | dula3) library="m3fftw";`` | for the wrapper library to | -| | | be created. It should be | -| | | distinct from the name of | -| | | the library to be wrapped. | -+---------+----------------------------+----------------------------+ +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * + - Pragma + - Example + - Description + * + - unsafe + - ``%pragma(modula3)unsafe="true";`` + - Mark the raw interface modules as ``UNSAFE``. + This will be necessary in many cases. + * + - library + - ``%pragma(modula3)library="m3fftw";`` + - Specifies the library name for the wrapper library to be created. + It should be distinct from the name of the library to be wrapped. Remarks ------------ diff --git a/SphinxDocs/source/Manual/Ocaml.rst b/SphinxDocs/source/Manual/Ocaml.rst index 0fae2895c..1affe847f 100644 --- a/SphinxDocs/source/Manual/Ocaml.rst +++ b/SphinxDocs/source/Manual/Ocaml.rst @@ -100,7 +100,7 @@ use is optional, but encouraged. The source file is included in the Lib/ocaml directory of the SWIG source distribution. You can checkout this file with ``"swig -ocaml -co swigp4.ml"``. You should compile the file with -:literal:`"ocamlc -I `camlp4 -where` -pp 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml"` +:literal:`"ocamlc -I \`camlp4 -where\` -pp 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml"` The basic principle of the module is to recognize certain non-caml expressions and convert them for use with C++ code as interfaced by @@ -109,64 +109,61 @@ interfaces, and probably isn't great to use with anything else. Here are the main rewriting rules: -Input - -Rewritten to - -| f'( ... ) as in -| atoi'("0") or -| \_exit'(0) - -| f(C_list [ ... ]) as in -| atoi (C_list [ C_string "0" ]) or -| \_exit (C_list [ C_int 0 ]) - -object -> method ( ... ) - -(invoke object) "method" (C_list [ ... ]) - -| object *'binop* argument as in -| a '+= b - -| (invoke object) "+=" argument as in -| (invoke a) "+=" b - -Note that because camlp4 always recognizes << and >>, they are replaced -by lsl and lsr in operator names. - -| *'unop* object as in -| '! a - -(invoke a) "!" C_void - -| **Smart pointer access like this** -| object '-> method ( args ) - -(invoke (invoke object "->" C_void)) - -| **Invoke syntax** -| object . '( ... ) - -(invoke object) "()" (C_list [ ... ]) - -| **Array syntax** -| object '[ 10 ] - -(invoke object) "[]" (C_int 10) - -| **Assignment syntax** -| let a = '10 and b = '"foo" and c = '1.0 and d = 'true - -let a = C_int 10 and b = C_string "foo" and c = C_double 1.0 and d = -C_bool true - -| **Cast syntax** -| let a = \_atoi '("2") as int -| let b = (getenv "PATH") to string -| This works for int, string, float, bool - -| let a = get_int (_atoi (C_string "2")) -| let b = C_string (getenv "PATH") +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + + * + - Input + - Rewritten_to + * + - f'( ... ) as in + - f(C_list [ ... ]) as in + * + - atoi'("0") or _exit'(0) + - atoi (C_list [ C_string "0" ]) or _exit_(C_list_[_C_int_0_]) + * + - object -> method ( ... ) + - (invoke object) "method" (C_list [ ...]) + * + - object 'binop argument as in a \'+=_b + - (invoke object) "+=" argument as in (invoke_a)_"+="_b + * + - Note that because camlp4 always recognizes << and >>, they are replaced by + lsl_and_lsr_in_operator_names. + - + * + - 'unop object as in !_a' + - (invoke a) "!" C_void + * + - Smart pointer access like this + object '->_method_(_args_) + - (invoke (invoke object "->" C_void)) + * + - Invoke syntax + object ._'(_..._) + - (invoke object) "()" (C_list [ ... ]) + * + - Array syntax + object '[_10_] + - (invoke object) "[]" (C_int 10) + * + - Assignment syntax + let a = '10 and b = '"foo" and + c = '1.0_and_d_=_'true + - let a = C_int 10 and b = C_string "foo" + and c = C_double 1.0 and d = C_bool + true + * + - Cast syntax + let a = _atoi '("2") as int + let b = (getenv "PATH") to + string + This works for int, string, + float, bool + - let a = get_int (_atoi (C_string "2")) + let b = C_string (getenv "PATH") Using your module ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -267,8 +264,8 @@ caml_ptr_val, the returned value is the result of a call to the object's "&" operator, taken as a pointer. You should only construct values using objective caml, or using the -functions caml_val_\* functions provided as static functions to a SWIG -ocaml module, as well as the caml_list_\* functions. These functions +functions caml_val_* functions provided as static functions to a SWIG +ocaml module, as well as the caml_list_* functions. These functions provide everything a typemap needs to produce values. In addition, value items pass through directly, but you must make your own type signature for a function that uses value in this way. @@ -286,28 +283,38 @@ the same as the C++ ones. You can introduce extra code into the output wherever you like with SWIG. These are the places you can introduce code: -+-----------------+---------------------------------------------------+ -| "header" | This code is inserted near the beginning of the C | -| | wrapper file, before any function definitions. | -+-----------------+---------------------------------------------------+ -| "wrapper" | This code is inserted in the function definition | -| | section. | -+-----------------+---------------------------------------------------+ -| "runtime" | This code is inserted near the end of the C | -| | wrapper file. | -+-----------------+---------------------------------------------------+ -| "mli" | This code is inserted into the caml interface | -| | file. Special signatures should be inserted here. | -+-----------------+---------------------------------------------------+ -| "ml" | This code is inserted in the caml code defining | -| | the interface to your C code. Special caml code, | -| | as well as any initialization which should run | -| | when the module is loaded may be inserted here. | -+-----------------+---------------------------------------------------+ -| "classtemplate" | The "classtemplate" place is special because it | -| | describes the output SWIG will generate for class | -| | definitions. | -+-----------------+---------------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + + * + - "header" + - This code is inserted near the beginning of the C + wrapper file, before any function definitions. + * + - "wrapper" + - This code is inserted in the function definition + section. + * + - "runtime" + - This code is inserted near the end of the C + wrapper file. + * + - "mli" + - This code is inserted into the caml interface + file. Special signatures should be inserted here. + * + - "ml" + - This code is inserted in the caml code defining + the interface to your C code. Special caml code, + as well as any initialization which should run + when the module is loaded may be inserted here. + * + - "classtemplate" + - The "classtemplate" place is special because it + describes the output SWIG will generate for class + definitions. Enums ~~~~~~~~~~~~ @@ -430,48 +437,50 @@ is called with a float array, and specified length. The actual length reported in the len argument is the length of the array passed from ocaml, making passing an array into this type of function convenient. -+-----------------------------------------------------------------------+ -| tarray.i | -+=======================================================================+ -| :: | -| | -| %module tarray | -| %{ | -| #include <stdio.h> | -| | -| void printfloats( float *tab, int len ) { | -| int i; | -| | -| for( i = 0; i < len; i++ ) { | -| printf( "%f ", tab[i] ); | -| } | -| | -| printf( "\n" ); | -| } | -| %} | -| | -| %typemap(in) (float *tab, int len) { | -| int i; | -| /* $*1_type */ | -| $2 = caml_array_len($input); | -| $1 = ($*1_type *)malloc( $2 * sizeof( float ) ); | -| for( i = 0; i < $2; i++ ) { | -| $1[i] = caml_double_val(caml_array_nth($input, i)); | -| } | -| } | -| | -| void printfloats( float *tab, int len ); | -+-----------------------------------------------------------------------+ -| Sample Run | -+-----------------------------------------------------------------------+ -| :: | -| | -| # open Tarray ;; | -| # _printfl | -| oats (C_array [| C_double 1.0 ; C_double 3.0 ; C_double 5.6666 |]) ;; | -| 1.000000 3.000000 5.666600 | -| - : Tarray.c_obj = C_void | -+-----------------------------------------------------------------------+ + ++---------------------------------------------------------------------------------+ +|tarray.i | ++=================================================================================+ +| :: | +| | +| %module tarray | +| %{ | +| #include <stdio.h> | +| | +| void printfloats( float *tab, int len ) { | +| int i; | +| | +| for( i = 0; i < len; i++ ) { | +| printf( "%f ", tab[i] ); | +| } | +| | +| printf( "\n" ); | +| } | +| %} | +| | +| %typemap(in) (float *tab, int len) { | +| int i; | +| /* $*1_type */ | +| $2 = caml_array_len($input); | +| $1 = ($*1_type *)malloc( $2 * sizeof( float ) ); | +| for( i = 0; i < $2; i++ ) { | +| $1[i] = caml_double_val(caml_array_nth($input, i)); | +| } | +| } | +| | +| void printfloats( float *tab, int len ); | ++---------------------------------------------------------------------------------+ +| Sample Run | ++---------------------------------------------------------------------------------+ +| :: | +| | +| # open Tarray ;; | +| # _printfloats (C_array [| C_double 1.0 ; C_double 3.0 ; C_double 5.6666 |]) | +| ;; | +| 1.000000 3.000000 5.666600 | +| - : Tarray.c_obj = C_void | +| | ++---------------------------------------------------------------------------------+ C++ Classes ~~~~~~~~~~~~~~~~~~ @@ -486,35 +495,47 @@ memory only once. In addition to any other operators an object might have, certain builtin ones are provided by SWIG: (all of these take no arguments (C_void)) -+---------------------+-----------------------------------------------+ -| "~" | Delete this object | -+---------------------+-----------------------------------------------+ -| "&" | Return an ordinary C_ptr value representing | -| | this object's address | -+---------------------+-----------------------------------------------+ -| "sizeof" | If enabled with ("sizeof"="1") on the module | -| | node, return the object's size in char. | -+---------------------+-----------------------------------------------+ -| ":methods" | Returns a list of strings containing the | -| | names of the methods this object contains | -+---------------------+-----------------------------------------------+ -| ":classof" | Returns the name of the class this object | -| | belongs to. | -+---------------------+-----------------------------------------------+ -| ":parents" | Returns a list of all direct parent classes | -| | which have been wrapped by SWIG. | -+---------------------+-----------------------------------------------+ -| "::[parent-class]" | Returns a view of the object as the indicated | -| | parent class. This is mainly used internally | -| | by the SWIG module, but may be useful to | -| | client programs. | -+---------------------+-----------------------------------------------+ -| "[member-variable]" | Each member variable is wrapped as a method | -| | with an optional parameter. Called with one | -| | argument, the member variable is set to the | -| | value of the argument. With zero arguments, | -| | the value is returned. | -+---------------------+-----------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - "~" + - Delete this object + * + - "&" + - Return an ordinary C_ptr value representing + this object's address + * + - "sizeof" + - If enabled with ("sizeof"="1") on the module + node, return the object's size in char. + * + - ":methods" + - Returns a list of strings containing the + names of the methods this object contains + * + - ":classof" + - Returns the name of the class this object + belongs to. + * + - ":parents" + - Returns a list of all direct parent classes + which have been wrapped by SWIG. + * + - "::[parent-class]" + - Returns a view of the object as the indicated + parent class. This is mainly used internally + by the SWIG module, but may be useful to + client programs. + * + - "[member-variable]" + - Each member variable is wrapped as a method + with an optional parameter. Called with one + argument, the member variable is set to the + value of the argument. With zero arguments, + the value is returned. + Note that this string belongs to the wrapper object, and not the underlying pointer, so using create_[x]_from_ptr alters the returned diff --git a/SphinxDocs/source/Manual/Octave.rst b/SphinxDocs/source/Manual/Octave.rst index 51077f9b6..e652dcc1e 100644 --- a/SphinxDocs/source/Manual/Octave.rst +++ b/SphinxDocs/source/Manual/Octave.rst @@ -1009,5 +1009,3 @@ that is accessed from Octave as, octave:1> my_det(rand(4)); ans = -0.18388 - -```` diff --git a/SphinxDocs/source/Manual/Pike.rst b/SphinxDocs/source/Manual/Pike.rst index eabb170e2..eac8d7434 100644 --- a/SphinxDocs/source/Manual/Pike.rst +++ b/SphinxDocs/source/Manual/Pike.rst @@ -3,7 +3,7 @@ SWIG and Pike This chapter describes SWIG support for Pike. As of this writing, the SWIG Pike module is still under development and is not considered ready -for prime time. The Pike module is being developed against the Pike +for prime time. The Pike module is being developed against the Pike 7.4.10 release and may not be compatible with previous versions of Pike. | This chapter covers most SWIG features, but certain low-level details diff --git a/SphinxDocs/source/Manual/Preface.rst b/SphinxDocs/source/Manual/Preface.rst index 4bb829500..7e805a869 100644 --- a/SphinxDocs/source/Manual/Preface.rst +++ b/SphinxDocs/source/Manual/Preface.rst @@ -1,4 +1,4 @@ -Preface +1 Preface ========= Introduction @@ -84,7 +84,7 @@ available. More information about this can be obtained at: :: - SWIG Bleeding Edge + SWIG_Bleeding_Edge Prerequisites ----------------- diff --git a/SphinxDocs/source/Manual/Preprocessor.rst b/SphinxDocs/source/Manual/Preprocessor.rst index 0b58f4b33..b028d23ec 100644 --- a/SphinxDocs/source/Manual/Preprocessor.rst +++ b/SphinxDocs/source/Manual/Preprocessor.rst @@ -156,14 +156,14 @@ More complex macros can be defined in the standard way. For example: The following operators can appear in macro definitions: - ``#x`` - Converts macro argument ``x`` to a string surrounded by double quotes - ("x"). + + Converts macro argument ``x`` to a string surrounded by double quotes ("x"). - ``x ## y`` + Concatenates x and y together to form ``xy``. - :literal:`\`x\`` - If ``x`` is a string surrounded by double quotes, do nothing. - Otherwise, turn into a string like ``#x``. This is a non-standard - SWIG extension. + + If ``x`` is a string surrounded by double quotes, do nothing. Otherwise, turn into a string like ``#x``. This is a non-standard SWIG extension. SWIG Macros ---------------- @@ -197,7 +197,7 @@ SWIG provides an enhanced macro capability with the ``%define`` and The primary purpose of ``%define`` is to define large macros of code. Unlike normal C preprocessor macros, it is not necessary to terminate -each line with a continuation character (\)--the macro definition +each line with a continuation character (``\``)--the macro definition extends to the first occurrence of ``%enddef``. Furthermore, when such macros are expanded, they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor directives except for diff --git a/SphinxDocs/source/Manual/Python.rst b/SphinxDocs/source/Manual/Python.rst index 91aa195ad..36a51f25f 100644 --- a/SphinxDocs/source/Manual/Python.rst +++ b/SphinxDocs/source/Manual/Python.rst @@ -684,51 +684,90 @@ for the Python module. They can also be seen by using: swig -python -help -+---------------------------+ -| Python specific options | -+===========================+ -| -builtin | -+---------------------------+ -| -castmode | -+---------------------------+ -| -debug-doxygen-parser | -+---------------------------+ -| -debug-doxygen-translator | -+---------------------------+ -| -dirvtable | -+---------------------------+ -| -doxygen | -+---------------------------+ -| -extranative | -+---------------------------+ -| -fastproxy | -+---------------------------+ -| -globals <name> | -+---------------------------+ -| -interface <mod> | -+---------------------------+ -| -keyword | -+---------------------------+ -| -nofastunpack | -+---------------------------+ -| -noh | -+---------------------------+ -| -noproxy | -+---------------------------+ -| -nortti | -+---------------------------+ -| -nothreads | -+---------------------------+ -| -olddefs | -+---------------------------+ -| -py3 | -+---------------------------+ -| -relativeimport | -+---------------------------+ -| -threads | -+---------------------------+ -| -O | -+---------------------------+ + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - Python specific options + - + * + - -builtin + - Create Python built-in types rather than proxy + classes, for better performance + * + - -castmode + - Enable the casting mode, which allows implicit cast + between types in Python + * + - -debug-doxygen-parser + - Display doxygen parser module debugging information + * + - -debug-doxygen-translator + - Display doxygen translator module debugging + information + * + - -dirvtable + - Generate a pseudo virtual table for directors for + faster dispatch + * + - -doxygen + - Convert C++ doxygen comments to pydoc comments in + proxy classes + * + - -extranative + - Return extra native wrappers for C++ std containers + wherever possible + * + - -fastproxy + - Use fast proxy mechanism for member methods + * + - -globals <name> + - Set <name> used to access C global variable ( + default:'cvar') + * + - -interface <mod> + - Set low-level C/C++ module name to <mod> (default: + module name prefixed by '_') + * + - -keyword + - Use keyword arguments + * + - -nofastunpack + - Use traditional UnpackTuple method to parse the + argument functions + * + - -noh + - Don't generate the output header file + * + - -noproxy + - Don't generate proxy classes + * + - -nortti + - Disable the use of the native C++ RTTI with directors + * + - -nothreads + - Disable thread support for the entire interface + * + - -olddefs + - Keep the old method definitions when using -fastproxy + * + - -py3 + - Generate code with Python 3 specific features and + syntax + * + - -relativeimport + - Use relative Python imports + * + - -threads + - Add thread support for all the interface + * + - -O + - Enable the following optimization options: - + fastdispatch -fastproxy -fvirtual + + Many of these options are covered later on and their use should become clearer by the time you have finished reading this section on SWIG and @@ -4935,7 +4974,7 @@ readability of the ``%module`` directive by using a macro. For example: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As alluded to above SWIG will generate all the function and method proxy -wrappers with just "*args" (or "*args, \**kwargs" if the -keyword option +wrappers with just "``*args``" (or "``*args, **kwargs``" if the -keyword option is used) for a parameter list and will then sort out the individual parameters in the C wrapper code. This is nice and simple for the wrapper code, but makes it difficult to be programmer and tool friendly @@ -5112,7 +5151,7 @@ any arbitrary descriptive text to a node in the parse tree with the docstring associated with classes, function or methods are output. If an item already has an autodoc string then it is combined with the docstring and they are output together. If the docstring is all on a -single line then it is output like this:: +single line then it is output like this: .. container:: targetlang @@ -5526,7 +5565,9 @@ Python 3.3 introduced `PEP <https://www.python.org/dev/peps/pep-0420/>`__ which implements implicit namespace packages. In a nutshell, implicit namespace packages remove the requirement of an \__init__.py file and allow packages to be -split across multiple PATH elements. For example: +split across multiple PATH elements. + +For example: .. container:: diagram @@ -6158,7 +6199,7 @@ completely decoded as UTF-8: %} -Note that "\xe9" is an invalid UTF-8 encoding, but "\xc3\xb6" is valid. +Note that "``\xe9``" is an invalid UTF-8 encoding, but "``\xc3\xb6``" is valid. When this method is called from Python 3, the return value is the following text string: @@ -6470,19 +6511,31 @@ For the curious about performance, here are some numbers for the profiletest.i test, which is used to check the speed of the wrapped code: -+---------------------+----------------------+----------------------+ -| Thread Mode | Execution Time (sec) | Comment | -+=====================+======================+======================+ -| Single Threaded | 9.6 | no "-threads" option | -| | | given | -+---------------------+----------------------+----------------------+ -| Fully Multithreaded | 15.5 | "-threads" option = | -| | | 'allow' + 'block' | -+---------------------+----------------------+----------------------+ -| No Thread block | 12.2 | only 'allow' | -+---------------------+----------------------+----------------------+ -| No Thread Allow | 13.6 | only block' | -+---------------------+----------------------+----------------------+ +.. list-table:: + :widths: 25 25 25 + :header-rows: 1 + + * + - Thread Mode + - Execution Time (sec) + - Comment + * + - Single Threaded + - 9.6 + - no "-threads" option given + * + - Fully Multithreaded + - 15.5 + - "-threads" option = 'allow' + 'block' + * + - No Thread block + - 12.2 + - only 'allow' + * + - No Thread Allow + - 13.6 + - only block' + Fully threaded code decreases the wrapping performance by around 60%. If that is important to your application, you can tune each method using diff --git a/SphinxDocs/source/Manual/Ruby.rst b/SphinxDocs/source/Manual/Ruby.rst index 98823d14b..c51d13151 100644 --- a/SphinxDocs/source/Manual/Ruby.rst +++ b/SphinxDocs/source/Manual/Ruby.rst @@ -2094,124 +2094,56 @@ The first way is to use ``SWIG_exception(int code, const char *msg)``. The following table shows the mappings from SWIG error codes to Ruby exceptions: -.. container:: diagram - - .. container:: - - SWIG_MemoryError - -.. container:: - - rb_eNoMemError - -.. container:: - - SWIG_IOError - -.. container:: - - rb_eIOError - -.. container:: - - SWIG_RuntimeError - -.. container:: - - rb_eRuntimeError - -.. container:: - - SWIG_IndexError - -.. container:: - - rb_eIndexError - -.. container:: - - SWIG_TypeError - -.. container:: - - rb_eTypeError - -.. container:: - - SWIG_DivisionByZero - -.. container:: - - rb_eZeroDivError - -.. container:: - - SWIG_OverflowError - -.. container:: - - rb_eRangeError - -.. container:: - - SWIG_SyntaxError - -.. container:: - - rb_eSyntaxError - -.. container:: - - SWIG_ValueError - -.. container:: - - rb_eArgError - -.. container:: - - SWIG_SystemError - -.. container:: - - rb_eFatal - -.. container:: - - SWIG_AttributeError - -.. container:: - - rb_eRuntimeError - -.. container:: - - SWIG_NullReferenceError - -.. container:: - - rb_eNullReferenceError\* - -.. container:: - - SWIG_ObjectPreviouslyDeletedError - -.. container:: - - rb_eObjectPreviouslyDeleted\* - -.. container:: - - SWIG_UnknownError - -.. container:: - - rb_eRuntimeError - -.. container:: - - \* These error classes are created by SWIG and are not built-in Ruby - exception classes +.. list-table:: + :widths: 25 25 + :header-rows: 0 + + * + - SWIG_MemoryError + - rb_eNoMemError + * + - SWIG_IOError + - rb_eIOError + * + - SWIG_RuntimeError + - rb_eRuntimeError + * + - SWIG_IndexError + - rb_eIndexError + * + - SWIG_TypeError + - rb_eTypeError + * + - SWIG_DivisionByZero + - rb_eZeroDivError + * + - SWIG_OverflowError + - rb_eRangeError + * + - SWIG_SyntaxError + - rb_eSyntaxError + * + - SWIG_ValueError + - rb_eArgError + * + - SWIG_SystemError + - rb_eFatal + * + - SWIG_AttributeError + - rb_eRuntimeError + * + - SWIG_NullReferenceError + - rb_eNullReferenceError* + * + - SWIG_ObjectPreviouslyDeletedError + - rb_eObjectPreviouslyDeleted* + * + - SWIG_UnknownError + - rb_eRuntimeError + * + - \* These error classes are created by SWIG and are not built-in Ruby + exception_classes + - The second way to raise errors is to use ``SWIG_Raise(obj, type, desc)``. Obj is a C++ instance of an exception @@ -2678,21 +2610,28 @@ Converts Ruby objects to input function arguments. For example: The following special variables are available: -.. container:: diagram - - +----------+------------------------------------------------------------------+ - | $input | Input object holding value to be converted. | - +----------+------------------------------------------------------------------+ - | $symname | Name of function/method being wrapped | - +----------+------------------------------------------------------------------+ - | $1...n | Argument being sent to the function | - +----------+------------------------------------------------------------------+ - | $1_name | Name of the argument (if provided) | - +----------+------------------------------------------------------------------+ - | $1_type | The actual C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ - | $1_ltype | The assignable version of the C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - $input + - Input object holding value to be converted. + * + - $symname + - Name of function/method being wrapped + * + - $1...n + - Argument being sent to the function + * + - $1_name + - Name of the argument (if provided) + * + - $1_type + - The actual C datatype matched by the typemap. + * + - $1_ltype + - The assignable version of the C datatype matched by the typemap. This is probably the most commonly redefined typemap because it can be used to implement customized conversions. @@ -2750,21 +2689,28 @@ Converts return value of a C function to a Ruby object. The following special variables are available. -.. container:: diagram - - +----------+------------------------------------------------------------------+ - | $result | Result object returned to target language. | - +----------+------------------------------------------------------------------+ - | $symname | Name of function/method being wrapped | - +----------+------------------------------------------------------------------+ - | $1...n | Argument being wrapped | - +----------+------------------------------------------------------------------+ - | $1_name | Name of the argument (if provided) | - +----------+------------------------------------------------------------------+ - | $1_type | The actual C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ - | $1_ltype | The assignable version of the C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - $result + - Result object returned to target language. + * + - $symname + - Name of function/method being wrapped + * + - $1...n + - Argument being wrapped + * + - $1_name + - Name of the argument (if provided) + * + - $1_type + - The actual C datatype matched by the typemap. + * + - $1_ltype + - The assignable version of the C datatype matched by the typemap. "arginit" typemap ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3017,23 +2963,31 @@ similar to the "out" typemap. The following special variables are available. -.. container:: diagram - - +----------+------------------------------------------------------------------+ - | $result | Result object returned to target language. | - +----------+------------------------------------------------------------------+ - | $symname | Name of function/method being wrapped | - +----------+------------------------------------------------------------------+ - | $1...n | Argument being wrapped | - +----------+------------------------------------------------------------------+ - | $1_name | Name of the argument (if provided) | - +----------+------------------------------------------------------------------+ - | $1_type | The actual C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ - | $1_ltype | The assignable version of the C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ - | this | C++ this, referring to the class itself. | - +----------+------------------------------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - $result + - Result object returned to target language. + * + - $symname + - Name of function/method being wrapped + * + - $1...n + - Argument being wrapped + * + - $1_name + - Name of the argument (if provided) + * + - $1_type + - The actual C datatype matched by the typemap. + * + - $1_ltype + - The assignable version of the C datatype matched by the typemap. + * + - this + - C++ this, referring to the class itself. directorout typemap ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3052,23 +3006,31 @@ to the "in" typemap. The following special variables are available: -.. container:: diagram - - +----------+------------------------------------------------------------------+ - | $input | Ruby object being sent to the function | - +----------+------------------------------------------------------------------+ - | $symname | Name of function/method being wrapped | - +----------+------------------------------------------------------------------+ - | $1...n | Argument being sent to the function | - +----------+------------------------------------------------------------------+ - | $1_name | Name of the argument (if provided) | - +----------+------------------------------------------------------------------+ - | $1_type | The actual C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ - | $1_ltype | The assignable version of the C datatype matched by the typemap. | - +----------+------------------------------------------------------------------+ - | this | C++ this, referring to the class itself. | - +----------+------------------------------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - $input + - Ruby object being sent to the function + * + - $symname + - Name of function/method being wrapped + * + - $1...n + - Argument being sent to the function + * + - $1_name + - Name of the argument (if provided) + * + - $1_type + - The actual C datatype matched by the typemap. + * + - $1_ltype + - The assignable version of the C datatype matched by the typemap. + * + - this + - C++ this, referring to the class itself. Currently, the directorout nor the out typemap support the option ``numoutputs``, but the Ruby module provides that functionality through @@ -3201,29 +3163,34 @@ languages. C Datatypes to Ruby Objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. container:: diagram - - +-----------------------+-----------------------+-----------------------+ - | **RUBY** | **SWIG** | | - +-----------------------+-----------------------+-----------------------+ - | INT2NUM(long or int) | SWIG_From_int(int x) | int to Fixnum or | - | | | Bignum | - +-----------------------+-----------------------+-----------------------+ - | INT2FIX(long or int) | | int to Fixnum (faster | - | | | than INT2NUM) | - +-----------------------+-----------------------+-----------------------+ - | CHR2FIX(char) | SWIG_From_char(char | char to Fixnum | - | | x) | | - +-----------------------+-----------------------+-----------------------+ - | rb_str_new2(char*) | SWIG_From | char\* to String | - | | CharPtrAndSize(char*, | | - | | size_t) | | - +-----------------------+-----------------------+-----------------------+ - | rb_float_new(double) | SWIG | float/double to Float | - | | _From_double(double), | | - | | S | | - | | WIG_From_float(float) | | - +-----------------------+-----------------------+-----------------------+ +.. list-table:: + :widths: 25 25 25 + :header-rows: 1 + + * + - **RUBY** + - **SWIG** + - + * + - INT2NUM(long or int) + - SWIG_From_int(int x) + - int to Fixnum or Bignum + * + - INT2FIX(long or int) + - + - int to Fixnum (faster than INT2NUM) + * + - CHR2FIX(char) + - SWIG_From_char(char x) + - char to Fixnum + * + - rb_str_new2(char*) + - SWIG_FromCharPtrAndSize(char*,size_t) + - char\* to String + * + - rb_float_new(double) + - SWIG_From_double(double), SWIG_From_float(float) + - float/double to Float Ruby Objects to C Datatypes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3244,40 +3211,45 @@ typemaps that report more helpful error messages, like: } } -.. container:: diagram - - +----------------------------------+----------------------------------+ - | int NUM2INT(Numeric) | SWIG_AsVal_int(VALUE, int*) | - +----------------------------------+----------------------------------+ - | int FIX2INT(Numeric) | SWIG_AsVal_int(VALUE, int*) | - +----------------------------------+----------------------------------+ - | unsigned int NUM2UINT(Numeric) | S | - | | WIG_AsVal_unsigned_SS_int(VALUE, | - | | int*) | - +----------------------------------+----------------------------------+ - | unsigned int FIX2UINT(Numeric) | S | - | | WIG_AsVal_unsigned_SS_int(VALUE, | - | | int*) | - +----------------------------------+----------------------------------+ - | long NUM2LONG(Numeric) | SWIG_AsVal_long(VALUE, long*) | - +----------------------------------+----------------------------------+ - | long FIX2LONG(Numeric) | SWIG_AsVal_long(VALUE, long*) | - +----------------------------------+----------------------------------+ - | unsigned long FIX2ULONG(Numeric) | SW | - | | IG_AsVal_unsigned_SS_long(VALUE, | - | | unsigned long*) | - +----------------------------------+----------------------------------+ - | char NUM2CHR(Numeric or String) | SWIG_AsVal_char(VALUE, int*) | - +----------------------------------+----------------------------------+ - | char \* StringValuePtr(String) | SWIG_AsCharPtrAndSize(VALUE, | - | | char*, size_t, int\* alloc) | - +----------------------------------+----------------------------------+ - | char \* rb_str2cstr(String, | | - | int*length) | | - +----------------------------------+----------------------------------+ - | double NUM2DBL(Numeric) | (double) SWIG_AsVal_int(VALUE) | - | | or similar | - +----------------------------------+----------------------------------+ +.. list-table:: + :widths: 25 25 + :header-rows: 0 + + * + - int NUM2INT(Numeric) + - SWIG_AsVal_int(VALUE, int*) + * + - int FIX2INT(Numeric) + - SWIG_AsVal_int(VALUE, int*) + * + - unsigned int NUM2UINT(Numeric) + - SWIG_AsVal_unsigned_SS_int(VALUE, int*) + * + - unsigned int FIX2UINT(Numeric) + - SWIG_AsVal_unsigned_SS_int(VALUE, int*) + * + - long NUM2LONG(Numeric) + - SWIG_AsVal_long(VALUE, long*) + * + - long FIX2LONG(Numeric) + - SWIG_AsVal_long(VALUE, long*) + * + - unsigned long FIX2ULONG(Numeric) + - SWIG_AsVal_unsigned_SS_long(VALUE, unsigned long*) + * + - char NUM2CHR(Numeric or String) + - SWIG_AsVal_char(VALUE, int*) + * + - char \* StringValuePtr(String) + - SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int\* alloc) + * + - char \* rb_str2cstr(String,int*length) + - + * + - double NUM2DBL(Numeric) + - (double) SWIG_AsVal_int(VALUE) + or similar + Macros for VALUE ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -4123,48 +4095,44 @@ from Python): .. container:: code diagram ======================= ======== - **General** - \__repr_\_ inspect - \__str_\_ to_s - \__cmp_\_ <=> - \__hash_\_ hash - \__nonzero_\_ nonzero? - \ - **Callable** - \__call_\_ call - \ - **Collection** - \__len_\_ length - \__getitem_\_ [] - \__setitem_\_ []= - \ - **Numeric** - \__add_\_ + - \__sub_\_ - - \__mul_\_ \* - \__div_\_ / - \__mod_\_ % - \__divmod_\_ divmod - \__pow_\_ \*\* - \__lshift_\_ << - \__rshift_\_ >> - \__and_\_ & - \__xor_\_ ^ - \__or_\_ \| - \__neg_\_ -@ - \__pos_\_ +@ - \__abs_\_ abs - \__invert_\_ ~ - \__int_\_ to_i - \__float_\_ to_f - \__coerce_\_ coerce - \ - **Additions in 1.3.13** - \__lt_\_ < - \__le_\_ <= - \__eq_\_ == - \__gt_\_ > - \__ge_\_ >= + **General** + \__repr_\_ inspect + \__str_\_ to_s + \__cmp_\_ <=> + \__hash_\_ hash + \__nonzero_\_ nonzero? + **Callable** \ + \__call_\_ call + **Collection** \ + \__len_\_ length + \__getitem_\_ [] + \__setitem_\_ []= + **Numeric** \ + \__add_\_ \+ + \__sub_\_ \- + \__mul_\_ \* + \__div_\_ / + \__mod_\_ % + \__divmod_\_ divmod + \__pow_\_ \*\* + \__lshift_\_ << + \__rshift_\_ >> + \__and_\_ & + \__xor_\_ ^ + \__or_\_ \| + \__neg_\_ -@ + \__pos_\_ +@ + \__abs_\_ abs + \__invert_\_ ~ + \__int_\_ to_i + \__float_\_ to_f + \__coerce_\_ coerce + **Additions in 1.3.13** \ + \__lt_\_ < + \__le_\_ <= + \__eq_\_ == + \__gt_\_ > + \__ge_\_ >= ======================= ======== Note that although SWIG supports the ``__eq__`` magic method name for diff --git a/SphinxDocs/source/Manual/SWIG.rst b/SphinxDocs/source/Manual/SWIG.rst index 697c71cbb..4d4f5d032 100644 --- a/SphinxDocs/source/Manual/SWIG.rst +++ b/SphinxDocs/source/Manual/SWIG.rst @@ -1,4 +1,4 @@ -SWIG Basics +5 SWIG Basics ============= This chapter describes the basic operation of SWIG, the structure of its @@ -1675,149 +1675,112 @@ example of applying each one. Note that some of them have two names, a shorter one and a more descriptive one, but the two functions are otherwise equivalent: -Function - -Returns - -Example (in/out) - -``uppercase`` or ``upper`` - -Upper case version of the string. - -``Print`` - -``PRINT`` - -``lowercase`` or ``lower`` - -Lower case version of the string. - -``Print`` - -``print`` - -``title`` - -String with first letter capitalized and the rest in lower case. - -``print`` - -``Print`` - -``firstuppercase`` - -String with the first letter capitalized and the rest unchanged. - -``printIt`` - -``PrintIt`` - -``firstlowercase`` - -String with the first letter in lower case and the rest unchanged. - -``PrintIt`` - -``printIt`` - -``camelcase`` or ``ctitle`` - -String with capitalized first letter and any letter following an -underscore (which are removed in the process) and rest in lower case. - -``print_it`` - -``PrintIt`` - -``lowercamelcase`` or ``lctitle`` - -String with every letter following an underscore (which is removed in -the process) capitalized and rest, including the first letter, in lower -case. - -``print_it`` - -``printIt`` - -``undercase`` or ``utitle`` - -Lower case string with underscores inserted before every upper case -letter in the original string and any number not at the end of string. -Logically, this is the reverse of ``camelcase``. - -``PrintIt`` - -``print_it`` - -``schemify`` - -String with all underscores replaced with dashes, resulting in more -Lispers/Schemers-pleasing name. - -``print_it`` - -``print-it`` - -``strip:[prefix]`` - -String without the given prefix or the original string if it doesn't -start with this prefix. Note that square brackets should be used -literally, e.g. ``%rename("strip:[wx]")`` - -``wxPrint`` - -``Print`` - -``rstrip:[suffix]`` - -String without the given suffix or the original string if it doesn't end -with this suffix. Note that square brackets should be used literally, -e.g. ``%rename("rstrip:[Cls]")`` - -``PrintCls`` - -``Print`` - -``regex:/pattern/subst/`` - -String after (Perl-like) regex substitution operation. This function -allows to apply arbitrary regular expressions to the identifier names. -The *pattern* part is a regular expression in Perl syntax (as supported -by the `Perl Compatible Regular Expressions -(PCRE) <http://www.pcre.org/>`__) library and the *subst* string can -contain back-references of the form ``\N`` where ``N`` is a digit from 0 -to 9, or one of the following escape sequences: ``\l``, ``\L``, ``\u``, -``\U`` or ``\E``. The back-references are replaced with the contents of -the corresponding capture group while the escape sequences perform the -case conversion in the substitution string: ``\l`` and ``\L`` convert to -the lower case, while ``\u`` and ``\U`` convert to the upper case. The -difference between the elements of each pair is that ``\l`` and ``\u`` -change the case of the next character only, while ``\L`` and ``\U`` do -it for all the remaining characters or until ``\E`` is encountered. -Finally please notice that backslashes need to be escaped in C strings, -so in practice ``"\\"`` must be used in all these escape sequences. For -example, to remove any alphabetic prefix before an underscore and -capitalize the remaining part you could use the following directive: -``%rename("regex:/(\\w+)_(.*)/\\u\\2/")`` - -``prefix_print`` - -``Print`` - -``command:cmd`` - -Output of an external command ``cmd`` with the string passed to it as -input. Notice that this function is extremely slow compared to all the -other ones as it involves spawning a separate process and using it for -many declarations is not recommended. The *cmd* is not enclosed in -square brackets but must be terminated with a triple ``'<'`` sign, e.g. -``%rename("command:tr -d aeiou <<<")`` (nonsensical example removing all -vowels) - -``Print`` - -``Prnt`` +.. list-table:: \ + :widths: 25 25 25 25 + :header-rows: 1 + + * + - Function + - Returns + - Example (in/out) + - \ + * + - uppercase or upper + - Upper case version of the string. + - Print + - PRINT + * + - lowercase or lower + - Lower case version of the string. + - Print + - print + * + - title + - String_with_first_letter_capitalized_and_the_rest_in_lower_case. + - print + - Print + * + - firstuppercase + - String_with_the_first_letter_capitalized_and_the_rest_unchanged. + - printIt + - PrintIt + * + - firstlowercase + - String_with_the_first_letter_in_lower_case_and_the_rest_unchanged. + - PrintIt + - printIt + * + - camelcase or ctitle + - String with capitalized first letter and any letter following an + underscore_(which_are_removed_in_the_process)_and_rest_in_lower_case. + - print_it + - PrintIt + * + - lowercamelcase or lctitle + - String with every letter following an underscore (which is removed in + the process) capitalized and rest, including the first letter, in lower + case. + - print_it + - printIt + * + - undercase or utitle + - Lower case string with underscores inserted before every upper case + letter in the original string and any number not at the end of string. + Logically,_this_is_the_reverse_of_camelcase. + - PrintIt + - print_it + * + - schemify + - String with all underscores replaced with dashes, resulting in more + Lispers/Schemers-pleasing_name. + - print_it + - print-it + * + - strip:[prefix] + - String without the given prefix or the original string if it doesn't + start with this prefix. Note that square brackets should be used + literally,_e.g._%rename("strip:[wx]") + - wxPrint + - Print + * + - rstrip:[suffix] + - String without the given suffix or the original string if it doesn't + end with this suffix. Note that square brackets should be used + literally,_e.g._%rename("rstrip:[Cls]") + - PrintCls + - Print + * + - regex:/pattern/subst/ + - String after (Perl-like) regex substitution operation. This function + allows to apply arbitrary regular expressions to the identifier names. + The pattern part is a regular expression in Perl syntax (as supported + by the Perl_Compatible_Regular_Expressions_(PCRE)) library and the + subst string can contain back-references of the form \\N where N is a + digit from 0 to 9, or one of the following escape sequences: \\l, \\L, + \\u, \\U or \\E. The back-references are replaced with the contents of + the corresponding capture group while the escape sequences perform the + case conversion in the substitution string: \\l and \\L convert to the + lower case, while \\u and \\U convert to the upper case. The difference + between the elements of each pair is that \\l and \\u change the case of + the next character only, while \\L and \\U do it for all the remaining + characters or until \\E is encountered. Finally please notice that + backslashes need to be escaped in C strings, so in practice "\\\\" must + be used in all these escape sequences. For example, to remove any + alphabetic prefix before an underscore and capitalize the remaining part + you could use the_following_directive:\ + _%rename("regex:/(\\\\w+)_(.*)/\\\\u\\\\2/") + - prefix_print + - Print + * + - command:cmd + - Output of an external command cmd with the string passed to it as + input. Notice that this function is extremely slow compared to all the + other ones as it involves spawning a separate process and using it for + many declarations is not recommended. The cmd is not enclosed in square + brackets but must be terminated with a triple '<' sign, e.g. %rename + ("command:tr -d aeiou_<<<")_(nonsensical_example_removing_all_vowels) + - Print + - Prnt The most general function of all of the above ones (not counting ``command`` which is even more powerful in principle but which should @@ -2947,21 +2910,21 @@ When SWIG creates its output C/C++ file, it is broken up into five sections corresponding to runtime code, headers, wrapper functions, and module initialization code (in that order). -- **Begin section**. - A placeholder for users to put code at the beginning of the C/C++ - wrapper file. This is most often used to define preprocessor macros - that are used in later sections. -- **Runtime code**. - This code is internal to SWIG and is used to include type-checking - and other support functions that are used by the rest of the module. -- **Header section**. - This is user-defined support code that has been included by the - ``%{ ... %}`` directive. Usually this consists of header files and - other helper functions. -- **Wrapper code**. - These are the wrappers generated automatically by SWIG. -- **Module initialization**. - The function generated by SWIG to initialize the module upon loading. +- | **Begin section**. + | A placeholder for users to put code at the beginning of the C/C++ + wrapper file. This is most often used to define preprocessor macros + that are used in later sections. +- | **Runtime code**. + | This code is internal to SWIG and is used to include type-checking + and other support functions that are used by the rest of the module. +- | **Header section**. + | This is user-defined support code that has been included by the + ``%{ ... %}`` directive. Usually this consists of header files and + other helper functions. +- | **Wrapper code**. + | These are the wrappers generated automatically by SWIG. +- | **Module initialization**. + | The function generated by SWIG to initialize the module upon loading. Code insertion blocks ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/SphinxDocs/source/Manual/SWIGPlus.rst b/SphinxDocs/source/Manual/SWIGPlus.rst index d87942fc0..6fd6469d6 100644 --- a/SphinxDocs/source/Manual/SWIGPlus.rst +++ b/SphinxDocs/source/Manual/SWIGPlus.rst @@ -1,12 +1,14 @@ SWIG and C++ -============== +============ 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 :doc:`CPlusPlus11` , -:doc:`CPlusPlus14` and :doc:`CPlusPlus17` chapters. :doc:`CPlusPlus20` -chapters. As a prerequisite, you -should first read the chapter :doc:`SWIG` to see +additions to the original C++ standard, please read the `SWIG and +C++11 <CPlusPlus11.html#CPlusPlus11>`__, `SWIG and +C++14 <CPlusPlus14.html#CPlusPlus14>`__ and `SWIG and +C++17 <CPlusPlus17.html#CPlusPlus17>`__ chapters. `SWIG and +C++20 <CPlusPlus20.html#CPlusPlus20>`__ chapters. As a prerequisite, you +should first read the chapter `SWIG Basics <SWIG.html#SWIG>`__ to see how SWIG wraps ISO C. Support for C++ builds upon ISO C wrapping and that material will be useful in understanding this chapter. @@ -2515,8 +2517,6 @@ further details. used to extend a structure with more than just methods, a more suitable directive name has been chosen. -.. _cpp_templates: - Templates -------------- diff --git a/SphinxDocs/source/Manual/Scilab.rst b/SphinxDocs/source/Manual/Scilab.rst index a02b6c3e5..49b158ae7 100644 --- a/SphinxDocs/source/Manual/Scilab.rst +++ b/SphinxDocs/source/Manual/Scilab.rst @@ -177,33 +177,43 @@ Scilab command line options The following table lists the Scilab specific command line options in addition to the generic SWIG options: -+----------------------------------+----------------------------------+ -| ``-builder`` | Generate the Scilab builder | -| | script | -+----------------------------------+----------------------------------+ -| ``-buildercflags <cflags>`` | Add <cflags> to the builder | -| | compiler flags | -+----------------------------------+----------------------------------+ -| ``-builderldflags <ldflags>`` | Add <ldlags> to the builder | -| | linker flags | -+----------------------------------+----------------------------------+ -| ``-buildersources <files>`` | Add the (comma separated) files | -| | <files> to the builder sources | -+----------------------------------+----------------------------------+ -| `` | Set the build verbosity level to | -| -builderverbositylevel <level>`` | <level> (default 0: off, 2: | -| | high) | -+----------------------------------+----------------------------------+ -| ``-builderflagscript <file>`` | Use the Scilab script <file> to | -| | configure the compiler and | -| | linker flags | -+----------------------------------+----------------------------------+ -| ``-gatewayxml <gateway_id>`` | Generate the gateway XML with | -| | the given <gateway_id> | -+----------------------------------+----------------------------------+ -| ``-targetversion`` | Generate for Scilab target | -| | (major) version | -+----------------------------------+----------------------------------+ +.. list-table:: + :widths: 25 25 + :header-rows: 1 + + * + - ``-builder`` + - Generate the Scilab builder + script + * + - ``-buildercflags <cflags>`` + - Add <cflags> to the builder + compiler flags + * + - ``-builderldflags <ldflags>`` + - Add <ldlags> to the builder + linker flags + * + - ``-buildersources <files>`` + - Add the (comma separated) files + <files> to the builder sources + * + - ``-builderverbositylevel <level>`` + - Set the build verbosity level to + <level> (default 0: off, 2:high) + * + - ``-builderflagscript <file>`` + - Use the Scilab script <file> to + configure the compiler and + linker flags + * + - ``-gatewayxml <gateway_id>`` + - Generate the gateway XML with + the given <gateway_id> + * + - ``-targetversion`` + - Generate for Scilab target + (major) version These options can be displayed with: diff --git a/SphinxDocs/source/Manual/Typemaps.rst b/SphinxDocs/source/Manual/Typemaps.rst index 55a049380..2a4bd03fa 100644 --- a/SphinxDocs/source/Manual/Typemaps.rst +++ b/SphinxDocs/source/Manual/Typemaps.rst @@ -1840,55 +1840,73 @@ is by no means a complete list as some target languages have additional special variables which are documented in the language specific chapters. -+------------------------+--------------------------------------------+ -| Variable | Meaning | -+========================+============================================+ -| $\ *n* | A C local variable corresponding to type | -| | *n* in the typemap pattern. | -+------------------------+--------------------------------------------+ -| $argnum | Argument number. Only available in | -| | typemaps related to argument conversion | -+------------------------+--------------------------------------------+ -| $\ *n*\ \_name | Argument name | -+------------------------+--------------------------------------------+ -| $\ *n*\ \_type | Real C datatype of type *n*. | -+------------------------+--------------------------------------------+ -| $\ *n*\ \_ltype | ltype of type *n* | -+------------------------+--------------------------------------------+ -| $\ *n*\ \_mangle | Mangled form of type *n*. For example | -| | ``_p_Foo`` | -+------------------------+--------------------------------------------+ -| $\ *n*\ \_descriptor | Type descriptor structure for type *n*. | -| | For example ``SWIGTYPE_p_Foo``. This is | -| | primarily used when interacting with the | -| | run-time type checker (described later). | -+------------------------+--------------------------------------------+ -| $\*\ *n*\ \_type | Real C datatype of type *n* with one | -| | pointer removed. | -+------------------------+--------------------------------------------+ -| $\*\ *n*\ \_ltype | ltype of type *n* with one pointer | -| | removed. | -+------------------------+--------------------------------------------+ -| $\*\ *n*\ \_mangle | Mangled form of type *n* with one pointer | -| | removed. | -+------------------------+--------------------------------------------+ -| $\*\ *n*\ \_descriptor | Type descriptor structure for type *n* | -| | with one pointer removed. | -+------------------------+--------------------------------------------+ -| $&\ *n*\ \_type | Real C datatype of type *n* with one | -| | pointer added. | -+------------------------+--------------------------------------------+ -| $&\ *n*\ \_ltype | ltype of type *n* with one pointer added. | -+------------------------+--------------------------------------------+ -| $&\ *n*\ \_mangle | Mangled form of type *n* with one pointer | -| | added. | -+------------------------+--------------------------------------------+ -| $&\ *n*\ \_descriptor | Type descriptor structure for type *n* | -| | with one pointer added. | -+------------------------+--------------------------------------------+ -| $\ *n*\ \_basetype | Base typename with all pointers and | -| | qualifiers stripped. | -+------------------------+--------------------------------------------+ +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * + - Variable + - Meaning + * + - $\ *n* + - A C local variable corresponding to type + *n* in the typemap pattern. + * + - $argnum + - Argument number. Only available in + typemaps related to argument conversion + * + - $\ *n*\ \_name + - Argument name + * + - $\ *n*\ \_type + - Real C datatype of type *n*. + * + - $\ *n*\ \_ltype + - ltype of type *n* + * + - $\ *n*\ \_mangle + - Mangled form of type *n*. For example + ``_p_Foo`` + * + - $\ *n*\ \_descriptor + - Type descriptor structure for type *n*. + For example ``SWIGTYPE_p_Foo``. This is + primarily used when interacting with the + run-time type checker (described later). + * + - $\*\ *n*\ \_type + - Real C datatype of type *n* with one + pointer removed. + * + - $\*\ *n*\ \_ltype + - ltype of type *n* with one pointer + removed. + * + - $\*\ *n*\ \_mangle + - Mangled form of type *n* with one pointer + removed. + * + - $\*\ *n*\ \_descriptor + - Type descriptor structure for type *n* + with one pointer removed. + * + - $&\ *n*\ \_type + - Real C datatype of type *n* with one + pointer added. + * + - $&\ *n*\ \_ltype + - ltype of type *n* with one pointer added. + * - $&\ *n*\ \_mangle + - Mangled form of type *n* with one pointer + added. + * + - $&\ *n*\ \_descriptor + - Type descriptor structure for type *n* + with one pointer added. + * - $\ *n*\ \_basetype + - Base typename with all pointers and + qualifiers stripped. Within the table, $\ *n* refers to a specific type within the typemap specification. For example, if you write this diff --git a/SphinxDocs/source/Manual/Warnings.rst b/SphinxDocs/source/Manual/Warnings.rst index 90e11c1fc..4985da52b 100644 --- a/SphinxDocs/source/Manual/Warnings.rst +++ b/SphinxDocs/source/Manual/Warnings.rst @@ -288,191 +288,191 @@ Warning number reference Deprecated features (100-199) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 101. Deprecated ``%extern`` directive. -- 102. Deprecated ``%val`` directive. -- 103. Deprecated ``%out`` directive. -- 104. Deprecated ``%disabledoc`` directive. -- 105. Deprecated ``%enabledoc`` directive. -- 106. Deprecated ``%doconly`` directive. -- 107. Deprecated ``%style`` directive. -- 108. Deprecated ``%localstyle`` directive. -- 109. Deprecated ``%title`` directive. -- 110. Deprecated ``%section`` directive. -- 111. Deprecated ``%subsection`` directive. -- 112. Deprecated ``%subsubsection`` directive. -- 113. Deprecated ``%addmethods`` directive. -- 114. Deprecated ``%readonly`` directive. -- 115. Deprecated ``%readwrite`` directive. -- 116. Deprecated ``%except`` directive. -- 117. Deprecated ``%new`` directive. -- 118. Deprecated ``%typemap(except)``. -- 119. Deprecated ``%typemap(ignore)``. -- 120. Deprecated command line option (-runtime, -noruntime). -- 121. Deprecated ``%name`` directive. -- 126. The 'nestedworkaround' feature is deprecated. +- **101.** Deprecated ``%extern`` directive. +- **102.** Deprecated ``%val`` directive. +- **103.** Deprecated ``%out`` directive. +- **104.** Deprecated ``%disabledoc`` directive. +- **105.** Deprecated ``%enabledoc`` directive. +- **106.** Deprecated ``%doconly`` directive. +- **107.** Deprecated ``%style`` directive. +- **108.** Deprecated ``%localstyle`` directive. +- **109.** Deprecated ``%title`` directive. +- **110.** Deprecated ``%section`` directive. +- **111.** Deprecated ``%subsection`` directive. +- **112.** Deprecated ``%subsubsection`` directive. +- **113.** Deprecated ``%addmethods`` directive. +- **114.** Deprecated ``%readonly`` directive. +- **115.** Deprecated ``%readwrite`` directive. +- **116.** Deprecated ``%except`` directive. +- **117.** Deprecated ``%new`` directive. +- **118.** Deprecated ``%typemap(except)``. +- **119.** Deprecated ``%typemap(ignore)``. +- **120.** Deprecated command line option (-runtime, -noruntime). +- **121.** Deprecated ``%name`` directive. +- **126.** The 'nestedworkaround' feature is deprecated. Preprocessor (200-299) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 201. Unable to find *filename*. -- 202. Could not evaluate expression *expr*. -- 203. Both includeall and importall are defined: using includeall. -- 204. CPP #warning, "*warning*". -- 205. CPP #error, "*error*". -- 206. Unexpected tokens after #\ *directive* directive. +- **201.** Unable to find *filename*. +- **202.** Could not evaluate expression *expr*. +- **203.** Both includeall and importall are defined: using includeall. +- **204.** CPP #warning, "*warning*". +- **205.** CPP #error, "*error*". +- **206.** Unexpected tokens after #\ *directive* directive. C/C++ Parser (300-399) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 301. ``class`` keyword used, but not in C++ mode. -- 302. Identifier '*name*' redefined (ignored). -- 303. ``%extend`` defined for an undeclared class '*name*'. -- 304. Unsupported constant value (ignored). -- 305. Bad constant value (ignored). -- 306. '*identifier*' is private in this context. -- 307. Can't set default argument value (ignored) -- 308. Namespace alias '*name*' not allowed here. Assuming '*name*' -- 309. [private \| protected] inheritance ignored. -- 310. Template '*name*' was already wrapped as '*name*' (ignored) -- 312. Unnamed nested class not currently supported (ignored). -- 313. Unrecognized extern type "*name*" (ignored). -- 314. '*identifier*' is a *lang* keyword. -- 315. Nothing known about '*identifier*'. -- 316. Repeated %module directive. -- 317. Specialization of non-template '*name*'. -- 318. Instantiation of template '*name*' is ambiguous, instantiation +- **301.** ``class`` keyword used, but not in C++ mode. +- **302.** Identifier '*name*' redefined (ignored). +- **303.** ``%extend`` defined for an undeclared class '*name*'. +- **304.** Unsupported constant value (ignored). +- **305.** Bad constant value (ignored). +- **306.** '*identifier*' is private in this context. +- **307.** Can't set default argument value (ignored) +- **308.** Namespace alias '*name*' not allowed here. Assuming '*name*' +- **309.** [private \| protected] inheritance ignored. +- **310.** Template '*name*' was already wrapped as '*name*' (ignored) +- **312.** Unnamed nested class not currently supported (ignored). +- **313.** Unrecognized extern type "*name*" (ignored). +- **314.** '*identifier*' is a *lang* keyword. +- **315.** Nothing known about '*identifier*'. +- **316.** Repeated %module directive. +- **317.** Specialization of non-template '*name*'. +- **318.** Instantiation of template '*name*' is ambiguous, instantiation *templ* used, instantiation *templ* ignored. -- 319. No access specifier given for base class *name* (ignored). -- 320. Explicit template instantiation ignored. -- 321. *identifier* conflicts with a built-in name. -- 322. Redundant redeclaration of '*name*'. -- 323. Recursive scope inheritance of '*name*'. -- 324. Named nested template instantiations not supported. Processing +- **319.** No access specifier given for base class *name* (ignored). +- **320.** Explicit template instantiation ignored. +- **321.** *identifier* conflicts with a built-in name. +- **322.** Redundant redeclaration of '*name*'. +- **323.** Recursive scope inheritance of '*name*'. +- **324.** Named nested template instantiations not supported. Processing as if no name was given to %template(). -- 325. Nested *kind* not currently supported (*name* ignored). -- 326. Deprecated %extend name used - the *kind* name '*name*' should +- **325.** Nested *kind* not currently supported (*name* ignored). +- **326.** Deprecated %extend name used - the *kind* name '*name*' should be used instead of the typedef name '*name*'. -- 350. operator new ignored. -- 351. operator delete ignored. -- 352. operator+ ignored. -- 353. operator- ignored. -- 354. operator\* ignored. -- 355. operator/ ignored. -- 356. operator% ignored. -- 357. operator^ ignored. -- 358. operator& ignored. -- 359. operator\| ignored. -- 360. operator~ ignored. -- 361. operator! ignored. -- 362. operator= ignored. -- 363. operator< ignored. -- 364. operator> ignored. -- 365. operator+= ignored. -- 366. operator-= ignored. -- 367. operator*= ignored. -- 368. operator/= ignored. -- 369. operator%= ignored. -- 370. operator^= ignored. -- 371. operator&= ignored. -- 372. operator|= ignored. -- 373. operator<< ignored. -- 374. operator>>ignored. -- 375. operator<<= ignored. -- 376. operator>>= ignored. -- 377. operator== ignored. -- 378. operator!= ignored. -- 379. operator<= ignored. -- 380. operator>= ignored. -- 381. operator&& ignored. -- 382. operator|\| ignored. -- 383. operator++ ignored. -- 384. operator-- ignored. -- 385. operator, ignored. -- 386. operator-<\* ignored. -- 387. operator-< ignored. -- 388. operator() ignored. -- 389. operator[] ignored. -- 390. operator+ ignored (unary). -- 391. operator- ignored (unary). -- 392. operator\* ignored (unary). -- 393. operator& ignored (unary). -- 394. operator new[] ignored. -- 395. operator delete[] ignored. +- **350.** operator new ignored. +- **351.** operator delete ignored. +- **352.** operator+ ignored. +- **353.** operator- ignored. +- **354.** operator\* ignored. +- **355.** operator/ ignored. +- **356.** operator% ignored. +- **357.** operator^ ignored. +- **358.** operator& ignored. +- **359.** operator\| ignored. +- **360.** operator~ ignored. +- **361.** operator! ignored. +- **362.** operator= ignored. +- **363.** operator< ignored. +- **364.** operator> ignored. +- **365.** operator+= ignored. +- **366.** operator-= ignored. +- **367.** operator*= ignored. +- **368.** operator/= ignored. +- **369.** operator%= ignored. +- **370.** operator^= ignored. +- **371.** operator&= ignored. +- **372.** operator|= ignored. +- **373.** operator<< ignored. +- **374.** operator>>ignored. +- **375.** operator<<= ignored. +- **376.** operator>>= ignored. +- **377.** operator== ignored. +- **378.** operator!= ignored. +- **379.** operator<= ignored. +- **380.** operator>= ignored. +- **381.** operator&& ignored. +- **382.** operator|\| ignored. +- **383.** operator++ ignored. +- **384.** operator-- ignored. +- **385.** operator, ignored. +- **386.** operator-<\* ignored. +- **387.** operator-< ignored. +- **388.** operator() ignored. +- **389.** operator[] ignored. +- **390.** operator+ ignored (unary). +- **391.** operator- ignored (unary). +- **392.** operator\* ignored (unary). +- **393.** operator& ignored (unary). +- **394.** operator new[] ignored. +- **395.** operator delete[] ignored. Types and typemaps (400-499) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 401. Nothing known about class 'name'. Ignored. -- 402. Base class 'name' is incomplete. -- 403. Class 'name' might be abstract. -- 450. Deprecated typemap feature ($source/$target). -- 451. Setting const char \* variable may leak memory. -- 452. Reserved -- 453. Can't apply (pattern). No typemaps are defined. -- 460. Unable to use type *type* as a function argument. -- 461. Unable to use return type *type* in function *name*. -- 462. Unable to set variable of type *type*. -- 463. Unable to read variable of type *type*. -- 464. Unsupported constant value. -- 465. Unable to handle type *type*. -- 466. Unsupported variable type *type*. -- 467. Overloaded *declaration* not supported (incomplete type checking +- **401.** Nothing known about class 'name'. Ignored. +- **402.** Base class 'name' is incomplete. +- **403.** Class 'name' might be abstract. +- **450.** Deprecated typemap feature ($source/$target). +- **451.** Setting const char \* variable may leak memory. +- **452.** Reserved +- **453.** Can't apply (pattern). No typemaps are defined. +- **460.** Unable to use type *type* as a function argument. +- **461.** Unable to use return type *type* in function *name*. +- **462.** Unable to set variable of type *type*. +- **463.** Unable to read variable of type *type*. +- **464.** Unsupported constant value. +- **465.** Unable to handle type *type*. +- **466.** Unsupported variable type *type*. +- **467.** Overloaded *declaration* not supported (incomplete type checking rule - no precedence level in typecheck typemap for '*type*') -- 468. No 'throw' typemap defined for exception type *type* -- 469. No or improper directorin typemap defined for *type* -- 470. Thread/reentrant unsafe wrapping, consider returning by value +- **468.** No 'throw' typemap defined for exception type *type* +- **469.** No or improper directorin typemap defined for *type* +- **470.** Thread/reentrant unsafe wrapping, consider returning by value instead. -- 471. Unable to use return type *type* in director method -- 474. Method *method* usage of the optimal attribute ignored in the +- **471.** Unable to use return type *type* in director method +- **474.** Method *method* usage of the optimal attribute ignored in the out typemap as the following cannot be used to generate optimal code: *code* -- 475. Multiple calls to *method* might be generated due to optimal +- **475.** Multiple calls to *method* might be generated due to optimal attribute usage in the out typemap. -- 476. Initialization using std::initializer_list. -- 477. No directorthrows typemap defined for *type* +- **476.** Initialization using std::initializer_list. +- **477.** No directorthrows typemap defined for *type* Code generation (500-559) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 501. Overloaded declaration ignored. *decl*. Previous declaration is +- **501.** Overloaded declaration ignored. *decl*. Previous declaration is *decl*. -- 502. Overloaded constructor ignored. *decl*. Previous declaration is +- **502.** Overloaded constructor ignored. *decl*. Previous declaration is *decl*. -- 503. Can't wrap '*identifier*' unless renamed to a valid identifier. -- 504. Function *name* must have a return type. Ignored. -- 505. Variable length arguments discarded. -- 506. Can't wrap varargs with keyword arguments enabled. -- 507. Adding native function *name* not supported (ignored). -- 508. Declaration of '*name*' shadows declaration accessible via +- **503.** Can't wrap '*identifier*' unless renamed to a valid identifier. +- **504.** Function *name* must have a return type. Ignored. +- **505.** Variable length arguments discarded. +- **506.** Can't wrap varargs with keyword arguments enabled. +- **507.** Adding native function *name* not supported (ignored). +- **508.** Declaration of '*name*' shadows declaration accessible via operator->(), previous declaration of'*declaration*'. -- 509. Overloaded method *declaration* effectively ignored, as it is +- **509.** Overloaded method *declaration* effectively ignored, as it is shadowed by *declaration*. -- 510. Friend function '*name*' ignored. -- 511. Can't use keyword arguments with overloaded functions. -- 512. Overloaded method *declaration* ignored, using non-const method +- **510.** Friend function '*name*' ignored. +- **511.** Can't use keyword arguments with overloaded functions. +- **512.** Overloaded method *declaration* ignored, using non-const method *declaration* instead. -- 513. Can't generate wrappers for unnamed struct/class. -- 514. -- 515. -- 516. Overloaded method *declaration* ignored, using *declaration* +- **513.** Can't generate wrappers for unnamed struct/class. +- **514.** +- **515.** +- **516.** Overloaded method *declaration* ignored, using *declaration* instead. -- 517. -- 518. Portability warning: File *file1* will be overwritten by *file2* +- **517.** +- **518.** Portability warning: File *file1* will be overwritten by *file2* on case insensitive filesystems such as Windows' FAT32 and NTFS unless the class/module name is renamed. -- 519. %template() contains no name. Template method ignored: +- **519.** %template() contains no name. Template method ignored: *declaration* -- 520. *Base/Derived* class '*classname1*' of '*classname2*' is not +- **520.** *Base/Derived* class '*classname1*' of '*classname2*' is not similarly marked as a smart pointer. -- 521. Illegal destructor name *name*. Ignored. -- 522. Use of an illegal constructor name '*name*' in %extend is +- **521.** Illegal destructor name *name*. Ignored. +- **522.** Use of an illegal constructor name '*name*' in %extend is deprecated, the constructor name should be '*name*'. -- 523. Use of an illegal destructor name '*name*' in %extend is +- **523.** Use of an illegal destructor name '*name*' in %extend is deprecated, the destructor name should be '*name*'. -- 524. Experimental target language. Target language *language* +- **524.** Experimental target language. Target language *language* specified by *lang* is an experimental language. Please read about SWIG experimental languages, *htmllink*. -- 525. Destructor *declaration* is final, *name* cannot be a director +- **525.** Destructor *declaration* is final, *name* cannot be a director class. Doxygen comments (560-599) @@ -488,58 +488,58 @@ Doxygen comments (560-599) Language module specific (700-899) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 801. Wrong name (corrected to '*name*'). (Ruby). +- **801.** Wrong name (corrected to '*name*'). (Ruby). -- 810. No jni typemap defined for *type* (Java). -- 811. No jtype typemap defined for *type* (Java). -- 812. No jstype typemap defined for *type* (Java). -- 813. Warning for *classname*, base *baseclass* ignored. Multiple +- **810.** No jni typemap defined for *type* (Java). +- **811.** No jtype typemap defined for *type* (Java). +- **812.** No jstype typemap defined for *type* (Java). +- **813.** Warning for *classname*, base *baseclass* ignored. Multiple inheritance is not supported in Java. (Java). -- 814. -- 815. No javafinalize typemap defined for *type* (Java). -- 816. No javabody typemap defined for *type* (Java). -- 817. No javaout typemap defined for *type* (Java). -- 818. No javain typemap defined for *type* (Java). -- 819. No javadirectorin typemap defined for *type* (Java). -- 820. No javadirectorout typemap defined for *type* (Java). -- 821. -- 822. Covariant return types not supported in Java. Proxy method will +- **814.** +- **815.** No javafinalize typemap defined for *type* (Java). +- **816.** No javabody typemap defined for *type* (Java). +- **817.** No javaout typemap defined for *type* (Java). +- **818.** No javain typemap defined for *type* (Java). +- **819.** No javadirectorin typemap defined for *type* (Java). +- **820.** No javadirectorout typemap defined for *type* (Java). +- **821.** +- **822.** Covariant return types not supported in Java. Proxy method will return *basetype* (Java). -- 823. No javaconstruct typemap defined for *type* (Java). -- 824. Missing JNI descriptor in directorin typemap defined for *type* +- **823.** No javaconstruct typemap defined for *type* (Java). +- **824.** Missing JNI descriptor in directorin typemap defined for *type* (Java). -- 825. "directorconnect" attribute missing in *type* "javaconstruct" +- **825.** "directorconnect" attribute missing in *type* "javaconstruct" typemap. (Java). -- 826. The nspace feature is used on '*type*' without -package. The +- **826.** The nspace feature is used on '*type*' without -package. The generated code may not compile as Java does not support types declared in a named package accessing types declared in an unnamed package. (Java). -- 830. No ctype typemap defined for *type* (C#). -- 831. No cstype typemap defined for *type* (C#). -- 832. No cswtype typemap defined for *type* (C#). -- 833. Warning for *classname*, base *baseclass* ignored. Multiple +- **830.** No ctype typemap defined for *type* (C#). +- **831.** No cstype typemap defined for *type* (C#). +- **832.** No cswtype typemap defined for *type* (C#). +- **833.** Warning for *classname*, base *baseclass* ignored. Multiple inheritance is not supported in C#. (C#). -- 834. -- 835. No csfinalize typemap defined for *type* (C#). -- 836. No csbody typemap defined for *type* (C#). -- 837. No csout typemap defined for *type* (C#). -- 838. No csin typemap defined for *type* (C#). -- 839. -- 840. -- 841. -- 842. Covariant return types not supported in C#. Proxy method will +- **834.** +- **835.** No csfinalize typemap defined for *type* (C#). +- **836.** No csbody typemap defined for *type* (C#). +- **837.** No csout typemap defined for *type* (C#). +- **838.** No csin typemap defined for *type* (C#). +- **839.** +- **840.** +- **841.** +- **842.** Covariant return types not supported in C#. Proxy method will return *basetype* (C#). -- 843. No csconstruct typemap defined for *type* (C#). -- 844. C# exception may not be thrown - no $excode or excode attribute +- **843.** No csconstruct typemap defined for *type* (C#). +- **844.** C# exception may not be thrown - no $excode or excode attribute in *typemap* typemap. (C#). -- 845. Unmanaged code contains a call to a +- **845.** Unmanaged code contains a call to a SWIG_CSharpSetPendingException method and C# code does not handle pending exceptions via the canthrow attribute. (C#). -- 870. Warning for *classname*: Base *baseclass* ignored. Multiple +- **870.** Warning for *classname*: Base *baseclass* ignored. Multiple inheritance is not supported in PHP. (Php). -- 871. Unrecognized pragma *pragma*. (Php). +- **871.** Unrecognized pragma *pragma*. (Php). User defined (900-999) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/SphinxDocs/source/Manual/Windows.rst b/SphinxDocs/source/Manual/Windows.rst index 51f651430..52629b614 100644 --- a/SphinxDocs/source/Manual/Windows.rst +++ b/SphinxDocs/source/Manual/Windows.rst @@ -76,64 +76,70 @@ automatically used by the solution file. Java ^^^^^^^^^^^^ -| **``JAVA_INCLUDE``** : Set this to the directory containing jni.h -| **``JAVA_BIN``** : Set this to the bin directory containing javac.exe +| **JAVA_INCLUDE** : Set this to the directory containing jni.h +| **JAVA_BIN** : Set this to the bin directory containing javac.exe | Example using JDK1.3: -| ``JAVA_INCLUDE: D:\jdk1.3\include JAVA_BIN: D:\jdk1.3\bin`` +| ``JAVA_INCLUDE: D:\jdk1.3\include`` +| ``JAVA_BIN: D:\jdk1.3\bin`` Perl ^^^^^^^^^^^^ -| **``PERL5_INCLUDE``** : Set this to the directory containing perl.h -| **``PERL5_LIB``** : Set this to the Perl library including path for +| **PERL5_INCLUDE** : Set this to the directory containing perl.h +| **PERL5_LIB** : Set this to the Perl library including path for linking Example using nsPerl 5.004_04: -``PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib`` +| ``PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE`` +| ``PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib`` Python ^^^^^^^^^^^^^^ -| **``PYTHON_INCLUDE``** : Set this to the directory that contains +| **PYTHON_INCLUDE** : Set this to the directory that contains Python.h -| **``PYTHON_LIB``** : Set this to the Python library including path for +| **PYTHON_LIB** : Set this to the Python library including path for linking | Example using Python 2.1.1: -| ``PYTHON_INCLUDE: D:\python21\include PYTHON_LIB: D:\python21\libs\python21.lib`` +| ``PYTHON_INCLUDE: D:\python21\include`` +| ``PYTHON_LIB: D:\python21\libs\python21.lib`` TCL ^^^^^^^^^^^ -| **``TCL_INCLUDE``** : Set this to the directory containing tcl.h -| **``TCL_LIB``** : Set this to the TCL library including path for +| **TCL_INCLUDE** : Set this to the directory containing tcl.h +| **TCL_LIB** : Set this to the TCL library including path for linking | Example using ActiveTcl 8.3.3.3 -| ``TCL_INCLUDE: D:\tcl\include TCL_LIB: D:\tcl\lib\tcl83.lib`` +| ``TCL_INCLUDE: D:\tcl\include`` +| ``TCL_LIB: D:\tcl\lib\tcl83.lib`` R ^^^^^^^^^ -| **``R_INCLUDE``** : Set this to the directory containing R.h -| **``R_LIB``** : Set this to the R library (Rdll.lib) including path +| **R_INCLUDE** : Set this to the directory containing R.h +| **R_LIB** : Set this to the R library (Rdll.lib) including path for linking. The library needs to be built as described in the R README.packages file (the pexports.exe approach is the easiest). | Example using R 2.5.1: -| ``R_INCLUDE: C:\Program Files\R\R-2.5.1\include R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib`` +| ``R_INCLUDE: C:\Program Files\R\R-2.5.1\include`` +| ``R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib`` Ruby ^^^^^^^^^^^^ -| **``RUBY_INCLUDE``** : Set this to the directory containing ruby.h -| **``RUBY_LIB``** : Set this to the ruby library including path for +| **RUBY_INCLUDE** : Set this to the directory containing ruby.h +| **RUBY_LIB** : Set this to the ruby library including path for linking | Example using Ruby 1.6.4: -| ``RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32 RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib`` +| ``RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32`` +| ``RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib`` Instructions for using the Examples with other compilers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -195,9 +201,10 @@ directories. - msys-autoconf-2.59.tar.bz2 - msys-automake-1.8.2.tar.bz2 -#. Install MinGW-3.1.0-1.exe (C:\MinGW is default location.) + +#. Install MinGW-3.1.0-1.exe (``C:\MinGW`` is default location.) #. Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on the - same windows drive letter as MinGW (C:\msys\1.0 is default). In the + same windows drive letter as MinGW (``C:\msys\1.0`` is default). In the post install script, - Answer y to the "do you wish to continue with the post install?" @@ -206,8 +213,8 @@ directories. default) #. Install msysDTK-1.0.1.exe to the same folder that you installed MSYS - (C:\msys\1.0 is default). -#. Copy the following to the MSYS install folder (C:\msys\1.0 is + (``C:\msys\1.0`` is default). +#. Copy the following to the MSYS install folder (``C:\msys\1.0`` is default): - msys-automake-1.8.2.tar.bz2 |