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://nsgit@git.netsurf-browser.org/"]
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://nsgit@netsurf-browser.org/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.