How to Build Libgit2

There is no One True Way™ to use an open-source C library. This article provides some guidance on how to use libgit2 with various build/project tools.

Basic Build

Libgit2 is developed with CMake, and this will be the easiest way to build a binary from the source. Once you have CMake installed, performing a libgit2 build is fairly simple. In a shell session with the libgit2 root directory as the cwd, simply do this:

$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .

On posix-type systems, the output is typically ./libgit2.so; on Windows, it’s usually Debug\git2.dll.

This also builds libgit2’s unit-test suite; to run it, just run ./libgit2_clar or Debug\libgit2_clar.exe.

Notes for Visual Studio Users

The commands above should be run from within a Visual Studio command prompt; an SDK prompt will not work. The default set of commands above result in a build that’s the same bitness as your command prompt – a command prompt configured for 64-bit cross-compile tools will result in a 64-bit git2.dll. Also note that CMake is generating a Visual Studio solution file and several project files, and by default it chooses the latest version of Visual Studio that’s installed on your machine.

If you want to change either of these defaults, you have to specify a “generator” to CMake using the -G flag.

Advanced Build

The CMake build system provides lots of options to configure the libgit2 build for your particular needs. These are set by passing -D<variable>=<value> to CMake during the project-file generation step. Here are some of the most useful:

Take a look at the CMakeLists.txt file for more information.

Linking and Usage

Once you have a build, you probably want to use it from within your application. You’ll need to include git2.h, and link to the binaries you built previously.

Visual Studio

Your Visual Studio project will need to know where to find the libgit2 headers and link libraries. Open up the project settings by clicking on the project in the Solution Explorer, and selecting Properties.

Make sure you’re configuring the proper build configuration:

Add C:\path\to\libgit2\include to “Additional Include Directories” under “C/C++ > General”.

The linker will need to know where to find the git2.lib file. Add C:\path\to\libgit2\build\Debug to “Linker > General > Additional Library Directories”. You may want to configure this path differently for a Release build.

Finally, add git2.lib to the list of libraries to link in:

If you built libgit2 as a static library, you’re done! If it’s a DLL, you’ll have to make sure that git2.dll gets into the same directory as your output EXE file. You can do this with a post-build script (check “Build Events”), or by including the git2.vcxproj file in your solution, and changing its output directory to match where the rest of your binaries go.

XCode

NOTE: It’s highly recommended that you build libgit2 as a static library for Xcode projects. This simplifies distribution significantly, as the resolution of dynamic libraries at runtime can be extremely problematic.

Your search paths will need to be modified to include the location of the libgit2 headers. In Xcode 5, open the project node, open the Build Settings tab, make sure all settings are shown, and look for Header Search Paths:

If you’re working from a source distribution, the include path to add is /path/to/libgit2/include. You can add this to the target or the entire project.

Next you’ll have to link to the right binary library. Switch to the “Build Phases” tab, and under Link Binary With Libraries, click the “+”:

Then select “Add Other…”:

Browse to the location where the libgit2 binaries are located (if you’re working from source, this is /path/to/libgit2/build), select the libgit2.a file (or libgit2.dylib if you built a dynamic library), and click OK.

If you built libgit2 as a static library (again, this is highly recommended), you’ll need to also add all of these libraries to the list. They should all be available with the system, and easy to find with the search interface.

• libiconv.dylib
• libSystem.dylib
• libcrypto.dylib
• libssl.dylib
• libz.dylib

Makefiles, Autotools

If you’re building statically, the output is typically a libgit2.a file. Dynamically-linked outputs are usually libgit2.so on posix, or libgit2.dylib on OS X.

Using these files is dependent on your application’s project system. If you installed the library to a standard system location, you can use pkg-config to get the right flags to pass to the compiler.

LDFLAGS = $(shell pkg-config --libs libgit2)
CFLAGS = $(shell pkg-config --cflags libgit2)

In the same vein, using GNU Autotools, pkg-config can help you there.

PKG_CHECK_MODULES([libgit2], [libgit2])
AC_SUBST([libgit2_LIBS])
AC_SUBST([libgit2_CFLAGS])

If none of these options are available, then you can do it by hand:

CFLAGS += -I/path/to/libgit2/include
LDFLAGS += -L/path/to/libgit2/binaries
LIBRARIES += -lgit2