diff --git a/Docs/JavaScript b/Docs/JavaScript deleted file mode 100644 index ced2fbe7c..000000000 --- a/Docs/JavaScript +++ /dev/null @@ -1,16 +0,0 @@ --------------------------------------------------------------------------------- - NetSurf: JavaScript 8 April 2013 --------------------------------------------------------------------------------- - - NetSurf may be built with primitive support for JavaScript. - - | Note: NetSurf's JavaScript handling is currently: - | - | * incomplete, - | * unsupported, - | * disabled by default. - - To test it, you may build NetSurf with JavaScript and ensure NetSurf's - "enable_javascript" run-time configuration option is set to "1". To do this - you may set the option in the frontend's settings GUI, create/edit a Choices - file, or pass --enable_javascript=1 to the executable. diff --git a/Docs/QUICK-START b/Docs/QUICK-START deleted file mode 100644 index 9ff3fb5e9..000000000 --- a/Docs/QUICK-START +++ /dev/null @@ -1,108 +0,0 @@ --------------------------------------------------------------------------------- - Quick Build Steps for NetSurf 24 February 2015 --------------------------------------------------------------------------------- - - This document provides steps for building NetSurf. - - - Grab a temporary env.sh --------------------------- - - $ wget http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh - $ source env.sh - - - Install any packages you need -------------------------------- - - Installs all packages required to build NetSurf and the NetSurf project - libraries. - - $ ns-package-install - - If your package manager is not supported, you will have to install third - party packages manually. - - - Get the NetSurf project source code from Git ----------------------------------------------- - - $ ns-clone - - - Build and install our project libraries ------------------------------------------ - - Updates NetSurf project library sources to latest, builds and installs them. - - $ ns-pull-install - - - Switch to new NetSurf workspace ---------------------------------- - - $ rm env.sh - $ cd ~/dev-netsurf/workspace - $ source env.sh - - - Build and run NetSurf ------------------------ - - $ cd netsurf - - To build the native front end (the GTK front end on Linux, BSDs, etc) you - could do: - - $ make - $ ./nsgtk - - To build the framebuffer front end, you could do: - - $ make TARGET=framebuffer - $ ./nsfb - - - Cross Compiling -================= - - If you are cross compiling, you can follow the above steps, but when sourcing - env.sh, you should set TARGET_ABI to the appropriate triplet for your cross - compiler. For example, to cross compile for RISC OS: - - $ TARGET_ABI=arm-unknown-riscos source env.sh - - After that, the commands such as `ns-package-install` and `ns-pull-install` - will do what is appropriate for the platform you are building for. - - To do the final build of NetSurf, pass the appropriate TARGET to make. For - example, to cross compile for RISC OS: - - $ make TARGET=riscos - - Finally, you can package up your build to transfer to the system you are - developing for. For example, to produce a package for RISC OS: - - $ make TARGET=riscos package - - Getting a cross compiler set up ---------------------------------- - - We maintain cross compilation environments and an SDK for a number of - platforms. These may be found in our toolchains repository. - - $ git clone git://git.netsurf-browser.org/toolchains - - Pre-built versions of the toolchains for Debian systems are often available - via our automated build and test infrastructure: - - http://ci.netsurf-browser.org/builds/toolchains/ - - - Not working? -============== - - If the above steps are inapplicable, or don't work, you can build manually. - Follow the instructions in the BUILDING-* documents in the Docs/ directory - the NetSurf browser source tree. - diff --git a/Docs/core-window-interface b/Docs/core-window-interface deleted file mode 100644 index 83c5f586b..000000000 --- a/Docs/core-window-interface +++ /dev/null @@ -1,679 +0,0 @@ -Core Window Interface -===================== - -The NetSurf core provides an optional API to frontend implementations -which allows a number of "standard" window content interfaces to be -provided. - -The currently available user interfaces are: - - - Cookies - - Global history - - Hotlist - - SSL certificate view - -Although not currently included in future additional user interfaces -will be available for: - - - local history - - browser render - -To be clear these are generic implementations of this functionality -that any frontend may use. Frontends are free to implement these -interfaces in any manner as they see fit, the corewindow interface -simply provides a default. - -core window API ---------------- - -The API is fairly simple and simply involves passing a callback table -and context pointer to the interface element being constructed. - -The header that defines the callback interface is netsurf/core_window.h - -The callback table contains five function pointer interfaces which the -frontend must implement for the core. - - - invalidate - invalidate an area of a window - - - update_size - Update the limits of the window - - - scroll_visible - Scroll the window to make area visible - - - get_window_dimensions - Get window viewport dimensions - - - drag_status - Inform corewindow owner of drag status - -Each callback will be passed the context pointer for the corewindow -instance and the relevant additional information necessary to perform -the operation. - -Each exported user interface element wraps this generic interface with -a concrete implementation. For example the SSL certificate viewer is -initialised with: - -nserror sslcert_viewer_init(struct core_window_callback_table *cw_t, - void *core_window_handle, - struct sslcert_session_data *ssl_d); - -This call creates a context which will display and navigate the ssl -session data passed. The frontend must service the callbacks from the -core to provide the necessary interactions with the frontend windowing -system. - -These actions should ideally use the standard frontend window -processing. So for the GTK frontend when the core calls the invalidate -operation it simply marks the area passed as damaged (using -gtk_widget_queue_draw_area()) and lets the standard expose event cause -the redraw to occur. - -If the frontend needs to redraw an area of a window (perhaps an expose -event occurred or the window has had an area marked as invalid) it -must call the core window API wrappers implementation which will -perform the plot operations required to update an area of the window. - -e.g in the case of ssl certificate viewer - -void sslcert_viewer_redraw(struct sslcert_session_data *ssl_d, - int x, int y, struct rect *clip, - const struct redraw_context *ctx); - -would perform the plot operations for that SSL data window. - -Usage ------ - -The usage pattern that is expected is for a frontend to create a core -window implementation that implements the necessary five API in a -generic way and allows the frontend to provide the specific -specialisation for each of the user interface elements it wishes to -use (cookies, SSL viewer etc). - -The GTK frontend for example: - -has source corewindow.[ch] which implement the five core callbacks -using generic GTK operations (invalidate calls -gtk_widget_queue_draw_area() etc.) and then provides additional -operations on a GTK drawing area object to attach expose event -processing, keypress processing etc. - -The GTK corewindow (not to be confused with the core window API -itself, this is purely the gtk wrapper) is used by ssl_cert.c which -creates a nsgtk_crtvrfy_window structure containing the -nsgtk_corewindow structure. It attaches actual GTK window handles to -this structure and populates elements of nsgtk_corewindow and then -calls sslcert_viewer_init() directly. - -frontend skeleton ------------------ - -An example core window implementation for a frontend ssl certificate -viewer is presented here. This implements the suggested usage above -and provides generic corewindow helpers. - - -frontends/example/corewindow.h ------------------------------- - -/* - * Copyright 2016 Vincent Sanders - * - * This file is part of NetSurf, http://www.netsurf-browser.org/ - * - * NetSurf is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * NetSurf is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - */ - -#ifndef EXAMPLE_COREWINDOW_H -#define EXAMPLE_COREWINDOW_H - -#include "netsurf/core_window.h" - -/** - * example core window state - */ -struct example_corewindow { - - - /* - * Any variables common to any frontend window would go here. - * e.g. drawing area handles, toolkit pointers or other state - */ - example_toolkit_widget *tk_widget; - - - - /** drag status set by core */ - core_window_drag_status drag_staus; - - /** table of callbacks for core window operations */ - struct core_window_callback_table *cb_table; - - /** - * callback to draw on drawable area of example core window - * - * \param example_cw The example core window structure. - * \param r The rectangle of the window that needs updating. - * \return NSERROR_OK on success otherwise apropriate error code - */ - nserror (*draw)(struct example_corewindow *example_cw, struct rect *r); - - /** - * callback for keypress on example core window - * - * \param example_cw The example core window structure. - * \param nskey The netsurf key code. - * \return NSERROR_OK if key processed, - * NSERROR_NOT_IMPLEMENTED if key not processed - * otherwise apropriate error code - */ - nserror (*key)(struct example_corewindow *example_cw, uint32_t nskey); - - /** - * callback for mouse event on example core window - * - * \param example_cw The example core window structure. - * \param mouse_state mouse state - * \param x location of event - * \param y location of event - * \return NSERROR_OK on sucess otherwise apropriate error code. - */ - nserror (*mouse)(struct example_corewindow *example_cw, browser_mouse_state mouse_state, int x, int y); -}; - -/** - * initialise elements of example core window. - * - * As a pre-requisite the draw, key and mouse callbacks must be defined - * - * \param example_cw A example core window structure to initialise - * \return NSERROR_OK on successful initialisation otherwise error code. - */ -nserror example_corewindow_init(struct example_corewindow *example_cw); - -/** - * finalise elements of example core window. - * - * \param example_cw A example core window structure to initialise - * \return NSERROR_OK on successful finalisation otherwise error code. - */ -nserror example_corewindow_fini(struct example_corewindow *example_cw); - -#endif - -frontends/example/corewindow.c ------------------------------- - -/* - * Copyright 2016 Vincent Sanders - * - * This file is part of NetSurf, http://www.netsurf-browser.org/ - * - * NetSurf is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * NetSurf is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - */ - -/** - * \file - * EXAMPLE generic core window interface. - * - * Provides interface for core renderers to the example toolkit drawable area. - * - * This module is an object that must be encapsulated. Client users - * should embed a struct example_corewindow at the beginning of their - * context for this display surface, fill in relevant data and then - * call example_corewindow_init() - * - * The example core window structure requires the callback for draw, key and - * mouse operations. - */ - -#include -#include -#include - -#include "utils/log.h" -#include "utils/utils.h" -#include "utils/messages.h" -#include "utils/utf8.h" -#include "netsurf/keypress.h" -#include "netsurf/mouse.h" -#include "netsurf/plot_style.h" - -/* extremely likely there will be additional headers required in a real frontend */ -#include "example/corewindow.h" - - -/* toolkit event handlers that do generic things and call internal callbacks */ - - -static bool -example_cw_mouse_press_event(toolkit_widget *widget, toolkit_button bt, int x, int y, void *ctx) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)ctx; - - example_cw->mouse(example_cw, state, x, y); - - return true; -} - -static bool -example_cw_keyrelease_event(toolkit_widget *widget, void *ctx) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)ctx; - - example_cw->key(example_cw, keycode); - - return true; -} - - - -/* signal handler for toolkit window redraw */ -static bool -example_cw_draw_event(toolkit_widget *widget, - toolkit_area *tk_area, - void *ctx) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)ctx; - struct rect clip; - - clip.x0 = tk_area.x; - clip.y0 = tk_area.y; - clip.x1 = tk_area.width; - clip.y1 = tk_area.height; - - example_cw->draw(example_cw, &clip); - - return true; -} - - -/** - * callback from core to request a redraw - */ -static nserror -example_cw_invalidate(struct core_window *cw, const struct rect *r) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)cw; - - toolkit_widget_queue_draw_area(example_cw->widget, - r->x0, r->y0, - r->x1 - r->x0, r->y1 - r->y0); -} - - -static void -example_cw_update_size(struct core_window *cw, int width, int height) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)cw; - - toolkit_widget_set_size_request(EXAMPLE_WIDGET(example_cw->drawing_area), - width, height); -} - - -static void -example_cw_scroll_visible(struct core_window *cw, const struct rect *r) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)cw; - - toolkit_scroll_widget(example_cw->widget, r); -} - - -static void -example_cw_get_window_dimensions(struct core_window *cw, int *width, int *height) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)cw; - - *width = toolkit_get_widget_width(example_cw->widget); - *height = toolkit_get_widget_height(example_cw->widget); -} - - -static void -example_cw_drag_status(struct core_window *cw, core_window_drag_status ds) -{ - struct example_corewindow *example_cw = (struct example_corewindow *)cw; - example_cw->drag_staus = ds; -} - - -struct core_window_callback_table example_cw_cb_table = { - .invalidate = example_cw_invalidate, - .update_size = example_cw_update_size, - .scroll_visible = example_cw_scroll_visible, - .get_window_dimensions = example_cw_get_window_dimensions, - .drag_status = example_cw_drag_status -}; - -/* exported function documented example/corewindow.h */ -nserror example_corewindow_init(struct example_corewindow *example_cw) -{ - /* setup the core window callback table */ - example_cw->cb_table = &example_cw_cb_table; - - /* frontend toolkit specific method of causing example_cw_draw_event to be called when a drawing operation is required */ - toolkit_connect_draw_event(example_cw->tk_widget, - example_cw_draw_event, - example_cw); - - /* frontend toolkit specific method of causing example_cw_button_press_event to be called when a button press occours */ - toolkit_connect_button_press_event(example_cw->tk_widget, - example_cw_button_press_event, - example_cw); - - /* frontend toolkit specific method of causing example_cw_button_release_event to be called when a button release occours */ - toolkit_connect_button_release_event(example_cw->tk_widget, - example_cw_button_release_event, - example_cw); - - /* frontend toolkit specific method of causing example_cw_motion_notify_event to be called when there is motion over the widget */ - toolkit_connect_motion_event(example_cw->tk_widget, - example_cw_motion_notify_event, - example_cw); - - /* frontend toolkit specific method of causing example_cw_key_press_event to be called when a key press occours */ - toolkit_connect_button_press_event(example_cw->tk_widget, - example_cw_key_press_event, - example_cw); - - /* frontend toolkit specific method of causing example_cw_key_release_event to be called when a key release occours */ - toolkit_connect_button_release_event(example_cw->tk_widget, - example_cw_key_release_event, - example_cw); - - - return NSERROR_OK; -} - -/* exported interface documented in example/corewindow.h */ -nserror example_corewindow_fini(struct example_corewindow *example_cw) -{ - return NSERROR_OK; -} - - -frontends/example/ssl_cert.h ----------------------------- - -/* - * Copyright 2016 Vincent Sanders - * - * This file is part of NetSurf, http://www.netsurf-browser.org/ - * - * NetSurf is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * NetSurf is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - */ - -#ifndef NETSURF_EXAMPLE_SSL_CERT_H -#define NETSURF_EXAMPLE_SSL_CERT_H 1 - -struct nsurl; -struct ssl_cert_info; - -/** - * Prompt the user to verify a certificate with issuse. - * - * \param url The URL being verified. - * \param certs The certificate to be verified - * \param num The number of certificates to be verified. - * \param cb Callback upon user decision. - * \param cbpw Context pointer passed to cb - * \return NSERROR_OK or error code if prompt creation failed. - */ -nserror example_cert_verify(struct nsurl *url, const struct ssl_cert_info *certs, unsigned long num, nserror (*cb)(bool proceed, void *pw), void *cbpw); - -#endif - -frontends/example/ssl_cert.c ----------------------------- - -/* - * Copyright 2015 Vincent Sanders - * - * This file is part of NetSurf, http://www.netsurf-browser.org/ - * - * NetSurf is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * NetSurf is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - */ - -/** - * \file - * Implementation of example certificate viewing using example core windows. - */ - -#include -#include - -#include "utils/log.h" -#include "netsurf/keypress.h" -#include "netsurf/plotters.h" -#include "desktop/sslcert_viewer.h" - -#include "example/corewindow.h" - - -/** - * EXAMPLE certificate viewing window context - */ -struct example_crtvrfy_window { - /** example core window context */ - struct example_corewindow core; - - /** SSL certificate viewer context data */ - struct sslcert_session_data *ssl_data; -}; - -/** - * destroy a previously created certificate view - */ -static nserror example_crtvrfy_destroy(struct example_crtvrfy_window *crtvrfy_win) -{ - nserror res; - - res = sslcert_viewer_fini(crtvrfy_win->ssl_data); - if (res == NSERROR_OK) { - res = example_corewindow_fini(&crtvrfy_win->core); - toolkit_windown_destroy(crtvrfy_win->window); - free(crtvrfy_win); - } - return res; -} - -static void -example_crtvrfy_accept(ExampleButton *w, gpointer data) -{ - struct example_crtvrfy_window *crtvrfy_win; - crtvrfy_win = (struct example_crtvrfy_window *)data; - - sslcert_viewer_accept(crtvrfy_win->ssl_data); - - example_crtvrfy_destroy(crtvrfy_win); -} - -static void -example_crtvrfy_reject(ExampleWidget *w, gpointer data) -{ - struct example_crtvrfy_window *crtvrfy_win; - crtvrfy_win = (struct example_crtvrfy_window *)data; - - sslcert_viewer_reject(crtvrfy_win->ssl_data); - - example_crtvrfy_destroy(crtvrfy_win); -} - - -/** - * callback for mouse action for certificate verify on core window - * - * \param example_cw The example core window structure. - * \param mouse_state netsurf mouse state on event - * \param x location of event - * \param y location of event - * \return NSERROR_OK on success otherwise apropriate error code - */ -static nserror -example_crtvrfy_mouse(struct example_corewindow *example_cw, - browser_mouse_state mouse_state, - int x, int y) -{ - struct example_crtvrfy_window *crtvrfy_win; - /* technically degenerate container of */ - crtvrfy_win = (struct example_crtvrfy_window *)example_cw; - - sslcert_viewer_mouse_action(crtvrfy_win->ssl_data, mouse_state, x, y); - - return NSERROR_OK; -} - -/** - * callback for keypress for certificate verify on core window - * - * \param example_cw The example core window structure. - * \param nskey The netsurf key code - * \return NSERROR_OK on success otherwise apropriate error code - */ -static nserror -example_crtvrfy_key(struct example_corewindow *example_cw, uint32_t nskey) -{ - struct example_crtvrfy_window *crtvrfy_win; - - /* technically degenerate container of */ - crtvrfy_win = (struct example_crtvrfy_window *)example_cw; - - if (sslcert_viewer_keypress(crtvrfy_win->ssl_data, nskey)) { - return NSERROR_OK; - } - return NSERROR_NOT_IMPLEMENTED; -} - -/** - * callback on draw event for certificate verify on core window - * - * \param example_cw The example core window structure. - * \param r The rectangle of the window that needs updating. - * \return NSERROR_OK on success otherwise apropriate error code - */ -static nserror -example_crtvrfy_draw(struct example_corewindow *example_cw, struct rect *r) -{ - struct redraw_context ctx = { - .interactive = true, - .background_images = true, - .plot = &example_plotters - }; - struct example_crtvrfy_window *crtvrfy_win; - - /* technically degenerate container of */ - crtvrfy_win = (struct example_crtvrfy_window *)example_cw; - - sslcert_viewer_redraw(crtvrfy_win->ssl_data, 0, 0, r, &ctx); - - return NSERROR_OK; -} - -/* exported interface documented in example/ssl_cert.h */ -nserror example_cert_verify(struct nsurl *url, - const struct ssl_cert_info *certs, - unsigned long num, - nserror (*cb)(bool proceed, void *pw), - void *cbpw) -{ - struct example_crtvrfy_window *ncwin; - nserror res; - - ncwin = malloc(sizeof(struct example_crtvrfy_window)); - if (ncwin == NULL) { - return NSERROR_NOMEM; - } - - res = toolkit_create_window(&ncwin->window); - if (res != NSERROR_OK) { - LOG("SSL UI builder init failed"); - free(ncwin); - return res; - } - - /* store the widget that the toolkit is drawing into */ - ncwin->core.widget = toolkit_get_widget(ncwin->window, "SSLDrawingArea")); - - /* would typicaly setup toolkit accept/reject buttons etc. here */ - toolkit_connect_button_press(ncwin->tk_accept_button, - example_crtvrfy_accept, - ncwin); - - - /* initialise example core window */ - ncwin->core.draw = example_crtvrfy_draw; - ncwin->core.key = example_crtvrfy_key; - ncwin->core.mouse = example_crtvrfy_mouse; - - res = example_corewindow_init(&ncwin->core); - if (res != NSERROR_OK) { - free(ncwin); - return res; - } - - /* initialise certificate viewing interface */ - res = sslcert_viewer_create_session_data(num, url, cb, cbpw, certs, - &ncwin->ssl_data); - if (res != NSERROR_OK) { - free(ncwin); - return res; - } - - res = sslcert_viewer_init(ncwin->core.cb_table, - (struct core_window *)ncwin, - ncwin->ssl_data); - if (res != NSERROR_OK) { - free(ncwin); - return res; - } - - toolkit_widget_show(ncwin->window); - - return NSERROR_OK; -} diff --git a/Makefile b/Makefile index 9c3b72e82..0c2933bf8 100644 --- a/Makefile +++ b/Makefile @@ -879,7 +879,7 @@ install: all-program install-$(TARGET) .PHONY: docs -docs: Docs/Doxyfile +docs: docs/Doxyfile doxygen $< diff --git a/content/urldb.c b/content/urldb.c index d702e581b..f5533686e 100644 --- a/content/urldb.c +++ b/content/urldb.c @@ -849,7 +849,7 @@ urldb_iterate_partial_host(struct search_node *root, * * Given: http://www.example.org/a/b/c/d//e * and assuming a path tree: - * . + * ^ * / \ * a1 b1 * / \ diff --git a/desktop/browser.c b/desktop/browser.c index 4b6a5bbd0..e7ff158f9 100644 --- a/desktop/browser.c +++ b/desktop/browser.c @@ -593,7 +593,7 @@ static void browser_window_set_selection(struct browser_window *bw, * scrolls the viewport to ensure the specified rectangle of the * content is shown. * - * \param gw gui_window to scroll + * \param bw window to scroll * \param rect The rectangle to ensure is shown. * \return NSERROR_OK on success or apropriate error code. */ diff --git a/Docs/Doxyfile b/docs/Doxyfile similarity index 99% rename from Docs/Doxyfile rename to docs/Doxyfile index 98f9fd693..f10669316 100644 --- a/Docs/Doxyfile +++ b/docs/Doxyfile @@ -753,7 +753,10 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = frontends/amiga \ +INPUT = docs \ + docs/env.sh \ + docs/UnimplementedJavascript.txt \ + frontends/amiga \ frontends/amiga/stringview \ frontends/atari \ frontends/atari/plot \ @@ -779,8 +782,7 @@ INPUT = frontends/amiga \ content/handlers/javascript \ content/handlers/javascript/duktape \ utils \ - utils/http \ - Docs/UnimplementedJavascript.txt + utils/http # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -805,7 +807,8 @@ FILE_PATTERNS = *.c \ *.y \ *.l \ *.cpp \ - *.m + *.m \ + *.md # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -921,7 +924,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = mainpage.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/Docs/PACKAGING-GTK b/docs/PACKAGING-GTK similarity index 100% rename from Docs/PACKAGING-GTK rename to docs/PACKAGING-GTK diff --git a/Docs/UnimplementedJavascript.txt b/docs/UnimplementedJavascript.txt similarity index 100% rename from Docs/UnimplementedJavascript.txt rename to docs/UnimplementedJavascript.txt diff --git a/Docs/BUILDING-AmigaCross b/docs/building-AmigaCross.md similarity index 100% rename from Docs/BUILDING-AmigaCross rename to docs/building-AmigaCross.md diff --git a/Docs/BUILDING-AmigaOS b/docs/building-AmigaOS.md similarity index 100% rename from Docs/BUILDING-AmigaOS rename to docs/building-AmigaOS.md diff --git a/Docs/BUILDING-Framebuffer b/docs/building-Framebuffer.md similarity index 100% rename from Docs/BUILDING-Framebuffer rename to docs/building-Framebuffer.md diff --git a/Docs/BUILDING-GTK b/docs/building-GTK.md similarity index 100% rename from Docs/BUILDING-GTK rename to docs/building-GTK.md diff --git a/Docs/BUILDING-BeOS b/docs/building-Haiku.md similarity index 100% rename from Docs/BUILDING-BeOS rename to docs/building-Haiku.md diff --git a/Docs/BUILDING-Windows b/docs/building-Windows.md similarity index 100% rename from Docs/BUILDING-Windows rename to docs/building-Windows.md diff --git a/docs/core-window-interface.md b/docs/core-window-interface.md new file mode 100644 index 000000000..09c29990d --- /dev/null +++ b/docs/core-window-interface.md @@ -0,0 +1,677 @@ +Core Window Interface +===================== + +The NetSurf core provides an optional API to frontend implementations +which allows a number of "standard" window content interfaces to be +provided. + +The currently available user interfaces are: + + - Cookies + - Global history + - Hotlist + - SSL certificate view + - local history + +Although not currently included in future additional user interfaces +will be available for the main browser render. + +To be clear these are generic implementations of this functionality +that any frontend may use. Frontends are free to implement these +interfaces in any manner as they see fit, the corewindow interface +simply provides a default. + +core window API +--------------- + +The API is fairly simple and simply involves passing a callback table +and context pointer to the interface element being constructed. + +The header that defines the callback interface is netsurf/core_window.h + +The callback table contains five function pointer interfaces which the +frontend must implement for the core. + + - invalidate + invalidate an area of a window + + - update_size + Update the limits of the window + + - scroll_visible + Scroll the window to make area visible + + - get_window_dimensions + Get window viewport dimensions + + - drag_status + Inform corewindow owner of drag status + +Each callback will be passed the context pointer for the corewindow +instance and the relevant additional information necessary to perform +the operation. + +Each exported user interface element wraps this generic interface with +a concrete implementation. For example the SSL certificate viewer is +initialised with: + + nserror sslcert_viewer_init(struct core_window_callback_table *cw_t, + void *core_window_handle, + struct sslcert_session_data *ssl_d); + +This call creates a context which will display and navigate the ssl +session data passed. The frontend must service the callbacks from the +core to provide the necessary interactions with the frontend windowing +system. + +These actions should ideally use the standard frontend window +processing. So for the GTK frontend when the core calls the invalidate +operation it simply marks the area passed as damaged (using +gtk_widget_queue_draw_area()) and lets the standard expose event cause +the redraw to occur. + +If the frontend needs to redraw an area of a window (perhaps an expose +event occurred or the window has had an area marked as invalid) it +must call the core window API wrappers implementation which will +perform the plot operations required to update an area of the window. + +e.g in the case of ssl certificate viewer + + void sslcert_viewer_redraw(struct sslcert_session_data *ssl_d, + int x, int y, struct rect *clip, + const struct redraw_context *ctx); + +would perform the plot operations for that SSL data window. + +Usage +----- + +The usage pattern that is expected is for a frontend to create a core +window implementation that implements the necessary five API in a +generic way and allows the frontend to provide the specific +specialisation for each of the user interface elements it wishes to +use (cookies, SSL viewer etc). + +The GTK frontend for example: + +has source corewindow.[ch] which implement the five core callbacks +using generic GTK operations (invalidate calls +gtk_widget_queue_draw_area() etc.) and then provides additional +operations on a GTK drawing area object to attach expose event +processing, keypress processing etc. + +The GTK corewindow (not to be confused with the core window API +itself, this is purely the gtk wrapper) is used by ssl_cert.c which +creates a nsgtk_crtvrfy_window structure containing the +nsgtk_corewindow structure. It attaches actual GTK window handles to +this structure and populates elements of nsgtk_corewindow and then +calls sslcert_viewer_init() directly. + +frontend skeleton +----------------- + +An example core window implementation for a frontend ssl certificate +viewer is presented here. This implements the suggested usage above +and provides generic corewindow helpers. + + +frontends/example/corewindow.h +------------------------------ + + /* + * Copyright 2016 Vincent Sanders + * + * This file is part of NetSurf, http://www.netsurf-browser.org/ + * + * NetSurf is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * NetSurf is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + + #ifndef EXAMPLE_COREWINDOW_H + #define EXAMPLE_COREWINDOW_H + + #include "netsurf/core_window.h" + + /** + * example core window state + */ + struct example_corewindow { + + + /* + * Any variables common to any frontend window would go here. + * e.g. drawing area handles, toolkit pointers or other state + */ + example_toolkit_widget *tk_widget; + + + + /** drag status set by core */ + core_window_drag_status drag_staus; + + /** table of callbacks for core window operations */ + struct core_window_callback_table *cb_table; + + /** + * callback to draw on drawable area of example core window + * + * \param example_cw The example core window structure. + * \param r The rectangle of the window that needs updating. + * \return NSERROR_OK on success otherwise apropriate error code + */ + nserror (*draw)(struct example_corewindow *example_cw, struct rect *r); + + /** + * callback for keypress on example core window + * + * \param example_cw The example core window structure. + * \param nskey The netsurf key code. + * \return NSERROR_OK if key processed, + * NSERROR_NOT_IMPLEMENTED if key not processed + * otherwise apropriate error code + */ + nserror (*key)(struct example_corewindow *example_cw, uint32_t nskey); + + /** + * callback for mouse event on example core window + * + * \param example_cw The example core window structure. + * \param mouse_state mouse state + * \param x location of event + * \param y location of event + * \return NSERROR_OK on sucess otherwise apropriate error code. + */ + nserror (*mouse)(struct example_corewindow *example_cw, browser_mouse_state mouse_state, int x, int y); + }; + + /** + * initialise elements of example core window. + * + * As a pre-requisite the draw, key and mouse callbacks must be defined + * + * \param example_cw A example core window structure to initialise + * \return NSERROR_OK on successful initialisation otherwise error code. + */ + nserror example_corewindow_init(struct example_corewindow *example_cw); + + /** + * finalise elements of example core window. + * + * \param example_cw A example core window structure to initialise + * \return NSERROR_OK on successful finalisation otherwise error code. + */ + nserror example_corewindow_fini(struct example_corewindow *example_cw); + + #endif + +frontends/example/corewindow.c +------------------------------ + + /* + * Copyright 2016 Vincent Sanders + * + * This file is part of NetSurf, http://www.netsurf-browser.org/ + * + * NetSurf is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * NetSurf is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + + /** + * file + * EXAMPLE generic core window interface. + * + * Provides interface for core renderers to the example toolkit drawable area. + * + * This module is an object that must be encapsulated. Client users + * should embed a struct example_corewindow at the beginning of their + * context for this display surface, fill in relevant data and then + * call example_corewindow_init() + * + * The example core window structure requires the callback for draw, key and + * mouse operations. + */ + + #include + #include + #include + + #include "utils/log.h" + #include "utils/utils.h" + #include "utils/messages.h" + #include "utils/utf8.h" + #include "netsurf/keypress.h" + #include "netsurf/mouse.h" + #include "netsurf/plot_style.h" + + /* extremely likely there will be additional headers required in a real frontend */ + #include "example/corewindow.h" + + + /* toolkit event handlers that do generic things and call internal callbacks */ + + + static bool + example_cw_mouse_press_event(toolkit_widget *widget, toolkit_button bt, int x, int y, void *ctx) + { + struct example_corewindow *example_cw = (struct example_corewindow *)ctx; + + example_cw->mouse(example_cw, state, x, y); + + return true; + } + + static bool + example_cw_keyrelease_event(toolkit_widget *widget, void *ctx) + { + struct example_corewindow *example_cw = (struct example_corewindow *)ctx; + + example_cw->key(example_cw, keycode); + + return true; + } + + + + /* signal handler for toolkit window redraw */ + static bool + example_cw_draw_event(toolkit_widget *widget, + toolkit_area *tk_area, + void *ctx) + { + struct example_corewindow *example_cw = (struct example_corewindow *)ctx; + struct rect clip; + + clip.x0 = tk_area.x; + clip.y0 = tk_area.y; + clip.x1 = tk_area.width; + clip.y1 = tk_area.height; + + example_cw->draw(example_cw, &clip); + + return true; + } + + + /** + * callback from core to request a redraw + */ + static nserror + example_cw_invalidate(struct core_window *cw, const struct rect *r) + { + struct example_corewindow *example_cw = (struct example_corewindow *)cw; + + toolkit_widget_queue_draw_area(example_cw->widget, + r->x0, r->y0, + r->x1 - r->x0, r->y1 - r->y0); + } + + + static void + example_cw_update_size(struct core_window *cw, int width, int height) + { + struct example_corewindow *example_cw = (struct example_corewindow *)cw; + + toolkit_widget_set_size_request(EXAMPLE_WIDGET(example_cw->drawing_area), + width, height); + } + + + static void + example_cw_scroll_visible(struct core_window *cw, const struct rect *r) + { + struct example_corewindow *example_cw = (struct example_corewindow *)cw; + + toolkit_scroll_widget(example_cw->widget, r); + } + + + static void + example_cw_get_window_dimensions(struct core_window *cw, int *width, int *height) + { + struct example_corewindow *example_cw = (struct example_corewindow *)cw; + + *width = toolkit_get_widget_width(example_cw->widget); + *height = toolkit_get_widget_height(example_cw->widget); + } + + + static void + example_cw_drag_status(struct core_window *cw, core_window_drag_status ds) + { + struct example_corewindow *example_cw = (struct example_corewindow *)cw; + example_cw->drag_staus = ds; + } + + + struct core_window_callback_table example_cw_cb_table = { + .invalidate = example_cw_invalidate, + .update_size = example_cw_update_size, + .scroll_visible = example_cw_scroll_visible, + .get_window_dimensions = example_cw_get_window_dimensions, + .drag_status = example_cw_drag_status + }; + + /* exported function documented example/corewindow.h */ + nserror example_corewindow_init(struct example_corewindow *example_cw) + { + /* setup the core window callback table */ + example_cw->cb_table = &example_cw_cb_table; + + /* frontend toolkit specific method of causing example_cw_draw_event to be called when a drawing operation is required */ + toolkit_connect_draw_event(example_cw->tk_widget, + example_cw_draw_event, + example_cw); + + /* frontend toolkit specific method of causing example_cw_button_press_event to be called when a button press occours */ + toolkit_connect_button_press_event(example_cw->tk_widget, + example_cw_button_press_event, + example_cw); + + /* frontend toolkit specific method of causing example_cw_button_release_event to be called when a button release occours */ + toolkit_connect_button_release_event(example_cw->tk_widget, + example_cw_button_release_event, + example_cw); + + /* frontend toolkit specific method of causing example_cw_motion_notify_event to be called when there is motion over the widget */ + toolkit_connect_motion_event(example_cw->tk_widget, + example_cw_motion_notify_event, + example_cw); + + /* frontend toolkit specific method of causing example_cw_key_press_event to be called when a key press occours */ + toolkit_connect_button_press_event(example_cw->tk_widget, + example_cw_key_press_event, + example_cw); + + /* frontend toolkit specific method of causing example_cw_key_release_event to be called when a key release occours */ + toolkit_connect_button_release_event(example_cw->tk_widget, + example_cw_key_release_event, + example_cw); + + + return NSERROR_OK; + } + + /* exported interface documented in example/corewindow.h */ + nserror example_corewindow_fini(struct example_corewindow *example_cw) + { + return NSERROR_OK; + } + + +frontends/example/ssl_cert.h +---------------------------- + + /* + * Copyright 2016 Vincent Sanders + * + * This file is part of NetSurf, http://www.netsurf-browser.org/ + * + * NetSurf is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * NetSurf is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + + #ifndef NETSURF_EXAMPLE_SSL_CERT_H + #define NETSURF_EXAMPLE_SSL_CERT_H 1 + + struct nsurl; + struct ssl_cert_info; + + /** + * Prompt the user to verify a certificate with issuse. + * + * \param url The URL being verified. + * \param certs The certificate to be verified + * \param num The number of certificates to be verified. + * \param cb Callback upon user decision. + * \param cbpw Context pointer passed to cb + * \return NSERROR_OK or error code if prompt creation failed. + */ + nserror example_cert_verify(struct nsurl *url, const struct ssl_cert_info *certs, unsigned long num, nserror (*cb)(bool proceed, void *pw), void *cbpw); + + #endif + +frontends/example/ssl_cert.c +---------------------------- + + /* + * Copyright 2015 Vincent Sanders + * + * This file is part of NetSurf, http://www.netsurf-browser.org/ + * + * NetSurf is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * NetSurf is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + + /** + * file + * Implementation of example certificate viewing using example core windows. + */ + + #include + #include + + #include "utils/log.h" + #include "netsurf/keypress.h" + #include "netsurf/plotters.h" + #include "desktop/sslcert_viewer.h" + + #include "example/corewindow.h" + + + /** + * EXAMPLE certificate viewing window context + */ + struct example_crtvrfy_window { + /** example core window context */ + struct example_corewindow core; + + /** SSL certificate viewer context data */ + struct sslcert_session_data *ssl_data; + }; + + /** + * destroy a previously created certificate view + */ + static nserror example_crtvrfy_destroy(struct example_crtvrfy_window *crtvrfy_win) + { + nserror res; + + res = sslcert_viewer_fini(crtvrfy_win->ssl_data); + if (res == NSERROR_OK) { + res = example_corewindow_fini(&crtvrfy_win->core); + toolkit_windown_destroy(crtvrfy_win->window); + free(crtvrfy_win); + } + return res; + } + + static void + example_crtvrfy_accept(ExampleButton *w, gpointer data) + { + struct example_crtvrfy_window *crtvrfy_win; + crtvrfy_win = (struct example_crtvrfy_window *)data; + + sslcert_viewer_accept(crtvrfy_win->ssl_data); + + example_crtvrfy_destroy(crtvrfy_win); + } + + static void + example_crtvrfy_reject(ExampleWidget *w, gpointer data) + { + struct example_crtvrfy_window *crtvrfy_win; + crtvrfy_win = (struct example_crtvrfy_window *)data; + + sslcert_viewer_reject(crtvrfy_win->ssl_data); + + example_crtvrfy_destroy(crtvrfy_win); + } + + + /** + * callback for mouse action for certificate verify on core window + * + * \param example_cw The example core window structure. + * \param mouse_state netsurf mouse state on event + * \param x location of event + * \param y location of event + * \return NSERROR_OK on success otherwise apropriate error code + */ + static nserror + example_crtvrfy_mouse(struct example_corewindow *example_cw, + browser_mouse_state mouse_state, + int x, int y) + { + struct example_crtvrfy_window *crtvrfy_win; + /* technically degenerate container of */ + crtvrfy_win = (struct example_crtvrfy_window *)example_cw; + + sslcert_viewer_mouse_action(crtvrfy_win->ssl_data, mouse_state, x, y); + + return NSERROR_OK; + } + + /** + * callback for keypress for certificate verify on core window + * + * \param example_cw The example core window structure. + * \param nskey The netsurf key code + * \return NSERROR_OK on success otherwise apropriate error code + */ + static nserror + example_crtvrfy_key(struct example_corewindow *example_cw, uint32_t nskey) + { + struct example_crtvrfy_window *crtvrfy_win; + + /* technically degenerate container of */ + crtvrfy_win = (struct example_crtvrfy_window *)example_cw; + + if (sslcert_viewer_keypress(crtvrfy_win->ssl_data, nskey)) { + return NSERROR_OK; + } + return NSERROR_NOT_IMPLEMENTED; + } + + /** + * callback on draw event for certificate verify on core window + * + * \param example_cw The example core window structure. + * \param r The rectangle of the window that needs updating. + * \return NSERROR_OK on success otherwise apropriate error code + */ + static nserror + example_crtvrfy_draw(struct example_corewindow *example_cw, struct rect *r) + { + struct redraw_context ctx = { + .interactive = true, + .background_images = true, + .plot = &example_plotters + }; + struct example_crtvrfy_window *crtvrfy_win; + + /* technically degenerate container of */ + crtvrfy_win = (struct example_crtvrfy_window *)example_cw; + + sslcert_viewer_redraw(crtvrfy_win->ssl_data, 0, 0, r, &ctx); + + return NSERROR_OK; + } + + /* exported interface documented in example/ssl_cert.h */ + nserror example_cert_verify(struct nsurl *url, + const struct ssl_cert_info *certs, + unsigned long num, + nserror (*cb)(bool proceed, void *pw), + void *cbpw) + { + struct example_crtvrfy_window *ncwin; + nserror res; + + ncwin = malloc(sizeof(struct example_crtvrfy_window)); + if (ncwin == NULL) { + return NSERROR_NOMEM; + } + + res = toolkit_create_window(&ncwin->window); + if (res != NSERROR_OK) { + LOG("SSL UI builder init failed"); + free(ncwin); + return res; + } + + /* store the widget that the toolkit is drawing into */ + ncwin->core.widget = toolkit_get_widget(ncwin->window, "SSLDrawingArea")); + + /* would typicaly setup toolkit accept/reject buttons etc. here */ + toolkit_connect_button_press(ncwin->tk_accept_button, + example_crtvrfy_accept, + ncwin); + + + /* initialise example core window */ + ncwin->core.draw = example_crtvrfy_draw; + ncwin->core.key = example_crtvrfy_key; + ncwin->core.mouse = example_crtvrfy_mouse; + + res = example_corewindow_init(&ncwin->core); + if (res != NSERROR_OK) { + free(ncwin); + return res; + } + + /* initialise certificate viewing interface */ + res = sslcert_viewer_create_session_data(num, url, cb, cbpw, certs, + &ncwin->ssl_data); + if (res != NSERROR_OK) { + free(ncwin); + return res; + } + + res = sslcert_viewer_init(ncwin->core.cb_table, + (struct core_window *)ncwin, + ncwin->ssl_data); + if (res != NSERROR_OK) { + free(ncwin); + return res; + } + + toolkit_widget_show(ncwin->window); + + return NSERROR_OK; + } diff --git a/Docs/env.sh b/docs/env.sh similarity index 98% rename from Docs/env.sh rename to docs/env.sh index 9cfc95650..518123e2f 100644 --- a/Docs/env.sh +++ b/docs/env.sh @@ -272,8 +272,8 @@ ns-clone() done # put current env.sh in place in workspace - if [ ! -f "${TARGET_WORKSPACE}/env.sh" -a -f ${TARGET_WORKSPACE}/${NS_BROWSER}/Docs/env.sh ]; then - cp ${TARGET_WORKSPACE}/${NS_BROWSER}/Docs/env.sh ${TARGET_WORKSPACE}/env.sh + if [ ! -f "${TARGET_WORKSPACE}/env.sh" -a -f ${TARGET_WORKSPACE}/${NS_BROWSER}/docs/env.sh ]; then + cp ${TARGET_WORKSPACE}/${NS_BROWSER}/docs/env.sh ${TARGET_WORKSPACE}/env.sh fi } diff --git a/Docs/gource.sh b/docs/gource.sh similarity index 100% rename from Docs/gource.sh rename to docs/gource.sh diff --git a/Docs/ideas/cache.txt b/docs/ideas/cache.txt similarity index 100% rename from Docs/ideas/cache.txt rename to docs/ideas/cache.txt diff --git a/Docs/ideas/css-engine.txt b/docs/ideas/css-engine.txt similarity index 100% rename from Docs/ideas/css-engine.txt rename to docs/ideas/css-engine.txt diff --git a/Docs/ideas/render-library.txt b/docs/ideas/render-library.txt similarity index 100% rename from Docs/ideas/render-library.txt rename to docs/ideas/render-library.txt diff --git a/docs/mainpage.md b/docs/mainpage.md new file mode 100644 index 000000000..c1b7a0c21 --- /dev/null +++ b/docs/mainpage.md @@ -0,0 +1,91 @@ +NetSurf web browser +=================== + +The NetSurf code makes use of Doxygen for code documentation. + +User Interface +-------------- + +There are some basic user guides for the +[framebuffer](docs/using-framebuffer.md) and +[monkey](docs/using-monkey.md) frontends. + +The [core user options](docs/netsurf-options.md) of the browser are +documented which are augmented by each frontend in a specific manner. + +Documented API +-------------- + +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 is provided by integrating the duktape library. There are [instructions](docs/updating-duktape.md) on how to update the library. + +A list of [unimplemented DOM and CSSOM methods](unimplemented.html) +is available outlining the remaining API that have to be implemented. + +Development +----------- + +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. + +### 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/) + +### 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. + diff --git a/Docs/netsurf-fb.1 b/docs/netsurf-fb.1 similarity index 100% rename from Docs/netsurf-fb.1 rename to docs/netsurf-fb.1 diff --git a/Docs/netsurf-gtk.1 b/docs/netsurf-gtk.1 similarity index 100% rename from Docs/netsurf-gtk.1 rename to docs/netsurf-gtk.1 diff --git a/Docs/LIBRARIES b/docs/netsurf-libraries.md similarity index 100% rename from Docs/LIBRARIES rename to docs/netsurf-libraries.md diff --git a/Docs/Options b/docs/netsurf-options.md similarity index 100% rename from Docs/Options rename to docs/netsurf-options.md diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 000000000..8bc90de81 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,111 @@ +Quick Build Steps for NetSurf +============================= + +Last Updated: 24 February 2015 + +This document provides steps for building NetSurf. + + +Grab a temporary env.sh +----------------------- + + $ wget http://git.netsurf-browser.org/netsurf.git/plain/docs/env.sh + $ source env.sh + + +Install any packages you need +----------------------------- + +Installs all packages required to build NetSurf and the NetSurf project +libraries. + + $ ns-package-install + +If your package manager is not supported, you will have to install third + party packages manually. + + +Get the NetSurf project source code from Git +-------------------------------------------- + + $ ns-clone + + +Build and install our project libraries +--------------------------------------- + +Updates NetSurf project library sources to latest, builds and installs them. + + $ ns-pull-install + + +Switch to new NetSurf workspace +------------------------------- + +Remove the bootstrack script and use the newly installed one + + $ rm env.sh + $ cd ~/dev-netsurf/workspace + $ source env.sh + + +Build and run NetSurf +--------------------- + + $ cd netsurf + +To build the native front end (the GTK front end on Linux, BSDs, etc) you +could do: + + $ make + $ ./nsgtk + +To build the framebuffer front end, you could do: + + $ make TARGET=framebuffer + $ ./nsfb + + +Cross Compiling +=============== + +If you are cross compiling, you can follow the above steps, but when +sourcing env.sh, you should set HOST environment variable to the +appropriate triplet for your cross compiler. For example, to cross +compile for RISC OS: + + $ HOST=arm-unknown-riscos source env.sh + +After that, the commands such as `ns-package-install` and +`ns-pull-install` will do what is appropriate for the platform you +are building for. + +To do the final build of NetSurf, pass the appropriate TARGET to make. +For example, to cross compile for RISC OS: + + $ make TARGET=riscos + +Finally, you can package up your build to transfer to the system you +are developing for. For example, to produce a package for RISC OS: + + $ make TARGET=riscos package + +Getting a cross compiler set up +------------------------------- + +We maintain cross compilation environments and an SDK for a number of +platforms. These may be found in our toolchains repository. + + $ git clone git://git.netsurf-browser.org/toolchains + +Pre-built versions of the toolchains for Debian systems are often available +via our [automated build and test infrastructure](http://ci.netsurf-browser.org/builds/toolchains/) + + +Not working? +============ + +If the above steps are inapplicable, or don't work, you can build manually. +Follow the instructions in the BUILDING-* documents in the docs/ directory +the NetSurf browser source tree. + diff --git a/Docs/source-object-backing-store b/docs/source-object-backing-store.md similarity index 100% rename from Docs/source-object-backing-store rename to docs/source-object-backing-store.md diff --git a/Docs/unit-testing b/docs/unit-testing similarity index 100% rename from Docs/unit-testing rename to docs/unit-testing diff --git a/Docs/updating-duktape.md b/docs/updating-duktape.md similarity index 72% rename from Docs/updating-duktape.md rename to docs/updating-duktape.md index a3e5a79b1..672fccc89 100644 --- a/Docs/updating-duktape.md +++ b/docs/updating-duktape.md @@ -13,11 +13,11 @@ Updating Duktape 2. Run the following command: - python2 tools/configure.py \ - --output-directory /tmp/output \ - --source-directory src-input \ - --config-metadata config \ - --fixup-line '#include "duk_custom.h"' + python2 tools/configure.py \ + --output-directory /tmp/output \ + --source-directory src-input \ + --config-metadata config \ + --fixup-line '#include "duk_custom.h"' 3. This generates a suitable set of duktape sources in `/tmp/output` diff --git a/Docs/USING-Framebuffer b/docs/using-framebuffer.md similarity index 100% rename from Docs/USING-Framebuffer rename to docs/using-framebuffer.md diff --git a/Docs/USING-Monkey b/docs/using-monkey.md similarity index 100% rename from Docs/USING-Monkey rename to docs/using-monkey.md diff --git a/frontends/amiga/corewindow.c b/frontends/amiga/corewindow.c index 6b2d9e8c6..776becdc5 100644 --- a/frontends/amiga/corewindow.c +++ b/frontends/amiga/corewindow.c @@ -806,7 +806,7 @@ static const struct ami_win_event_table ami_cw_table = { * invalidated. * * \param[in] cw The core window to invalidate. - * \param[in] rect area to redraw or NULL for the entire window area. + * \param[in] r area to redraw or NULL for the entire window area. * \return NSERROR_OK on success or appropriate error code. */ static nserror diff --git a/frontends/amiga/gui.c b/frontends/amiga/gui.c index 7eacda784..31687589d 100644 --- a/frontends/amiga/gui.c +++ b/frontends/amiga/gui.c @@ -4986,7 +4986,7 @@ static bool gui_window_get_scroll(struct gui_window *g, int *restrict sx, int *r * content is shown. The amiga implementation scrolls the contents so * the specified point in the content is at the top of the viewport. * - * \param gw gui_window to scroll + * \param g gui_window to scroll * \param rect The rectangle to ensure is shown. * \return NSERROR_OK on success or apropriate error code. */ diff --git a/frontends/gtk/window.c b/frontends/gtk/window.c index 78a6f6274..de5311e2e 100644 --- a/frontends/gtk/window.c +++ b/frontends/gtk/window.c @@ -1048,7 +1048,7 @@ static void gui_window_set_status(struct gui_window *g, const char *text) * content is shown. The GTK implementation scrolls the contents so * the specified point in the content is at the top of the viewport. * - * \param gw gui window to scroll + * \param g gui window to scroll * \param rect The rectangle to ensure is shown. * \return NSERROR_OK on success or apropriate error code. */ diff --git a/frontends/riscos/window.c b/frontends/riscos/window.c index de0fcab2b..4fb404e34 100644 --- a/frontends/riscos/window.c +++ b/frontends/riscos/window.c @@ -3948,9 +3948,8 @@ void ro_gui_window_action_new_window(struct gui_window *g) /** * Open a local history pane for a browser window. * - * \param g The browser window to act on. + * \param gw The browser window to act on. */ - void ro_gui_window_action_local_history(struct gui_window *gw) { nserror res;