Getting Started

Requirements

These components will almost certainly already be on your system.

  • gcc (4.8+) OR clang (v3.1+)
  • pthreads
  • zlib

Double-check your compiler version, to be sure it is compatible.

$ g++ -v
$ clang -v

Additional requirements:

For additional languages:

For building API documentation locally:

For maximal convenience, install htslib and google test in the same parent directory you plan to install pbbam.

Clone & Build

Note

The following steps are for building the C++ library and command-line utilities. If you are integrating pbbam into a C#, Python, or R project, take a look at the instructions for additional languages.

The basic steps for obtaining pbbam and building it from source are as follows:

$ git clone https://github.com/PacificBiosciences/pbbam.git
$ cd pbbam
$ mkdir build
$ cd build
$ cmake ..
$ make -j 4    # compiles using 4 threads

Output:

  • Library : <pbbam_root>/lib
  • Headers : <pbbam_root>/include
  • Utilities : <pbbam_root>/bin

You may need to set a few options on the cmake command, to point to dependencies’ install locations. Common installation-related options include:

  • HTSLIB_ROOTDIR
  • GTEST_SRC_DIR

Add these using the ‘-D’ argument, like this:

$ cmake .. -DHTSLIB_ROOTDIR="path/to/htslib"

To run the test suite, run:

$ make test

To build a local copy of the (Doxygen-style) API documentation, run:

$ make doc

And then open <pbbam_root>/docs/html/index.html in your favorite browser.

Integrate

CMake-based projects

For CMake-based projects that will “ship with” or otherwise live alongside pbbam, you can use the approach described here.

Before defining your library or executable, add the following:

add_subdirectory(<path/to/pbbam> external/build/pbbam)

When it’s time to run “make” this will ensure that pbbam will be built, inside your own project’s build directory. After this point in the CMakeLists.txt file(s), a few variables will be available that can be used to setup your include paths and library linking targets:

include_directories(
    ${PacBioBAM_INCLUDE_DIRS}
    # other includes that your project needs
)

add_executable(foo)

target_link_libraries(foo
    ${PacBioBAM_LIBRARIES}
    # other libs that your project needs
)

Non-CMake projects

If you’re using something other than CMake for your project’s build system, then you need to point it to pbbam’s include directory & library, as well as those of its dependencies (primarily htslib).