building vg (or not building vg)

Before we begin

vg isn't exactly easy to build. We use a lot of external libraries, many of which are quite large and might themselves have external dependencies.

If you want to try vg before committing to the build process, checkout our docker image (and please lets know if it doesn't work for you!). vg is also available on the SBG Cancer Genomics Cloud using Docker.

Basics

Alright, we need a few things before we even think about building vg:

1. A modern version (4.9+) of GCC.
2. automake / autotools
3. libtool (usually GNU-provided)
4. jq (for tests)
5. redland-utils (for RDF)
6. libRDF
7. CMAKE
8. raptor2 (for RDF)
9. rasqal (for RDF)
10. bison (for RDF)
11. flex (for RDF)
12. jansson
13. bzip2 library
14. ncurses
15. a bit of patience

We're working on wrapping these into a single repository with build scripts, but for the moment you'll either have to install them locally 1. by hand 2. using a package manager like apt, yum, or pacman, or 3. with the help of your system administrator.

make get-deps

We have to install all of the above packages on Travis CI when we test a nightly build, so we implemented a make command to install them. If you're on your own Ubuntu / Mint machine you might be able to leverage this to install vg's dependencies - simply type make get-deps, respond with your password when prompted with the sudo command, and you'll be off. This unfortunately won't work on clusters, servers, or the cloud.

Some notes on OS X builds

Many of us have had success building vg on OS X, though there are some additional challenges to do so.

1. You'll need to alias GNU libtool (glibtool on OS X) to libtool. alias libtool="glibtool"
2. You'll have to make sure your C++ compilers are organized correctly, with gcc the default compiler.
3. You'll have to ensure the right autotools/automake are present.
4. You'll have to make GNU make your default make system, instead of the Apple defaults.

Most of these can be performed easily enough with macports or homebrew. We'll keep expanding this section of the wiki as we can to make this process more transparent, but most of us find Linux builds (especially Ubuntu / Mint) to be easiest.

Git the vg source code

Move to your desired build directory - let's just say ~ - and grab the source code from github.

          cd ~
          git clone --recursive https://github.com/vgteam/vg.git

This will probably take a few minutes, depending on your connection speed.

Let's build it

Alright, first we need to prep our environment. We wrote a script to do this for you:

      cd vg
      source source_me.sh

Now, assuming you've got the right dependencies in place, all we need to do is run make. We design our makefiles for parallel builds, so you can use the -j flag to speed things up:

      make -j 4  # only use as at most many threads as your machine as cores

And that should be it; you can now run vg by sourcing the source_me.sh script and using the executable in ./bin.

     source source_me.sh
     ./bin/vg

If you run into problems, post an issue on our github. We want to make it easier to use vg so everyone can do more science with it; if you post something publicly we can all work together on a solution that might help others.

Help! It doesn't work!

Common problems with building and running vg may be answered on the Troubleshooting page. If that doesn't help, you can submit an issue.