[PATCH c-hglib] readme: adding a description of the project

Iulian Stana julian.stana at gmail.com
Fri Sep 20 18:14:37 CDT 2013


# HG changeset patch
# User Iulian Stana <julian.stana at gmail.com>
# Date 1379718831 -10800
#      Sat Sep 21 02:13:51 2013 +0300
# Node ID 43bbd8b7a56b5a321bf073246225672ad7402461
# Parent  375cba922415aa678abd47ecd8b57875ab55743a
readme: adding a description of the project

diff --git a/README b/README
new file mode 100644
--- /dev/null
+++ b/README
@@ -0,0 +1,87 @@
+c-hglib
+""""""""
+
+c-hglib is a high-level C library for interacting with Mercurial.
+The project homepage is http://mercurial.selenic.com/wiki/C-Hglib.
+
+
+Features
+""""""""
+
+c-hglib gives you:
+
+    Fast: Normally, you would start a Mercurial process and then
+          parse the output. C-hglib uses the Mercurial command server instead.
+          This means that c-hglib starts a single Mercurial server process and
+          interacts with that for the following operations.
+
+    Convenient: We have done the hard work of parsing the output and
+          turning it into a useful C API. Parsing a command like hg log is
+          easy enough, but c-hglib also has code to talk with
+          the interactive commands such as hg merge.
+
+    Documented: c-hglib comes with extensive doxygen documentation
+          that describes how each command works and a complete suite of
+          examples.
+
+    Tested: We have unit tests for all commands.
+
+
+Purpose
+"""""""""
+
+c-hglib exists to provide a stable programmatic interface with Mercurial.
+Mercurial internal python API is deliberatedly unstable and undocumented;
+it can change from a Mercurial release without further notice.
+On the other hand, c-hglib focuses on stability of the interface for use
+in external projects: this is possible since it uses the Mercurial Command
+Server to communicate with Mercurial.
+
+Unlike Mercurial itself, which requires derived works be licensed with the
+GPLv2+, c-hglib is available under the less restrictive MIT license.
+
+This is possible since c-hglib is not derived work from Mercurial:
+*) it uses an interface explictly declared to be unencumbered
+*) was explicitly created to be unencumbered
+*) exactly mirrors the other unencumbered interface (the command line).
+You can't do anything with it that you can't already do from the command line...
+except go a bit faster.
+
+
+Deployment
+""""""""""
+c-hglib is build with autotools, i.e. configure/make/make install
+should be all what is needed to install it.
+
+
+Contact
+""""""""
+
+If you want to contact us, then please use one of these channels:
+
+    Mercurial-Devel mailing list:
+        http://mercurial.selenic.com/wiki/MailingLists#The_Mercurial-Devel_list
+        This is the place for discussion about the development of c-hglib.
+        You're also very welcome to send us a mail if you're using c-hglib in
+        a project.
+        Subscribe here: http://www.selenic.com/mailman/listinfo/mercurial/
+
+    Bitbucket Issue Tracker: This is where you should report bugs in c-hglib.
+       That would be problems of the form
+       "When I do ..., c-hglib doesn't behave as expected".
+
+Please remember to tell us which c-hglib version you're using.
+
+
+License
+""""""""
+
+c-hglib is distributed under the MIT license.
+
+
+Authors
+""""""""
+
+c-hglib was started by Iulian Stana as a Google Summer of Code 2013 project.
+See the commit log for the full list of authors.
+


More information about the Mercurial-devel mailing list