mirrors/netsurf
1
0
Fork 0
mirror of https://github.com/netsurf-browser/netsurf synced 2024-11-26 16:29:36 +03:00
Code Issues Packages Projects Releases Wiki Activity
9e1b4218a1
netsurf/docs/building-Framebuffer.md

351 lines
12 KiB
Markdown
Raw Blame History

--------------------------------------------------------------------------------
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.
Reference in New Issue View Git Blame Copy Permalink