From 703427a48612bf98fba599dfcd6e91485efd5b77 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Fri, 9 Jun 2017 17:28:55 +0100 Subject: Update documentation removing junk and moving to markdown for most text files --- docs/building-Framebuffer.md | 350 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 350 insertions(+) create mode 100644 docs/building-Framebuffer.md (limited to 'docs/building-Framebuffer.md') diff --git a/docs/building-Framebuffer.md b/docs/building-Framebuffer.md new file mode 100644 index 000000000..3c8858a32 --- /dev/null +++ b/docs/building-Framebuffer.md @@ -0,0 +1,350 @@ +-------------------------------------------------------------------------------- + Build Instructions for Framebuffer NetSurf 16 March 2014 +-------------------------------------------------------------------------------- + + This document provides instructions for building the Framebuffer version of + NetSurf and provides guidance on obtaining NetSurf's build dependencies. + + Framebuffer NetSurf has been tested on Ubuntu and Debian. + + Depending on the framebuffer frontend selected the build may need specific + libraries installed, e.g. the SDL port requires SDL1.2 or later + + There are two ways to get NetSurf building. The QUICK-START (recommended), + and the manual build. Whichever you choose, you should read both the + "Fonts", and "Selecting a frontend and appropriate options" sections below. + + + Quick Start +============= + + See the QUICK-START document, which provides a simple environment with + which you can fetch, build and install NetSurf and its dependencies. + + The QUICK-START is the recommended way to build NetSurf. + + + Manual building +================= + + If you can't follow the quick start instructions, you will have to build + NetSurf manually. The instructions for doing this are given below. + + + Obtaining the 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 Git checkouts. + + Package installation + -------------------- + + Debian-like OS: + + $ apt-get install libcurl3-dev libpng-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 Framebuffer + flavour of NetSurf, this won't make a difference at all. + + Fedora: + + $ yum install curl-devel libpng-devel lcms-devel + + Other: + + You'll need to install the development resources for libcurl3 and libpng. + + + Preparing your workspace +-------------------------- + + NetSurf has a number of libraries which must be built in-order and + installed into your workspace. Each library depends on a core build + system which NetSurf projects use. This build system relies on the + presence of things like pkg-config to find libraries and also certain + environment variables in order to work correctly. + + Assuming you are preparing a workspace in /home/netsurf/workspace then + the following steps will set you up: + + Make the workspace directory and change to it + --------------------------------------------- + + $ mkdir -p ${HOME}/netsurf/workspace + $ cd ${HOME}/netsurf/workspace + + Make the temporary install space + -------------------------------- + + $ mkdir inst + + Make an environment script + -------------------------- + $ cat > env.sh <<'EOF' + export PKG_CONFIG_PATH=${HOME}/netsurf/workspace/inst/lib/pkgconfig:: + export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/netsurf/workspace/inst/lib + export PREFIX=${HOME}/netsurf/workspace/inst + EOF + + Change to workspace and source the environment + ---------------------------------------------- + + Whenever you wish to start development in a new shell, run the following: + + $ cd ${HOME}/netsurf/workspace + $ source env.sh + + From here on, any commands in this document assume you have sourced your + shell environment. + + + The NetSurf project's libraries +--------------------------------- + + The NetSurf project has developed several libraries which are required by + the browser. These are: + + BuildSystem -- Shared build system, needed to build the other libraries + 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 + LibNSFB -- Framebuffer abstraction + + To fetch each of these libraries, run the appropriate commands from the + Docs/LIBRARIES file. + + To build and install these libraries, simply enter each of their directories + and run: + + $ 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. + + + Getting the NetSurf source +---------------------------- + + From your workspace directory, run the following command to get the NetSurf + source: + + $ git clone git://git.netsurf-browser.org/netsurf.git + + And change to the 'netsurf' directory: + + $ cd netsurf + + + 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 in 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 "Obtaining NetSurf's + dependencies" section for specifics. + + Once done, to build Framebuffer NetSurf on a UNIX-like platform, simply run: + + $ make TARGET=framebuffer + + 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 your Makefile.config. You may + need to "make clean" before attempting to build after installing the + dependencies. + + Run NetSurf by executing the "nsfb" program: + + $ ./nsfb + + | Note: NetSurf uses certain resources at run time. In order to find these + | resources, it searches three locations: + | + | 1. ~/.netsurf/ + | 2. $NETSURFRES/ + | 3. /usr/share/netsurf/ + | + | In the build tree, the resources are located at + | + | framebuffer/res + | + | Setting $NETSURFRES to point at the resources in the build tree + | will enable you to run NetSurf from here without installation. + | To do this, run: + | + | export NETSURFRES=`pwd`/framebuffer/res + + + Fonts +======= + + The framebuffer port currently has two choices for font + handling. The font handler may be selected at compile time by using + the NETSURF_FB_FONTLIB configuration key. Currently supported values + are internal and freetype + + Internal +---------- + + The internal font system has a single built in monospaced face with + CP467 encoding. The internal font plotter requires no additional + resources and is very fast, it is also aesthetically unappealing. + + Freetype +---------- + + The freetype font system (freetype version 2 API is used) has + support for a number of different font file formats and faces. The + framebuffer font handler takes advantage of the freetype library + caching system to give good performance. + + The font glyphs are, by default, rendered as 256 level transparency + which gives excellent visual results even on small font sizes. + + The default font is the DejaVu trutype font set. The default path they + are sourced from is /usr/share/fonts/truetype/ttf-dejavu/ . + + The compiled in default paths may be altered by setting values in + the user configuration makefile Makefile.config. These values must + be set to the absolute path of the relevant font file including its + .ttf extension. The variables are: + + NETSURF_FB_FONT_SANS_SERIF + NETSURF_FB_FONT_SANS_SERIF_BOLD + NETSURF_FB_FONT_SANS_SERIF_ITALIC + NETSURF_FB_FONT_SANS_SERIF_ITALIC_BOLD + NETSURF_FB_FONT_SERIF + NETSURF_FB_FONT_SERIF_BOLD + NETSURF_FB_FONT_MONOSPACE + NETSURF_FB_FONT_MONOSPACE_BOLD + NETSURF_FB_FONT_CURSIVE + NETSURF_FB_FONT_FANTASY + + The font selection may be changed by placing truetype font files + in the resources path. The resource files will be the generic names + sans_serif.ttf, sans_serif_bold.ttf etc. + + The font system is configured at runtime by several options. The + fb_font_monochrome option causes the renderer to use monochrome + glyph rendering which is faster to plot but slower to render and + much less visually appealing. + + The remaining seven options control the files to be used for font faces. + + fb_face_sans_serif - The sans serif face + fb_face_sans_serif_bold - The bold sans serif face + fb_face_sans_serif_italic - The italic sans serif face + fb_face_sans_serif_italic_bold - The bold italic sans serif face. + fb_face_serif - The serif font + fb_serif_bold - The bold serif font + fb_face_monospace - The monospaced font + fb_face_monospace_bold - The bold monospaced font + fb_face_cursive - The cursive font + fb_face_fantasy - The fantasy font + + Old Freetype +-------------- + + The framebuffer port Freetype font implementation was constructed + using a modern version of the library (2.3.5) to use versions 2.2.1 + and prior the following patch is necessary. + + +Index: framebuffer/font_freetype.c +=================================================================== +--- framebuffer/font_freetype.c (revision 6750) ++++ framebuffer/font_freetype.c (working copy) +@@ -311,6 +311,7 @@ + FT_Glyph glyph; + FT_Error error; + fb_faceid_t *fb_face; ++ FTC_ImageTypeRec trec; + + fb_fill_scalar(style, &srec); + +@@ -318,15 +319,24 @@ + + glyph_index = FTC_CMapCache_Lookup(ft_cmap_cache, srec.face_id, fb_face->cidx, ucs4); + +- error = FTC_ImageCache_LookupScaler(ft_image_cache, +- &srec, +- FT_LOAD_RENDER | +- FT_LOAD_FORCE_AUTOHINT | +- ft_load_type, +- glyph_index, +- &glyph, +- NULL); + ++ trec.face_id = srec.face_id; ++ if (srec.pixel) { ++ trec.width = srec.width; ++ trec.height = srec.height; ++ } else { ++ /* Convert from 1/64 pts to pixels */ ++ trec.width = srec.width * css_screen_dpi / 64 / srec.x_res; ++ trec.height = srec.height * css_screen_dpi / 64 / srec.y_res; ++ } ++ trec.flags = FT_LOAD_RENDER | FT_LOAD_FORCE_AUTOHINT | ft_load_type; ++ ++ error = FTC_ImageCache_Lookup(ft_image_cache, ++ &trec, ++ glyph_index, ++ &glyph, ++ NULL); ++ + return glyph; + } + + + Selecting a frontend and appropriate options +============================================== + + The framebuffer port interfaces to its input and output devices + using the NetSurf Framebuffer library (libnsfb). This library + provides an abstraction layer to input and output devices. + + The surface used by libnsfb is selected by using the -f switch to + NetSurf when executed. A surface in this context is simply the + combination of input and output devices. + + A surface output device may be any linearly mapped area of + memory. The framebuffer may be treated as values at 32, 16 or 8 bits + per pixel. The input device is typically selected to complement the + output device and is completely specific to the surface. + + There are several configuration options which may influence the + framebuffer surfaces. These are: + + fb_refresh - The refresh rate (for physical displays) + fb_depth - The depth (in bits per pixel) of the framebuffer + window_width - The width of the framebuffer + window_height - The height of the framebuffer + + The defaults are for 800 by 600 pixels at 16bpp and 70Hz refresh rate. + + The documentation of libnsfb should be consulted for futher + information about supported frontends and their configuration. + -- cgit v1.2.3