Ben Visness

Compiling and using libgit2

Building libgit2

Installing dependencies

Windows

You must have CMake installed to compile libgit2. If it is not installed, visit the CMake download page and download the appropriate binary for your version of Windows.

Important: All terminal commands in this guide must be run from within a Visual Studio command prompt with administrator privileges. To launch this, search the start menu for "Developer Command Prompt" and choose the appropriate option. (The exact wording may vary based on your version of Visual Studio.)

Mac

You must have cmake installed to compile libgit2. You must have OpenSSL and libSSH2 installed for libgit2 to build correctly. The easiest way to install all of these is through Homebrew:

brew install cmake
brew install openssl
brew install libssh2

Compiling

When you have downloaded the libgit2 source, unzip it and cd into the folder. In that folder, run one of the following, depending on your operating system:

Windows

mkdir build
cd build
cmake .. -DBUILD_SHARED_LIBS=OFF -DBUILD_CLAR=OFF -DTHREADSAFE=ON
cmake --build .

Mac

mkdir build
cd build
cmake .. -DBUILD_SHARED_LIBS=OFF -DBUILD_CLAR=OFF -DTHREADSAFE=ON -DCMAKE_OSX_ARCHITECTURES="i386;x86_64"
cmake --build .

Options explained

  • BUILD_SHARED_LIBS=OFF makes libgit2 build as a static library (.lib for Windows, .a for Mac) instead of a dynamic library (.dll for Windows, .dylib for Mac). This is recommended by the libgit2 authors, as it simplifies project distribution.
  • BUILD_CLAR=OFF prevents cmake from also building the libgit2 unit test suite (which is only useful for libgit2 development.)
  • THREADSAFE=ON ensures that libgit2 will be safe for use in a multithreaded application.
  • CMAKE_OSX_ARCHITECTURES="i386;x86_64" is a necessary flag when building for OS X or macOS. (See the libgit2 readme.)

Installing

Once libgit2 is successfully built, run the following to install the library and C/C++ headers into a directory on your system:

Windows

To install libgit2 globally:

cmake --build . --target install

To install libgit2 into a specific project:

cmake .. -DCMAKE_INSTALL_PREFIX=\path\to\your\project
cmake --build . --target install

Mac

cmake .. -DCMAKE_INSTALL_PREFIX=<install directory>
cmake --build . --target install

<install directory> can be replaced with whatever path you like. You might do /usr/local for a system-wide installation, or /path/to/your/project for a project-specific installation.

Compiling a project that uses libgit2

This is the hard part. libgit2 has secret dependencies that tend to cause lots of linker errors.

Windows

libgit2 depends on the following libraries: winhttp, Rpcrt4, Crypt32.

Visual Studio

First follow the official instructions for linking libgit2 into a Visual Studio project.

When that is done, add the following as additional dependencies: winhttp.lib, Rpcrt4.lib, and Crypt32.lib. When finished, your Additional Dependencies line should look like the following:

git2.lib;winhttp.lib;Rpcrt4.lib;Crypt32.lib;%(AdditionalDependencies)

Mac

libgit2 depends on the following:

  • Frameworks: Security and CoreFoundation
  • Libraries: curl, z, iconv, ssh2

g++

g++ -I/path/to/git2/include                       \
    -L/path/to/git2/lib                           \
    -framework CoreFoundation -framework Security \
    -lcurl -lz -liconv -lssh2 -lgit2              \
    my_project.cpp

If you installed libgit2 in a system-standard location, you may omit the -I and -L lines, which tell g++ extra include and library paths.

Xcode

Someday...

Resolving linker errors

If you still get linker errors even when your compiler is configured correctly, you may not have all the required libraries installed. libssh2 is the most likely culprit, since it is not installed by default on Mac. You can install it with Homebrew like so:

brew install libssh2

curl, z, and iconv should be installed by default on your Mac, but if for some reason they are not, they can be installed through Homebrew as well:

brew install curl
brew install zlib
brew install libiconv

Homebrew will probably present warnings and extra messages when installing these typically standard libraries. Be careful.

Resources