Commit f9b1e182 authored by Pavel Hrdina's avatar Pavel Hrdina

docs: rewrite HACKING and README into markdown format and improve it

Reviewed-by: 's avatarDaniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Pavel Hrdina's avatarPavel Hrdina <phrdina@redhat.com>
parent 73635bd7
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;
}
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.
......@@ -7,6 +7,8 @@ EXTRA_DIST = \
$(PACKAGE).spec \
$(PACKAGE).spec.in \
AUTHORS.in \
HACKING.md \
README.md \
$(NULL)
DISTCLEAN_FILES = $(PACKAGE).spec
......
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@redhat.com
Questions about usage / deployment can be send to the end users mailing
list
libvirt-users@redhat.com
For further information about mailing lists & contacting the developers,
please consult
http://libvirt.org/contact.html
--End
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@redhat.com
Questions about usage / deployment can be send to the end users mailing
list
* libvirt-users@redhat.com
For further information about mailing lists & contacting the developers,
please consult
[https://libvirt.org/contact.html](https://libvirt.org/contact.html)
......@@ -52,7 +52,7 @@ exit 0
%files
%defattr(-,root,root,-)
%doc README COPYING AUTHORS NEWS
%doc README.md HACKING.md COPYING AUTHORS NEWS
%{_sysconfdir}/polkit-1/rules.d/libvirt-dbus.rules
%{_bindir}/libvirt-dbus
%{_datadir}/dbus-1/services/org.libvirt.service
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment