From f4f67698eb6eb92a8ac606f771401c0c480d0ad5 Mon Sep 17 00:00:00 2001 From: Michael Drake Date: Thu, 1 Aug 2019 16:57:14 +0100 Subject: Docs: Convert GTK doc to markdown. --- docs/building-GTK.md | 311 ++++++++++++++++++++++++--------------------------- 1 file changed, 147 insertions(+), 164 deletions(-) (limited to 'docs') diff --git a/docs/building-GTK.md b/docs/building-GTK.md index 5451a8c32..dd1b7e2f3 100644 --- a/docs/building-GTK.md +++ b/docs/building-GTK.md @@ -1,234 +1,217 @@ --------------------------------------------------------------------------------- - Build Instructions for GTK NetSurf 16 March 2014 --------------------------------------------------------------------------------- +Build Instructions for GTK NetSurf +================================== - This document provides instructions for building the GTK version of NetSurf - and provides guidance on obtaining NetSurf's build dependencies. +This document provides instructions for building the GTK version of NetSurf +and provides guidance on obtaining NetSurf's build dependencies. - GTK NetSurf has been tested on Debian, Ubuntu, Fedora 8, FreeBSD, NetBSD and - Solaris 10. NetSurf requires at minimum GTK 2.12. +GTK NetSurf has been tested on Debian, Ubuntu, Fedora 8, FreeBSD, NetBSD and +Solaris 10. NetSurf requires at minimum GTK 2.12. - Quick Start -============= +Quick Start +----------- - See the QUICK-START document, which provides a simple environment with - which you can fetch, build and install NetSurf and its dependencies. +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. +The QUICK-START is the recommended way to build NetSurf. - Manual building -================= +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. +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 - -------------------- +Obtaining the build dependencies +-------------------------------- - Debian-like OS: +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. - $ apt-get install libgtk2.0-dev libcurl3-dev libpng-dev - $ apt-get install librsvg2-dev libjpeg-dev +### Package installation - If you want to build with gtk 3 replace libgtk2.0-dev with libgtk-3-dev +Debian-like OS: - 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. + $ apt-get install libgtk2.0-dev libcurl3-dev libpng-dev + $ apt-get install librsvg2-dev libjpeg-dev - Fedora: +If you want to build with gtk 3 replace libgtk2.0-dev with libgtk-3-dev - $ yum install curl-devel libpng-devel - $ yum install librsvg2-devel expat-devel +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. - Other: +Fedora: - You'll need to install the development resources for libglade2, libcurl3, - libpng and librsvg. + $ yum install curl-devel libpng-devel + $ yum install librsvg2-devel expat-devel - Libharu - ------- +Other: - NetSurf can use Haru PDF to enable PDF export. Haru PDF can be obtained - from http://libharu.org/. We require libharu 2.2 or later. +You'll need to install the development resources for libglade2, libcurl3, +libpng and librsvg. - | Note: libharu cannot be auto-detected by the Makefile. If you wish to - | enable it, do so by creating a Makefile.config file. +### Preparing your workspace - 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. - 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: - 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 - Make the workspace directory and change to it - --------------------------------------------- + $ mkdir -p ${HOME}/netsurf/workspace + $ cd ${HOME}/netsurf/workspace - $ mkdir -p ${HOME}/netsurf/workspace - $ cd ${HOME}/netsurf/workspace +### Make the temporary install space - Make the temporary install space - -------------------------------- + $ mkdir inst - $ mkdir inst +### Make an environment script - 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 + $ 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 - ---------------------------------------------- +### Change to workspace and source the environment - Whenever you wish to start development in a new shell, run the following: +Whenever you wish to start development in a new shell, run the following: - $ cd ${HOME}/netsurf/workspace - $ source env.sh + $ cd ${HOME}/netsurf/workspace + $ source env.sh - From here on, any commands in this document assume you have sourced your - shell environment. +From here on, any commands in this document assume you have sourced your +shell environment. - The NetSurf project's libraries ---------------------------------- +### The NetSurf project's libraries - The NetSurf project has developed several libraries which are required by - the browser. These are: +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 +| 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 | - To fetch each of these libraries, run the appropriate commands from the - Docs/LIBRARIES file, from within your workspace directory. +To fetch each of these libraries, run the appropriate commands from the +Docs/LIBRARIES file, from within your workspace directory. - To build and install these libraries, simply enter each of their directories - and run: - - $ make install +To build and install these libraries, simply enter each of their directories +and run: - | 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. + $ make install - Now you should have all the NetSurf project libraries built and installed. +> 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. +Now you should have all the NetSurf project libraries built and installed. - Getting the NetSurf source ----------------------------- - From your workspace directory, run the following command to get the NetSurf - source: +### Getting the NetSurf source - $ git clone git://git.netsurf-browser.org/netsurf.git +From your workspace directory, run the following command to get the NetSurf +source: - And change to the 'netsurf' directory: + $ git clone git://git.netsurf-browser.org/netsurf.git - $ cd netsurf +And change to the 'netsurf' directory: - Building and executing NetSurf --------------------------------- + $ cd netsurf - First of all, you should examine the options in Makefile.defaults - and gtk/Makefile.defaults and enable and disable relevant features - as you see fit by editing a Makefile.config file. +Building and executing NetSurf +------------------------------ - 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. +First of all, you should examine the options in Makefile.defaults +and gtk/Makefile.defaults and enable and disable relevant features +as you see fit by editing a Makefile.config file. - 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. +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. - Once done, to build GTK NetSurf on a UNIX-like platform, simply run: +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. - $ make +Once done, to build GTK NetSurf on a UNIX-like platform, simply run: - 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. + $ make - Run NetSurf by executing the "test-nsgtk" shell script: +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. - $ ./test-nsgtk +Run NetSurf by executing the "test-nsgtk" shell script: - This script makes it easy to run the nsgtk binary from the build tree. It - sets up some environment variables which enable NetSurf to find its - resources. + $ ./test-nsgtk - Builtin resources -------------------- +This script makes it easy to run the nsgtk binary from the build tree. It +sets up some environment variables which enable NetSurf to find its +resources. - There are numerous resources that accompany NetSurf, such as the - image files for icons, cursors and the ui builder files that - construct the browsers interface. +### Builtin resources - Some of these resources can be compiled into the browser executable - removing the need to install these resources separately. The GLib - library on which GTK is based provides this functionality to - NetSurf. +There are numerous resources that accompany NetSurf, such as the +image files for icons, cursors and the ui builder files that +construct the browsers interface. - Up until GLib version 2.32 only the GDK pixbuf could be integrated - in this way and is controlled with the NETSURF_USE_INLINE_PIXBUF - variable (set in makefile.config). +Some of these resources can be compiled into the browser executable +removing the need to install these resources separately. The GLib +library on which GTK is based provides this functionality to +NetSurf. - Glib version 2.32 and later integrated support for any file to be a - resource while depreciating the old inline pixbuf interface. NetSurf - gtk executables can integrate many resources using this interface, - configuration is controlled with the NETSURF_USE_GRESOURCE variable. +Up until GLib version 2.32 only the GDK pixbuf could be integrated +in this way and is controlled with the NETSURF_USE_INLINE_PIXBUF +variable (set in makefile.config). - Loading from file is the fallback if a resource has not been - compiled in, because of this if both of these features are - unavailable (or disabled) NetSurf will automatically fall back to - loading all its resources from files. +Glib version 2.32 and later integrated support for any file to be a +resource while depreciating the old inline pixbuf interface. NetSurf +gtk executables can integrate many resources using this interface, +configuration is controlled with the NETSURF_USE_GRESOURCE variable. - The resource initialisation within the browser ensures it can access - all the resources at start time, however it does not verify the - resources are valid so failures could still occur subsequently. This - is especially true for file based resources as they can become - inaccessible after initialisation. +Loading from file is the fallback if a resource has not been +compiled in, because of this if both of these features are +unavailable (or disabled) NetSurf will automatically fall back to +loading all its resources from files. +The resource initialisation within the browser ensures it can access +all the resources at start time, however it does not verify the +resources are valid so failures could still occur subsequently. This +is especially true for file based resources as they can become +inaccessible after initialisation. - Note for packagers -==================== - If you are packaging NetSurf, see the PACKAGING-GTK document. +Note for packagers +------------------ +If you are packaging NetSurf, see the PACKAGING-GTK document. -- cgit v1.2.3