[libvirt] [dbus PATCH v3 5/5] docs: rewrite HACKING and README into markdown format and improve it
Pavel Hrdina
phrdina at redhat.com
Wed Mar 21 10:02:47 UTC 2018
Signed-off-by: Pavel Hrdina <phrdina at redhat.com>
---
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 at redhat.com
-
-Questions about usage / deployment can be send to the end users mailing
-list
-
- libvirt-users at redhat.com
-
-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 at redhat.com
+
+Questions about usage / deployment can be send to the end users mailing
+list
+
+ * libvirt-users at redhat.com
+
+For further information about mailing lists & contacting the developers,
+please consult
+
+[https://libvirt.org/contact.html](https://libvirt.org/contact.html)
--
2.14.3
More information about the libvir-list
mailing list