[[PageOutline]]

= BOINC source code =

== Browsing source code on the web ==

You can browse the boinc code via [/browser a web-based interface]
([http://boinc.berkeley.edu/git alternative]).
This is useful for getting individual files, or seeing the revision history.

== Getting a copy of the BOINC source ==

The BOINC source code is stored in a [http://www.git-scm.com Git] repository.
To get the source code on Unix:
{{{
git clone git://boinc.berkeley.edu/boinc-v2.git boinc
or
git clone http://boinc.berkeley.edu/git/boinc-v2.git boinc
}}}

This will give you a copy that you can modify locally,
but not push changes to the BOINC repository.
For write access, see below.

On Windows, you'll need a Git client such as !TortoiseGit (see below).
Right-click on the parent directory, select 'Git Clone...',
and fill in the dialog with one of the above URLs,
with no 'git clone' in front of it. 

== Branches ==

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.

To checkout the '''master''' branch:
{{{
git checkout master
}}}

=== Client releases ===

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 '''client_release_6_3_14'''.
 * A 'branch' is created for each released minor version.
  For example, the branch '''client_release_6_2''' is the code for the latest release of version 6.2.

To checkout the '''client_release_6_12''' branch:
{{{
git checkout client_release_6_12
}}}

=== Server releases ===

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


== Installing Git ==

To access the BOINC Git repository you'll need Git client software:

 * On Windows, get a Git client like Git for Windows (console)] and !TortoiseGit (GUI) (see this [SourceCodeGit/Windows guide for Windows]).
  * Recommended free GUI: [http://www.sourcetreeapp.com SourceTree (includes an embedded git)],
 * On Linux, Git is usually provided by all modern distributions.
   If not, check your package manager and look for "git" or "git-core"
 * On Mac OS X, use [http://www.macports.org MacPorts]
   (to keep git up to date, recommended) or a manual
   [http://code.google.com/p/git-osx-installer installation package].
  * Recommended free GUIs: [http://www.sourcetreeapp.com SourceTree (includes an embedded git)],
   [http://www.syntevo.com/smartgit/ SmartGit (free for non-commercial use)],
   [http://gitx.laullon.com GitX] ([https://github.com/laullon/gitx latest])

To get a copy of the BOINC source code you don't need to understand Git -
just follow the directions above.
However, if you intend to modify BOINC or to look at branches,
you'll need to know something about Git.
Recommended reading/watching:

 * [http://vimeo.com/14629850 Getting Git]: 1 hour video (technical, but highly recommended)
 * [http://git-scm.com/book Pro Git]: Great free online book (also commercially available in print!)
 * [http://git-scm.com/doc All the rest]: Cheat sheets, tutorials and more videos


== Write access to the main repository ==

Note: you don't need direct write access to contribute code to BOINC.
Given the [http://git-scm.com/about/distributed distributed nature] of Git
you can publish your contributions elsewhere (e.g. on [https://github.com GitHub])
or send your patches via mail (using {{{git format-patch}}}).

Direct write access to the main repository is currently available via the SSH protocol
with public-key authentication.
If you want direct write access, contact David Anderson and/or Rom Walton.
They'll ask you for your public-key.
Here's how you can create a public/private key pair and use it after you've been
granted access to the repository:

=== Windows ===

Please see [http://boinc.berkeley.edu/trac/wiki/SourceCodeGit/WindowsKeygen this page] for details.

=== !Linux/Mac OS X ===

 * 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 used the standard key filename id_rsa and you want the repository named boinc-v2.git,
use the following URL to access the repository:
{{{
ssh://gitolite@boinc.berkeley.edu/boinc-v2.git
}}}

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.
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 boinc.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-v2.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
[source:boinc_depends_win_vs2010 boinc_depends_win_vs2010];;
get them using {{{git clone git://boinc.berkeley.edu/boinc_depends_win_vs2010.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_vs2010
    | |
    | + curl
    | + openssl
    | + wxwidgets
    | + zlib
}}}

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

== 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 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 [ExampleApps 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.