## page was renamed from Getting Started
The goal of this article is to guide you through compiling and running Barrelfish inside QEMU, and to write and run programs on Barrelfish itself.
The instructions below assume you are using a recent version of Ubuntu.

To run Barrelfish on the Pandaboard, have a look at [[PandaBoard]].

=== Requirements ===
Barrelfish requires the following tools to compile correctly:
 * GCC 5.4.0
 * GNU binutils 2.26.1 are known to work
 * GNU make
 * GHC and some additional libraries
      Some versions of GHC are not supported. See [[#ghc|Section on GHC]] for more information

We are running nightly build tests on the latest Ubuntu LTS release (16.04.x) and are ensuring Barrelfish always builds using the Ubuntu versions of the above-mentioned tools. You can get a full build environment on Ubuntu by running the following command

{{{{
$ sudo apt-get install build-essential bison flex cmake qemu-system-x86 qemu-system-arm ghc libghc-src-exts-dev libghc-ghc-paths-dev libghc-parsec3-dev libghc-random-dev libghc-ghc-mtl-dev libghc-src-exts-dev libghc-async-dev gcc-arm-linux-gnueabi g++-arm-linux-gnueabi libgmp3-dev cabal-install curl freebsd-glue libelf-freebsd-dev libusb-1.0-0-dev qemu-utils gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
$ cabal install bytestring-trie
}}}}

Note: Sometimes cabal fails because its repository, [[hackage.haskell.org]], is down. In this case a mirror can be used, for example as documented in [[https://www.fpcomplete.com/blog/2015/03/hackage-mirror]].
=== Getting Barrelfish ===

First we need to get the latest version of Barrelfish from the mercurial repository. Use the following command:
{{{{
git clone git://git.barrelfish.org/git/barrelfish
}}}}

=== Configuring ===

Once you have cloned the repository, cd into it, create a build directory, and enter it:
{{{{
cd barrelfish
mkdir build
cd build
}}}}

=== Prepare for build: The hake build system ===
<<Anchor(ghc)>>

We use [[http://barrelfish.org/TN-003-Hake.pdf|hake]] to build barrelfish.

    * You need ghc. See the [[http://git.barrelfish.org/?p=barrelfish;a=blob;f=README|README]]. Please, read section [[#ghcVers|GHC Versions]] for more details.
    * Packages (already installed if you've followed the steps in the requirement section)
      * libghc-ghc-paths-dev
      * libghc-parsec3-dev
      * libghc-ghc-mtl-dev
      * libghc-src-exts-dev
      * libghc-async-dev
      * libghc-src-exts-dev
      * libghc-random-dev
      * freebsd-glue
      * libelf-freebsd-dev
      * and via Cabal: bytestring-trie

==== GHC Versions ====
<<Anchor(ghcVers)>>
7.10.3 is the version we use internally (read: the version Ubuntu 16.04 LTS ships). Note that Haskell/GHC tends to be not very backwards compatible even for different minor versions. Therefore, it is strongly recommended to use the version that Ubuntu LTS is currently shipping.


=== Build barrelfish ===

Then create the required makefile:
{{{{
../hake/hake.sh -s .. -a x86_64
}}}}

Valid arm targets are:
{{{{
../hake/hake.sh -s .. -a armv7
}}}}
or (experimental)
{{{{
../hake/hake.sh -s .. -a armv8 
}}}}

To see what make targets are available for building Barrelfish run
{{{{
make help-platforms
}}}}

To see what make targets are available for running Barrelfish run
{{{{
make help-boot
}}}}


'''Note:''' If you get the following error:
{{{{
stack overflow: use +RTS -K<size> to increase it
}}}}
Try to avoid having the build directory in the source tree

=== Compiling ===

Now we can build Barrelfish. The following target builds the basic binaries for X86.
{{{{
make X86_64_Basic
}}}}

To speed things up you can specify a number of jobs. This should ideally be slightly more than the number of cores, so on a 4-core machine you could use:
{{{{
make -j 5 X86_64_Basic
}}}}

Once that has completed, you can issue the following command to run Barrelfish on QEMU:
{{{{
make qemu_x86_64
}}}}

To change options for QEMU, such as allocating more cores, you might want to execute the '''tools/qemu_wrapper.sh''' directly.
The following commands allocates 4 cores.
{{{{
../tools/qemu-wrapper.sh --menu ./platforms/x86/menu.lst.x86_64 --arch x86_64  --smp 4
}}}}



== Known Issues ==

=== Gold linker ===
GNU binutils includes an ELF linker named "''gold''" which is faster than the default BFD linker for large C++ applications.  However, when linking Barrelfish's CPU driver you may see the following error:
{{{{
/usr/bin/ld: fatal error: -pie and -static are incompatible
collect2: error: ld returned 1 exit status
make: *** [x86_64/sbin/cpu] Error 1
}}}}

To fix this issue uninstall the ''binutils-gold'' package. For further details on why this occurs see [[http://sourceware-org.1504.n7.nabble.com/patch-ob-Disallow-pie-and-static-td150575.html#a33326172|this discussion]].