[[PageOutline]] = BOINC source code = == Browsing source code on the web == You can browse the BOINC code using [/browser a web-based interface] ([http://boinc.berkeley.edu/gitweb/ alternative]). This is useful for getting individual files, or seeing the revision history. == Installing Git == The BOINC source is stored in a [http://www.git-scm.com Git] repository. To access the BOINC Git repository you'll need the Git client software: * On Windows, get a Git client like 'Git for Windows' (console) and !TortoiseGit (GUI) (see this [SourceCodeGit/Windows guide for Windows]). * On Linux, Git is usually provided by your distribution. 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 fully understand Git, just skim the instructions below. However, if you intend to modify BOINC or to look at branches, you'll need to know at least the basics. 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 == Getting a copy of the BOINC source == To clone the BOINC Git repository into a local directory called (for example) 'boinc_repo', run: {{{ git clone git://boinc.berkeley.edu/boinc-v2.git boinc_repo }}} or, using HTTP: {{{ git clone http://boinc.berkeley.edu/git/boinc-v2.git boinc_repo }}} 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. Don't forget to remove both 'git clone' and 'boinc_repo' from the commands above. The 'clone' operation pulls down ~134 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 further below. Change to the directory 'boinc_repo'. Here you find the files corresponding to the 'remote master branch', the bleeding edge of development. Run `git status` to show that this is actually true: {{{ $ cd boinc_repo $ git status # On branch master nothing to commit, working directory clean # What's the most recent tag for the currently checked-out version? $ git describe --always --tag client_release/7.2/7.2.9 }}} The fully navigable development history of the project can be found in the 'boinc_repo/.git' subdirectory. You can replace the files on your 'master branch' by files from older branches or older tags using the appropriate git command - without needing to contact the Git repository server again as all the history can be found under 'boinc_repo/.git'. This is called 'checking out'. == Tags & Branches == 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'. Run `git remote show origin` to list the remote branches. As you cloned the Git repository, a 'local master branch' was created. This initially corresponds to 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. * See [http://git-scm.com/book/en/Git-Basics-Tagging Git Basics - Tagging] for the concept of 'tagging'. * See [http://git-scm.com/book/en/Git-Branching-Remote-Branches Git Branching - Remote Branches] for the concept of 'remote branches' and the concepts of the 'local' and 'remote' master branches. * See [http://stackoverflow.com/questions/1457103/what-is-the-difference-between-a-tag-and-a-branch-in-git What is the difference between a tag and a branch in git?] for a short intro on 'tags' and 'branches'. * See [http://stackoverflow.com/questions/5582208/checkout-git-tag Checkout GIT tag] for an explanation about 'checking out git tags'. If you want to have an overview of the development history, refer to [http://stackoverflow.com/questions/1057564/pretty-git-branch-graphs - this discussion on stack overflow] about generating pretty pictures of the same. For the impatient living on Unix, follow Slipp D. Thompson's idead 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 'boinc_repo' for a quick text-only history dump: {{{ * 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 }}} === Development on the bleeding edge === If you want to work on the remote 'master' branch, check it out locally: {{{ git checkout master }}} Actually this has already happened when you cloned the repository, so the above command is mainly useful if you want to go back to the remote master branch after you modified some files in a hasty fashion. === Check out a specific tag for compilation === As said above, the code for each 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. == Server releases == For all software other than the client (i.e., server, web, and API) a "stable" version is kept in a branch, '''server_release'''. Don't use the server software in a client tag or branch; it probably isn't stable. Run {{{ git tag --list 'server_release*' }}} to list the available tags for stable server releases. Notes: * There is no formal testing process for server software. Every so often, when no bugs have been reported for some time, we tag the '''master''' branch to '''server_release'''. * Because of limited resources, bug fixes to server software are normally NOT back-ported from '''master''' to '''server_release'''. For these reasons: '''the master branch is typically a better choice than server_release for server software''' (should this not be the reverse?? .ed) == Write Access to the Git 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: || '''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 [https://developer.nvidia.com/nvapi - 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 [http://en.wikipedia.org/wiki/M4_%28language%29 - 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 [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. || || '''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. ||