wiki:SourceCodeGit

Version 69 (modified by davea, 5 years ago) (diff)

--

  1. BOINC source code
  2. Getting the code using Git
    1. Installing Git
    2. Cloning the Git repository
    3. Working with the local Git repository
      1. Staying Current
      2. Tags & Branches
        1. Examples using tags and branches
        2. Check out a specific tag for compilation
  3. Windows build dependencies
  4. HTC Power to Give source code
  5. Source code structure overview

BOINC source code

BOINC is free software, distributed under the ​Lesser General Public License (LGPL), version 3 or later.

The BOINC source code is maintained in a Git repository on Github: ​https://github.com/BOINC/boinc

Getting the code using Git

Installing Git

You don't need to fully understand Git; just skim the instructions below. If you intend to modify BOINC or to look at branches, you'll need to know at least the basics.

Recommended reading/watching:

  • ​Pro Git: Great free online book (also commercially available in print!)
  • ​All the rest: Cheat sheets, tutorials and more videos

Cloning the Git repository

The easiest way to download the current GIT master source tree is to go to ​https://github.com/BOINC/boinc and click on "Clone or download". You can also download the source tree for any branch by selecting the desired branch from the pull-down menu on that page.

To clone the repository into a local directory called (for example) 'boinc', run the following command in the Terminal utility (Macintosh) or "Command Prompt" utility (Windows) : 

git clone https://github.com/BOINC/boinc boinc

On Windows using TortoiseGit, right-click on the parent directory, select 'Git Clone...', and fill in the dialog with one of the above URLs. Don't forget to remove both 'git clone' and 'boinc' from the commands above.

The 'clone' operation pulls down ~150 MiB of source and gives you a copy that you can modify and compile locally. However, you will not be able to push changes to the BOINC repository. For write access, see below.

Change to the directory 'boinc'. Here you will find the files corresponding to the HEAD of the 'remote master branch'.

Sometimes it is necessary to purge all untracked files created by build tools (_autosetup, configure, make) and reset the source directory without pulling a new clone. This can be done using: 

$ git clean -f -d -x

Working with the local Git repository

Staying Current

The local git repository which you created when you cloned the remote repository has a complete snapshot of development at the time it was cloned. You can use this to build the BOINC software, and you can even make local changes to your local copy. Meanwhile the BOINC developers will be making changes to the remote repository as they continue working on the software. To see what changes have been made there since you cloned the repository you must first "fetch" the changes from that repository. These will go into a branch called "origin/master", which is not the current working branch of your repository (which by default will be the "master" branch). So to compare your local copy with the remote, follow this example: 

$ cd boinc
$ git fetch
$ git diff --name-status master..origin/master
M       client/app.cpp
M       client/app_config.cpp
M       client/client_types.h
M       client/cpu_sched.cpp
M       client/cs_prefs.cpp
M       client/cs_scheduler.cpp
M       client/result.cpp
M       client/result.h
M       client/rr_sim.cpp
M       client/sim.cpp
M       clientgui/MainDocument.cpp
M       doc/versions.inc
M       html/user/get_passwd.php
M       html/user/server_status.php
M       lib/coproc.h

The "--name-status" flag causes only the name and status of differing files to be displayed. The "master..origin/master" specification causes the difference to be displayed between your local repository (the "master" branch) and the remote repository (as fetched onto the local "origin/master" branch).

If you wish to update your local branch to match the remote repository then simply use the git "pull" command, as in this example: 

$ git pull
Updating 6790085..2bb3e74
Fast-forward
 client/app.cpp              |   2 +-
 client/app_config.cpp       |  12 ++
 client/client_types.h       |   2 +-
 client/cpu_sched.cpp        |  12 +-
 client/cs_prefs.cpp         |   5 +-
 client/cs_scheduler.cpp     |  15 +-
 client/result.cpp           |   7 +-
 client/result.h             |   3 +
 client/rr_sim.cpp           |   4 +-
 client/sim.cpp              |   6 +-
 clientgui/MainDocument.cpp  |  12 +-
 doc/versions.inc            | 380 ++++++++++++++++++++++----------------------
 html/user/get_passwd.php    | 101 ++++++------
 html/user/server_status.php |  38 ++++-
 lib/coproc.h                |   5 +
 15 files changed, 332 insertions(+), 272 deletions(-)

You could also use the "git merge" command, which would merge the changes from your local copy of the "origin/master" branch into your local "master" branch. The "git pull" command is shorthand for "git fetch" followed immediately by "git merge".

Tags & Branches

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

Various versions of the source code are available in the remote repository (and now, in your local copy of it):

  • remote tags: These are snapshots of the state of development taken at a specific point in time. You can check out a 'remote tag', but you should not modify the files thus checked out - for that you need a separate branch (which can be created later though). The tag's name indicates what's in there. For example, the release of BOINC client version 7.0.60 has been given then tag 'client_release/7.0/7.0.60'. Run git tag to list the remote tags.
  • remote branches: BOINC developers perform long-running work on source code that needs to be visible to other members of the team by working on a 'remote branch'. There are:
    • The remote master branch: This is the most recent version of the source code. It always exists, contains the freshest code and has not necessarily been thoroughly tested.
    • Other branches: For example, work on version 6.12 of BOINC that is not done in the 'remote master branch', (let's say because of the need for a immediate bugfix) may be done in a remote branch called 'client_release/6/6.12'.

Some tagged versions are available as compressed archives from ​here.

Run git remote show origin to list the remote branches. When you cloned the Git repository a 'local master branch' was created. This initially matches the 'remote master branch', but once you start editing files, it will of course deviate from it. You can create local branches and tags (both invisible to anyone but yourself). You can check out a specific 'remote tag' to compile, or you can create a local branch based on a specific 'remote tag' to work on the code.

If you want to have an overview of the development history, refer to ​- this discussion on stack overflow about generating pretty pictures of the same.

For the impatient living on Unix, you can follow Slipp D. Thompson's idea and edit (or create) your '~/.gitconfig' file, adding the following command aliases: 

[alias]
lg1 = log --graph --abbrev-commit --decorate --date=relative --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
lg2 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold cyan)%aD%C(reset) %C(bold green)(%ar)%C(reset)%C(bold yellow)%d%C(reset)%n''          %C(white)%s%C(reset) %C(dim white)- %an%C(reset)' --all
lg = !"git lg1"

Then run 

git lg

inside the 'boinc' directory for a quick text-only history dump, which will look something like this: 

* 403afa4 - (14 hours ago) client: work fetch policy tweak - David Anderson (HEAD, origin/master, origin/HEAD, master)
* 28f7f95 - (17 hours ago) client: Default to /usr/bin when looking for VboxManage. - Rom Walton
* b4f7e33 - (18 hours ago) client, Android: run CPU-intensive apps in background mode - David Anderson
* b0504e9 - (24 hours ago) Mac: script builds boinc_zip library when building other BOINC libraries - Charlie Fenton
* edc96a2 - (24 hours ago) Mac: update build scripts for OS 10.9 - Charlie Fenton
* 0d04b84 - (24 hours ago) Mac: Update build script for wxWidgets 3.0.0 - Charlie Fenton
* 04e8f00 - (30 hours ago) client, Win: when running GPU detect, use "boinc.exe" rather than "boinc" on cmdline. - David Anderson
* be2f175 - (2 days ago) DOC: Add entries for MIPS and x86 for Android. - Rom Walton
*   cc32c51 - (2 days ago) Merge branch 'master' of ssh://isaac.ssl.berkeley.edu/boinc-v2 - Rom Walton
|\
| * 6d78613 - (2 days ago) API: make boinc_api_fortran.cpp compile - David Anderson
| * 36460bc - (2 days ago) Compile fixes for Ubuntu - David Anderson
* | 8bb3af6 - (2 days ago) DOC: Update android client to 7.2.41. - Rom Walton
|/
* 9b041f7 - (2 days ago) VBOX: Fix case of virtualbox and vboxheadless for platforms that are case sensitive.  The code...
* 9220ceb - (3 days ago) Admin web: deprecate problem_host.php, which sends a confusing email to user - David Anderson

Examples using tags and branches

To revert back to the remote master branch after you have modified some files in a too hasty fashion: 

git checkout master

What is the absolutely latest tag issued? 

$ git describe --tags `git rev-list --tags --max-count=1`
client_release/7.2/7.2.41

What's the most recent tag for the currently checked-out version? 

$ git describe --always --tag
client_release/7.2/7.2.4-2866-g6ff59ea

This means that the HEAD is based on 'client_release/7.2/7.2.4', with 2866 commits on top (I think).

What are the differences between the HEAD and the latest tag issued? 

$ git diff HEAD client_release/7.2/7.2.41 | wc -l
271949

271949 lines have differences.

You may want to see the differences to file 'version.h': 

$ git diff HEAD client_release/7.2/7.2.41 version.h | grep BOINC_VERSION_STRING
-#define BOINC_VERSION_STRING "7.3.0"
+#define BOINC_VERSION_STRING "7.2.41"

Looks like the HEAD is an as-yet-untagged 7.3.0. The choice is yours ... what do you want to compile? You probably want something more stable.

Check out a specific tag for compilation

As mentioned above, the code for each client release is 'tagged'. For example, the code for version 7.2.9 is tagged with client_release/7.2/7.2.9.

Run 

git tag

to list all the visible tags. Note that the tags come in lexicographical order, not in version order! If you want to sort them by version number: 

git tag | perl version_path_sorter.pl

Where the source for the sorter function is here: VersionPathSorter

Run 

git tag --list '*/7.2/*'

to list only the tags matching '/7.2/'.

Run 

git checkout client_release/7.2/7.2.9; git status

to check out BOINC client version 7.2.9.

...and proceed with compilation.

Windows build dependencies

The Windows build for VS 2019 automatically fetches and builds the dependent libraries (openSSL, etc.). For earlier versions of Visual Studio we've collected pre-built versions of these libraries, available as .zip files from here:

​https://boinc.berkeley.edu/dl/boinc_depends

VS Dependency
Visual Studio 2010 boinc_depends_win_vs2010
Visual Studio 2013 boinc_depends_win_vs2013

The dependencies should be stored in the same parent directory as the BOINC source code: 

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

HTC Power to Give source code

The source code for HTC Power to Give (a variant of the BOINC Android client) can be found using the instructions ​here.

Source code structure overview

The BOINC source tree includes the following directories:

android Android port
api The BOINC API (for applications).
apps Some test applications.
client The BOINC client.
clientctrl BOINC-as-Windows-Service.
clientgui The BOINC Manager.
clientscr The BOINC screensaver for Windows.
clienttray The BOINC Tray component (checks for user activity on Windows).
coprocs Header file for ​- NVIDIA API.
curl Bunch of Certificate Authority Certificates (for libcurl?).
db The database schema and C++ interface layer (needs mysql.h).
dcapi Data collection API (?).
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.
m4 Code for the ​- m4 macro processor (Why!)
mac_build For building on Macs.
mac_installer For installing on Macs.
packages Files required to create a distribution package for various operating systems.
py Python modules used by tools.
rboinc Remote job submission system for BOINC.
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.
sched The scheduling server, feeder, and file upload handler.
stripchart Generate plots using gnuplot
test Test scripts.
tools Operational utility programs.
vda Volunteer Data Archival code.
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.

Attachments (1)

Download all attachments as: .zip