[dbus PATCH v3 5/5] docs: rewrite HACKING and README into markdown format and improve it

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Pavel Hrdina <phrdina@xxxxxxxxxx>
---
 HACKING     | 199 ------------------------------------------------------------
 HACKING.md  | 191 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile.am |   2 +
 README      |  80 ------------------------
 README.md   |  72 ++++++++++++++++++++++
 5 files changed, 265 insertions(+), 279 deletions(-)
 delete mode 100644 HACKING
 create mode 100644 HACKING.md
 delete mode 100644 README
 create mode 100644 README.md

diff --git a/HACKING b/HACKING
deleted file mode 100644
index 21fb683..0000000
--- a/HACKING
+++ /dev/null
@@ -1,199 +0,0 @@
-              Tips for hacking on libvirt-dbus
-              ================================
-
-
-Coding style rules
-
- - Opening & closing braces for functions should be at start of line
-
-     int
-     foo(int bar)
-     {
-       ...
-     }
-
-   Not
-
-     int
-     foo(int bar) {
-       ...
-     }
-
-
-
- - Opening brace for if/while/for loops should be at the end of line
-
-     if (foo) {
-        bar;
-        wizz;
-     }
-
-   Not
-
-     if (foo)
-     {
-        bar;
-        wizz;
-     }
-
-   Rationale: putting every if/while/for opening brace on a new line
-   expands function length too much
-
-
-
- - If a brace needs to be used for one clause in an if/else statement,
-   it should be used for both clauses, even if the other clauses are
-   only single statements. eg
-
-      if (foo) {
-         bar;
-         wizz;
-      } else {
-         eek;
-      }
-
-   Not
-
-      if (foo) {
-         bar;
-         wizz;
-      } else
-         eek;
-
-
-
- - Function parameter attribute annotations should follow the parameter
-   name, eg
-
-      int
-      foo(int bar G_GNUC_UNUSED)
-      {
-      }
-
-   Not
-
-      int
-      foo(G_GNUC_UNUSED int bar)
-      {
-      }
-
-   Rationale: Adding / removing G_GNUC_UNUSED  should not cause the
-   rest of the line to move around since that obscures diffs.
-
-
-
- - There should be no space between function names & open brackets eg
-
-      int
-      foo(int bar)
-      {
-      }
-
-   Not
-
-      int
-      foo (int bar)
-      {
-      }
-
-
-
- - To keep lines under 80 characters (where practical), multiple parameters
-   should be on new lines. Do not attempt to line up parameters vertically
-   eg
-
-      int
-      foo(int bar,
-          unsigned long wizz)
-      {
-      }
-
-   Not
-
-      int
-      foo(int bar, unsigned long wizz)
-      {
-      }
-
-   Not
-
-      int
-      foo(int           bar,
-          unsigned long wizz)
-      {
-      }
-
-    Rationale: attempting vertical alignment causes bigger diffs when
-    modifying code if type names change causing whitespace re-alignment.
-
-
- - Usage of goto should follow one of the following patterns, and
-   label naming conventions. In particular any exit path jumps should
-   obay the 'cleanup' vs 'error' label naming
-
-   * Interrupted system calls:
-
-      retry:
-        err = func()
-        if (err < 0 && errno == EINTR)
-            goto retry;
-
-     Alternate label name:  retry_func:
-
-
-   * Shared cleanup paths:
-
-       int
-       foo(int bar)
-       {
-          int ret = -1;
-
-
-          if (something goes wrong)
-             goto cleanup;
-
-          ret = 0;
-        cleanup:
-          ...shared cleanup code...
-          return ret;
-       }
-
-
-   * Separate error exit paths:
-
-       int
-       foo(int bar)
-       {
-          if (something goes wrong)
-             goto error;
-
-          return 0;
-
-        error:
-          ...error cleanup code...
-          return -1;
-       }
-
-
-   * Separate and shared error exit paths:
-
-       int
-       foo(int bar)
-       {
-          int ret = -1;
-
-          if (something very bad goes wrong)
-             goto error;
-
-          if (something goes wrong)
-             goto cleanup;
-
-          ret = 0;
-        cleanup:
-          ...shared cleanup code...
-          return 0;
-
-        error:
-          ...error cleanup code...
-          return -1;
-       }
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..75aa6d0
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,191 @@
+Tips for hacking on libvirt-dbus
+================================
+
+Here is where to get code:
+
+```
+$ git clone https://libvirt.org/git/libvirt-dbus.git
+```
+
+Alternatively you can use one of the mirrors:
+
+[https://github.com/libvirt/libvirt-dbus](https://github.com/libvirt/libvirt-dbus)
+[https://gitlab.com/libvirt/libvirt-dbus](https://gitlab.com/libvirt/libvirt-dbus)
+
+
+Running from git repository
+---------------------------
+
+  * The first step is to run autoreconf to create configure script:
+
+    ```
+    ./autogen.sh
+    ```
+
+    Now you can compile libvirt-dbus:
+
+    ```
+    make
+    ```
+
+
+  * Before posting a patch, you should run tests:
+
+    ```
+    make check
+    ```
+
+    The test tool requires python3 and python3-dbus.
+
+
+  * To run libvirt-dbus directly from the build dir without installing it
+    use the run script:
+
+    ```
+    ./run ./src/libvirt-dbus
+    ```
+
+
+Coding style rules
+------------------
+
+  * Opening & closing braces for functions should be at start of line:
+
+    ```
+    int
+    foo(int bar)
+    {
+        ...
+    }
+    ```
+
+    Not
+
+    ```
+    int
+    foo(int bar) {
+        ...
+    }
+    ```
+
+  * Opening brace for if/while/for loops should be at the end of line:
+
+    ```
+    if (foo) {
+        bar;
+        wizz;
+    }
+    ```
+
+    Not
+
+    ```
+    if (foo)
+    {
+        bar;
+        wizz;
+    }
+    ```
+
+    Rationale: putting every if/while/for opening brace on a new line
+    expands function length too much.
+
+
+  * If a brace needs to be used for one clause in an if/else statement,
+    it should be used for both clauses, even if the other clauses are
+    only single statements. eg:
+
+    ```
+    if (foo) {
+        bar;
+        wizz;
+    } else {
+        eek;
+    }
+    ```
+
+    Not
+
+    ```
+    if (foo) {
+        bar;
+        wizz;
+    } else
+        eek;
+    ```
+
+
+  * Function parameter attribute annotations should follow the parameter
+    name, eg:
+
+    ```
+    int
+    foo(int bar G_GNUC_UNUSED)
+    {
+    }
+    ```
+
+    Not
+
+    ```
+    int
+    foo(G_GNUC_UNUSED int bar)
+    {
+    }
+    ```
+
+    Rationale: Adding / removing G_GNUC_UNUSED  should not cause the
+    rest of the line to move around since that obscures diffs.
+
+
+  * There should be no space between function names & open brackets eg:
+
+    ```
+    int
+    foo(int bar)
+    {
+    }
+    ```
+
+    Not
+
+    ```
+    int
+    foo (int bar)
+    {
+    }
+    ```
+
+
+  * To keep lines under 80 characters (where practical), multiple parameters
+    should be on new lines. Do not attempt to line up parameters vertically eg:
+
+    ```
+    int
+    foo(int bar,
+        unsigned long wizz)
+    {
+    }
+    ```
+
+    Not
+
+    ```
+    int
+    foo(int bar, unsigned long wizz)
+    {
+    }
+    ```
+
+    Not
+
+    ```
+    int
+    foo(int           bar,
+        unsigned long wizz)
+    {
+    }
+    ```
+
+    Rationale: attempting vertical alignment causes bigger diffs when
+    modifying code if type names change causing whitespace re-alignment.
diff --git a/Makefile.am b/Makefile.am
index d2c3fc5..a890ff1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -7,6 +7,8 @@ EXTRA_DIST = \
 	$(PACKAGE).spec \
 	$(PACKAGE).spec.in \
 	AUTHORS.in \
+	HACKING.md \
+	README.md \
 	$(NULL)
 
 DISTCLEAN_FILES = $(PACKAGE).spec
diff --git a/README b/README
deleted file mode 100644
index b95b09b..0000000
--- a/README
+++ /dev/null
@@ -1,80 +0,0 @@
-libvirt-dbus
-============
-
-libvirt is a C toolkit to interact with the virtualization capabilities
-of recent versions of Linux (and other OSes). It is free software
-available under the GNU Lesser General Public License. Virtualization on
-the Linux Operating System means the ability to run multiple instances of
-Operating Systems concurrently on a single hardware system where the basic
-resources are driven by a Linux instance. The library aim at providing
-long term stable C API initially for the Xen paravirtualization but
-should be able to integrate other virtualization mechanisms if needed.
-
-libvirt-dbus wraps libvirt to provide a high-level object-oriented API better
-suited for dbus-based applications
-
-libvirt-dbus is Free Software and licenced under LGPLv2+.
-
-The latest official releases can be found at:
-
-  ftp://libvirt.org/libvirt/dbus/
-
-NB: at this time, libvirt-dbus is *NOT* considered API/ABI stable. Future
-releases may still include API/ABI incompatible changes.
-
-Dependencies / supported platforms
-==================================
-
-The libvirt-dbus projects attempts to be moderately conservative
-about updating the minimum required versions of external package
-dependencies, to strike a balance between enabling use of new
-features while minimizing inconvenience for downstream developers
-on distro platforms with specific shipped versions.
-
-There are roughly two classes of Linux distro - short lifetime
-(Fedora, Ubuntu non-LTS, etc) and extended lifetime (RHEL, CentOS,
-Debian, Ubuntu LTS). Based on this classification, the libvirt-dbus
-project will generally aim to ensure build support for
-
- - Most recent 2 releases of short lifetime distros
- - Most recent major release of extended lifetime distros,
-   with most recent 2 minor updates
-
-The project will consider RHEL, Fedora, Debian, Ubuntu LTS, Ubuntu,
-OpenSUSE and SUSE (SLES/SLED) distros to be a representative subset
-of distros when determining min required versions of external deps
-that is reasonable to target. Other distros of similar release vintage
-will typically have similar versions to at least one of these distros.
-In the case of Debian, the project may at times choose to require use
-of an update from the backports repository.
-
-At any time, it may be possible to build on versions of distros
-that are older than those implied by this policy, but the project
-will not guarantee this remains the case in future releases. The
-min required package versions of external dependencies may be
-raised in future releases based on this distro build target policy.
-
-The packages required to build libvirt-dbus are
-
- - libvirt
- - glib2
-
-Patches submissions
-===================
-
-Patch submissions are welcomed from any interested contributor. Please
-send them to the main libvir-list mailing list
-
-    libvir-list@xxxxxxxxxx
-
-Questions about usage / deployment can be send to the end users mailing
-list
-
-    libvirt-users@xxxxxxxxxx
-
-For further information about mailing lists & contacting the developers,
-please consult
-
-    http://libvirt.org/contact.html
-
---End
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ce265c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+libvirt-dbus
+============
+
+Libvirt provides a portable, long term stable C API for managing the
+virtualization technologies provided by many operating systems. It
+includes support for QEMU, KVM, Xen, LXC, bhyve, Virtuozzo, VMware
+vCenter and ESX, VMware Desktop, Hyper-V, VirtualBox and the POWER
+Hypervisor.
+
+libvirt-dbus wraps libvirt API to provide a high-level object-oriented
+API better suited for dbus-based applications.
+
+libvirt-dbus is Free Software and licenced under LGPLv2+.
+
+  * [https://libvirt.org/libvirt-dbus.html](https://libvirt.org/dbus.html)
+
+The latest official releases can be found at:
+
+  * [https://libvirt.org/sources/dbus/](https://libvirt.org/sources/dbus/)
+
+NB: at this time, libvirt-dbus is *NOT* considered API/ABI stable. Future
+releases may still include API/ABI incompatible changes.
+
+
+Dependencies / supported platforms
+----------------------------------
+
+The packages required to build libvirt-dbus are
+
+  - libvirt
+  - libvirt-glib
+  - glib2
+
+
+Installation
+------------
+
+libvirt-dbus uses GNU Autotools build system, so the build & install
+process is fairly simple. For example, to install as root user:
+
+```
+# ./configure --prefix=/usr --sysconfigdir=/etc --localstatedir=/var
+# make
+# make install
+```
+
+or to install as unprivileged user:
+
+```
+$ ./configure --prefix=$HOME/usr
+$ make
+$ make install
+```
+
+
+Patches submissions
+===================
+
+Patch submissions are welcomed from any interested contributor. Please
+send them to the main libvir-list mailing list
+
+  * libvir-list@xxxxxxxxxx
+
+Questions about usage / deployment can be send to the end users mailing
+list
+
+  * libvirt-users@xxxxxxxxxx
+
+For further information about mailing lists & contacting the developers,
+please consult
+
+[https://libvirt.org/contact.html](https://libvirt.org/contact.html)
-- 
2.14.3

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list



[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux