summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/Doxyfile3
-rw-r--r--docs/PACKAGING-GTK3
-rw-r--r--docs/env.sh319
-rw-r--r--docs/logging.md10
-rw-r--r--docs/quick-start.md47
5 files changed, 228 insertions, 154 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile
index f10669316..9f72bc186 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -773,7 +773,6 @@ INPUT = docs \
frontends/riscos/scripts \
frontends/windows \
include/netsurf \
- render \
desktop \
content \
content/fetchers \
@@ -781,6 +780,8 @@ INPUT = docs \
content/handlers/css \
content/handlers/javascript \
content/handlers/javascript/duktape \
+ content/handlers/html \
+ content/handlers/text \
utils \
utils/http
diff --git a/docs/PACKAGING-GTK b/docs/PACKAGING-GTK
index 8f675229f..7436f238e 100644
--- a/docs/PACKAGING-GTK
+++ b/docs/PACKAGING-GTK
@@ -24,8 +24,7 @@
The GTK port of NetSurf requires access to some resources at run time.
These are stored in gtk/res/ in the source tree. Some of these files are
- symlinks into the !NetSurf directory, which is the application container
- for the native RISC OS build. None of the other files from the !NetSurf
+ symlinks into the top level resources directory. Not all of the files in the
directory are required - the symlinks are used only as a way of making
checkouts smaller and making sure changes to one set of resources updates
the other.
diff --git a/docs/env.sh b/docs/env.sh
index 8a82ad083..b9adb92f9 100644
--- a/docs/env.sh
+++ b/docs/env.sh
@@ -1,22 +1,188 @@
#!/bin/sh
#
-# NetSurf Library, tool and browser support script
+# NetSurf Library, tool and browser development support script
#
-# Usage: source env.sh
-# TARGET_ABI / HOST sets the target for library builds
-# TARGET_WORKSPACE is the workspace directory to keep the sandboxes
+# Copyright 2013-2017 Vincent Sanders <vince@netsurf-browser.org>
+# Released under the MIT Licence
#
# This script allows NetSurf and its libraries to be built without
# requiring installation into a system.
#
-# Copyright 2013 Vincent Sanders <vince@netsurf-browser.org>
-# Released under the MIT Licence
+# Usage: source env.sh
+#
+# Controlling variables
+# HOST sets the target architecture for library builds
+# BUILD sets the building machines architecture
+# TARGET_WORKSPACE is the workspace directory to keep the sandboxes
+#
+# The use of HOST and BUILD here is directly comprable to the GCC
+# usage as described at:
+# http://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html
+#
+
+###############################################################################
+# OS Package installation
+###############################################################################
+
+# deb packages for dpkg based systems
+NS_DEV_DEB="build-essential pkg-config git gperf libcurl3-dev libpng-dev libjpeg-dev"
+NS_TOOL_DEB="flex bison libhtml-parser-perl"
+if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
+ NS_GTK_DEB="libgtk-3-dev librsvg2-dev"
+else
+ NS_GTK_DEB="libgtk2.0-dev librsvg2-dev"
+fi
+
+# apt get commandline to install necessary dev packages
+ns-apt-get-install()
+{
+ if /usr/bin/apt-cache show libssl1.0-dev >/dev/null 2>&1; then
+ NS_DEV_DEB="${NS_DEV_DEB} libssl1.0-dev"
+ else
+ NS_DEV_DEB="${NS_DEV_DEB} libssl-dev"
+ fi
+ sudo apt-get install $(echo ${NS_DEV_DEB} ${NS_TOOL_DEB} ${NS_GTK_DEB})
+}
+
+
+# packages for yum installer RPM based systems (tested on fedora 20)
+NS_DEV_YUM_RPM="git gcc pkgconfig expat-devel openssl-devel gperf libcurl-devel perl-Digest-MD5-File libjpeg-devel libpng-devel"
+NS_TOOL_YUM_RPM="flex bison"
+if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
+ NS_GTK_YUM_RPM="gtk3-devel librsvg2-devel"
+else
+ NS_GTK_YUM_RPM="gtk2-devel librsvg2-devel"
+fi
+
+# yum commandline to install necessary dev packages
+ns-yum-install()
+{
+ sudo yum -y install $(echo ${NS_DEV_YUM_RPM} ${NS_TOOL_YUM_RPM} ${NS_GTK_YUM_RPM})
+}
+
+
+# packages for dnf installer RPM based systems (tested on fedora 25)
+NS_DEV_DNF_RPM="java-1.8.0-openjdk-headless gcc clang pkgconfig libcurl-devel libjpeg-devel expat-devel libpng-devel openssl-devel gperf perl-HTML-Parser"
+NS_TOOL_DNF_RPM="git flex bison ccache screen"
+if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
+ NS_GTK_DNF_RPM="gtk3-devel"
+else
+ NS_GTK_DNF_RPM="gtk2-devel"
+fi
+
+# dnf commandline to install necessary dev packages
+ns-dnf-install()
+{
+ sudo dnf install $(echo ${NS_DEV_DNF_RPM} ${NS_TOOL_DNF_RPM} ${NS_GTK_DNF_RPM})
+}
+
+
+# packages for zypper installer RPM based systems (tested on openSUSE leap 42)
+NS_DEV_ZYP_RPM="java-1_8_0-openjdk-headless gcc clang pkgconfig libcurl-devel libjpeg-devel libexpat-devel libpng-devel openssl-devel gperf perl-HTML-Parser"
+NS_TOOL_ZYP_RPM="git flex bison gperf ccache screen"
+if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
+ NS_GTK_ZYP_RPM="gtk3-devel"
+else
+ NS_GTK_ZYP_RPM="gtk2-devel"
+fi
+
+# zypper commandline to install necessary dev packages
+ns-zypper-install()
+{
+ sudo zypper install -y $(echo ${NS_DEV_ZYP_RPM} ${NS_TOOL_ZYP_RPM} ${NS_GTK_ZYP_RPM})
+}
+
+
+# Packages for Haiku install
+
+# Haiku secondary arch suffix:
+# empty for primary (gcc2 on x86) or "_x86" for gcc4 secondary.
+HA=_x86
+
+NS_DEV_HPKG="devel:libcurl${HA} devel:libpng${HA} devel:libjpeg${HA} devel:libcrypto${HA} devel:libiconv${HA} devel:libexpat${HA} cmd:pkg_config${HA} cmd:gperf html_parser"
+
+# pkgman commandline to install necessary dev packages
+ns-pkgman-install()
+{
+ pkgman install $(echo ${NS_DEV_HPKG})
+}
+
+
+# MAC OS X
+NS_DEV_MACPORT="git expat openssl curl libjpeg-turbo libpng"
+
+ns-macport-install()
+{
+ PATH=/opt/local/bin:/opt/local/sbin:$PATH sudo /opt/local/bin/port install $(echo ${NS_DEV_MACPORT})
+}
+
+
+# packages for FreeBSD install
+NS_DEV_FREEBSDPKG="gmake curl"
+
+# FreeBSD package install
+ns-freebsdpkg-install()
+{
+ pkg install $(echo ${NS_DEV_FREEBSDPKG})
+}
+
+
+# generic for help text
+NS_DEV_GEN="git, gcc, pkgconfig, expat library, openssl library, libcurl, perl, perl MD5 digest, libjpeg library, libpng library"
+NS_TOOL_GEN="flex tool, bison tool"
+if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
+ NS_GTK_GEN="gtk+ 3 toolkit library, librsvg2 library"
+else
+ NS_GTK_GEN="gtk+ 2 toolkit library, librsvg2 library"
+fi
+
+# Generic OS package install
+# looks for package managers and tries to use them if present
+ns-package-install()
+{
+ if [ -x "/usr/bin/zypper" ]; then
+ ns-zypper-install
+ elif [ -x "/usr/bin/apt-get" ]; then
+ ns-apt-get-install
+ elif [ -x "/usr/bin/dnf" ]; then
+ ns-dnf-install
+ elif [ -x "/usr/bin/yum" ]; then
+ ns-yum-install
+ elif [ -x "/bin/pkgman" ]; then
+ ns-pkgman-install
+ elif [ -x "/opt/local/bin/port" ]; then
+ ns-macport-install
+ elif [ -x "/usr/sbin/pkg" ]; then
+ ns-freebsdpkg-install
+ else
+ echo "Unable to determine OS packaging system in use."
+ echo "Please ensure development packages are installed for:"
+ echo ${NS_DEV_GEN}"," ${NS_TOOL_GEN}"," ${NS_GTK_GEN}
+ fi
+}
+
+###############################################################################
+# Setup environment
+###############################################################################
-# parameters
+# find which command used to find everything else on path
+if [ -x /usr/bin/which ]; then
+ WHICH_CMD=/usr/bin/which
+else
+ WHICH_CMD=/bin/which
+fi
+
+# environment parameters
# The system doing the building
if [ "x${BUILD}" = "x" ]; then
- BUILD=$(cc -dumpmachine)
+ BUILD_CC=$(${WHICH_CMD} cc)
+ if [ $? -eq 0 ];then
+ BUILD=$(cc -dumpmachine)
+ else
+ echo "Unable to locate a compiler. Perhaps run ns-package-install"
+ return 1
+ fi
fi
# Get the host build if unset
@@ -29,7 +195,7 @@ if [ "x${HOST}" = "x" ]; then
else
HOST_CC_LIST="${HOST}-cc ${HOST}-gcc /opt/netsurf/${HOST}/cross/bin/${HOST}-cc /opt/netsurf/${HOST}/cross/bin/${HOST}-gcc"
for HOST_CC_V in $(echo ${HOST_CC_LIST});do
- HOST_CC=$(/bin/which ${HOST_CC_V})
+ HOST_CC=$(${WHICH_CMD} ${HOST_CC_V})
if [ "x${HOST_CC}" != "x" ];then
break
fi
@@ -48,10 +214,12 @@ else
unset HOST_CC_LIST HOST_CC_V HOST_CC HOST_CC_MACHINE
fi
+# set up a default target workspace
if [ "x${TARGET_WORKSPACE}" = "x" ]; then
TARGET_WORKSPACE=${HOME}/dev-netsurf/workspace
fi
+# set up default parallelism
if [ "x${USE_CPUS}" = "x" ]; then
NCPUS=$(getconf _NPROCESSORS_ONLN 2>/dev/null || getconf NPROCESSORS_ONLN 2>/dev/null)
NCPUS="${NCPUS:-1}"
@@ -64,20 +232,17 @@ if [ "x${NETSURF_GTK_MAJOR}" = "x" ]; then
NETSURF_GTK_MAJOR=2
fi
-
-###############################################################################
-# Setup environment
-###############################################################################
-
+# report to user
echo "BUILD=${BUILD}"
echo "HOST=${HOST}"
echo "TARGET_WORKSPACE=${TARGET_WORKSPACE}"
echo "USE_CPUS=${USE_CPUS}"
export PREFIX=${TARGET_WORKSPACE}/inst-${HOST}
+export BUILD_PREFIX=${TARGET_WORKSPACE}/inst-${BUILD}
export PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH}::
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${PREFIX}/lib
-export PATH=${PATH}:${PREFIX}/bin
+export PATH=${PATH}:${BUILD_PREFIX}/bin
export NETSURF_GTK_MAJOR
# make tool
@@ -152,117 +317,6 @@ esac
export MAKE
-################ OS Package installation ################
-
-# deb packages for dpkg based systems
-NS_DEV_DEB="build-essential pkg-config git gperf libcurl3-dev libssl-dev libpng-dev libjpeg-dev"
-NS_TOOL_DEB="flex bison libhtml-parser-perl"
-if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
- NS_GTK_DEB="libgtk-3-dev librsvg2-dev"
-else
- NS_GTK_DEB="libgtk2.0-dev librsvg2-dev"
-fi
-
-# apt get commandline to install necessary dev packages
-ns-apt-get-install()
-{
- sudo apt-get install $(echo ${NS_DEV_DEB} ${NS_TOOL_DEB} ${NS_GTK_DEB})
-}
-
-# RPM packages for rpm based systems (tested on fedora 20)
-NS_DEV_RPM="git gcc pkgconfig libexpat-devel openssl-devel libcurl-devel perl-Digest-MD5-File libjpeg-devel libpng-devel"
-NS_TOOL_RPM="flex bison"
-if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
- NS_GTK_RPM="gtk3-devel librsvg2-devel"
-else
- NS_GTK_RPM="gtk2-devel librsvg2-devel"
-fi
-
-# yum commandline to install necessary dev packages
-ns-yum-install()
-{
- sudo yum -y install $(echo ${NS_DEV_RPM} ${NS_TOOL_RPM} ${NS_GTK_RPM})
-}
-
-
-# DNF RPM packages for rpm based systems (tested on fedora 25)
-NS_DEV_DNF_RPM="java-1.8.0-openjdk-headless gcc clang pkgconfig libcurl-devel libjpeg-devel expat-devel libpng-devel openssl-devel gperf perl-HTML-Parser"
-NS_TOOL_DNF_RPM="git flex bison ccache screen"
-if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
- NS_GTK_DNF_RPM="gtk3-devel"
-else
- NS_GTK_DNF_RPM="gtk2-devel"
-fi
-
-# dnf commandline to install necessary dev packages
-ns-dnf-install()
-{
- sudo dnf install $(echo ${NS_DEV_DNF_RPM} ${NS_TOOL_DNF_RPM} ${NS_GTK_DNF_RPM})
-}
-
-
-
-# Haiku secondary arch suffix:
-# empty for primary (gcc2 on x86),
-# "_x86" for gcc4 secondary.
-HA=_x86
-# Haiku packages
-NS_DEV_HPKG="devel:libcurl${HA} devel:libpng${HA} devel:libjpeg${HA} devel:libcrypto${HA} devel:libiconv${HA} devel:libexpat${HA} cmd:pkg_config${HA} cmd:gperf html_parser"
-
-# pkgman commandline to install necessary dev packages
-ns-pkgman-install()
-{
- pkgman install $(echo ${NS_DEV_HPKG})
-}
-
-# MAC OS X
-NS_DEV_MACPORT="git expat openssl curl libjpeg-turbo libpng"
-
-ns-macport-install()
-{
- PATH=/opt/local/bin:/opt/local/sbin:$PATH sudo /opt/local/bin/port install $(echo ${NS_DEV_MACPORT})
-}
-
-NS_DEV_FREEBSDPKG="gmake curl"
-
-# FreeBSD package install
-ns-freebsdpkg-install()
-{
- pkg install $(echo ${NS_DEV_FREEBSDPKG})
-}
-
-# generic for help text
-NS_DEV_GEN="git, gcc, pkgconfig, expat library, openssl library, libcurl, perl, perl MD5 digest, libjpeg library, libpng library"
-NS_TOOL_GEN="flex tool, bison tool"
-if [ "x${NETSURF_GTK_MAJOR}" = "x3" ]; then
- NS_GTK_GEN="gtk+ 3 toolkit library, librsvg2 library"
-else
- NS_GTK_GEN="gtk+ 2 toolkit library, librsvg2 library"
-fi
-
-# Genertic OS package install
-# looks for package managers and tries to use them if present
-ns-package-install()
-{
- if [ -x "/usr/bin/apt-get" ]; then
- ns-apt-get-install
- elif [ -x "/usr/bin/dnf" ]; then
- ns-dnf-install
- elif [ -x "/usr/bin/yum" ]; then
- ns-yum-install
- elif [ -x "/bin/pkgman" ]; then
- ns-pkgman-install
- elif [ -x "/opt/local/bin/port" ]; then
- ns-macport-install
- elif [ -x "/usr/sbin/pkg" ]; then
- ns-freebsdpkg-install
- else
- echo "Unable to determine OS packaging system in use."
- echo "Please ensure development packages are installed for:"
- echo ${NS_DEV_GEN}"," ${NS_TOOL_GEN}"," ${NS_GTK_GEN}
- fi
-}
-
################ Development helpers ################
# git pull in all repos parameters are passed to git pull
@@ -300,17 +354,21 @@ ns-clone()
# issues a make command to all libraries
ns-make-libs()
{
- for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_TOOLS}); do
+ for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_INTERNAL_LIBS} ${NS_FRONTEND_LIBS}); do
echo " MAKE: make -C ${REPO} $USE_CPUS $*"
- ${MAKE} -C ${TARGET_WORKSPACE}/${REPO} $USE_CPUS $*
+ ${MAKE} -C ${TARGET_WORKSPACE}/${REPO} HOST=${HOST} $USE_CPUS $*
if [ $? -ne 0 ]; then
return $?
fi
done
+}
- for REPO in $(echo ${NS_INTERNAL_LIBS} ${NS_FRONTEND_LIBS}); do
+# issues make command for all tools
+ns-make-tools()
+{
+ for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_TOOLS}); do
echo " MAKE: make -C ${REPO} $USE_CPUS $*"
- ${MAKE} -C ${TARGET_WORKSPACE}/${REPO} HOST=${HOST} $USE_CPUS $*
+ ${MAKE} -C ${TARGET_WORKSPACE}/${REPO} PREFIX=${BUILD_PREFIX} HOST=${BUILD} $USE_CPUS $*
if [ $? -ne 0 ]; then
return $?
fi
@@ -329,6 +387,7 @@ ns-pull-install()
{
ns-pull $*
+ ns-make-tools install
ns-make-libs install
}
diff --git a/docs/logging.md b/docs/logging.md
index 41c7ea1bd..abc852bca 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -62,12 +62,18 @@ The main command line switches that control logging are:
- -V <file>
Send the logging to a file instead of standard output
- - -log_filter=<filter>
+ - --log_filter=<filter>
Set the non verbose filter
- - -log_verbose_filter=<filter>
+ - --verbose_filter=<filter>
Set the verbose filter
+Examples:
+
+ ./nsgtk --log_filter="level:INFO"
+ ./nsgtk -v --verbose_filter="(cat:layout && level:DEBUG)"
+ ./nsgtk -v --verbose_filter="((cat:layout && level:DEBUG) || level:INFO)"
+
Options
-------
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 8bc90de81..601269c96 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -1,15 +1,18 @@
Quick Build Steps for NetSurf
=============================
-Last Updated: 24 February 2015
+Last Updated: 15th December 2017
This document provides steps for building NetSurf.
+Native build
+============
Grab a temporary env.sh
-----------------------
- $ wget http://git.netsurf-browser.org/netsurf.git/plain/docs/env.sh
+ $ wget https://git.netsurf-browser.org/netsurf.git/plain/docs/env.sh
+ $ unset HOST
$ source env.sh
@@ -28,6 +31,11 @@ If your package manager is not supported, you will have to install third
Get the NetSurf project source code from Git
--------------------------------------------
+All the sources for the browser and support libraries is available
+ from the public git server.
+
+Local copies may be easily obtained with the ns-clone command.
+
$ ns-clone
@@ -42,7 +50,7 @@ Updates NetSurf project library sources to latest, builds and installs them.
Switch to new NetSurf workspace
-------------------------------
-Remove the bootstrack script and use the newly installed one
+Remove the bootstrap script and use the newly installed one
$ rm env.sh
$ cd ~/dev-netsurf/workspace
@@ -54,8 +62,8 @@ Build and run NetSurf
$ cd netsurf
-To build the native front end (the GTK front end on Linux, BSDs, etc) you
-could do:
+To build the native front end (the GTK front end on Linux, BSDs, etc)
+ you could do:
$ make
$ ./nsgtk
@@ -70,23 +78,23 @@ Cross Compiling
===============
If you are cross compiling, you can follow the above steps, but when
-sourcing env.sh, you should set HOST environment variable to the
-appropriate triplet for your cross compiler. For example, to cross
-compile for RISC OS:
+ sourcing env.sh, you should set HOST environment variable to the
+ appropriate triplet for your cross compiler. For example, to cross
+ compile for RISC OS:
$ HOST=arm-unknown-riscos source env.sh
After that, the commands such as `ns-package-install` and
-`ns-pull-install` will do what is appropriate for the platform you
-are building for.
+ `ns-pull-install` will do what is appropriate for the platform you are
+ building for.
-To do the final build of NetSurf, pass the appropriate TARGET to make.
-For example, to cross compile for RISC OS:
+To do the final build of NetSurf, pass the appropriate TARGET to
+ make. For example, to cross compile for RISC OS:
$ make TARGET=riscos
Finally, you can package up your build to transfer to the system you
-are developing for. For example, to produce a package for RISC OS:
+ are developing for. For example, to produce a package for RISC OS:
$ make TARGET=riscos package
@@ -94,18 +102,19 @@ Getting a cross compiler set up
-------------------------------
We maintain cross compilation environments and an SDK for a number of
-platforms. These may be found in our toolchains repository.
+ platforms. These may be found in our toolchains repository.
$ git clone git://git.netsurf-browser.org/toolchains
-Pre-built versions of the toolchains for Debian systems are often available
-via our [automated build and test infrastructure](http://ci.netsurf-browser.org/builds/toolchains/)
+Pre-built versions of the toolchains for 64bit x86 Debian systems are
+ available via our [automated build and test
+ infrastructure](https://ci.netsurf-browser.org/builds/toolchains/)
Not working?
============
-If the above steps are inapplicable, or don't work, you can build manually.
-Follow the instructions in the BUILDING-* documents in the docs/ directory
-the NetSurf browser source tree.
+If the above steps are inapplicable, or don't work, you can build
+ manually. Follow the instructions in the BUILDING-* documents in the
+ docs/ directory the NetSurf browser source tree.