diff options
Diffstat (limited to 'documentation/gettingcoding.mdwn')
| -rw-r--r-- | documentation/gettingcoding.mdwn | 155 |
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"]] + + +[[!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. + |