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

Signed-off-by: Pavel Hrdina <phrdina(a)redhat.com&gt; --- 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(a)redhat.com - -Questions about usage / deployment can be send to the end users mailing -list - - libvirt-users(a)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(a)redhat.com + +Questions about usage / deployment can be send to the end users mailing +list + + * libvirt-users(a)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