mirror of
https://git.proxmox.com/git/libgit2
synced 2025-05-28 08:58:41 +00:00
Update README.md
Add info on libgit2sharp, new build system, and usage guide. Signed-off-by: Vicent Marti <tanoku@gmail.com>
This commit is contained in:
Vicent Marti
parent
2619dee430
commit
e0d9e12e50
211
README.md
211
README.md
@ -5,22 +5,9 @@ libgit2 is a portable, pure C implementation of the Git core methods provided as
|
||||
re-entrant linkable library with a solid API, allowing you to write native
|
||||
speed custom Git applications in any language with bindings.
|
||||
|
||||
Why Do We Need It
|
||||
=======================
|
||||
|
||||
In the current Git project, though a libgit.a file is produced it is
|
||||
not re-entrant (it will call <code>die()</code> on basically any error)
|
||||
and it has no stable or well-designed public API. As there is no good
|
||||
way to link to this effectively, a new library was needed that fulfilled
|
||||
these requirements. Thus libgit2.
|
||||
|
||||
Though it would be nice to use the same library that Git itself uses,
|
||||
Git actually has a pretty simple storage format and just having native
|
||||
access to that is pretty useful. Eventually we would like to have most
|
||||
of the functionality of the core Git tools or even get the library
|
||||
integrated into Git itself, but in the meantime having a cleanly designed
|
||||
and maintained linkable Git library with a public API will likely be helpful
|
||||
to lots of people.
|
||||
* Website: <http://libgit2.github.com>
|
||||
* API documentation: <http://libgit2.github.com/libgit2/modules.html>
|
||||
* Usage guide: <http://libgit2.github.com/api.html>
|
||||
|
||||
What It Can Do
|
||||
==================================
|
||||
@ -35,144 +22,43 @@ libgit2 is already very usable.
|
||||
* tree traversal
|
||||
* basic index file (staging area) operations
|
||||
|
||||
Building libgit2 - Using CMake
|
||||
==============================
|
||||
Building libgit2 - External dependencies
|
||||
========================================
|
||||
|
||||
When building using CMake the following dependencies are required:
|
||||
|
||||
* CMake 2.6+ <http://www.cmake.org>
|
||||
|
||||
Required dependency:
|
||||
The following libraries are required to manually build the libgit2 library:
|
||||
|
||||
* zlib 1.2+ <http://www.zlib.net/>
|
||||
|
||||
Optional dependency:
|
||||
|
||||
* LibSSL <http://www.openssl.org/>
|
||||
|
||||
On most systems you can build the library using the following commands
|
||||
|
||||
$ mkdir build && cd build
|
||||
$ cmake ..
|
||||
$ cmake --build .
|
||||
|
||||
Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace.
|
||||
|
||||
To install the library you can specify the install prefix by setting:
|
||||
|
||||
$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
|
||||
$ cmake --build . --target install
|
||||
|
||||
For more advanced use or questions about CMake please read <http://www.cmake.org/Wiki/CMake_FAQ>.
|
||||
|
||||
Building libgit2 - Unix systems
|
||||
==================================
|
||||
|
||||
In Unix-like systems, like Linux, xBSD and Mac OS X, libgit2 has
|
||||
the following dependencies:
|
||||
|
||||
* Python 2.5-3.1 <http://www.python.org>
|
||||
|
||||
Used to run the build system; no extra libraries required.
|
||||
Should probably ship installed with your OS.
|
||||
|
||||
* zlib 1.2+ <http://www.zlib.net/>
|
||||
|
||||
* LibSSL <http://www.openssl.org/>
|
||||
|
||||
Only needed if you want to re-use OpenSSL's SHA1 routines; libgit2 compiles its own routines by default.
|
||||
|
||||
To build it, first configure the build system by running:
|
||||
|
||||
$ ./waf configure
|
||||
|
||||
Then build the library, either in its shared (libgit2.so) or static form (libgit2.a)
|
||||
|
||||
$ ./waf build-static
|
||||
$ ./waf build-shared
|
||||
|
||||
You can then test the library with:
|
||||
|
||||
$ ./waf test
|
||||
|
||||
And finally you can install it with (you may need to sudo):
|
||||
|
||||
$ ./waf install
|
||||
|
||||
Building libgit2 - Windows MSVC++
|
||||
==================================
|
||||
|
||||
When building under Windows using the MSVC compiler, libgit2 has
|
||||
the following dependencies:
|
||||
|
||||
* Python 2.5-3.1 <http://www.python.org>
|
||||
|
||||
Used to run the build system; no extra libraries required.
|
||||
|
||||
* zlib 1.2+ (Windows API Version) <http://www.zlib.net/>
|
||||
|
||||
Make sure you compile the ZLib library using the MSVC solution that ships in its source distribution.
|
||||
When building in Windows using MSVC, make sure you compile ZLib using the MSVC solution that ships in its source distribution.
|
||||
Alternatively, you may download precompiled binaries from: <http://www.winimage.com/zLibDll/>
|
||||
|
||||
* LibSSL <http://www.openssl.org/>
|
||||
* LibSSL **(optional)** <http://www.openssl.org/>
|
||||
|
||||
Only needed if you want to re-use OpenSSL's SHA1 routines; libgit2 compiles its own routines by default.
|
||||
libgit2 can be built using the SHA1 implementation of LibSSL-Crypto, instead of the built-in custom implementations. Performance wise, they are quite similar.
|
||||
|
||||
To build it, first configure the build system by running:
|
||||
* pthreads-w32 **(required on MinGW)** <http://sourceware.org/pthreads-win32/>
|
||||
|
||||
Building libgit2 - Using waf
|
||||
======================
|
||||
|
||||
Waf is a minimalist build system which only requires a Python 2.5+ interpreter to run. This is the default build system for libgit2.
|
||||
|
||||
To build libgit2 using waf, first configure the build system by running:
|
||||
|
||||
$ ./waf configure
|
||||
|
||||
Then build the library, either in its shared (libgit2.dll) or static form (libgit2.lib)
|
||||
Then build the library, either in its shared (libgit2.so) or static form (libgit2.a):
|
||||
|
||||
$ ./waf build-static
|
||||
$ ./waf build-shared
|
||||
|
||||
You can then test the library with:
|
||||
You can then run the full test suite with:
|
||||
|
||||
$ ./waf test
|
||||
|
||||
Lastly, you can manually install the generated *.lib and *.dll files, depending on your preferences.
|
||||
And finally you can install the library with (you may need to sudo):
|
||||
|
||||
Building libgit2 - Windows MinGW
|
||||
==================================
|
||||
|
||||
When building under Windows using the GCC compiler that ships with MinGW, libgit2 has the following dependencies:
|
||||
|
||||
* Python 2.5-3.1 <http://www.python.org>
|
||||
|
||||
Used to run the build system; no extra libraries required.
|
||||
|
||||
* zlib 1.2+ <http://www.zlib.net/>
|
||||
|
||||
* pthreads-w32 <http://sourceware.org/pthreads-win32/>
|
||||
|
||||
Or an equivalent pthreads implementation for non-POSIX systems
|
||||
|
||||
* LibSSL <http://www.openssl.org/>
|
||||
|
||||
Only needed if you want to re-use OpenSSL's SHA1 routines; libgit2 compiles its own routines by default.
|
||||
|
||||
To build it, first configure the build system and force GCC as the compiler,
|
||||
instead of the default MSVC:
|
||||
|
||||
$ ./waf configure --check-c-compiler=gcc
|
||||
|
||||
Then build the library, either in its shared (libgit2.so) or static form (libgit2.a)
|
||||
|
||||
$ ./waf build-static
|
||||
$ ./waf build-shared
|
||||
|
||||
You can then test the library with:
|
||||
|
||||
$ ./waf test
|
||||
|
||||
And finally you can install it with:
|
||||
|
||||
$ ./waf install
|
||||
|
||||
|
||||
Configuration settings
|
||||
==================================
|
||||
$ sudo ./waf install
|
||||
|
||||
The waf build system for libgit2 accepts the following flags:
|
||||
|
||||
@ -195,36 +81,37 @@ The waf build system for libgit2 accepts the following flags:
|
||||
You can run `./waf --help` to see a full list of install options and
|
||||
targets.
|
||||
|
||||
|
||||
Building libgit2 - Using CMake
|
||||
==============================
|
||||
|
||||
The libgit2 library can also be built using CMake 2.6+ (<http://www.cmake.org>) on all platforms.
|
||||
|
||||
On most systems you can build the library using the following commands
|
||||
|
||||
$ mkdir build && cd build
|
||||
$ cmake ..
|
||||
$ cmake --build .
|
||||
|
||||
Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace.
|
||||
|
||||
To install the library you can specify the install prefix by setting:
|
||||
|
||||
$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
|
||||
$ cmake --build . --target install
|
||||
|
||||
For more advanced use or questions about CMake please read <http://www.cmake.org/Wiki/CMake_FAQ>.
|
||||
|
||||
|
||||
Language Bindings
|
||||
==================================
|
||||
|
||||
So you want to use Git from your favorite programming language. Here are
|
||||
the bindings to libgit2 that are currently available:
|
||||
Here are the bindings to libgit2 that are currently available:
|
||||
|
||||
Ruby
|
||||
--------------------
|
||||
|
||||
Rugged is the reference library used to make sure the
|
||||
libgit2 API is sane. This should be mostly up to date.
|
||||
|
||||
<https://github.com/libgit2/rugged>
|
||||
|
||||
|
||||
Python
|
||||
--------------------
|
||||
|
||||
Pygit2 is a Python binding to libgit2.
|
||||
|
||||
<https://github.com/libgit2/pygit2>
|
||||
|
||||
Erlang
|
||||
--------------------
|
||||
|
||||
Geef is an example of an Erlang NIF binding to libgit2. A bit out of
|
||||
date, but basically works. Best as a proof of concept of what you could
|
||||
do with Erlang and NIFs with libgit2.
|
||||
|
||||
<https://github.com/schacon/geef>
|
||||
* Rugged (Ruby bindings) <https://github.com/libgit2/rugged>
|
||||
* pygit2 (Python bindings) <https://github.com/libgit2/pygit2>
|
||||
* libgit2sharp (.NET bindings) <https://github.com/nulltoken/libgit2sharp>
|
||||
* Geef (Erlang bindings) <https://github.com/schacon/geef>
|
||||
|
||||
If you start another language binding to libgit2, please let us know so
|
||||
we can add it to the list.
|
||||
@ -243,7 +130,7 @@ libgit2@librelist.com
|
||||
|
||||
License
|
||||
==================================
|
||||
libgit2 is under GPL2 with linking exemption, which basically means you
|
||||
libgit2 is under GPL2 **with linking exemption**. This means you
|
||||
can link to the library with any program, commercial, open source or
|
||||
other. However, you cannot modify libgit2 and distribute it without
|
||||
supplying the source.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user