summaryrefslogtreecommitdiff
path: root/docs/PACKAGING-GTK
diff options
context:
space:
mode:
Diffstat (limited to 'docs/PACKAGING-GTK')
-rw-r--r--docs/PACKAGING-GTK97
1 files changed, 97 insertions, 0 deletions
diff --git a/docs/PACKAGING-GTK b/docs/PACKAGING-GTK
new file mode 100644
index 000000000..8f675229f
--- /dev/null
+++ b/docs/PACKAGING-GTK
@@ -0,0 +1,97 @@
+--------------------------------------------------------------------------------
+ Packaging suggestions for NetSurf 30 July 2008
+--------------------------------------------------------------------------------
+
+ This document lays out some suggestions for people interested in packaging
+ NetSurf for UNIX-like OSes.
+
+ We consider the Debian (and thus Ubuntu) packages excellent examples to
+ crib from. They do everything right.
+
+
+ Building NetSurf
+==================
+
+ You should change Makefile.config to be specific (rather than rely on AUTO)
+ for the libraries and functionality you want to include. This will help
+ your packages be consistent. Also remember that you can turn off
+ functionality such as PDF export, RISC OS Sprite support, SVG rendering etc.
+ from here should you require a smaller, lighter build.
+
+
+ Launching NetSurf
+===================
+
+ 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
+ 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.
+
+ The binary that the build system produces is called "nsgtk". There is also
+ a shell script called "netsurf" that will set up the environment and launch
+ the nsgtk binary. Do not ship this shell script with your package. It is
+ included only as a convience for launching NetSurf from the build tree.
+ Instead, you should move nsgtk to /usr/bin/netsurf (or wherever your
+ distribution's packaging policy suggests) and copy the contents of
+ gtk/res/ (dereferencing the symlinks, obviously) to /usr/share/netsurf (or
+ wherever your packaging policy suggests).
+
+ You will need to tell NetSurf where to find its run time loaded
+ resources. NetSurf searches three locations by default when trying
+ to load them, in this order:
+
+ 1. ~/.netsurf/
+
+ This entry allows the user some flexibility in changing what
+ resources NetSurf uses by placing resources in their home
+ directory.
+
+ 2. $NETSURFRES/
+
+ This entry allows the user or packager to control resource
+ aquisition through the environment. This entry is how the
+ developer launcher script controls resource location.
+
+ 3. NETSURF_GTK_RES_PATH option
+
+ This location is controlled by the option in Makefile.config
+ (defaulting to ${PREFIX}/share/netsurf/ ). This configuration
+ is the recommended way for packagers to change the location
+ NetSurf finds external resources. The first path element of the
+ NETSURF_GTK_RES_PATH option is used in the install target as
+ the destination for installed resources.
+
+ User agent string
+===================
+
+ You may also want to change NetSurf's user agent string to include the
+ name of your distribution. The user agent string is build by a function
+ kept in utils/useragent.c - you'll want to change the macro called
+ NETSURF_UA_FORMAT_STRING. It's processed via sprintf, so keep that in
+ mind when changing it. The first two printf parameters are major and minor
+ version numbers, the second two are OS name (uname -s) and architecture
+ (uname -m). You might want change this to something like:
+
+ "NetSurf/%d.%d (%s; %s; Debian GNU/Linux)"
+
+ or similar. Please don't be tempted to mention Mozilla or similar - let's
+ let that lie die.
+
+
+ Home page URL
+===============
+
+ If the user hasn't specified a home page URL in their Preferences, NetSurf
+ defaults to a "portal" welcome page at about:netsurf - if you wish to
+ change this, you can do so by overriding the NETSURF_HOMEPAGE URL in
+ Makefile.config.
+
+
+ If you make significant changes to NetSurf in your package, please ask your
+ users to report bugs to your bug tracker, not ours. We'd also be interested
+ in seeing the diffs for these changes - we may be able to integrate them
+ to make your job easier in future.
+