gettingcoding

!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.

There are two ways to go. You can use our 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, follow the steps in our 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/${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://[email protected]/"]
    pushInsteadOf = 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 (fetch)
origin ssh://[email protected]/netsurf.git (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 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 for more help.