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:
parent
ccb499b800
commit
148639b70c
59
docs/jsbinding.md
Normal file
59
docs/jsbinding.md
Normal 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.
|
189
docs/mainpage.md
189
docs/mainpage.md
@ -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.
|
||||||
|
Loading…
Reference in New Issue
Block a user