1
0
mirror of https://github.com/netsurf-browser/netsurf synced 2024-12-27 14:29:42 +03:00

add initial javascript binding documentation

This commit is contained in:
Vincent Sanders 2019-05-02 11:13:09 +01:00
parent ccb499b800
commit 148639b70c
2 changed files with 187 additions and 61 deletions

59
docs/jsbinding.md Normal file
View File

@ -0,0 +1,59 @@
Javascript bindings
===================
In order for javascript programs to to interact with the page contents
it must use the Document Object Model (DOM) and Cascading Style Sheet
Object Model (CSSOM) API.
These interfaces are described using web Interface Description
Language (IDL) within the relevant specifications
(e.g. https://dom.spec.whatwg.org/).
Each interface described by the webIDL must be bound (connected) to
the browsers internal representation for the DOM or CSS, etc. These
bindings desciptions are processed together with the WebIDL by the
nsgenbind tool to generate source code.
A list of [DOM and CSSOM methods](unimplemented.html) is available
outlining the remaining unimplemented API bindings.
WebIDL
------
The WebIDL specification defines the interface description language used.
These descriptions should be periodicaly updated to keep the browser
interfaces current.
There is a content/handlers/javascript/WebIDL/Makefile which attempts
to automaticaly update the IDL files by scraping the web specs.
This tool needs a great deal of hand holding, not least because many of the
source documents list the IDL fragments multiple times, some even have
appendicies with the entrire IDL repeated.
Interface binding introduction
------------------------------
The binding files are processed by the nsgenbind tool to generate c
source code which implements the interfaces within the javascript
engine.
The bindings are specific to a javascript engine, the DOM library, the
CSS library and the browser. In this case that is the tuple of
duktape, libdom, libcss and NetSurf.
In principle other engines or libraries could be substituted
(historicaly NetSurf unsucessfully tried to use spidermonkey) but the
engineering to do so is formidable.
The bindings are kept the sorce rpository within the duktape
javascript handler content/handlers/javascript/duktape/
The root binding which contains all the interfaces initroduced into
the javascript programs initial execution context is nesurf.bnd this
references all the WebIDL to be bound and includes all additional
binding definitions to implement the interfaces.
The bindings are a Domain Specific Language (DSL) which allows
implementations to be added to each WebIDL method.

View File

@ -3,25 +3,123 @@ NetSurf web browser
![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1037/badge)[*](https://bestpractices.coreinfrastructure.org/projects/1037) ![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1037/badge)[*](https://bestpractices.coreinfrastructure.org/projects/1037)
The NetSurf code makes use of Doxygen for code documentation. # User Interface
User Interface Netsurf is divided into a series of frontends which provide a user
-------------- interface around common core functionality. Each frontend is a
distinct implementation for a specific GUI toolkit.
There are some basic user guides for the Because of this the user interface has different features in
[framebuffer](docs/using-framebuffer.md) and each frontend allowing the browser to be a native application.
[monkey](docs/using-monkey.md) frontends.
The [core user options](docs/netsurf-options.md) of the browser are ## Frontends
documented which are augmented by each frontend in a specific manner.
### Logging As GUI toolkits are often applicable to a single Operating
System (OS) some frontends are named for their OS instead of the
toolkit e.g. RISC OS WIMP frontend is named riscos and the Windows
win32 frontend is named windows.
### amiga
Frontend specific to the amiga
### atari
Frontend specific to the atari
### beos
Frontend specific to the Haiku OS
### framebuffer
There is a basic user guide for the[framebuffer](docs/using-framebuffer.md)
### gtk
Frontend that uses the GTK+2 or GTK+3 toolkit
### monkey
This is the internal unit test frontend.
There is a basic user guide [monkey](docs/using-monkey.md)
### riscos
Frontend for the RISC OS WIMP toolkit.
### windows
Frontend which uses the Microsodt win32 GDI toolkit.
## User configuration
The behaviour of the browser can be changed from the defaults with a
configuration file. The [core user options](docs/netsurf-options.md)
of the browser are common to all versions and are augmented by each
frontend in a specific manner.
# Development
## Working with the team
Generally it is sensible to check with the other developers if you are
planning to make a change to NetSurf intended to be merged.
We are often about on the IRC channel but failing that the developer
mailing list is a good place to try.
All the project sources are held in [public git repositories](http://source.netsurf-browser.org/)
## Compilation environment
Compiling a development edition of NetSurf requires a POSIX style
environment. Typically this means a Linux based system although Free
BSD, Open BSD, Mac OS X and Haiku all known to work.
## Toolchains
Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally
relies upon a cross compilation environment which is generated using
the makefiles found in our
[toolchains](http://source.netsurf-browser.org/toolchains.git/)
repository. These toolchains are built by the Continuous Integration
(CI) system and the
[results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
are published as a convenience.
## Quick setup
The [quick start guide](docs/quick-start.md) can be used to get a
development environment setup quickly and uses the
[env.sh](env_8sh_source.html) script the core team utilises.
## Manual setup
The Manual environment setup and compilation method is covered by the
details in the [netsurf libraries](docs/netsurf-libraries.md) document
for the core libraries and then one of the building documents for the
specific frontend.
- [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md)
- [Framebuffer](docs/building-Framebuffer.md)
- [GTK](docs/building-GTK.md)
- [Haiku (BeOS)](docs/building-Haiku.md)
- [Windows Win32](docs/building-Windows.md)
These documents are sometimes not completely up to
date and the env.sh script should be considered canonical.
## Logging
The [logging](docs/logging.md) interface controls debug and error The [logging](docs/logging.md) interface controls debug and error
messages not output through the GUI. messages not output through the GUI.
Documented API ## Documented API
--------------
The NetSurf code makes use of Doxygen for code documentation.
There are several documents which detail specific aspects of the There are several documents which detail specific aspects of the
codebase and APIs. codebase and APIs.
@ -39,60 +137,29 @@ provides a way for downloaded content to be kept on a persistent
storage medium such as hard disc to make future retrieval of that storage medium such as hard disc to make future retrieval of that
content quickly. content quickly.
### Javascript ## Javascript
JavaScript is provided by integrating the duktape library. There are [instructions](docs/updating-duktape.md) on how to update the library. Javascript provision is split into four parts:
- An engine that takes source code and executes it.
- Interfaces between the program and the web page.
- Browser support to retrive and manage the source code to be executed.
- Browser support for the dispatch of events from user interface.
A list of [unimplemented DOM and CSSOM methods](unimplemented.html) ### Library
is available outlining the remaining API that have to be implemented.
Development JavaScript is provided by integrating the duktape library. There are
----------- [instructions](docs/updating-duktape.md) on how to update the library.
Compiling a development edition of NetSurf requires a POSIX style ### Interface binding
environment. Typically this means a Linux based system although Free
BSD, Open BSD, Mac OS X and Haiku all known to work.
### Working with the team In order for javascript programs to to interact with the page contents
it must use the Document Object Model (DOM) and Cascading Style Sheet
Object Model (CSSOM) API.
Generally it is sensible to check with the other developers if you are These interfaces are described using web Interface Description
planning to make a change to NetSurf intended to be merged. Language (IDL) within the relevant specifications
(e.g. https://dom.spec.whatwg.org/).
We are often about on the IRC channel but failing that the developer
mailing list is a good place to try.
All the project sources are held in [public git repositories](http://source.netsurf-browser.org/)
### Toolchains
Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally
relies upon a cross compilation environment which is generated using
the makefiles found in our
[toolchains](http://source.netsurf-browser.org/toolchains.git/)
repository. These toolchains are built by the Continuous Integration
(CI) system and the
[results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
are published as a convenience.
### Quick setup
The [quick start guide](docs/quick-start.md) can be used to get a
development environment setup quickly and uses the
[env.sh](env_8sh_source.html) script the core team utilises.
### Manual setup
The Manual environment setup and compilation method is covered by the
details in the [netsurf libraries](docs/netsurf-libraries.md) document
for the core libraries and then one of the building documents for the
specific frontend.
- [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md)
- [Framebuffer](docs/building-Framebuffer.md)
- [GTK](docs/building-GTK.md)
- [Haiku (BeOS)](docs/building-Haiku.md)
- [Windows Win32](docs/building-Windows.md)
These documents are sometimes not completely up to
date and the env.sh script should be considered canonical.
Each interface described by the webIDL must be bound (connected) to
the browsers internal representation for the DOM or CSS, etc. The
process of [writing bindings](docs/jsbinding.md) is ongoing.