diff --git a/README.md b/README.md index 11f0ef464..5ead27ce8 100644 --- a/README.md +++ b/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 die() 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: +* API documentation: +* Usage guide: 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+ - -Required dependency: +The following libraries are required to manually build the libgit2 library: * zlib 1.2+ -Optional dependency: - -* LibSSL - -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 . - -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 - -Used to run the build system; no extra libraries required. -Should probably ship installed with your OS. - -* zlib 1.2+ - -* LibSSL - -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 - -Used to run the build system; no extra libraries required. - -* zlib 1.2+ (Windows API Version) - -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: -* LibSSL +* LibSSL **(optional)** -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)** + +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 - -Used to run the build system; no extra libraries required. - -* zlib 1.2+ - -* pthreads-w32 - -Or an equivalent pthreads implementation for non-POSIX systems - -* LibSSL - -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+ () 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 . + + 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. - - - - -Python --------------------- - -Pygit2 is a Python binding to libgit2. - - - -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. - - +* Rugged (Ruby bindings) +* pygit2 (Python bindings) +* libgit2sharp (.NET bindings) +* Geef (Erlang bindings) 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.