Idea-Studios/libgit2
2
0
Fork 0
mirror of https://github.com/libgit2/libgit2.git synced 2026-06-22 06:26:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'pks/docs-improvements'

Browse Source
This commit is contained in:
Edward Thomson
2018-06-09 18:31:57 +01:00
parent 8a2de3538c 432dfda0fb
commit f81923efbe
9 changed files with 47 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1031
docs/changelog.md Normal file
View File

File diff suppressed because it is too large Load Diff

75
docs/code_of_conduct.md Normal file
View File

@@ -0,0 +1,75 @@
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at [libgit2@gmail.com][email]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]
[email]: mailto:libgit2@gmail.com
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/

175
docs/contributing.md Normal file
View File

@@ -0,0 +1,175 @@
# Welcome to libgit2!
We're making it easy to do interesting things with git, and we'd love to have
your help.
## Licensing
By contributing to libgit2, you agree to release your contribution under
the terms of the license. Except for the `examples` directory, all code
is released under the [GPL v2 with linking exception](COPYING).
The `examples` code is governed by the
[CC0 Public Domain Dedication](examples/COPYING), so that you may copy
from them into your own application.
## Discussion & Chat
We hang out in the
[`#libgit2`](http://webchat.freenode.net/?channels=#libgit2)) channel on
irc.freenode.net.
Also, feel free to open an
[Issue](https://github.com/libgit2/libgit2/issues/new) to start a discussion
about any concerns you have. We like to use Issues for that so there is an
easily accessible permanent record of the conversation.
## Libgit2 Versions
The `master` branch is the main branch where development happens.
Releases are tagged
(e.g. [v0.21.0](https://github.com/libgit2/libgit2/releases/tag/v0.21.0) )
and when a critical bug fix needs to be backported, it will be done on a
`<tag>-maint` maintenance branch.
## Reporting Bugs
First, know which version of libgit2 your problem is in and include it in
your bug report. This can either be a tag (e.g.
[v0.17.0](https://github.com/libgit2/libgit2/releases/tag/v0.17.0)) or a
commit SHA
(e.g. [01be7863](https://github.com/libgit2/libgit2/commit/01be7863)).
Using [`git describe`](http://git-scm.com/docs/git-describe) is a
great way to tell us what version you're working with.
If you're not running against the latest `master` branch version,
please compile and test against that to avoid re-reporting an issue that's
already been fixed.
It's *incredibly* helpful to be able to reproduce the problem. Please
include a list of steps, a bit of code, and/or a zipped repository (if
possible). Note that some of the libgit2 developers are employees of
GitHub, so if your repository is private, find us on IRC and we'll figure
out a way to help you.
## Pull Requests
Our work flow is a [typical GitHub
flow](https://guides.github.com/introduction/flow/index.html), where
contributors fork the [libgit2 repository](https://github.com/libgit2/libgit2),
make their changes on branch, and submit a
[Pull Request](https://help.github.com/articles/using-pull-requests)
(a.k.a. "PR"). Pull requests should usually be targeted at the `master`
branch.
Life will be a lot easier for you (and us) if you follow this pattern
(i.e. fork, named branch, submit PR). If you use your fork's `master`
branch directly, things can get messy.
Please include a nice description of your changes when you submit your PR;
if we have to read the whole diff to figure out why you're contributing
in the first place, you're less likely to get feedback and have your change
merged in.
In addition to outlining your thought process in the PR's description, please
also try to document it in your commits. We welcome it if every commit has a
description of why you have been doing your changes alongside with your
reasoning why this is a good idea. The messages shall be written in
present-tense and in an imperative style (e.g. "Add feature foobar", not "Added
feature foobar" or "Adding feature foobar"). Lines should be wrapped at 80
characters so people with small screens are able to read the commit messages in
their terminal without any problem.
To make it easier to attribute commits to certain parts of our code base, we
also prefer to have the commit subject be prefixed with a "scope". E.g. if you
are changing code in our merging subsystem, make sure to prefix the subject with
"merge:". The first word following the colon shall start with an lowercase
letter. The maximum line length for the subject is 70 characters, preferably
shorter.
If you are starting to work on a particular area, feel free to submit a PR
that highlights your work in progress (and note in the PR title that it's
not ready to merge). These early PRs are welcome and will help in getting
visibility for your fix, allow others to comment early on the changes and
also let others know that you are currently working on something.
Before wrapping up a PR, you should be sure to:
* Write tests to cover any functional changes
* Update documentation for any changed public APIs
* Add to the [`changelog.md`](changelog.md) file describing any major changes
## Unit Tests
We believe that our unit tests allow us to keep the quality of libgit2
high: any new changes must not cause unit test failures, and new changes
should include unit tests that cover the bug fixes or new features.
For bug fixes, we prefer unit tests that illustrate the failure before
the change, but pass with your changes.
In addition to new tests, please ensure that your changes do not cause
any other test failures. Running the entire test suite is helpful
before you submit a pull request. When you build libgit2, the test
suite will also be built. You can run most of the tests by simply running
the resultant `libgit2_clar` binary. If you want to run a specific
unit test, you can name it with the `-s` option. For example:
libgit2_clar -sstatus::worktree::long_filenames
Or you can run an entire class of tests. For example, to run all the
worktree status tests:
libgit2_clar -sstatus::worktree
The default test run is fairly exhaustive, but it will exclude some
unit tests by default: in particular, those that talk to network
servers and the tests that manipulate the filesystem in onerous
ways (and may need to have special privileges to run). To run the
network tests:
libgit2_clar -ionline
In addition, various tests may be enabled by environment variables,
like the ones that write exceptionally large repositories or manipulate
the filesystem structure in unexpected ways. These tests *may be
dangerous* to run on a normal machine and may harm your filesystem. It's
not recommended that you run these; instead, the continuous integration
servers will run these (in a sandbox).
## Porting Code From Other Open-Source Projects
`libgit2` is licensed under the terms of the GPL v2 with a linking
exception. Any code brought in must be compatible with those terms.
The most common case is porting code from core Git. Git is a pure GPL
project, which means that in order to port code to this project, we need the
explicit permission of the author. Check the
[`git.git-authors`](https://github.com/libgit2/libgit2/blob/development/git.git-authors)
file for authors who have already consented.
Other licenses have other requirements; check the license of the library
you're porting code *from* to see what you need to do. As a general rule,
MIT and BSD (3-clause) licenses are typically no problem. Apache 2.0
license typically doesn't work due to GPL incompatibility.
If your pull request uses code from core Git, another project, or code
from a forum / Stack Overflow, then *please* flag this in your PR and make
sure you've given proper credit to the original author in the code
snippet.
## Style Guide
The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
(a.k.a. C89) compatible. Internally, `libgit2` is written using a portable
subset of C99 - in order to compile with GCC, Clang, MSVC, etc., we keep
local variable declarations at the tops of blocks only and avoid `//` style
comments. Additionally, `libgit2` follows some extra conventions for
function and type naming, code formatting, and testing.
We like to keep the source code consistent and easy to read. Maintaining
this takes some discipline, but it's been more than worth it. Take a look
at the [conventions file](conventions.md).
## Starter Projects
See our [projects list](projects.md).

266
docs/conventions.md Normal file
View File

@@ -0,0 +1,266 @@
# Libgit2 Conventions
We like to keep the source consistent and readable. Herein are some
guidelines that should help with that.
## External API
We have a few rules to avoid surprising ways of calling functions and
some rules for consumers of the library to avoid stepping on each
other's toes.
- Property accessors return the value directly (e.g. an `int` or
`const char *`) but if a function can fail, we return a `int` value
and the output parameters go first in the parameter list, followed
by the object that a function is operating on, and then any other
arguments the function may need.
- If a function returns an object as a return value, that function is
a getter and the object's lifetime is tied to the parent
object. Objects which are returned as the first argument as a
pointer-to-pointer are owned by the caller and it is responsible
for freeing it. Strings are returned via `git_buf` in order to
allow for re-use and safe freeing.
- Most of what libgit2 does relates to I/O so as a general rule
you should assume that any function can fail due to errors as even
getting data from the filesystem can result in all sorts of errors
and complex failure cases.
- Paths inside the Git system are separated by a slash (0x2F). If a
function accepts a path on disk, then backslashes (0x5C) are also
accepted on Windows.
- Do not mix allocators. If something has been allocated by libgit2,
you do not know which is the right free function in the general
case. Use the free functions provided for each object type.
## Compatibility
`libgit2` runs on many different platforms with many different compilers.
The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
(a.k.a. C89) compatible.
Internally, `libgit2` is written using a portable subset of C99 - in order
to maximize compatibility (e.g. with MSVC) we avoid certain C99
extensions. Specifically, we keep local variable declarations at the tops
of blocks only and we avoid `//` style comments.
Also, to the greatest extent possible, we try to avoid lots of `#ifdef`s
inside the core code base. This is somewhat unavoidable, but since it can
really hamper maintainability, we keep it to a minimum.
## Match Surrounding Code
If there is one rule to take away from this document, it is *new code should
match the surrounding code in a way that makes it impossible to distinguish
the new from the old.* Consistency is more important to us than anyone's
personal opinion about where braces should be placed or spaces vs. tabs.
If a section of code is being completely rewritten, it is okay to bring it
in line with the standards that are laid out here, but we will not accept
submissions that contain a large number of changes that are merely
reformatting.
## Naming Things
All external types and functions start with `git_` and all `#define` macros
start with `GIT_`. The `libgit2` API is mostly broken into related
functional modules each with a corresponding header. All functions in a
module should be named like `git_modulename_functioname()`
(e.g. `git_repository_open()`).
Functions with a single output parameter should name that parameter `out`.
Multiple outputs should be named `foo_out`, `bar_out`, etc.
Parameters of type `git_oid` should be named `id`, or `foo_id`. Calls that
return an OID should be named `git_foo_id`.
Where a callback function is used, the function should also include a
user-supplied extra input that is a `void *` named "payload" that will be
passed through to the callback at each invocation.
## Typedefs
Wherever possible, use `typedef`. In some cases, if a structure is just a
collection of function pointers, the pointer types don't need to be
separately typedef'd, but loose function pointer types should be.
## Exports
All exported functions must be declared as:
```c
GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
```
## Internals
Functions whose *modulename* is followed by two underscores,
for example `git_odb__read_packed`, are semi-private functions.
They are primarily intended for use within the library itself,
and may disappear or change their signature in a future release.
## Parameters
Out parameters come first.
Whenever possible, pass argument pointers as `const`. Some structures (such
as `git_repository` and `git_index`) have mutable internal structure that
prevents this.
Callbacks should always take a `void *` payload as their last parameter.
Callback pointers are grouped with their payloads, and typically come last
when passed as arguments:
```c
int git_foo(git_repository *repo, git_foo_cb callback, void *payload);
```
## Memory Ownership
Some APIs allocate memory which the caller is responsible for freeing; others
return a pointer into a buffer that's owned by some other object. Make this
explicit in the documentation.
## Return codes
Most public APIs should return an `int` error code. As is typical with most
C library functions, a zero value indicates success and a negative value
indicates failure.
Some bindings will transform these returned error codes into exception
types, so returning a semantically appropriate error code is important.
Check
[`include/git2/errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h)
for the return codes already defined.
In your implementation, use `giterr_set()` to provide extended error
information to callers.
If a `libgit2` function internally invokes another function that reports an
error, but the error is not propagated up, use `giterr_clear()` to prevent
callers from getting the wrong error message later on.
## Structs
Most public types should be opaque, e.g.:
```C
typedef struct git_odb git_odb;
```
...with allocation functions returning an "instance" created within
the library, and not within the application. This allows the type
to grow (or shrink) in size without rebuilding client code.
To preserve ABI compatibility, include an `int version` field in all opaque
structures, and initialize to the latest version in the construction call.
Increment the "latest" version whenever the structure changes, and try to only
append to the end of the structure.
## Option Structures
If a function's parameter count is too high, it may be desirable to package
up the options in a structure. Make them transparent, include a version
field, and provide an initializer constant or constructor. Using these
structures should be this easy:
```C
git_foo_options opts = GIT_FOO_OPTIONS_INIT;
opts.baz = BAZ_OPTION_ONE;
git_foo(&opts);
```
## Enumerations
Typedef all enumerated types. If each option stands alone, use the enum
type for passing them as parameters; if they are flags to be OR'ed together,
pass them as `unsigned int` or `uint32_t` or some appropriate type.
## Code Layout
Try to keep lines less than 80 characters long. This is a loose
requirement, but going significantly over 80 columns is not nice.
Use common sense to wrap most code lines; public function declarations
can use a couple of different styles:
```c
/** All on one line is okay if it fits */
GIT_EXTERN(int) git_foo_simple(git_oid *id);
/** Otherwise one argument per line is a good next step */
GIT_EXTERN(int) git_foo_id(
git_oid **out,
int a,
int b);
```
Indent with tabs; set your editor's tab width to 4 for best effect.
Avoid trailing whitespace and only commit Unix-style newlines (i.e. no CRLF
in the repository - just set `core.autocrlf` to true if you are writing code
on a Windows machine).
## Documentation
All comments should conform to Doxygen "javadoc" style conventions for
formatting the public API documentation. Try to document every parameter,
and keep the comments up to date if you change the parameter list.
## Public Header Template
Use this template when creating a new public header.
```C
#ifndef INCLUDE_git_${filename}_h__
#define INCLUDE_git_${filename}_h__
#include "git/common.h"
/**
* @file git/${filename}.h
* @brief Git some description
* @defgroup git_${filename} some description routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/* ... definitions ... */
/** @} */
GIT_END_DECL
#endif
```
## Inlined functions
All inlined functions must be declared as:
```C
GIT_INLINE(result_type) git_modulename_functionname(arg_list);
```
`GIT_INLINE` (or `inline`) should not be used in public headers in order
to preserve ANSI C compatibility.
## Tests
`libgit2` uses the [clar](https://github.com/vmg/clar) testing framework.
All PRs should have corresponding tests.
* If the PR fixes an existing issue, the test should fail prior to applying
the PR and succeed after applying it.
* If the PR is for new functionality, then the tests should exercise that
new functionality to a certain extent. We don't require 100% coverage
right now (although we are getting stricter over time).
When adding new tests, we prefer if you attempt to reuse existing test data
(in `tests-clar/resources/`) if possible. If you are going to add new test
repositories, please try to strip them of unnecessary files (e.g. sample
hooks, etc).

93
docs/projects.md Normal file
View File

@@ -0,0 +1,93 @@
Projects For LibGit2
====================
So, you want to start helping out with `libgit2`? That's fantastic! We
welcome contributions and we promise we'll try to be nice.
This is a list of libgit2 related projects that new contributors can take
on. It includes a number of good starter projects as well as some larger
ideas that no one is actively working on.
## Before You Start
Please start by reading the [README.md](../README.md),
[contributing.md](contributing.md), and [conventions.md](conventions.md)
files before diving into one of these projects. Those explain our work
flow and coding conventions to help ensure that your work will be easily
integrated into libgit2.
Next, work through the build instructions and make sure you can clone the
repository, compile it, and run the tests successfully. That will make
sure that your development environment is set up correctly and you are
ready to start on libgit2 development.
## Starter Projects
These are good small projects to get started with libgit2.
* Look at the `examples/` programs, find an existing one that mirrors a
core Git command and add a missing command-line option. There are many
gaps right now and this helps demonstrate how to use the library. Here
are some specific ideas (though there are many more):
* Fix the `examples/diff.c` implementation of the `-B`
(a.k.a. `--break-rewrites`) command line option to actually look for
the optional `[<n>][/<m>]` configuration values. There is an
existing comment that reads `/* TODO: parse thresholds */`. The
trick to this one will be doing it in a manner that is clean and
simple, but still handles the various cases correctly (e.g. `-B/70%`
is apparently a legal setting).
* As an extension to the matching idea for `examples/log.c`, add the
`-i` option to use `strcasestr()` for matches.
* For `examples/log.c`, implement the `--first-parent` option now that
libgit2 supports it in the revwalk API.
* Pick a Git command that is not already emulated in `examples/` and write
a new example that mirrors the behavior. Examples don't have to be
perfect emulations, but should demonstrate how to use the libgit2 APIs
to get results that are similar to Git commands. This lets you (and us)
easily exercise a particular facet of the API and measure compatibility
and feature parity with core git.
* Submit a PR to clarify documentation! While we do try to document all of
the APIs, your fresh eyes on the documentation will find areas that are
confusing much more easily.
If none of these appeal to you, take a look at our issues list to see if
there are any unresolved issues you'd like to jump in on.
## Larger Projects
These are ideas for larger projects mostly taken from our backlog of
[Issues](https://github.com/libgit2/libgit2/issues). Please don't dive
into one of these as a first project for libgit2 - we'd rather get to
know you first by successfully shipping your work on one of the smaller
projects above.
Some of these projects are broken down into subprojects and/or have
some incremental steps listed towards the larger goal. Those steps
might make good smaller projects by themselves.
* Port part of the Git test suite to run against the command line emulation
in `examples/`
* Pick a Git command that is emulated in our `examples/` area
* Extract the Git tests that exercise that command
* Convert the tests to call our emulation
* These tests could go in `examples/tests/`...
* Add hooks API to enumerate and manage hooks (not run them at this point)
* Enumeration of available hooks
* Lookup API to see which hooks have a script and get the script
* Read/write API to load a hook script and write a hook script
* Eventually, callback API to invoke a hook callback when libgit2
executes the action in question
* Isolate logic of ignore evaluation into a standalone API
* Upgrade internal libxdiff code to latest from core Git
* Tree builder improvements:
* Extend to allow building a tree hierarchy
* Apply-patch API
* Add a patch editing API to enable "git add -p" type operations
* Textconv API to filter binary data before generating diffs (something
like the current Filter API, probably).
* Performance profiling and improvement
* Support "git replace" ref replacements
* Include conflicts in diff results and in status
* GIT_DELTA_CONFLICT for items in conflict (with multiple files)
* Appropriate flags for status
* Support sparse checkout (i.e. "core.sparsecheckout" and ".git/info/sparse-checkout")

8
docs/release.md
View File

@@ -15,8 +15,8 @@ We aim to release once every six months. We start the process by opening an issu
- [ ] Make a release candidate
- [ ] Plug any final leaks
- [ ] Fix any last-minute issues
- [ ] Make sure CHANGELOG reflects everything worth discussing
- [ ] Update the version in CHANGELOG and the header
- [ ] Make sure changelog.md reflects everything worth discussing
- [ ] Update the version in changelog.md and the header
- [ ] Produce a release candidate
- [ ] Tag
- [ ] Create maint/v0.X
@@ -26,13 +26,13 @@ We tag at least one release candidate. This RC must carry the new version in the
Preparing the first release candidate includes updating the version number of libgit2 to the new version number. To do so, a pull request shall be submitted that adjusts the version number in the following places:
- CHANGELOG.md
- docs/changelog.md
- include/git2/version.h
- package.json
As soon as the pull request is merged, the merge commit shall be tagged with a lightweight tag.
The tagging happens via GitHub's "releases" tab which lets us attach release notes to a particular tag. In the description we include the changes in `CHANGELOG.md` between the last full release. Use the following as a base for the release notes
The tagging happens via GitHub's "releases" tab which lets us attach release notes to a particular tag. In the description we include the changes in `docs/changelog.md` between the last full release. Use the following as a base for the release notes
This is the first release of the v0.X series, <codename>. The changelog follows.

115
docs/threading.md Normal file
View File

@@ -0,0 +1,115 @@
Threads in libgit2
==================
You may safely use any libgit2 object from any thread, though there
may be issues depending on the cryptographic libraries libgit2 or its
dependencies link to (more on this later). For libgit2 itself,
provided you take the following into consideration you won't run into
issues:
Sharing objects
---------------
Use an object from a single thread at a time. Most data structures do
not guard against concurrent access themselves. This is because they
are rarely used in isolation and it makes more sense to synchronize
access via a larger lock or similar mechanism.
There are some objects which are read-only/immutable and are thus safe
to share across threads, such as references and configuration
snapshots.
Error messages
--------------
The error message is thread-local. The `giterr_last()` call must
happen on the same thread as the error in order to get the
message. Often this will be the case regardless, but if you use
something like the [GCD](http://en.wikipedia.org/wiki/Grand_Central_Dispatch)
on Mac OS X (where code is executed on an arbitrary thread), the code
must make sure to retrieve the error code on the thread where the error
happened.
Threads and cryptographic libraries
=======================================
On Windows
----------
When built as a native Windows DLL, libgit2 uses WinCNG and WinHTTP,
both of which are thread-safe. You do not need to do anything special.
When using libssh2 which itself uses WinCNG, there are no special
steps necessary. If you are using a MinGW or similar environment where
libssh2 uses OpenSSL or libgcrypt, then the general case affects
you.
On Mac OS X
-----------
By default we use libcurl to perform the encryption. The
system-provided libcurl uses SecureTransport, so no special steps are
necessary. If you link against another libcurl (e.g. from homebrew)
refer to the general case.
If the option to use libcurl was deactivated, the library makes use of
CommonCrypto and SecureTransport for cryptographic support. These are
thread-safe and you do not need to do anything special.
Note that libssh2 may still use OpenSSL itself. In that case, the
general case still affects you if you use ssh.
General Case
------------
If it's available, by default we use libcurl to provide HTTP tunneling support,
which may be linked against a number of cryptographic libraries and has its
own
[recommendations for thread safety](https://curl.haxx.se/libcurl/c/threadsafe.html).
If there are no alternative TLS implementations (currently only
SecureTransport), libgit2 uses OpenSSL in order to use HTTPS as a transport.
OpenSSL is thread-safe starting at version 1.1.0. If your copy of libgit2 is
linked against that version, you do not need to take any further steps.
Older versions of OpenSSL are made to be thread-implementation agnostic, and the
users of the library must set which locking function it should use. libgit2
cannot know what to set as the user of libgit2 may also be using OpenSSL independently and
the locking settings must then live outside the lifetime of libgit2.
Even if libgit2 doesn't use OpenSSL directly, OpenSSL can still be used by
libssh2 or libcurl depending on the configuration. If OpenSSL is used by
more than one library, you only need to set up threading for OpenSSL once.
If libgit2 is linked against OpenSSL, it provides a last-resort convenience function
`git_openssl_set_locking()` (available in `sys/openssl.h`) to use the
platform-native mutex mechanisms to perform the locking, which you can use
if you do not want to use OpenSSL outside of libgit2, or you
know that libgit2 will outlive the rest of the operations. It is then not
safe to use OpenSSL multi-threaded after libgit2's shutdown function
has been called. Note `git_openssl_set_locking()` only works if
libgit2 uses OpenSSL directly - if OpenSSL is only used as a dependency
of libssh2 or libcurl as described above, `git_openssl_set_locking()` is a no-op.
If your programming language offers a package/bindings for OpenSSL,
you should very strongly prefer to use that in order to set up
locking, as they provide a level of coordination which is impossible
when using this function.
See the
[OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html)
on threading for more details, and http://trac.libssh2.org/wiki/MultiThreading
for a specific example of providing the threading callbacks.
libssh2 may be linked against OpenSSL or libgcrypt. If it uses OpenSSL,
see the above paragraphs. If it uses libgcrypt, then you need to
set up its locking before using it multi-threaded. libgit2 has no
direct connection to libgcrypt and thus has no convenience functions for
it (but libgcrypt has macros). Read libgcrypt's
[threading documentation for more information](http://www.gnupg.org/documentation/manuals/gcrypt/Multi_002dThreading.html)
It is your responsibility as an application author or packager to know
what your dependencies are linked against and to take the appropriate
steps to ensure the cryptographic libraries are thread-safe. We agree
that this situation is far from ideal but at this time it is something
the application authors need to deal with.

13
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,13 @@
Troubleshooting libgit2 Problems
================================
CMake Failures
--------------
* **`Asked for OpenSSL TLS backend, but it wasn't found`**
CMake cannot find your SSL/TLS libraries. By default, libgit2 always
builds with HTTPS support, and you are encouraged to install the
OpenSSL libraries for your system (eg, `apt-get install libssl-dev`).
For development, if you simply want to disable HTTPS support entirely,
pass the `-DUSE_HTTPS=OFF` argument to `cmake` when configuring it.