summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMichael Drake <michael.drake@codethink.co.uk>2019-08-01 16:57:14 +0100
committerMichael Drake <michael.drake@codethink.co.uk>2019-08-01 16:57:44 +0100
commitf4f67698eb6eb92a8ac606f771401c0c480d0ad5 (patch)
tree04186e9866fd894e77f899661d0efdcfe48662b7
parent83c9d2017f16be6ef42a590e1eff76006a897d67 (diff)
downloadnetsurf-f4f67698eb6eb92a8ac606f771401c0c480d0ad5.tar.gz
netsurf-f4f67698eb6eb92a8ac606f771401c0c480d0ad5.tar.bz2
Docs: Convert GTK doc to markdown.
-rw-r--r--docs/building-GTK.md311
1 files changed, 147 insertions, 164 deletions
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.