proxmox-mirrors/libgit2
1
0
Fork 0
mirror of https://git.proxmox.com/git/libgit2 synced 2025-05-03 00:43:41 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Clarify C compatibility policy

Browse Source 
and a couple of other minor doc fixups.
This commit is contained in:
Russell Belfer 2014-02-20 11:26:51 -08:00
parent 978a4ed5eb
commit 68a19ca9ff
3 changed files with 36 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
CONTRIBUTING.md
View File

@ -5,9 +5,13 @@ your help.
## Licensing
By contributing to libgit2, you agree to release your contribution under the terms of the license.
For code under `examples`, this is governed by the [CC0 Public Domain Dedication](examples/COPYING).
All other code is released under the [GPL v2 with linking exception](COPYING).
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
@ -76,15 +80,19 @@ 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 you are pulling in code from core Git, another project or code you've pulled from
a forum / Stack Overflow then please flag this in your PR and also make sure you've
given proper credit to the original author in the code snippet.
If you are pulling in code from core Git, another project or code you've
pulled from a forum / Stack Overflow then please flag this in your PR and
also make sure you've given proper credit to the original author in the
code snippet.
## Style Guide
`libgit2` is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
(a.k.a. C89) with some specific conventions for function and type naming,
code formatting, and testing.
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 compiler 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

21
CONVENTIONS.md
View File

@ -6,14 +6,18 @@ guidelines that should help with that.
## Compatibility
`libgit2` runs on many different platforms with many different compilers.
It is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C) (a.k.a. C89)
with some specific standards for function and type naming, code formatting,
and testing.
We try to avoid more recent extensions to maximize portability. We also, to
the greatest extent possible, 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.
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
@ -209,6 +213,9 @@ All inlined functions must be declared as:
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.

10
README.md
View File

@ -20,17 +20,17 @@ Additionally, the example code has been released to the public domain (see the
* API documentation: <http://libgit2.github.com/libgit2>
* IRC: [#libgit2](irc://irc.freenode.net/libgit2) on irc.freenode.net.
* Mailing list: The libgit2 mailing list was
traditionally hosted in Librelist but has been deprecated. We encourage you to
traditionally hosted in Librelist but has been deprecated. We encourage you to
[use StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) instead for any questions regarding
the library, or [open an issue](https://github.com/libgit2/libgit2/issues)
on GitHub for bug reports. The mailing list archives are still available at
the library, or [open an issue](https://github.com/libgit2/libgit2/issues)
on GitHub for bug reports. The mailing list archives are still available at
<http://librelist.com/browser/libgit2/>.
What It Can Do
==============
`libgit2` is already very usable and is being used in production for many applications including the GitHub.com site, in Plastic SCM
`libgit2` is already very usable and is being used in production for many applications including the GitHub.com site, in Plastic SCM
and also powering Microsoft's Visual Studio tools for Git. The library provides:
* SHA conversions, formatting and shortening
@ -65,7 +65,7 @@ Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthrea
they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API
for threading.
The `libgit2` library is built using `CMake 2.6+` (<http://www.cmake.org>) on all platforms.
The `libgit2` library is built using [CMake](<http://www.cmake.org>) (version 2.6 or newer) on all platforms.
On most systems you can build the library using the following commands