path: root/documentation/gettingcoding.mdwn
diff options
Diffstat (limited to 'documentation/gettingcoding.mdwn')
1 files changed, 155 insertions, 0 deletions
diff --git a/documentation/gettingcoding.mdwn b/documentation/gettingcoding.mdwn
new file mode 100644
index 0000000..d53fe33
--- /dev/null
+++ b/documentation/gettingcoding.mdwn
@@ -0,0 +1,155 @@
+[[!meta title="Documentation/GettingCoding"]]
+[[!meta author="Tlsa"]]
+[[!meta date="2014-03-15T12:02:06Z"]]
+Getting started with the NetSurf code base
+NetSurf and its libraries are kept in the `git` revision control system.
+This document guides though setting up an envronment to build and
+develop NetSurf and the NetSurf project libraries from scratch..
+You can see the `git` repositories at [The NetSurf
+There are two ways to go. You can use our
+which will fetch the sources from git and build NetSurf and the
+libraries with a few commands, or you can set up things manually.
+Easy way: Using NetSurf's and QUICK-START
+This makes it simple to git clone the sources for NetSurf and the
+project libraries, build and install them.
+To use
+follow the steps in our
+Less easy: Manual setup
+If you need to do things manually, the rest of this section will take
+you through the process.
+### 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
+sequence of commands will set you up.
+`# Make the workspace directory`
+`mkdir -p ${HOME}/netsurf/workspace`
+`# Change to it`
+`cd ${HOME}/netsurf/workspace`
+`# Make the temporary install space`
+`mkdir inst`
+`# Prepare environment script`
+`cat > <<'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`
+Whenever you wish to start development in a new shell, run the
+`# Change to workspace`
+`cd ${HOME}/netsurf/workspace`
+`# Prepare shell environment`
+From here down, any commands in this document assume you have prepared
+your shell environment and you are starting from the workspace
+### Checking the codebase out for the first time
+Now you can clone all of the core libraries and build them in turn. Some
+may have additional dependencies outside of the NetSurf project's
+codebase, and you should check the documentation in each library for
+information about that.
+`# Acquire all the core libraries and NetSurf codebase`
+`for REPO in buildsystem libwapcaplet libparserutils libcss libdom libhubbub libnsgif libnsbmp libsvgtiny librosprite libnsfb netsurf; do \`
+`   git clone `[`git://`](git://`${REPO}.git ; \`
+### Compiling the codebase
+Assuming you have done the above and checked out all of the code, the
+following is the process of getting it all built. The assumption is
+being made that you're on a GTK development system on Linux. Different
+environments may require slightly different instructions. Refer to the
+documentation in the codebase for more help.
+If you wish to run the tests for each of the libraries, then refer to
+that library's documentation. Some of the libraries require additional
+test harnesses to be installed.
+`# Install the shared build system`
+`make -C buildsystem install`
+`# Build the core libraries in turn (order matters due to dependencies)`
+`make -C libwapcaplet install`
+`make -C libparserutils install`
+`make -C libcss install`
+`make -C libhubbub install`
+`make -C libdom install`
+`# Build the core image decoders`
+`make -C libnsbmp install`
+`make -C libnsgif install`
+`# Build the optional decoders`
+`make -C librosprite install`
+`make -C libsvgtiny install`
+`# Build NetSurf`
+`cd netsurf`
+`# Try running NetSurf (GTK) from the build tree`
+Configuring `git` for pushing changes
+If you have push rights to the NetSurf repository, you need to ensure
+you're pushing to the `ssh://` url rather than the `git://` one.
+The easiest way to do this is to run `git config --global -e` and ensure
+that a section is inserted like the one below.
+`[url "`[`ssh://`](ssh://`"]`
+`    pushInsteadOf = `[`git://`](git://
+This will cause `git` to automatically convert any `git://` url to the
+NetSurf codebase to the corresponding `ssh://` one when pushing. Pulling
+changes still happens over the more efficient and lighter weight
+`git://` protocol. You can verify that this change is working correctly
+by running `git remote -v` in any of your NetSurf code trees. It should
+show something like the following.
+`origin `[`git://`](git://` (fetch)`
+`origin `[`ssh://`](ssh://` (push)`
+Rules on branches
+The `git` server (a [Gitano]( instance on
+[Pepperfish]( has varying rules regarding
+where you are allowed to push in terms of branch names. Usually core
+developers may push to the `master` ref (equivalent of the trunk in
+subversion) and anyone else must push to a ref named after their
+All developers are encouraged to work in branches anyway, merging to
+`master` only when changes are ready for others to use. See the
+[[Git Cheat Sheet|documentation/gitcheatsheet]] for more help.