From 388d8fd007d3240cba3c295cc46ab3a265770e89 Mon Sep 17 00:00:00 2001 From: Simon Marchetto Date: Wed, 14 Jan 2015 15:44:28 +0100 Subject: [PATCH] change 'Module' section to 'Builder modes' and other fixes --- Doc/Manual/Scilab.html | 203 +++++++++++++++++------------------------ 1 file changed, 85 insertions(+), 118 deletions(-) diff --git a/Doc/Manual/Scilab.html b/Doc/Manual/Scilab.html index 272115ff4..f14296303 100644 --- a/Doc/Manual/Scilab.html +++ b/Doc/Manual/Scilab.html @@ -48,14 +48,16 @@
  • Matrices
  • STL -
  • Module +
  • Module_initialization +
  • Building modes +
  • Generated scripts +
  • Other resources @@ -101,7 +103,7 @@ In this example we bind from C a function and a global variable into Scilab. The 
     %module example
 
-%inline {
+%inline %{
 double Foo = 3.0;
 
 int fact(int n) {
@@ -119,8 +121,7 @@ int fact(int n) {

    -Note: there are other approaches to write an interface file, this one was used only for simplicity. -See Module to see other ways to write an interface file. +Note: a code in an %inline section is both parsed and wrapped by SWIG, and inserted as is in the wrapper source file.

    @@ -130,18 +131,6 @@ See Module to see other ways to write an interface The module is generated using the swig executable and its -scilab option.

    -

    -SWIG for Scilab can work in two modes: the builder and the nobuilder mode (mode used by default). -

    - - -

    -In this section, we consider only using the nobuilder mode. See the Module section to have details on the other mode. -

    - 
     $ swig -scilab example.i
    @@ -150,8 +139,8 @@ $ swig -scilab example.i This command generates two files:

    @@ -167,6 +156,12 @@ Note: if the following error is returned: it may be because the SWIG library is not found. Check the SWIG_LIB environment variable or your SWIG installation.

    +

    +Note: SWIG for Scilab can work in two modes related to the way the module is build, see the Building modes section for details. +This example uses the builder mode. +

    + +

    The swig executable has several other command line options you can use. See Scilab command line options for further details.

    @@ -175,33 +170,29 @@ The swig executable has several other command line options you can use.

    37.2.2 Building the module

    -To be loaded in Scilab, the wrapper has to be build into a dynamic module. +To be loaded in Scilab, the wrapper has to be build into a dynamic module (or shared library).

    -We suppose the path to the Scilab include directory is here /usr/local/include (that's the case in a Debian environment). -

    - -

    -The commands to build the wrapper with gcc are: +The commands to compile and link the wrapper (with gcc) into the shared library libexample.so are: 

    -$ gcc -fPIC -c -I/usr/local/include example_wrap.c
+$ gcc -fPIC -c -I/usr/local/include/scilab example_wrap.c
 $ gcc -shared example_wrap.o -o libexample.so

    -The shared library libexample.so should be produced in the current folder. +Note: we supposed in this example the path to the Scilab include directory is /usr/local/include/scilab (which is the case in a Debian environment), this sould be changed for another environment.

    37.2.3 Loading the module

    -Loading the module by running the loader script in Scilab: +Loading a module is done by running the loader script in Scilab:

    -
    +
     --> exec loader.sce
 
    
 
@@ -209,13 +200,13 @@ Loading the module by running the loader script in Scilab:
 Scilab should output the following messages:
 
    
 
-
    +
     Shared archive loaded.
 Link done.
 
    
 
 
    
-Which means that Scilab has sucessfully loaded the shared library. Its functions and other symbols are now available in Scilab.
+Which means that Scilab has sucessfully loaded the shared library. The module functions and other symbols are now available in Scilab.
 
    
 
 
    37.2.4 Using the module
    
@@ -1077,7 +1068,7 @@ struct triplet {
 Then in Scilab:
 
    
 
-
    
+
    
 
     -->t = new_IntTriplet(3, 4, 1);
 
@@ -1659,7 +1650,7 @@ namespace std {
 
 
    
 Additionally, the module initialization function has to be executed first in Scilab, so that all the types are known to Scilab.
-See the initialization paragraph for more details.
+See the Module initialization section for more details.
 
    
 
 
@@ -1798,66 +1789,66 @@ ans  =
 
    
 
    
 
-
    37.5 Module
    
+
    37.5 Module initialization
    
 
 
    
-In this part we describe how a module can be structured, how to build it and give some details about the generated scripts.
+The wrapped module contains an initialization function to:
 
    
-
-
    37.5.1 Structure
    
-
-
    
-Usually, one module is created to bind one library. Each library to be wrapped comes with the following files:
-
    
-
 
      
-
    • header files (.h, .hpp,...) of the module, or of a third party library.
      • 
-
    • source files (.c, .cpp,...).
      • 
-
    • some third party libraries (.so) to link with.
      • 
+
    • initialize the SWIG runtime, which is necessary when working with the STL
      • 
+
    • initialize in Scilab the module constants and enumerations declared with %scilabconst()
      • 
 
    
 
-
-
    37.5.2 Interface file
    
-
 
    
-Each module needs one interface file. Multi modules in an interface file are not yet supported.
+This initialization function should be executed at the start of a script, before the wrapped library has to be used.
 
    
 
 
    
-The module interface file begins by declaring the module name, followed by the wrapping declarations.
-It is often easier to include the whole header of a library being wrapped. Then the interface file typically looks like this:
+The function has the name of the module suffixed by _Init.
+For example, to initialize the module example:
 
    
 
-
    -%module module_name
-
-%{
-#include "myheader.h"
-...
-%}
-
-#include "myheader.h"
-...
+
    +--> example_Init();
 
    
 
-
    37.5.3 Building
    
+
    37.6 Building modes
    
 
 
    
-The mechanism to load an external module in Scilab is called Dynamic Link and works with dynamic modules (or shared libraries i.e. so files).
+The mechanism to load an external module in Scilab is called Dynamic Link and works with dynamic modules (or shared libraries, .so files).
 
    
 
 
    
 To produce a dynamic module, when generating the wrapper, there are two possibilities, or build modes:
 
    
 
      
-
    • the nobuilder mode. This is the standard mode in SWIG. The sources have to be manually compiled and linked.
-It is the best option to use when the module build has to be integrated into a larger build process.
-
    • the builder mode. In this mode, Scilab is responsible of the building. SWIG produces a builder script, which is executed in Scilab to build the module.
-An advantage of this mode is that it hides all the complexity of the build and platform issues.
-Also it allows the module to conform to a Scilab external module convention which is that an external module should be simply built by calling a builder script.
+
    • the nobuilder mode, this is the default mode in SWIG. The user is responsible of the build.
+
    • the builder mode. In this mode, Scilab is responsible of building.
 
    
 
-
    37.5.4 Builder mode
    
+
    37.6.1 No-builder mode
    
+
+
    
+In this mode, used by default, SWIG generates the wrapper sources, which have to be manually compiled and linked.
+A loader script loader.sce is also produced, this one is executed further in Scilab to load the module.
+
    
+
+
    
+This mode is the best option to use when you have to integrate the module build into a larger build process.
+
    
+
+
+
    37.6.2 Builder mode
    
+
+
    
+In this mode, in addition to the wrapper sources, SWIG produces a builder Scilab script (builder.sce), which is executed in Scilab to build the module.
+In a few words, the Scilab ilib_build() command is used, which produces the shared library file, and the loader script loader.sce (and also a cleaner script cleaner.sce).
+
    
+
+
    
+An advantage of this mode is that it hides all the complexity of the build and other platform issues.
+Also it allows the module to conform to a Scilab external module convention which is that an external module should be simply built by calling a builder script.
+
    
 
 
    
 The builder mode is activated with the -builder SWIG option.
@@ -1865,29 +1856,21 @@ In this mode, the following SWIG options may be used to setup the build:
 
    
 
 
      
-
    • buildersources: to add sources to be compiled and linked with (several files must be separated by a comma).
      • 
-
    • buildercflags: to add compiler flags to the builder flags (to add include paths for example).
      • 
-
    • builderldflags: to add linker flags to the builder flags (to add library dependencies for example).
      • 
+
    • buildersources: to add sources to the build (several files must be separated by a comma)
      • 
+
    • buildercflags: to add flags to the builder compiler flags, for example to set library dependencies include paths
      • 
+
    • builderldflags: to add flags to the linker flags, for example to set library dependency names and paths
      • 
 
    
 
 
    
-The SWIG command may have the following syntax:
-
    
-
-
    -swig -scilab -builder -buildercflags "-I[inc_path]..." -builderldflags "-L[lib_path] -l[lib_name]..." -buildersources [source1],... [module_name].i
-
    
-
-
    
-For example, to add to the build:
+Let's give an example how to build a module example, composed of two sources, and using a library dependency:
 
      
-
    • the sources baa1.c and baa2.c (stored in in the current directory)
      • 
-
    • the library foo in /opt/foo (headers stored in /opt/foo/include, and shared library in /opt/foo/lib)
      • 
+
    • the sources are baa1.c and baa2.c (and are stored in in the current directory)
      • 
+
    • the library is libfoo in /opt/foo (headers stored in /opt/foo/include, and shared library in /opt/foo/lib)
      • 
 
    
 
    
 
 
    
-the command is:
+The command is:
 
    
 
 
    @@ -1895,21 +1878,27 @@ $ swig -scilab -builder -buildercflags -I/opt/foo/include -builderldflags "-L/op
 
    
 
    
 
-
    Builder script
    
+
    37.7 Generated scripts
    
 
 
    
-builder.sce is the name of the builder script generated by SWIG. It contains code like this:
+In this part we give some details about the generated Scilab scripts.
+
    
+
+
    37.7.1 Builder script
    
+
+
    
+builder.sce is the name of the builder script generated by SWIG in builder mode. It contains code like this:
 
    
 
     ilib_name = "examplelib";
 files = ["example_wrap.c"];
 libs = [];
-table = ["gcd","_wrap_gcd";"Foo_set","_wrap_Foo_set";"Foo_get","_wrap_Foo_get";];
+table = ["fact","_wrap_fact";"Foo_set","_wrap_Foo_set";"Foo_get","_wrap_Foo_get";];
 ilib_build(ilib_name,table,files,libs);
 
    
 
 
    
-ilib_build(lib_name,table,files,libs) is used to create shared libraries and to generate a loader file which can be used to dynamically load the shared library into Scilab.
+ilib_build(lib_name,table,files,libs) is used to create shared libraries, and to generate a loader file used to dynamically load the shared library into Scilab.
 
    
 
 
      
@@ -1919,7 +1908,7 @@ ilib_build(ilib_name,table,files,libs);
 
    • table: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.
      • 
 
    
 
-
    37.5.5 Loader script
    
+
    37.7.2 Loader script
    
 
 
    
 The loader script is used to load in Scilab all the module functions. When loaded, these functions can be used as other Scilab functions.
@@ -1935,7 +1924,7 @@ The loader script loader.sce contains code similar to:
 // ------------------------------------------------------
 
 libexamplelib_path = get_file_path('loader.sce');
-list_functions = [             'gcd';
+list_functions = [             'fact';
             'Foo_set';
             'Foo_get';
 ];
@@ -1956,30 +1945,8 @@ clear get_file_path;
 
  • fcts: vector of character strings. The name of new Scilab function.
    • 
 
 
-
    37.5.6 Initialization
    
 
-
    
-The wrapped module contains an initialization function to:
-
    
-
      
-
    • initialize the SWIG runtime, which is necessary when working with the STL.
      • 
-
    • initialize the constants of the module, needed for the %scilabconst() feature.
      • 
-
    
-
-
    
-This initialization function should be executed at the start of a script, before the wrapped library has to be used.
-
    
-
-
    
-The function has the name of the module suffixed by _Init.
-For example, to initialize the module example:
-
    
-
-
    ---> example_Init();
-
    
-
-
    37.6 Other resources
    
+
    37.8 Other resources
    
 
 
      
 
    • Example use cases can be found in the Examples/scilab directory.
      •