Getting source code

The BOINC source code is stored in a ​Git repository. Various versions of the code are available at any given point:

Development

The master branch contains the latest source code for all components of BOINC. It is always under development, and has not necessarily been thoroughly tested. Use it if you need a recently-added feature.

Client software

The client software (client and manager) is maintained as follows:

• The code for each release is 'tagged'. For example, the code for version 6.3.14 is tagged with boinc_core_release_6_3_14.
• A 'branch' is created for each released minor version. For example, the branch boinc_core_release_6_2 is the code for the latest release of version 6.2.

Server software

For all software other than the client (i.e., server, web, and API) a "stable" version is kept in a branch, server_stable. Don't use the server software in a client tag or branch; it probably isn't stable.

Notes:

• There is no formal testing process for server software. Every so often, when no bugs have been reported recently, we merge the master branch into server_stable.
• Because of limited resources, bug fixes to server software are normally NOT back-ported from master to server_stable.

For these reasons: the master branch is typically a better choice than server_stable for server software.

Using Git

Recommended reading/watching

• ​Getting Git: 1 hour video (technical, but highly recommended)
• ​Pro Git: Great free online book (also commercially available in print!)
• ​All the rest: Cheat sheets, tutorials and more videos

Installation

• On Windows, get a Git client like Git for Windows (console) and TortoiseGit (GUI).
• On Linux git is usually provided by all modern distributions. Check your package manager and look for "git" or "git-core"
• On Mac OS X you want to use ​MacPorts (to keep git up to date, recommended) or a manual ​installation package.
  • Recommended free GUIs: ​SourceTree, ​GitX (​latest)

Read-only access (cloning / checkout code)

Note: this will give you anonymous read-only access only. For direct write access, please refer to the next section.

In a shell/terminal, use the the following commands to clone the repository:

git clone git://isaac.ssl.berkeley.edu/boinc.git

On Windows, using TortoiseGit:

Right-click on the parent directory, select 'Git Clone...', and fill in the dialog with one of the above URLs. There is no need to add 'git clone' in front of it.

Direct write access

Note: you don't need direct write access to contribute code to BOINC. Given the ​distributed nature of git you can also publish your contributions elsewhere (e.g. on ​GitHub) or send your patches via mail (using git format-patch).

Direct write access to the official repositories in currently available via the SSH protocol (with public-key authentication). If you think you need direct write you should contact David Anderson and/or Rom Walton. They'll ask you for your public-key. Here's how you can create one and use it after you've been grated access to the repository:

Windows users

Please see this page for details.

Linux/Mac OS X users

• General note: before you start, please check whether you already have an existing key at ~/.ssh/id_rsa. If so, please choose a different key filename for the commands below! Alternatively, you could also reuse the existing key and continue with the final step.
• Note to Mac OS X users: if you prefer "Finder" over "Terminal" hit CMD+SHIFT+G in "Finder", then enter ~/.ssh to go to that hidden folder.

The following shell/terminal command will create a key pair that gets stored in your ~/.ssh directory:

• Public key: ~/.ssh/id_rsa.pub
• Private key: ~/.ssh/id_rsa

  ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa
  

If you had to use a different key filename because of an existing key that you don't want to overwrite or reuse, you can define a so called ssh host alias that allows you to specify which key to use when accessing the BOINC repo. In order to do so, add the following to ~/.ssh/config (create the file if necessary), assuming that you created the ssh key as ~/.ssh/boinc-key:

host boinc-git-server
       Hostname isaac.ssl.berkeley.edu
       Port 22
       IdentityFile ~/.ssh/boinc-key
       User gitolite

Now that you have the host alias defined you may access the repo using the alias in the clone URL (instead of the full user/hostname information):

git clone boinc-git-server:boinc.git

Finally, send the public key to David or Rom. Important: the private key should never leave your system! Keep it safe!

Windows build dependencies

All the additional dependency files are now stored in build-depends-vs2005, get them using git clone git://isaac.ssl.berkeley.edu/build-depends-vs2005.git. The dependencies should be stored in the same parent directory as the BOINC source code, for example:

+-+ source
    |
    + boinc
    | |
    | + api
    | + client
    | + clientgui
    | + etc...
    |
    + build_depends_vs2005
    | |
    | + curl
    | + openssl
    | + wxwidgets
    | + zlib

When you have older source code, I found that deleting all previous source code and downloading it fresh, will fix the breaks in building BOINC. Make sure to backup your own code prior to deleting the source code.

Browsing source code via the web

You can browse the boinc code via a web-based interface (alternative). This is useful for getting individual files, or seeing the revision history.

Source code road map

The BOINC source tree includes the following directories:

api

The BOINC API (for applications).

apps

Some test applications.

client

The BOINC core client.

clientgui

The BOINC Manager.

clientscr

The BOINC screensaver for Windows.

clienttray

The BOINC Tray component (checks for user activity on Windows).

db

The database schema and C++ interface layer.

html/ops

PHP files for the operational web interface.

html/user

PHP files for the participant web interface.

html/inc

PHP include files.

html/languages

Translation files for project websites.

lib

Code that is shared by more than one component (core client, scheduling server, etc.).

locale

Translation files for BOINC Manager.

py

Python modules used by tools.

sched

The scheduling server, feeder, and file upload handler.

samples

Several example applications together with Windows and Mac project files and a Linux makefile for building the applications. It also includes Windows versions of some libraries (GLUT, jpeglib, etc.) that many applications will need, but which are not part of BOINC.

test

Test scripts.

tools

Operational utility programs.

win_build

Project files for compiling the client under Windows, and the Windows installer.

zip

Compression functions; not used by BOINC, but may be useful for applications.