From f218297b7764fe282ad03198387bcc3f7ee94fe5 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Sun, 13 Mar 2011 10:51:58 +0000 Subject: Initial building/using monkey docs svn path=/trunk/netsurf/; revision=12015 --- Docs/BUILDING-Monkey | 111 +++++++++++++++++++++++++ Docs/USING-Monkey | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 337 insertions(+) create mode 100644 Docs/BUILDING-Monkey create mode 100644 Docs/USING-Monkey (limited to 'Docs') diff --git a/Docs/BUILDING-Monkey b/Docs/BUILDING-Monkey new file mode 100644 index 000000000..8abd0c798 --- /dev/null +++ b/Docs/BUILDING-Monkey @@ -0,0 +1,111 @@ +-------------------------------------------------------------------------------- + Build Instructions for Monkey NetSurf 13 March 2011 +-------------------------------------------------------------------------------- + + This document provides instructions for building the Monkey + automation version of NetSurf and provides guidance on obtaining + NetSurf's build dependencies. + + Monkey NetSurf has been tested on Ubuntu 10.10/amd64. + + + Building and executing NetSurf + ============================== + + First of all, you should examine the contents of Makefile.defaults + and enable and disable relevant features as you see fit by creating + a Makefile.config file. Some of these options can be automatically + detected and used, and where this is the case they are set to such. + Others cannot be automatically detected from the Makefile, so you + will either need to install the dependencies, or set them to NO. + + You should then obtain NetSurf's dependencies, keeping in mind which options + you have enabled in the configuration file. See the next section for + specifics. + + Once done, to build Monkey NetSurf on a UNIX-like platform, simply run: + + $ make TARGET=monkey + + If that produces errors, you probably don't have some of NetSurf's + build dependencies installed. See "Obtaining NetSurf's dependencies" + below. Or turn off the complaining features in a Makefile.config + file. You may need to "make clean" before attempting to build after + installing the dependencies. + + Run NetSurf by executing the "nsmonkey" command from within the build tree. + + $ ./nsmonkey + + If you are packaging NetSurf, do NOT package nsmonkey. It is a debug tool. + + + Obtaining NetSurf's build dependencies + ====================================== + + Many of NetSurf's dependencies are packaged on various operating systems. + The remainder must be installed manually. Currently, some of the libraries + developed as part of the NetSurf project have not had official releases. + Hopefully they will soon be released with downloadable tarballs and packaged + in common distros. For now, you'll have to make do with svn checkouts. + + Some of NetSurf's own libraries will be installed in /usr/local/ by default. + Fedora, and perhaps some other distributions of Linux, do not ship a + pkg-config that will search here, so you will either need to change where + these libraries install, or do the following before building NetSurf itself; + + $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig + $ export PKG_CONFIG_PATH + + Package installation +---------------------- + + Debian-like OS: + + $ apt-get install libcurl3-dev libxml2-dev + + Recent OS versions might need libcurl4-dev instead of libcurl3-dev but + note that when it has not been built with OpenSSL, the SSL_CTX is not + available and results that certification details won't be presented in case + they are invalid. But as this is currently unimplemented in the GTK + flavour of NetSurf, this won't make a difference at all. + + + The NetSurf project's libraries + ------------------------------- + + The NetSurf project has developed several libraries which are required by + the browser. These are: + + LibParserUtils -- Parser building utility functions + LibWapcaplet -- String internment + Hubbub -- HTML5 compliant HTML parser + LibCSS -- CSS parser and selection engine + LibNSGIF -- GIF format image decoder + LibNSBMP -- BMP and ICO format image decoder + LibROSprite -- RISC OS Sprite format image decoder + + To fetch each of these libraries, run the following commands: + + $ svn co svn://svn.netsurf-browser.org/trunk/libparserutils + $ svn co svn://svn.netsurf-browser.org/trunk/libwapcaplet + $ svn co svn://svn.netsurf-browser.org/trunk/hubbub + $ svn co svn://svn.netsurf-browser.org/trunk/libcss + $ svn co svn://svn.netsurf-browser.org/trunk/libnsgif + $ svn co svn://svn.netsurf-browser.org/trunk/libnsbmp + $ svn co svn://svn.netsurf-browser.org/trunk/librosprite + + To build and install these libraries, simply enter each of their directories + and run: + + $ sudo make install + + | Note: We advise enabling iconv() support in libparserutils, which vastly + | increases the number of supported character sets. To do this, + | create a file called Makefile.config.override in the libparserutils + | directory, containing the following line: + | + | CFLAGS += -DWITH_ICONV_FILTER + | + | For more information, consult the libparserutils README file. + diff --git a/Docs/USING-Monkey b/Docs/USING-Monkey new file mode 100644 index 000000000..7e30a49ad --- /dev/null +++ b/Docs/USING-Monkey @@ -0,0 +1,226 @@ +-------------------------------------------------------------------------------- + Usage Instructions for Monkey NetSurf 13 March 2011 +-------------------------------------------------------------------------------- + + This document provides usage instructions for the Monkey version of + NetSurf. + + Monkey NetSurf has been tested on Ubuntu. + +Overview +======== + + What it is + ---------- + + The NetSurf Monkey front end is a developer debug tool used to + test how the core interacts with the user interface. It allows + the developers to profile NetSurf and to interact with the core + directly as though the developer were a front end. + + What it is not + -------------- + + Monkey is not a tool for building web-crawling robots or indeed + anything other than a debug tool for the NetSurf developers. + + How to interact with nsmonkey + ----------------------------- + + In brief, monkey will produce tagged output on stdout and expect + commands on stdin. Windows are numbered and for the most part + tokens are space separated. In some cases (e.g. title or status) + the final element on the output line is a string which might have + spaces embedded within it. As such, output from nsmonkey should be + parsed a token at a time, so that when such a string is encountered, + the parser can stop splitting and return the rest. + + Top level tags for nsmonkey + --------------------------- + + GENERIC + + WARN, ERROR, DIE + + WINDOW + + DOWNLOAD_WINDOW + + SSLCERT + + 401LOGIN + + In the below, %something% indicates a substitution made by Monkey. + + %url% will be a URL + %id% will be an opaque ID + %n% will be a number + %bool% will be TRUE or FALSE + %str% is a string and will only ever be at the end of an output line. + + Warnings, errors etc + -------------------- + + Warnings (tagged WARN) come from the NetSurf core. + Errors (tagged ERROR) tend to come from Monkey's parsers + Death (tagged DIE) comes from the core and kills Monkey dead. + + Generic messages + ---------------- + + GENERIC STARTED + Monkey has started and is ready for commands + GENERIC CLOSING_DOWN + Monkey has been told to shut down and is doing so + GENERIC FINISHED + Monkey has finished and will now exit + GENERIC LAUNCH URL %url% + The core asked monkey to launch the given URL + GENERIC THUMBNAIL URL %url% + The core asked monkey to thumbnail a content without + a window. + GENERIC POLL BLOCKING + Monkey reached a point where it could sleep waiting for + commands or scheduled timeouts. No fetches nor redraws + were pending. + + Window messages + --------------- + + WINDOW NEW WIN %id% FOR %id% CLONE %id% NEWTAB %bool% + The core asked Monkey to open a new window. The IDs for 'FOR' and + 'CLONE' are core window IDs, the WIN id is a Monkey window ID. + + WINDOW SIZE WIN %id% WIDTH %num% HEIGHT %num% + The window specified has been set to the shown width and height. + + WINDOW DESTROY WIN %id% + The core has instructed Monkey to destroy the named window. + + WINDOW TITLE WIN %id% STR %str% + The core supplied a titlebar title for the given window. + + WINDOW REDRAW WIN %id% + The core asked that Monkey redraw the given window. + + WINDOW GET_DIMENSIONS WIN %id% WIDTH %num% HEIGHT %num% + The core asked Monkey what the dimensions of the window are. + Monkey has to respond immediately and returned the supplied width + and height values to the core. + + WINDOW NEW_CONTENT WIN %id% + The core has informed Monkey that the named window has a new + content object. + + WINDOW NEW_ICON WIN %id% + The core has informed Monkey that the named window hsa a new + icon (favicon) available. + + WINDOW START_THROBBER WIN %id% + The core asked Monkey to start the throbber for the named + window. This indicates to the user that the window is busy. + + WINDOW STOP_THROBBER WIN %id% + The core asked Monkey to stop the throbber for the named + window. This indicates to the user that the window is finished. + + WINDOW SET_SCROLL WIN %id% X %num% Y %num% + The core asked Monkey to set the named window's scroll offsets + to the given X and Y position. + + WINDOW UPDATE_BOX WIN %id% X %num% Y %num% WIDTH %num% HEIGHT %num% + The core asked Monkey to redraw the given portion of the content + display. Note these coordinates refer to the content, not the + viewport which Monkey is simulating. + + WINDOW UPDATE_EXTENT WIN %id% WIDTH %num% HEIGHT %num% + The core has told us that the content in the given window has a + total width and height as shown. This allows us (along with the + window's width and height) to know the scroll limits. + + WINDOW SET_STATUS WIN %id% STR %str% + The core has told us that the given window needs its status bar + updating with the given message. + + WINDOW SET_POINTER WIN %id% POINTER %id% + The core has told us to update the mouse pointer for the given + window to the given pointer ID. + + WINDOW SET_SCALE WIN %id% SCALE %num% + The core has asked us to scale the given window by the given scale + factor. + + WINDOW SET_URL WIN %id% URL %url% + The core has informed us that the given window's URL bar needs + updating to the given url. + + WINDOW GET_SCROLL WIN %id% X %num% Y %num% + The core asked Monkey for the scroll offsets. Monkey returned the + numbers shown for the window named. + + WINDOW SCROLL_START WIN %id% + The core asked Monkey to scroll the named window to the top/left. + + WINDOW POSITION_FRAME WIN %id% X0 %num% Y0 %num% X1 %num% Y1 %num% + The core asked Monkey to position the named window as a frame at + the given coordinates of its parent. + + WINDOW SCROLL_VISIBLE WIN %id% X0 %num% Y0 %num% X1 %num% Y1 %num% + The core asked Monkey to scroll the named window until the + indicated box is visible. + + WINDOW PLACE_CARET WIN %id% X %num% Y %num% HEIGHT %num% + The core asked Monkey to render a caret in the named window at the + indicated position with the indicated height. + + WINDOW REMOVE_CARET WIN %id% + The core asked Monkey to remove any caret in the named window. + + WINDOW SCROLL_START WIN %id% X0 %num% Y0 %num% X1 %num% Y1 %num% + The core asked Monkey to scroll the named window to the start of + the given box. + + WINDOW SELECT_MENU WIN %id% + The core asked Monkey to produce a selection menu for the named + window. + + WINDOW SAVE_LINK WIN %id% URL %url% TITLE %str% + The core asked Monkey to save a link from the given window with + the given URL and anchor title. + + WINDOW THUMBNAIL WIN %id% URL %url% + The core asked Monkey to render a thumbnail for the given window + which is currently at the given URL. + + Download window messages + ------------------------ + + DOWNLOAD_WINDOW CREATE DWIN %id% WIN %id% + The core asked Monkey to create a download window owned by the + given browser window. + + DOWNLOAD_WINDOW DATA DWIN %id% SIZE %num% DATA %str% + The core asked Monkey to update the named download window with + the given byte size and data string. + + DOWNLOAD_WINDOW ERROR DWIN %id% ERROR %str% + The core asked Monkey to update the named download window with + the given error message. + + DOWNLOAD_WINDOW DONE DWIN %id% + The core asked Monkey to destroy the named download window. + + SSL Certificate messages + ------------------------ + + SSLCERT VERIFY CERT %id% URL %url% + The core asked Monkey to say whether or not a given SSL + certificate is OK. + + 401 Login messages + ------------------ + + 401LOGIN OPEN M4 %id% URL %url% REALM %str% + The core asked Monkey to ask for identification for the named + realm at the given URL. + -- cgit v1.2.3