[[!meta title="Documentation/GettingCoding"]]
[[!meta author="Tlsa"]]
[[!meta date="2014-03-15T12:02:06Z"]]


[[!toc]]

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
Gitweb](http://git.netsurf-browser.org/).

There are two ways to go. You can use our
[env.sh](http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh)
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 env.sh and QUICK-START
------------------------------------------------

This makes it simple to git clone the sources for NetSurf and the
project libraries, build and install them.

To use
[env.sh](http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh),
follow the steps in our
[QUICK-START](http://git.netsurf-browser.org/netsurf.git/plain/Docs/QUICK-START)
document.

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 > 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`

Whenever you wish to start development in a new shell, run the
following.

`# Change to workspace`  
`cd ${HOME}/netsurf/workspace`  
`# Prepare shell environment`  
`source env.sh`

From here down, any commands in this document assume you have prepared
your shell environment and you are starting from the workspace
directory.

### 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.netsurf-browser.org/`](git://git.netsurf-browser.org/)`${REPO}.git ; \`  
`done`

### 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`  
`make`  
`# Try running NetSurf (GTK) from the build tree`  
`./test-nsgtk`

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://nsgit@git.netsurf-browser.org/`](ssh://nsgit@git.netsurf-browser.org/)`"]`  
`    pushInsteadOf = `[`git://git.netsurf-browser.org/`](git://git.netsurf-browser.org/)

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.netsurf-browser.org/netsurf.git`](git://git.netsurf-browser.org/netsurf.git)` (fetch)`  
`origin `[`ssh://nsgit@netsurf-browser.org/netsurf.git`](ssh://nsgit@netsurf-browser.org/netsurf.git)` (push)`

Rules on branches
-----------------

The `git` server (a [Gitano](http://www.gitano.org.uk/) instance on
[Pepperfish](http://www.pepperfish.net/)) 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
username.

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.