= Building BOINC on Unix =
	
The BOINC software consists of several components:

[[Image(components.png,nolink)]]

    * '''Miscellaneous''': the API and various shared code.
    * '''Client''': the core client and Manager.
    * '''Server''': the scheduler, file upload handler, daemons, and tools. 

== Compilation pipeline ==

On Unix systems, the BOINC software can be built by:

    * Making sure a number of packages exist on your system (in particular, a missing g++ will mean you get confronted with mysterious error messages later on). In Linux using 'yum', run this as 'root':

{{{
yum install make autoconf automake libtool libcurl-devel openssl-devel gcc-c++
}}}

    * After that, 'cd' to the directory into which you cloned the BOINC Git repository (probably 'boinc_repo') and run:

{{{
./_autosetup
}}}

    * This has created the 'configure' script. Execute that script (passing it a _number of options_) using 

{{{
./configure [see options below]
}}}

    * This has created the 'Makefile'. Run compilation using

{{{
make
}}}

Note that none of the above except the installation of missing packages should be run as root.

== Use cases ==

    * If you are '''creating a project''', you need to build the server and miscellaneous software (you '''don't''' need to build the client software; participants can get that from the BOINC web site). Use

{{{
./configure --disable-client --disable-manager
}}}

    * If you are ''porting the BOINC client software to a new platform''', you need the client and miscellaneous components. Use

{{{
./configure --disable-server
}}}

    * If you are '''developing or porting a BOINC application''', you need only the miscellaneous component. Use

{{{
./configure --disable-server --disable-client --disable-manager
}}}

    * If you are '''compiling the client''', use

{{{
./configure --disable-server --disable-manager
}}}

== Configuration ==

Usage:

{{{
./configure [OPTION]... [VAR=VALUE]...
}}}

Run 

{{{
./configure --help
}}}

for a complete listing of available options.

You can use environment variables to override the choices made by `configure` or to help it to find libraries and programs with nonstandard names/locations. To assign environment variables (e.g., CC, CFLAGS...), specify them as `VAR=VALUE`. Example: to compile BOINC with strict compiler warnings, use

{{{
./configure CXXFLAGS="-Wall -W -Wshadow -Wpointer-arith -Wcast-qual -Wcast-align -Wwrite-strings -fno-common"
}}}

In particular, you can set the installation directory like this for example:

{{{
VERSION=7.2.9
./configure CXXFLAGS="-Wall -W -Wshadow -Wpointer-arith -Wcast-qual -Wcast-align -Wwrite-strings -fno-common" --disable-server --disable-manager --prefix=${HOME}/boinc_${VERSION} 
}}}

== Problems during compilation ==

Once you run `make`, a few problems may occur.

Make breaks off with 

{{{
error: wrong number of arguments
usage: git config [options]
}}}

Solution: Edit "generate_svn_version.sh" to put quotes around an argument (see https://boinc.berkeley.edu/trac/ticket/1253)

== Installation ==

(Apparently 'make install' is not the correct way to install. What _is_ the correct way?)

Once compilation succeeded, run:

{{{
make install
}}}

== Problems during installation ==

Once you run `make install`, a few problems may occur.

Make breaks off with:

{{{
/usr/bin/install -c -d /etc/init.d
/usr/bin/install -c -b ./boinc-client /etc/init.d/boinc-client
/usr/bin/install: cannot create regular file `/etc/init.d/boinc-client': Permission denied
}}}

This happens if you don't want to 'make install' as root. Edit {{{client/scripts/Makefile}}} and zero out the 'install-exec-hook' make target (see https://boinc.berkeley.edu/trac/ticket/1255)

== Source layout ==

The top-level `Makefile.am` contains the `SUBDIRS=` line which sets up directory recursion, and the rules for creating source distributions.

Each subdirectory's `Makefile.am` contains the rules for making the binaries and libraries in that directory and any extra files to distribute.

Usually you will want to run `make` from the top level (the directory containing the file `configure`), but sometimes it is useful to run `make` and `make check` in certain subdirectories (e.g. `client/`).

== Adding new directories ==

If you create a new directory with another `Makefile.am`, you should

    * make sure the directory is referenced by a `SUBDIRS=` line from its parent `Makefile.am`
    * add it to the AC_CONFIG_FILES directive in `configure.ac`. 

== Version number ==

To set the BOINC client version:

{{{
set-version 5.12.47
}}}

in the BOINC top-level source directory. This updates the `AC_INIT` line in `configure.ac` and regenerates files that use the version numbers (config.h, py/version.py, test/version.inc, client/win/win_config.h, Makefiles)