mirror of
https://github.com/netsurf-browser/netsurf
synced 2024-12-20 11:12:46 +03:00
split up mainpage docs and add section on testing
This commit is contained in:
Vincent Sanders
parent
fb4f1d28ba
commit
bcc64cf263
153
docs/development.md
Normal file
153
docs/development.md
Normal file
@ -0,0 +1,153 @@
|
||||
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
|
||||
messages not output through the GUI.
|
||||
|
||||
# Unit testing
|
||||
|
||||
NetSurf [unit tests](docs/unit-testing.md) provide basic test coverage
|
||||
of many core parts of the browser code such as url parsing and utility
|
||||
functions.
|
||||
|
||||
# Integration testing
|
||||
|
||||
The monkey frontend is used to perform complex tests involving
|
||||
operating the browser as a user might (opening windows, navigating to
|
||||
websites and rendering the contents etc.)
|
||||
|
||||
A test is written as a set of operations in a yaml file. A test can be
|
||||
run using the monkey_driver.py python script
|
||||
|
||||
$ ./test/monkey_driver.py -m ./nsmonkey -t test/monkey-tests/start-stop.yaml
|
||||
|
||||
There are very few tests within the netsurf repository. The large
|
||||
majority of integration tests are held within the
|
||||
[netsurf-test](http://source.netsurf-browser.org/netsurf-test.git/)
|
||||
repository.
|
||||
|
||||
To allow more effective use of these tests additional infrastructure
|
||||
has been constructed to allow groupings of tests to be run. This is
|
||||
used extensively by the CI system to perform integration testing on
|
||||
every commit.
|
||||
|
||||
Each test is a member of a group and the tests within each group are
|
||||
run together. Groups are listed within division index files. To run
|
||||
the integration tests the monkey-see-monkey-do python script is
|
||||
used. It downloads the test plan for a division from the netsurf test
|
||||
infrastructrure and executes it.
|
||||
|
||||
$ ./test/monkey-see-monkey-do
|
||||
Fetching tests...
|
||||
Parsing tests...
|
||||
Running tests...
|
||||
Start group: initial
|
||||
[ Basic checks that the browser can start and stop ]
|
||||
=> Run test: start-stop-no-js.yaml
|
||||
=> Run test: basic-navigation.yaml
|
||||
=> Run test: start-stop.yaml
|
||||
Start group: no-networking
|
||||
[ Tests that require no networking ]
|
||||
=> Run test: resource-scheme.yaml
|
||||
Start group: ecmascript
|
||||
[ ECMAScript tests ]
|
||||
PASS
|
||||
|
||||
|
||||
# Documented API
|
||||
|
||||
The NetSurf code makes use of Doxygen for code documentation.
|
||||
|
||||
There are several documents which detail specific aspects of the
|
||||
codebase and APIs.
|
||||
|
||||
## Core window
|
||||
|
||||
The [core window API](docs/core-window-interface.md) allows frontends
|
||||
to use generic core code for user interface elements beyond the
|
||||
browser render.
|
||||
|
||||
## Source object caching
|
||||
|
||||
The [source object caching](docs/source-object-backing-store.md)
|
||||
provides a way for downloaded content to be kept on a persistent
|
||||
storage medium such as hard disc to make future retrieval of that
|
||||
content quickly.
|
||||
|
||||
# Javascript
|
||||
|
||||
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 retrieve and manage the source code to be executed.
|
||||
- Browser support for the dispatch of events from user interface.
|
||||
|
||||
## Library
|
||||
|
||||
JavaScript is provided by integrating the duktape library. There are
|
||||
[instructions](docs/updating-duktape.md) on how to update the library.
|
||||
|
||||
## Interface binding
|
||||
|
||||
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. The
|
||||
process of [writing bindings](docs/jsbinding.md) is ongoing.
|
||||
163
docs/mainpage.md
163
docs/mainpage.md
@ -3,163 +3,6 @@ NetSurf web browser
|
||||
|
||||
[*](https://bestpractices.coreinfrastructure.org/projects/1037)
|
||||
|
||||
# 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.
|
||||
|
||||
Because of this the user interface has different features in
|
||||
each frontend allowing the browser to be a native application.
|
||||
|
||||
## Frontends
|
||||
|
||||
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
|
||||
messages not output through the GUI.
|
||||
|
||||
## Documented API
|
||||
|
||||
The NetSurf code makes use of Doxygen for code documentation.
|
||||
|
||||
There are several documents which detail specific aspects of the
|
||||
codebase and APIs.
|
||||
|
||||
### Core window
|
||||
|
||||
The [core window API](docs/core-window-interface.md) allows frontends
|
||||
to use generic core code for user interface elements beyond the
|
||||
browser render.
|
||||
|
||||
### Source object caching
|
||||
|
||||
The [source object caching](docs/source-object-backing-store.md)
|
||||
provides a way for downloaded content to be kept on a persistent
|
||||
storage medium such as hard disc to make future retrieval of that
|
||||
content quickly.
|
||||
|
||||
## Javascript
|
||||
|
||||
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.
|
||||
|
||||
### Library
|
||||
|
||||
JavaScript is provided by integrating the duktape library. There are
|
||||
[instructions](docs/updating-duktape.md) on how to update the library.
|
||||
|
||||
### Interface binding
|
||||
|
||||
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. The
|
||||
process of [writing bindings](docs/jsbinding.md) is ongoing.
|
||||
# [Project](docs/project.md)
|
||||
# [User Interface](docs/user-interface.md)
|
||||
# [Development](docs/development.md)
|
||||
|
||||
17
docs/project.md
Normal file
17
docs/project.md
Normal file
@ -0,0 +1,17 @@
|
||||
NetSurf Project
|
||||
===============
|
||||
|
||||
The NetSurf project is developing a document browser for the World
|
||||
Wide Web. It was started in 2002 on the RISC OS platform and has
|
||||
support for numerous operating systems and graphical toolkits.
|
||||
|
||||
NetSurf is very modular and built from many component libraries which
|
||||
provide functionality from GIF image format decoding (libnsgif) to
|
||||
HTML document object model handling (libdom).
|
||||
|
||||
NetSurf browser is open source and is licensed under the GPLv2 (with
|
||||
OpenSSL exception). Many of the supporting libraries are under a MIT
|
||||
licence.
|
||||
|
||||
The [main website](http://www.netsurf-browser.org/) contains links to
|
||||
other resources and additional information.
|
||||
59
docs/user-interface.md
Normal file
59
docs/user-interface.md
Normal file
@ -0,0 +1,59 @@
|
||||
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.
|
||||
|
||||
Because of this the user interface has different features in
|
||||
each frontend allowing the browser to be a native application.
|
||||
|
||||
# Frontends
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user