From 362583c63601abb0b6a39ea04c1a490cd432393d Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Wed, 16 Apr 2014 07:35:49 +0100 Subject: [PATCH] Javascript html documentation tidy up --- Doc/Manual/Javascript.html | 129 +++++++++++++++++++++---------------- 1 file changed, 72 insertions(+), 57 deletions(-) diff --git a/Doc/Manual/Javascript.html b/Doc/Manual/Javascript.html index 8d8f436ca..329ee4421 100644 --- a/Doc/Manual/Javascript.html +++ b/Doc/Manual/Javascript.html @@ -5,16 +5,21 @@ -

SWIG and Javascript

+ +

SWIG and Javascript

This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.

-

Overview

+ +

Overview

Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development. Javascript has gone beyond being a browser-based scripting language and with node.js, it is also used as a backend development language.

Native Javascript extensions can be used for applications that embed a web-browser view or that embed a Javascript engine (such as node.js). Extending a general purpose web-browser is not possible as this would be a severe security issue.

SWIG Javascript currently supports JavascriptCore, the Javascript engine used by Safari/Webkit, and v8, which is used by Chromium and node.js.

WebKit is a modern browser implementation available as open-source which can be embedded into an application.

-

Preliminaries

-

Running SWIG

+ +

Preliminaries

+ +

Running SWIG

+

Suppose that you defined a SWIG module such as the following:

@@ -44,13 +49,14 @@ bool example_initialize(JSGlobalContextRef context, JSObjectRef *exports)

and for v8:

-void example_initialize (v8::Handle exports)
+void example_initialize(v8::Handle exports)
-
-

Note: be aware that v8 comes as a C++ API, and thus, the generated modules must be compiled as C++.

-
-

Running Tests and Examples

-

The configuration for tests and examples currently supports Linux and Mac only, MinGW not yet.

+

+

Note: be aware that v8 has a C++ API, and thus, the generated modules must be compiled as C++.

+

+ +

Running Tests and Examples

+

The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.

The default interpreter is node.js as it is available on all platforms and convenient to use.

Running the examples with JavascriptCore requires libjavascriptcoregtk-1.0 to be installed, e.g., under Ubuntu with

@@ -65,18 +71,13 @@ $ sudo apt-get install libv8-dev

Examples can be run using

-$ make ENGINE=jsc check-javascript-examples
+$ make check-javascript-examples ENGINE=jsc

ENGINE can be node, jsc, or v8.

The test-suite can be run using

-$ make ENGINE=jsc check-javascript-test-suite
-
-

A smaller, manually selected set of tests can be run using

-
-
-$ make SMOKE=1 ENGINE=jsc check-javascript-test-suite
+$ make check-javascript-test-suite ENGINE=jsc

Tests should run without any problems, i.e., have been tried out, on the following platforms/interpreters:

@@ -95,19 +96,20 @@ $ make SMOKE=1 ENGINE=jsc check-javascript-test-suite - Windows 7 64bit (VS 2010) - Node.js
-
-

Note: a CMake based configuration can be found in the cmake which can be used to generate a VisualStudio solution. It is rather limited and can only be used for building the SWIG executable.

-
-

Future work

-

The Javascript module is not yet as mature as other modules and some things are still missing. As it makes use of Swigs Unified typemap library (UTL), many typemaps are inherited. We could work on that if requested:

+

+ +

Future work

+

The Javascript module is not yet as mature as other modules and some things are still missing. As it makes use of SWIG's Unified Typemap Library (UTL), many typemaps are inherited. We could work on that if requested:

  • More typemaps: compared to other modules there are only a few typemaps implemented. For instance a lot of the std_*.i typemaps are missing, such as std_iostream, for instance.

  • Director support: this would allow to extend a C++ abstract base class in Javascript. A pragmatic intermediate step for the most important usecase would be to support Javascript callbacks as arguments.

-

Integration

+ +

Integration

This chapter gives a short introduction how to use a native Javascript extension: as a node.js module, and as an extension for an embedded Webkit.

-

Creating node.js Extensions

-

To install node.js you can download an installer from their web-site for OSX and Windows. For Linux you can either build the source yourself and to a sudo checkinstall or stick to the (probably stone-age) packaged version. For Ubuntu there is a PPA available.

+ +

Creating node.js Extensions

+

To install node.js you can download an installer from their web-site for OSX and Windows. For Linux you can either build the source yourself and run sudo checkinstall or keep to the (probably stone-age) packaged version. For Ubuntu there is a PPA available.

 $ sudo add-apt-repository ppa:chris-lea/node.js
@@ -143,24 +145,27 @@ $ swig -javascript -node -c++ example.cxx
 $ node-gyp
-

This will create a build folder containing the native module. To use the extension you have to require it in your javascript source file.

+

This will create a build folder containing the native module. To use the extension you need to 'require' it in your Javascript source file:

 require("./build/Release/example")
-

A more detailed exlanation is given in section Examples.

-

Troubleshooting

+

A more detailed explanation is given in the Examples section.

+ +

Troubleshooting

  • 'module' object has no attribute 'script_main'
-

This happened when gyp was installed as distribution package. It seems to be outdated. Removing it resolves the problem.

+

This error happens when gyp is installed as a distribution package. It seems to be outdated. Removing it resolves the problem.

 $ sudo apt-get remove gyp
-

Embedded Webkit

-

Webkit is built-in for OSX and available as library for GTK.

-

OSX

+ +

Embedded Webkit

+

Webkit is pre-installed on OSX and available as a library for GTK.

+ +

OSX

There is general information about programming with WebKit on Apple Developer Documentation. Details about Cocoa programming are not covered here.

An integration of a native extension 'example' would look like this:

@@ -193,8 +198,9 @@ extern bool example_initialize(JSGlobalContextRef context); @end
-

GTK

-

There is general information about programming GTK on the GTK documentation, in the GTK tutorial, and for Webkit there is a Webkit GTK+ API Reference.

+ +

GTK

+

There is general information about programming GTK at GTK documentation and in the GTK tutorial, and for Webkit there is a Webkit GTK+ API Reference.

An integration of a native extension 'example' would look like this:

@@ -229,13 +235,16 @@ int main(int argc, char* argv[])
     return 0;
 }
-

Creating Applications with node-webkit

-
+ +

Creating Applications with node-webkit

+

TODO: documentation is coming soon

-
-

Examples

+

+ +

Examples

Some basic examples are shown here in more detail.

-

Simple

+ +

Simple

The common example simple looks like this:

@@ -247,7 +256,7 @@ extern int    gcd(int x, int y);
 extern double Foo;
 %}
-

To make this available as node extension a binding.gyp has to be created:

+

To make this available as a node extension a binding.gyp has to be created:

 {
@@ -264,7 +273,7 @@ extern double Foo;
 
 $ node-gyp configure build
-

From a 'nodejs` application this would be used this way:

+

From a 'nodejs` application the extension would be used like this:

 // import the extension via require
@@ -280,10 +289,11 @@ var f = example.Foo;
 example.Foo = 3.1415926;

First the module example is loaded from the previously built extension. Global methods and variables are available in the scope of the module.

-
-

Note: ECMAScript 5, the currently implemented Javascript standard, does not have modules. node.js and other implementations provide this mechanism defined by the CommonJS group. For browsers this is provided by Browserify, for instance.

-
-

Class

+

+

Note: ECMAScript 5, the currently implemented Javascript standard, does not have modules. node.js and other implementations provide this mechanism defined by the CommonJS group. For browsers this is provided by Browserify, for instance.

+

+ +

Class

The common example class defines three classes, Shape, Circle, and Square:

@@ -322,7 +332,7 @@ public:

Circle and Square inherit from Shape. Shape has a static variable nshapes, a function move that can't be overridden (non-virtual), and two abstract functions area and perimeter (pure virtual) that must be overridden by the sub-classes.

A nodejs extension is built the same way as for the simple example.

-

In javascript it can be used this way:

+

In Javascript it can be used as follows:

 var example = require("./build/Release/example");
@@ -407,12 +417,14 @@ at ReadStream.onkeypress (readline.js:99:10)
 at ReadStream.EventEmitter.emit (events.js:98:17)
 at emitKey (readline.js:1095:12)
-
-

Note: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property prototype of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in Inheritance and the prototype chain, for instance.

-
-

Implementation

-

The Javascript Module implementation has take a very different approach than other modules to be able to generate code for different Javascript interpreters.

-

Source Code

+

+

Note: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property prototype of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in Inheritance and the prototype chain, for instance.

+

+ +

Implementation

+

The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.

+ +

Source Code

The Javascript module is implemented in Source/Modules/javascript.cxx. It dispatches the code generation to a JSEmitter instance, V8Emitter or JSCEmitter. Additionally there are some helpers: Template, for templated code generation, and JSEmitterState, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:

@@ -510,7 +522,8 @@ JSEmitterState::JSEmitterState() { ... }
 Template::Template(const String *code_) { ... }
 ...
-

Code Templates

+ +

Code Templates

All generated code is created on the basis of code templates. The templates for JavascriptCore can be found in Lib/javascript/jsc/javascriptcode.swg, for v8 in Lib/javascript/v8/javascriptcode.swg.

To track the originating code template for generated code you can run

@@ -520,11 +533,11 @@ $ swig -javascript -jsc -debug-codetemplates

which wraps generated code with a descriptive comment

-/* begin fragment("temlate_name") */
+/* begin fragment("template_name") */
 
 ...generated code ...
 
-/* end fragment("temlate_name") */
+/* end fragment("template_name") */

The Template class is used like this:

@@ -546,7 +559,8 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED)) %}

Template creates a copy of that string and Template::replace uses Swig's Replaceall to replace variables in the template. Template::trim can be used to eliminate leading and trailing whitespaces. Template::print is used to write the final template string to a Swig DOH (based on Printv). All methods allow chaining.

-

Emitter

+ +

Emitter

The Javascript module delegates code generation to a JSEmitter instance. The following extract shows the essential interface:

@@ -662,7 +676,8 @@ int JAVASCRIPT::classHandler(Node *n) {
 }

In enterClass the emitter stores state information that is necessary when processing class members. In exitClass the wrapper code for the whole class is generated.

-

Emitter states

+ +

Emitter states

For storing information during the AST traversal the emitter provides a JSEmitterState with different slots to store data representing the scopes global, class, function, and variable.