NetSurf
docs/development.md
Go to the documentation of this file.
1 Development
2 ===========
3 
4 [TOC]
5 
6 # Working with the team
7 
8 Generally it is sensible to check with the other developers if you are
9 planning to make a change to NetSurf intended to be merged.
10 
11 We are often about on the IRC channel but failing that the developer
12 mailing list is a good place to try.
13 
14 All the project sources are held in [public git repositories](http://source.netsurf-browser.org/)
15 
16 # Compilation environment
17 
18 Compiling a development edition of NetSurf requires a POSIX style
19 environment. Typically this means a Linux based system although Free
20 BSD, Open BSD, Mac OS X and Haiku all known to work.
21 
22 ## Toolchains
23 
24 Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally
25 relies upon a cross compilation environment which is generated using
26 the makefiles found in our
27 [toolchains](http://source.netsurf-browser.org/toolchains.git/)
28 repository. These toolchains are built by the Continuous Integration
29 (CI) system and the
30 [results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
31 are published as a convenience.
32 
33 ## Quick setup
34 
35 The [quick start guide](docs/quick-start.md) can be used to get a
36 development environment setup quickly and uses the
37 [env.sh](env_8sh_source.html) script the core team utilises.
38 
39 ## Manual setup
40 
41 The Manual environment setup and compilation method is covered by the
42 details in the [netsurf libraries](docs/netsurf-libraries.md) document
43 for the core libraries and then one of the building documents for the
44 specific frontend.
45 
46 - [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md)
47 - [Framebuffer](docs/building-Framebuffer.md)
48 - [GTK](docs/building-GTK.md)
49 - [Haiku (BeOS)](docs/building-Haiku.md)
50 - [Windows Win32](docs/building-Windows.md)
51 
52 These documents are sometimes not completely up to
53 date and the env.sh script should be considered canonical.
54 
55 # Logging
56 
57 The [logging](docs/logging.md) interface controls debug and error
58 messages not output through the GUI.
59 
60 # Unit testing
61 
62 NetSurf [unit tests](docs/unit-testing.md) provide basic test coverage
63 of many core parts of the browser code such as url parsing and utility
64 functions.
65 
66 # Integration testing
67 
68 NetSurf [integration tests](docs/integration-testing.md) use the
69 monkey frontend to operate the browser as a whole. These tests open
70 windows, navigate to websites and render contents as a user might.
71 
72 # New frontend development
73 
74 [Implementing a new frotend](docs/implementing-new-frontend.md) for a
75 toolkit can be challenging and this guide provides an overview and
76 worked example.
77 
78 # Documented API
79 
80 The NetSurf code makes use of Doxygen for code documentation.
81 
82 There are several documents which detail specific aspects of the
83 codebase and APIs.
84 
85 ## Core window
86 
87 The [core window API](docs/core-window-interface.md) allows frontends
88 to use generic core code for user interface elements beyond the
89 browser render.
90 
91 ## Source object caching
92 
93 The [source object caching](docs/source-object-backing-store.md)
94 provides a way for downloaded content to be kept on a persistent
95 storage medium such as hard disc to make future retrieval of that
96 content quickly.
97 
98 # Javascript
99 
100 Javascript provision is split into four parts:
101 - An engine that takes source code and executes it.
102 - Interfaces between the program and the web page.
103 - Browser support to retrieve and manage the source code to be executed.
104 - Browser support for the dispatch of events from user interface.
105 
106 ## Library
107 
108 JavaScript is provided by integrating the duktape library. There are
109 [instructions](docs/updating-duktape.md) on how to update the library.
110 
111 ## Interface binding
112 
113 In order for javascript programs to to interact with the page contents
114 it must use the Document Object Model (DOM) and Cascading Style Sheet
115 Object Model (CSSOM) API.
116 
117 These interfaces are described using web Interface Description
118 Language (IDL) within the relevant specifications
119 (e.g. https://dom.spec.whatwg.org/).
120 
121 Each interface described by the webIDL must be bound (connected) to
122 the browsers internal representation for the DOM or CSS, etc. The
123 process of [writing bindings](docs/jsbinding.md) is ongoing.