git-annex/doc/install/fromsource.mdwn

So you want to build git-annex from source. This is encouraged for
users with experience building code from source. But the build may
require some care and feeding. This page will start with the easy
methods and work up to the harder ones.

This page also covers installing git-annex from source, but in many
cases it's better to install it using your OS's package manager.

## downloading the source code

The easiest way is using git; see [[download]] or just run:

	git clone git://git-annex.branchable.com/ git-annex

## building from source on Debian

This is the method used by git-annex's author, and so it's the one most
likely to work without problems.

First, install everything git-annex needs to build:

	sudo apt-get build-dep git-annex

Now you can build git-annex by running `make` inside the source tree.

Then, to install the program and associated files system-wide in `/usr/local`,
run:

	sudo make install PREFIX=/usr/local

Or, to install the program into $HOME/.local/bin, and associated files
into other parts of your HOME directory, run:

	make install-home

## building from source with stack

Using stack automates nearly everything, will work on many systems,
and avoids build failures due to fast-changing haskell libraries.

First, [install stack](https://docs.haskellstack.org/en/stable/install_and_upgrade/)  
On Debian:

	sudo apt-get install haskell-stack zlib1g-dev

Get the git-annex source code, and inside the source tree run:

	stack setup
	stack build

To install the program and all associated files system-wide
in `/usr/local`, run:

	sudo make install BUILDER=stack PREFIX=/usr/local

Or, to install the program into $HOME/.local/bin, and associated files
into other parts of your HOME directory, run:

	make install-home BUILDER=stack

(Why not run `stack install git-annex`? Because that causes stack to 
[ignore git-annex's stack.yaml file](https://github.com/commercialhaskell/stack/issues/2371),
yielding a less reliable build. Stack also only installs the binary,
and not other files.)

Note that this build produces a git-annex without the build flags
DBUS and MagicMime.
These optional features require installing additional C libraries.
To try to build with these features 
enabled, pass extra parameters when running `stack build`: 
`--flag git-annex:DBUS --flag git-annex:MagicMime`

## minimal build from source with cabal

This can be done anywhere, and builds git-annex without some optional
features that require harder-to-install C libraries. This is plenty to let
you get started with git-annex, but it does not include the assistant or
webapp.

Be warned that this involves building a lot of Haskell libraries from
source, and so it has a lot of moving parts, and it's not uncommon for it
to be broken from time to time.

Get the git-annex source code, and inside the source tree, run:

	cabal install -j -f"-assistant -webapp -pairing -dbus -magicmime" --only-dependencies
	cabal configure -f"-assistant -webapp -pairing -dbus -magicmime"
	cabal build -j

To install the program and all associated files system-wide
in `/usr/local`, run:

	sudo make install BUILDER=cabal PREFIX=/usr/local

Or, to install the program into $HOME/.local/bin, and associated files
into other parts of your HOME directory, run:

	make install-home BUILDER=cabal

## full build from source with cabal

To build with all features enabled, including the assistant and webapp,
you will need to install several C libraries and their headers,
including libmagic, and zlib. How to do that for your OS is beyond
the scope of this page. 

Once the C libraries are installed, run inside the source tree:

	cabal install -j --only-dependencies
	cabal configure
	cabal build -j

To install the program and all associated files system-wide
in `/usr/local`, run:

	sudo make install BUILDER=cabal PREFIX=/usr/local

Or, to install the program into $HOME/.local/bin, and associated files
into other parts of your HOME directory, run:

	make install-home BUILDER=cabal