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.
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
This also builds libgit2’s unit-test suite; to run it, just run
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
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
|VS Version||Command Line|
|Visual Studio 2010 (x86)||
|Visual Studio 2010 (amd64)||
|Visual Studio 2012 (x86)||
|Visual Studio 2012 (amd64)||
|Visual Studio 2013 (x86)||
|Visual Studio 2013 (amd64)||
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:
||This defaults to
||This selects the build configuration; available options are
||Selects whether the unit-test suite is built. This defaults to
||Selects whether libgit2 tries to be threadsafe. This defaults to
||Sets the basename of the output binary. For example, if this is set to
||(MSVC Only) By default, libgit2 builds with the
||(MSVC Only) By default, libgit2 will link to a DLL version of the C runtime. Set this to
Take a look at the
CMakeLists.txt file for more information.
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.
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
Make sure you’re configuring the proper build configuration:
C:\path\to\libgit2\include to “Additional Include Directories” under “C/C++ > General”.
The linker will need to know where to find the
C:\path\to\libgit2\build\Debug to “Linker > General > Additional Library Directories”.
You may want to configure this path differently for a Release build.
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.
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
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.
If you’re building statically, the output is typically a
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