External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-28 08:35:22 +00:00
Code Issues Packages Projects Releases Wiki Activity
8e7f57a7b8
libvirt/docs/hacking.html.in

1154 lines
39 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<body>
<h1>Contributor guidelines</h1>
<ul id="toc"></ul>
<h2><a name="patches">General tips for contributing patches</a></h2>
<ol>
<li>Discuss any large changes on the mailing list first. Post patches
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
early and listen to feedback.</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
docs: mention git rename detection I've noticed a number of people sending patches with file renames not compressed, so we might as well document how to set this up. (Git won't do it by default, for back-compat reasons) * docs/hacking.html.in: Add git config tip. * HACKING: Regenerate.
2013-01-11 00:39:04 +00:00
<li><p>Post patches in unified diff format, with git rename
detection enabled. You need a one-time setup of:</p>
<pre>
git config diff.renames true
</pre>
<p>After that, a command similar to this should work:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
diff -urp libvirt.orig/ libvirt.modified/ &gt; libvirt-myfeature.patch
</pre>
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<p>
or:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Various typos and misspellings
2012-10-11 16:31:20 +00:00
git diff &gt; libvirt-myfeature.patch
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
docs: mention git rename detection I've noticed a number of people sending patches with file renames not compressed, so we might as well document how to set this up. (Git won't do it by default, for back-compat reasons) * docs/hacking.html.in: Add git config tip. * HACKING: Regenerate.
2013-01-11 00:39:04 +00:00
<p>Also, for code motion patches, you may find that <code>git
diff --patience</code> provides an easier-to-read patch.
However, the usual workflow of libvirt developer is:</p>
docs: Improve patch submission guidelines We should really advise (new) developers to send rebased patches that apply cleanly and use git-send-email rather than all other obscure ways.
2012-07-09 08:01:21 +00:00
<pre>
git checkout master
git pull
git checkout -t origin -b workbranch
Hack, committing any changes along the way
</pre>
build: honor autogen.sh --no-git Based on a report by Chandrashekar Shastri, at https://bugzilla.redhat.com/show_bug.cgi?id=979360 On systems where git cannot access the outside world, a developer can instead arrange to get a copy of gnulib at the right commit via side channels (such as NFS share drives), set GNULIB_SRCDIR, then use ./autogen.sh --no-git. In this setup, we will now avoid direct use of git. Of course, this means no automatic gnulib updates when libvirt.git updates its submodule, but it is expected that any developer in such a situation is already prepared to deal with the fallout. * .gnulib: Update to latest, for bootstrap. * bootstrap: Synchronize from gnulib. * autogen.sh (no_git): Avoid git when requested. * cfg.mk (_update_required): Skip automatic rerun of bootstrap if we can't use git. * docs/compiling.html.in: Document this setup. * docs/hacking.html.in: Mention this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-03 20:43:11 +00:00
<p>More hints on compiling can be
found <a href="compiling.html">here</a>. When you want to
post your patches:</p>
docs: Improve patch submission guidelines We should really advise (new) developers to send rebased patches that apply cleanly and use git-send-email rather than all other obscure ways.
2012-07-09 08:01:21 +00:00
<pre>
git pull --rebase
(fix any conflicts)
docs: point out git send-email location, be more stern about make check An email came to libvir-list wondering why the git send-email command was missing in spite of having git installed; this is due to the send-email command being in a sub-package of the main git package. While touching the hacking file, I thought it would be useful to 1) indicate the location of the source (docs/hacking.html.in) in the message at the top of HACKING, and also to make the note about running "make check" and "make syntax-check" a bit more stern.
2012-09-06 17:21:21 +00:00
git send-email --cover-letter --no-chain-reply-to --annotate \
--to=libvir-list@redhat.com master
docs: Improve patch submission guidelines We should really advise (new) developers to send rebased patches that apply cleanly and use git-send-email rather than all other obscure ways.
2012-07-09 08:01:21 +00:00
</pre>
docs: point out git send-email location, be more stern about make check An email came to libvir-list wondering why the git send-email command was missing in spite of having git installed; this is due to the send-email command being in a sub-package of the main git package. While touching the hacking file, I thought it would be useful to 1) indicate the location of the source (docs/hacking.html.in) in the message at the top of HACKING, and also to make the note about running "make check" and "make syntax-check" a bit more stern.
2012-09-06 17:21:21 +00:00
<p>(Note that the "git send-email" subcommand may not be in
doc: fix typo in HACKING s/installion/installation Signed-off-by: Chen Hanxiao <chenhanxiao@cn.fujitsu.com>
2013-10-07 04:51:13 +00:00
the main git package and using it may require installation of a
docs: point out git send-email location, be more stern about make check An email came to libvir-list wondering why the git send-email command was missing in spite of having git installed; this is due to the send-email command being in a sub-package of the main git package. While touching the hacking file, I thought it would be useful to 1) indicate the location of the source (docs/hacking.html.in) in the message at the top of HACKING, and also to make the note about running "make check" and "make syntax-check" a bit more stern.
2012-09-06 17:21:21 +00:00
separate package, for example the "git-email" package in
Fedora.) For a single patch you can omit
<code>--cover-letter</code>, but a series of two or more
patches needs a cover letter. If you get tired of typing
<code>--to=libvir-list@redhat.com</code> designation you can
docs: Improve patch submission guidelines We should really advise (new) developers to send rebased patches that apply cleanly and use git-send-email rather than all other obscure ways.
2012-07-09 08:01:21 +00:00
set it in git config:</p>
<pre>
git config sendemail.to libvir-list@redhat.com
</pre>
<p>Please follow this as close as you can, especially the rebase and
git send-email part, as it makes life easier for other developers to
review your patch set. One should avoid sending patches as attachments,
but rather send them in email body along with commit message. If a
developer is sending another version of the patch (e.g. to address
review comments), he is advised to note differences to previous
versions after the <code>---</code> line in the patch so that it helps
reviewers but doesn't become part of git history. Moreover, such patch
needs to be prefixed correctly with
<code>--subject-prefix=PATCHv2</code> appended to <code>git
send-email</code> (substitute <code>v2</code> with the correct
version if needed though).</p>
</li>
docs: add some more hacking tips Based on a suggestion by John Ferlan: https://www.redhat.com/archives/libvir-list/2013-January/msg00158.html * docs/hacking.html.in: Add some commit message instructions. Mention the ./run script. * HACKING: Regenerate.
2013-01-04 17:27:16 +00:00
<li><p>In your commit message, make the summary line reasonably
short (60 characters is typical), followed by a blank line,
followed by any longer description of why your patch makes
sense. If the patch fixes a regression, and you know what
commit introduced the problem, mentioning that is useful.
If the patch resolves a bugzilla report, mentioning the URL
of the bug number is useful; but also summarize the issue
rather than making all readers follow the link. You can use
'git shortlog -30' to get an idea of typical summary lines.
Libvirt does not currently attach any meaning to
Signed-off-by: lines, so it is up to you if you want to
include or omit them in the commit message.
</p>
</li>
docs: Improve patch submission guidelines We should really advise (new) developers to send rebased patches that apply cleanly and use git-send-email rather than all other obscure ways.
2012-07-09 08:01:21 +00:00
<li><p>Split large changes into a series of smaller patches,
docs: point out git send-email location, be more stern about make check An email came to libvir-list wondering why the git send-email command was missing in spite of having git installed; this is due to the send-email command being in a sub-package of the main git package. While touching the hacking file, I thought it would be useful to 1) indicate the location of the source (docs/hacking.html.in) in the message at the top of HACKING, and also to make the note about running "make check" and "make syntax-check" a bit more stern.
2012-09-06 17:21:21 +00:00
self-contained if possible, with an explanation of each patch
and an explanation of how the sequence of patches fits
together. Moreover, please keep in mind that it's required to
be able to compile cleanly (<b>including</b> <code>make
check</code> and <code>make syntax-check</code>) after each
patch. A feature does not have to work until the end of a
series, but intermediate patches must compile and not cause
test-suite failures (this is to preserve the usefulness
of <code>git bisect</code>, among other things).</p>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
</li>
docs: Improve patch submission guidelines We should really advise (new) developers to send rebased patches that apply cleanly and use git-send-email rather than all other obscure ways.
2012-07-09 08:01:21 +00:00
Replace old CVS references with GIT
2010-01-08 00:40:38 +00:00
<li>Make sure your patches apply against libvirt GIT. Developers
only follow GIT and don't care much about released versions.</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<li><p>Run the automated tests on your code before submitting any changes.
Update how to compile with -Werror --enable-compile-warnings=error has been renamed to --enable-werror so update the HACKING and the hacking.html to reflect that.
2012-09-24 23:44:34 +00:00
In particular, configure with compile warnings set to
-Werror. This is done automatically for a git checkout; from a
tarball, use:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Update how to compile with -Werror --enable-compile-warnings=error has been renamed to --enable-werror so update the HACKING and the hacking.html to reflect that.
2012-09-24 23:44:34 +00:00
./configure --enable-werror
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<p>
and run the tests:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
make check
make syntax-check
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
make -C tests valgrind
</pre>
hacking: Add some details to handle Valgrind output hacking: Add some text around the running of Valgrind along with example output for "real" vs. "false positives". cfg.mk: Add hacking.in.html to sc_prohibit_raw_allocation
2013-02-05 15:03:56 +00:00
<p><a href="http://valgrind.org/">Valgrind</a> is a test that checks
for memory management issues, such as leaks or use of uninitialized
variables.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
build: add configure option to disable gnulib tests The gnulib testsuite is relatively stable - the only times it is likely to have a test change from pass to fail is on a gnulib submodule update or a major system change (such as moving from Fedora 18 to 19, or other large change to libc). While it is an important test for end users on arbitrary machines (to make sure that the portability glue works for their machine), it mostly wastes time for development testing (as most developers aren't making any of the major changes that would cause gnulib tests to alter behavior). Thus, it pays to make the tests optional at configure time, defaulting to off for development, on for tarballs, with autobuilders requesting it to be on. It also helps to allow a make-time override, via VIR_TEST_EXPENSIVE=[01] (much the way automake sets up V=[01] for overriding the configure time default of how verbose to be). Automake has some pretty hard-coded magic with regards to the TESTS variable; I had quite a job figuring out how to keep 'make distcheck' passing regardless of the configure option setting in use, while still disabling the tests at runtime when I did not configure them on and did not use the override variable. Thankfully, we require GNU make, which lets me hide some information from Automake's magic handling of TESTS. * bootstrap.conf (bootstrap_epilogue): Munge gnulib test variable. * configure.ac (--enable-expensive-tests): Add new enable switch. (VIR_TEST_EXPENSIVE_DEFAULT, WITH_EXPENSIVE_TESTS): Set new witnesses. * gnulib/tests/Makefile.am (TESTS): Make tests conditional on configure settings and the VIR_TEST_EXPENSIVE variable. * tests/Makefile.am (TESTS_ENVIRONMENT): Expose VIR_TEST_EXPENSIVE to all tests. * autobuild.sh: Enable all tests during autobuilds. * libvirt.spec.in (%configure): Likewise. * mingw-libvirt.spec.in (%mingw_configure): Likewise. * docs/hacking.html.in: Document the option. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-31 13:18:58 +00:00
<p>
Some tests are skipped by default in a development environment,
based on the time they take in comparison to the likelihood
that those tests will turn up problems during incremental builds.
These tests default to being run when when building from a
tarball or with the configure option --enable-expensive-tests;
you can also force a one-time toggle of these tests by
setting VIR_TEST_EXPENSIVE to 0 or 1 at make time, as in:
</p>
<pre>
make check VIR_TEST_EXPENSIVE=1
</pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<p>
If you encounter any failing tests, the VIR_TEST_DEBUG
environment variable may provide extra information to debug
the failures. Larger values of VIR_TEST_DEBUG may provide
larger amounts of information:
</p>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
VIR_TEST_DEBUG=1 make check (or)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
VIR_TEST_DEBUG=2 make check
</pre>
docs: mention VIR_TEST_RANGE Commit ab92ae333 added a cool feature, but didn't document it. * docs/hacking.html.in: Document debugging a subset of tests. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-08-13 02:40:54 +00:00
<p>
When debugging failures during development, it is possible
to focus in on just the failing subtests by using TESTS and
VIR_TEST_RANGE:
</p>
<pre>
make check VIR_TEST_DEBUG=1 VIR_TEST_RANGE=3-5 TESTS=qemuxml2argvtest
</pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<p>
Also, individual tests can be run from inside the <code>tests/</code>
directory, like:
</p>
<pre>
./qemuxml2xmltest
</pre>
docs: add some more hacking tips Based on a suggestion by John Ferlan: https://www.redhat.com/archives/libvir-list/2013-January/msg00158.html * docs/hacking.html.in: Add some commit message instructions. Mention the ./run script. * HACKING: Regenerate.
2013-01-04 17:27:16 +00:00
<p>There is also a <code>./run</code> script at the top level,
to make it easier to run programs that have not yet been
installed, as well as to wrap invocations of various tests
hacking: Add some details to handle Valgrind output hacking: Add some text around the running of Valgrind along with example output for "real" vs. "false positives". cfg.mk: Add hacking.in.html to sc_prohibit_raw_allocation
2013-02-05 15:03:56 +00:00
under gdb or Valgrind.
</p>
</li>
<li><p>The Valgrind test should produce similar output to
<code>make check</code>. If the output has traces within libvirt
API's, then investigation is required in order to determine the
cause of the issue. Output such as the following indicates some
sort of leak:
</p>
<pre>
==5414== 4 bytes in 1 blocks are definitely lost in loss record 3 of 89
==5414== at 0x4A0881C: malloc (vg_replace_malloc.c:270)
==5414== by 0x34DE0AAB85: xmlStrndup (in /usr/lib64/libxml2.so.2.7.8)
==5414== by 0x4CC97A6: virDomainVideoDefParseXML (domain_conf.c:7410)
==5414== by 0x4CD581D: virDomainDefParseXML (domain_conf.c:10188)
==5414== by 0x4CD8C73: virDomainDefParseNode (domain_conf.c:10640)
==5414== by 0x4CD8DDB: virDomainDefParse (domain_conf.c:10590)
==5414== by 0x41CB1D: testCompareXMLToArgvHelper (qemuxml2argvtest.c:100)
==5414== by 0x41E20F: virtTestRun (testutils.c:161)
==5414== by 0x41C7CB: mymain (qemuxml2argvtest.c:866)
==5414== by 0x41E84A: virtTestMain (testutils.c:723)
==5414== by 0x34D9021734: (below main) (in /usr/lib64/libc-2.15.so)
</pre>
<p>In this example, the <code>virDomainDefParseXML()</code> had
an error path where the <code>virDomainVideoDefPtr video</code>
pointer was not properly disposed. By simply adding a
<code>virDomainVideoDefFree(video);</code> in the error path,
the issue was resolved.
</p>
<p>Another common mistake is calling a printing function, such as
<code>VIR_DEBUG()</code> without initializing a variable to be
printed. The following example involved a call which could return
an error, but not set variables passed by reference to the call.
The solution was to initialize the variables prior to the call.
</p>
<pre>
==4749== Use of uninitialised value of size 8
==4749== at 0x34D904650B: _itoa_word (in /usr/lib64/libc-2.15.so)
==4749== by 0x34D9049118: vfprintf (in /usr/lib64/libc-2.15.so)
==4749== by 0x34D9108F60: __vasprintf_chk (in /usr/lib64/libc-2.15.so)
==4749== by 0x4CAEEF7: virVasprintf (stdio2.h:199)
==4749== by 0x4C8A55E: virLogVMessage (virlog.c:814)
==4749== by 0x4C8AA96: virLogMessage (virlog.c:751)
==4749== by 0x4DA0056: virNetTLSContextCheckCertKeyUsage (virnettlscontext.c:225)
==4749== by 0x4DA06DB: virNetTLSContextCheckCert (virnettlscontext.c:439)
==4749== by 0x4DA1620: virNetTLSContextNew (virnettlscontext.c:562)
==4749== by 0x4DA26FC: virNetTLSContextNewServer (virnettlscontext.c:927)
==4749== by 0x409C39: testTLSContextInit (virnettlscontexttest.c:467)
==4749== by 0x40AB8F: virtTestRun (testutils.c:161)
</pre>
<p>Valgrind will also find some false positives or code paths
which cannot be resolved by making changes to the libvirt code.
For these paths, it is possible to add a filter to avoid the
errors. For example:
</p>
<pre>
==4643== 7 bytes in 1 blocks are possibly lost in loss record 4 of 20
==4643== at 0x4A0881C: malloc (vg_replace_malloc.c:270)
==4643== by 0x34D90853F1: strdup (in /usr/lib64/libc-2.15.so)
==4643== by 0x34EEC2C08A: ??? (in /usr/lib64/libnl.so.1.1)
==4643== by 0x34EEC15B81: ??? (in /usr/lib64/libnl.so.1.1)
==4643== by 0x34D8C0EE15: call_init.part.0 (in /usr/lib64/ld-2.15.so)
==4643== by 0x34D8C0EECF: _dl_init (in /usr/lib64/ld-2.15.so)
==4643== by 0x34D8C01569: ??? (in /usr/lib64/ld-2.15.so)
</pre>
Fix minor typos in messages and docs Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-30 08:21:11 +00:00
<p>In this instance, it is acceptable to modify the
hacking: Add some details to handle Valgrind output hacking: Add some text around the running of Valgrind along with example output for "real" vs. "false positives". cfg.mk: Add hacking.in.html to sc_prohibit_raw_allocation
2013-02-05 15:03:56 +00:00
<code>tests/.valgrind.supp</code> file in order to add a
suppression filter. The filter should be unique enough to
not suppress real leaks, but it should be generic enough to
cover multiple code paths. The format of the entry can be
found in the documentation found at the
maint: tweak use of <a> in HACKING The previous handling of <a> tags led to some less-than-ideal layout in HACKING (most noticeable on a mid-sentence reference to the valgrind home page). * docs/hacking.html.in: Slight tweaks to <a> tags. * docs/hacking1.xsl: Move <a> handling... * docs/hacking2.xsl: ...here. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-08 22:37:11 +00:00
<a href="http://valgrind.org/">Valgrind home page</a>.
hacking: Add some details to handle Valgrind output hacking: Add some text around the running of Valgrind along with example output for "real" vs. "false positives". cfg.mk: Add hacking.in.html to sc_prohibit_raw_allocation
2013-02-05 15:03:56 +00:00
The following trace was added to <code>tests/.valgrind.supp</code>
in order to suppress the warning:
</p>
<pre>
{
dlInitMemoryLeak1
Memcheck:Leak
fun:?alloc
...
fun:call_init.part.0
fun:_dl_init
...
obj:*/lib*/ld-2.*so*
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<li>Update tests and/or documentation, particularly if you are adding
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
a new feature or changing the output of a program.</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</ol>
<p>
There is more on this subject, including lots of links to background
reading on the subject, on
<a href="http://et.redhat.com/~rjones/how-to-supply-code-to-open-source-projects/">
maint: tweak use of <a> in HACKING The previous handling of <a> tags led to some less-than-ideal layout in HACKING (most noticeable on a mid-sentence reference to the valgrind home page). * docs/hacking.html.in: Slight tweaks to <a> tags. * docs/hacking1.xsl: Move <a> handling... * docs/hacking2.xsl: ...here. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-08 22:37:11 +00:00
Richard Jones' guide to working with open source projects</a>.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</p>
<h2><a name="indent">Code indentation</a></h2>
<p>
Libvirt's C source code generally adheres to some basic code-formatting
conventions. The existing code base is not totally consistent on this
front, but we do prefer that contributed code be formatted similarly.
In short, use spaces-not-TABs for indentation, use 4 spaces for each
indentation level, and other than that, follow the K&amp;R style.
</p>
<p>
If you use Emacs, add the following to one of one of your start-up files
(e.g., ~/.emacs), to help ensure that you get indentation right:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
;;; When editing C sources in libvirt, use this style.
(defun libvirt-c-mode ()
"C mode with adjusted defaults for use with libvirt."
(interactive)
(c-set-style "K&amp;R")
(setq indent-tabs-mode nil) ; indent using spaces, not TABs
(setq c-indent-level 4)
(setq c-basic-offset 4))
(add-hook 'c-mode-hook
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
'(lambda () (if (string-match "/libvirt" (buffer-file-name))
(libvirt-c-mode))))
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
Add vim configuration that makes vim auto-indent code
2011-03-17 02:35:17 +00:00
<p>
If you use vim, append the following to your ~/.vimrc file:
</p>
<pre>
set nocompatible
filetype on
set autoindent
set smartindent
set cindent
set tabstop=8
set shiftwidth=4
set expandtab
set cinoptions=(0,:0,l1,t0
filetype plugin indent on
au FileType make setlocal noexpandtab
au BufRead,BufNewFile *.am setlocal noexpandtab
match ErrorMsg /\s\+$\| \+\ze\t/
</pre>
<p>
Or if you don't want to mess your ~/.vimrc up, you can save the above
into a file called .lvimrc (not .vimrc) located at the root of libvirt
source, then install a vim script from
http://www.vim.org/scripts/script.php?script_id=1408,
which will load the .lvimrc only when you edit libvirt code.
</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<h2><a name="formatting">Code formatting (especially for new code)</a></h2>
<p>
With new code, we can be even more strict.
Please apply the following function (using GNU indent) to any new code.
Note that this also gives you an idea of the type of spacing we prefer
around operators and keywords:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
indent-libvirt()
{
indent -bad -bap -bbb -bli4 -br -ce -brs -cs -i4 -l75 -lc75 \
-sbi4 -psl -saf -sai -saw -sbi4 -ss -sc -cdw -cli4 -npcs -nbc \
--no-tabs "$@"
}
</pre>
<p>
doc: fix typos in hacking.html.in; mark HACKING as read-only * HACKING: Mark as read-only. Soon we'll generate it from... * docs/hacking.html.in: ... this file. More typo fixes.
2010-03-09 16:59:25 +00:00
Note that sometimes you'll have to post-process that output further, by
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
piping it through <code>expand -i</code>, since some leading TABs can get through.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Usually they're in macro definitions or strings, and should be converted
anyhow.
</p>
docs: mention C89 syntax preferences * docs/hacking.html.in (Code formatting): Document that // comment and declaration-after-statement are discouraged. * HACKING: Regenerate.
2011-03-30 15:48:51 +00:00
<p>
Libvirt requires a C99 compiler for various reasons. However,
most of the code base prefers to stick to C89 syntax unless
there is a compelling reason otherwise. For example, it is
preferable to use <code>/* */</code> comments rather
than <code>//</code>. Also, when declaring local variables, the
prevailing style has been to declare them at the beginning of a
scope, rather than immediately before use.
</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Document bracket whitespace rules & add syntax-check rule This documents the following whitespace rules if(foo) // Bad if (foo) // Good int foo (int wizz) // Bad int foo(int wizz) // Good bar = foo (wizz); // Bad bar = foo(wizz); // Good typedef int (*foo) (int wizz); // Bad typedef int (*foo)(int wizz); // Good int foo( int wizz ); // Bad int foo(int wizz); // Good There is a syntax-check rule extension to validate all these rules. Checking for 'function (...args...)' is quite difficult since it needs to ignore valid usage with keywords like 'if (...test...)' and while/for/switch. It must also ignore source comments and quoted strings. It is not possible todo this with a simple regex in the normal syntax-check style. So a short Perl script is created instead to analyse the source. In practice this works well enough. The only thing it can't cope with is multi-line quoted strings of the form "start of string\ more lines\ more line\ the end" but this can and should be written as "start of string" "more lines" "more line" "the end" with this simple change, the bracket checking script does not have any false positives across libvirt source, provided it is only run against .c files. It is not practical to run it against .h files, since those use whitespace extensively to get alignment (though this is somewhat inconsistent and could arguably be fixed). The only limitation is that it cannot detect a violation where the first arg starts with a '*', eg foo(*wizz); since this generates too many false positives on function typedefs which can't be supressed efficiently. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-10-17 09:25:35 +00:00
<h2><a name="bracket_spacing">Bracket spacing</a></h2>
<p>
The keywords <code>if</code>, <code>for</code>, <code>while</code>,
and <code>switch</code> must have a single space following them
Sync HACKING and hacking.html.in After one last-minute change, only HACKING was updated and not hacking.html.in, so this patch synchronizes that.
2013-01-30 10:01:31 +00:00
before the opening bracket. E.g.
Document bracket whitespace rules & add syntax-check rule This documents the following whitespace rules if(foo) // Bad if (foo) // Good int foo (int wizz) // Bad int foo(int wizz) // Good bar = foo (wizz); // Bad bar = foo(wizz); // Good typedef int (*foo) (int wizz); // Bad typedef int (*foo)(int wizz); // Good int foo( int wizz ); // Bad int foo(int wizz); // Good There is a syntax-check rule extension to validate all these rules. Checking for 'function (...args...)' is quite difficult since it needs to ignore valid usage with keywords like 'if (...test...)' and while/for/switch. It must also ignore source comments and quoted strings. It is not possible todo this with a simple regex in the normal syntax-check style. So a short Perl script is created instead to analyse the source. In practice this works well enough. The only thing it can't cope with is multi-line quoted strings of the form "start of string\ more lines\ more line\ the end" but this can and should be written as "start of string" "more lines" "more line" "the end" with this simple change, the bracket checking script does not have any false positives across libvirt source, provided it is only run against .c files. It is not practical to run it against .h files, since those use whitespace extensively to get alignment (though this is somewhat inconsistent and could arguably be fixed). The only limitation is that it cannot detect a violation where the first arg starts with a '*', eg foo(*wizz); since this generates too many false positives on function typedefs which can't be supressed efficiently. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-10-17 09:25:35 +00:00
</p>
<pre>
if(foo) // Bad
if (foo) // Good
</pre>
<p>
Function implementations must <strong>not</strong> have any whitespace
Sync HACKING and hacking.html.in After one last-minute change, only HACKING was updated and not hacking.html.in, so this patch synchronizes that.
2013-01-30 10:01:31 +00:00
between the function name and the opening bracket. E.g.
Document bracket whitespace rules & add syntax-check rule This documents the following whitespace rules if(foo) // Bad if (foo) // Good int foo (int wizz) // Bad int foo(int wizz) // Good bar = foo (wizz); // Bad bar = foo(wizz); // Good typedef int (*foo) (int wizz); // Bad typedef int (*foo)(int wizz); // Good int foo( int wizz ); // Bad int foo(int wizz); // Good There is a syntax-check rule extension to validate all these rules. Checking for 'function (...args...)' is quite difficult since it needs to ignore valid usage with keywords like 'if (...test...)' and while/for/switch. It must also ignore source comments and quoted strings. It is not possible todo this with a simple regex in the normal syntax-check style. So a short Perl script is created instead to analyse the source. In practice this works well enough. The only thing it can't cope with is multi-line quoted strings of the form "start of string\ more lines\ more line\ the end" but this can and should be written as "start of string" "more lines" "more line" "the end" with this simple change, the bracket checking script does not have any false positives across libvirt source, provided it is only run against .c files. It is not practical to run it against .h files, since those use whitespace extensively to get alignment (though this is somewhat inconsistent and could arguably be fixed). The only limitation is that it cannot detect a violation where the first arg starts with a '*', eg foo(*wizz); since this generates too many false positives on function typedefs which can't be supressed efficiently. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-10-17 09:25:35 +00:00
</p>
<pre>
int foo (int wizz) // Bad
int foo(int wizz) // Good
</pre>
<p>
Function calls must <strong>not</strong> have any whitespace
Sync HACKING and hacking.html.in After one last-minute change, only HACKING was updated and not hacking.html.in, so this patch synchronizes that.
2013-01-30 10:01:31 +00:00
between the function name and the opening bracket. E.g.
Document bracket whitespace rules & add syntax-check rule This documents the following whitespace rules if(foo) // Bad if (foo) // Good int foo (int wizz) // Bad int foo(int wizz) // Good bar = foo (wizz); // Bad bar = foo(wizz); // Good typedef int (*foo) (int wizz); // Bad typedef int (*foo)(int wizz); // Good int foo( int wizz ); // Bad int foo(int wizz); // Good There is a syntax-check rule extension to validate all these rules. Checking for 'function (...args...)' is quite difficult since it needs to ignore valid usage with keywords like 'if (...test...)' and while/for/switch. It must also ignore source comments and quoted strings. It is not possible todo this with a simple regex in the normal syntax-check style. So a short Perl script is created instead to analyse the source. In practice this works well enough. The only thing it can't cope with is multi-line quoted strings of the form "start of string\ more lines\ more line\ the end" but this can and should be written as "start of string" "more lines" "more line" "the end" with this simple change, the bracket checking script does not have any false positives across libvirt source, provided it is only run against .c files. It is not practical to run it against .h files, since those use whitespace extensively to get alignment (though this is somewhat inconsistent and could arguably be fixed). The only limitation is that it cannot detect a violation where the first arg starts with a '*', eg foo(*wizz); since this generates too many false positives on function typedefs which can't be supressed efficiently. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-10-17 09:25:35 +00:00
</p>
<pre>
bar = foo (wizz); // Bad
bar = foo(wizz); // Good
</pre>
<p>
Function typedefs must <strong>not</strong> have any whitespace
between the closing bracket of the function name and opening
Sync HACKING and hacking.html.in After one last-minute change, only HACKING was updated and not hacking.html.in, so this patch synchronizes that.
2013-01-30 10:01:31 +00:00
bracket of the arg list. E.g.
Document bracket whitespace rules & add syntax-check rule This documents the following whitespace rules if(foo) // Bad if (foo) // Good int foo (int wizz) // Bad int foo(int wizz) // Good bar = foo (wizz); // Bad bar = foo(wizz); // Good typedef int (*foo) (int wizz); // Bad typedef int (*foo)(int wizz); // Good int foo( int wizz ); // Bad int foo(int wizz); // Good There is a syntax-check rule extension to validate all these rules. Checking for 'function (...args...)' is quite difficult since it needs to ignore valid usage with keywords like 'if (...test...)' and while/for/switch. It must also ignore source comments and quoted strings. It is not possible todo this with a simple regex in the normal syntax-check style. So a short Perl script is created instead to analyse the source. In practice this works well enough. The only thing it can't cope with is multi-line quoted strings of the form "start of string\ more lines\ more line\ the end" but this can and should be written as "start of string" "more lines" "more line" "the end" with this simple change, the bracket checking script does not have any false positives across libvirt source, provided it is only run against .c files. It is not practical to run it against .h files, since those use whitespace extensively to get alignment (though this is somewhat inconsistent and could arguably be fixed). The only limitation is that it cannot detect a violation where the first arg starts with a '*', eg foo(*wizz); since this generates too many false positives on function typedefs which can't be supressed efficiently. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-10-17 09:25:35 +00:00
</p>
<pre>
typedef int (*foo) (int wizz); // Bad
typedef int (*foo)(int wizz); // Good
</pre>
<p>
There must not be any whitespace immediately following any
Sync HACKING and hacking.html.in After one last-minute change, only HACKING was updated and not hacking.html.in, so this patch synchronizes that.
2013-01-30 10:01:31 +00:00
opening bracket, or immediately prior to any closing bracket. E.g.
Document bracket whitespace rules & add syntax-check rule This documents the following whitespace rules if(foo) // Bad if (foo) // Good int foo (int wizz) // Bad int foo(int wizz) // Good bar = foo (wizz); // Bad bar = foo(wizz); // Good typedef int (*foo) (int wizz); // Bad typedef int (*foo)(int wizz); // Good int foo( int wizz ); // Bad int foo(int wizz); // Good There is a syntax-check rule extension to validate all these rules. Checking for 'function (...args...)' is quite difficult since it needs to ignore valid usage with keywords like 'if (...test...)' and while/for/switch. It must also ignore source comments and quoted strings. It is not possible todo this with a simple regex in the normal syntax-check style. So a short Perl script is created instead to analyse the source. In practice this works well enough. The only thing it can't cope with is multi-line quoted strings of the form "start of string\ more lines\ more line\ the end" but this can and should be written as "start of string" "more lines" "more line" "the end" with this simple change, the bracket checking script does not have any false positives across libvirt source, provided it is only run against .c files. It is not practical to run it against .h files, since those use whitespace extensively to get alignment (though this is somewhat inconsistent and could arguably be fixed). The only limitation is that it cannot detect a violation where the first arg starts with a '*', eg foo(*wizz); since this generates too many false positives on function typedefs which can't be supressed efficiently. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-10-17 09:25:35 +00:00
</p>
<pre>
int foo( int wizz ); // Bad
int foo(int wizz); // Good
</pre>
syntax-check: mandate space after mid-line semicolon Enforce the style cleanup in the previous patch. * build-aux/bracket-spacing.pl: Enforce trailing spacing. * cfg.mk (bracket-spacing-check): Tweak error wording. * docs/hacking.html.in: Document the rule. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-24 16:43:45 +00:00
<h2><a name="semicolon">Semicolons</a></h2>
<p>
Semicolons should never have a space beforehand. Inside the
condition of a <code>for</code> loop, there should always be a
space or line break after each semicolon, except for the special
case of an infinite loop (although more infinite loops
use <code>while</code>). While not enforced, loop counters
generally use post-increment.
</p>
<pre>
for (i = 0 ;i &lt; limit ; ++i) { // Bad
for (i = 0; i &lt; limit; i++) { // Good
for (;;) { // ok
while (1) { // Better
</pre>
<p>
Empty loop bodies are better represented with curly braces and a
comment, although use of a semicolon is not currently rejected.
</p>
<pre>
while ((rc = waitpid(pid, &amp;st, 0) == -1) &amp;&amp;
errno == EINTR); // ok
while ((rc = waitpid(pid, &amp;st, 0) == -1) &amp;&amp;
errno == EINTR) { // Better
/* nothing */
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<h2><a name="curly_braces">Curly braces</a></h2>
<p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
Omit the curly braces around an <code>if</code>, <code>while</code>,
<code>for</code> etc. body only
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
when that body occupies a single line. In every other case we require
the braces. This ensures that it is trivially easy to identify a
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
single-<i>statement</i> loop: each has only one <i>line</i> in its body.
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
</p>
<p>
Omitting braces with a single-line body is fine:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
while (expr) // one-line body -> omitting curly braces is ok
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
single_line_stmt();
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
docs: fix usage of 'onto' http://www.uhv.edu/ac/newsletters/writing/grammartip2009.07.01.htm (and several other sites) give hints that 'onto' is best used if you can also add 'up' just before it and still make sense. In many cases in the code base, we really want the two-word form, or even a simplification to just 'on' or 'to'. * docs/hacking.html.in: Use correct 'on to'. * python/libvirt-override.c: Likewise. * src/lxc/lxc_controller.c: Likewise. * src/util/virpci.c: Likewise. * daemon/THREADS.txt: Use simpler 'on'. * docs/formatdomain.html.in: Better usage. * docs/internals/rpc.html.in: Likewise. * src/conf/domain_event.c: Likewise. * src/rpc/virnetclient.c: Likewise. * tests/qemumonitortestutils.c: Likewise. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-04-19 20:18:14 +00:00
However, the moment your loop/if/else body extends on to a second
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
line, for whatever reason (even if it's just an added comment), then
you should add braces. Otherwise, it would be too easy to insert a
statement just before that comment (without adding braces), thinking
it is already a multi-statement loop:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
while (true) // BAD! multi-line body with no braces
/* comment... */
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
single_line_stmt();
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
Do this instead:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
while (true) { // Always put braces around a multi-line body.
/* comment... */
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
single_line_stmt();
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
There is one exception: when the second body line is not at the same
indentation level as the first body line:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
if (expr)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
die("a diagnostic that would make this line"
" extend past the 80-column limit"));
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
It is safe to omit the braces in the code above, since the
further-indented second body line makes it obvious that this is still
a single-statement body.
</p>
<p>
To reiterate, don't do this:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
if (expr) // BAD: no braces around...
while (expr_2) { // ... a multi-line body
...
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
Do this, instead:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
if (expr) {
while (expr_2) {
...
}
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
However, there is one exception in the other direction, when even a
one-line block should have braces. That occurs when that one-line,
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
brace-less block is an <code>if</code> or <code>else</code>
block, and the counterpart block <b>does</b> use braces. In
that case, put braces around both blocks. Also, if
the <code>else</code> block is much shorter than
the <code>if</code> block, consider negating the
<code>if</code>-condition and swapping the bodies, putting the
short block first and making the longer, multi-line block be the
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<code>else</code> block.
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
if (expr) {
...
...
}
else
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
x = y; // BAD: braceless "else" with braced "then",
// and short block last
if (expr)
x = y; // BAD: braceless "if" with braced "else"
else {
...
...
}
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
Keeping braces consistent and putting the short block first is
preferred, especially when the multi-line body is more than a
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
few lines long, because it is easier to read and grasp the semantics of
an if-then-else block when the simpler block occurs first, rather than
after the more involved block:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
if (!expr) {
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
x = y; // putting the smaller block first is more readable
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
} else {
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
...
...
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
<p>
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
But if negating a complex condition is too ugly, then at least
add braces:
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
maint: document dislike of mismatched if/else bracing * docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange.
2011-01-05 17:58:35 +00:00
if (complex expr not worth negating) {
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
...
...
} else {
x = y;
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
}
</pre>
docs: hacking: explain why using curly braces well is important * docs/hacking.html.in: Use the "curly braces" section from coreutils' HACKING, adapting for libvirt's different formatting style. * HACKING: Sync from the above, still mostly manually.
2010-04-15 17:31:04 +00:00
docs: hacking.html.in: fix table of contents Two sections didn't have a working link in the TOC.
2012-09-11 12:01:56 +00:00
<h2><a name="preprocessor">Preprocessor</a></h2>
hacking: add a section on preprocessor conventions * doc/hacking.html.in (preprocessor): New section to document recently-discussed style issues. Signed-off-by: Eric Blake <eblake@redhat.com>
2010-03-09 00:02:45 +00:00
alloc: make VIR_APPEND_ELEMENT safer VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression for 'size' had side effects. While no one in the current code base was trying to pass side effects, we might as well be robust and explicitly document our intentions. * src/util/viralloc.c (virInsertElementsN): Add special case. * src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it. (VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N) (VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT) (VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document which macros are safe in the presence of side effects. * docs/hacking.html.in: Document this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
<p>Macros defined with an ALL_CAPS name should generally be
assumed to be unsafe with regards to arguments with side-effects
(that is, MAX(a++, b--) might increment a or decrement b too
many or too few times). Exceptions to this rule are explicitly
string: make VIR_STRDUP easier to use While reviewing proposed VIR_STRDUP conversions, I've already noticed several places that do: if (str && VIR_STRDUP(dest, str) < 0) which can be simplified by allowing str to be NULL (something that strdup() doesn't allow). Meanwhile, code that wants to ensure a non-NULL dest regardless of the source can check for <= 0. Also, make it part of the VIR_STRDUP contract that macro arguments are evaluated exactly once. * src/util/virstring.h (VIR_STRDUP, VIR_STRDUP_QUIET, VIR_STRNDUP) (VIR_STRNDUP_QUIET): Improve contract. * src/util/virstring.c (virStrdup, virStrndup): Change return conventions. * docs/hacking.html.in: Document this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-07 02:42:44 +00:00
documented for macros in viralloc.h and virstring.h.
alloc: make VIR_APPEND_ELEMENT safer VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression for 'size' had side effects. While no one in the current code base was trying to pass side effects, we might as well be robust and explicitly document our intentions. * src/util/viralloc.c (virInsertElementsN): Add special case. * src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it. (VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N) (VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT) (VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document which macros are safe in the presence of side effects. * docs/hacking.html.in: Document this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
</p>
hacking: add a section on preprocessor conventions * doc/hacking.html.in (preprocessor): New section to document recently-discussed style issues. Signed-off-by: Eric Blake <eblake@redhat.com>
2010-03-09 00:02:45 +00:00
<p>
For variadic macros, stick with C99 syntax:
docs: <pre> cannot be nested in <p> xsltproc complained about this.
2010-03-13 14:04:34 +00:00
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
hacking: add a section on preprocessor conventions * doc/hacking.html.in (preprocessor): New section to document recently-discussed style issues. Signed-off-by: Eric Blake <eblake@redhat.com>
2010-03-09 00:02:45 +00:00
#define vshPrint(_ctl, ...) fprintf(stdout, __VA_ARGS__)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
hacking: add a section on preprocessor conventions * doc/hacking.html.in (preprocessor): New section to document recently-discussed style issues. Signed-off-by: Eric Blake <eblake@redhat.com>
2010-03-09 00:02:45 +00:00
<p>Use parenthesis when checking if a macro is defined, and use
indentation to track nesting:
docs: <pre> cannot be nested in <p> xsltproc complained about this.
2010-03-13 14:04:34 +00:00
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
hacking: add a section on preprocessor conventions * doc/hacking.html.in (preprocessor): New section to document recently-discussed style issues. Signed-off-by: Eric Blake <eblake@redhat.com>
2010-03-09 00:02:45 +00:00
#if defined(HAVE_POSIX_FALLOCATE) &amp;&amp; !defined(HAVE_FALLOCATE)
# define fallocate(a,ignored,b,c) posix_fallocate(a,b,c)
#endif
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
hacking: add a section on preprocessor conventions * doc/hacking.html.in (preprocessor): New section to document recently-discussed style issues. Signed-off-by: Eric Blake <eblake@redhat.com>
2010-03-09 00:02:45 +00:00
docs: hacking.html.in: fix table of contents Two sections didn't have a working link in the TOC.
2012-09-11 12:01:56 +00:00
<h2><a name="types">C types</a></h2>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<p>
Use the right type.
</p>
<h3>Scalars</h3>
<ul>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<li>If you're using <code>int</code> or <code>long</code>, odds are
good that there's a better type.</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<li>If a variable is counting something, be sure to declare it with an
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
unsigned type.</li>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<li>If it's memory-size-related, use <code>size_t</code> (use
<code>ssize_t</code> only if required).</li>
<li>If it's file-size related, use uintmax_t, or maybe <code>off_t</code>.</li>
<li>If it's file-offset related (i.e., signed), use <code>off_t</code>.</li>
<li>If it's just counting small numbers use <code>unsigned int</code>;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
(on all but oddball embedded systems, you can assume that that
type is at least four bytes wide).</li>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<li>If a variable has boolean semantics, give it the <code>bool</code> type
and use the corresponding <code>true</code> and <code>false</code> macros.
It's ok to include &lt;stdbool.h&gt;, since libvirt's use of gnulib ensures
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
that it exists and is usable.</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<li>In the unusual event that you require a specific width, use a
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
standard type like <code>int32_t</code>, <code>uint32_t</code>,
<code>uint64_t</code>, etc.</li>
<li>While using <code>bool</code> is good for readability, it comes with
minor caveats:
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<ul>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<li>Don't use <code>bool</code> in places where the type size must be constant across
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
all systems, like public interfaces and on-the-wire protocols. Note
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
that it would be possible (albeit wasteful) to use <code>bool</code> in libvirt's
logical wire protocol, since XDR maps that to its lower-level <code>bool_t</code>
type, which <b>is</b> fixed-size.</li>
<li>Don't compare a bool variable against the literal, <code>true</code>,
since a value with a logical non-false value need not be <code>1</code>.
I.e., don't write <code>if (seen == true) ...</code>. Rather,
write <code>if (seen)...</code>.</li>
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
</ul>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</li>
</ul>
<p>
Of course, take all of the above with a grain of salt. If you're about
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
to use some system interface that requires a type like <code>size_t</code>,
<code>pid_t</code> or <code>off_t</code>, use matching types for any
corresponding variables.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</p>
<p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
Also, if you try to use e.g., <code>unsigned int</code> as a type, and that
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
conflicts with the signedness of a related variable, sometimes
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
it's best just to use the <b>wrong</b> type, if <i>pulling the thread</i>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
and fixing all related variables would be too invasive.
</p>
<p>
Finally, while using descriptive types is important, be careful not to
go overboard. If whatever you're doing causes warnings, or requires
casts, then reconsider or ask for help.
</p>
<h3>Pointers</h3>
<p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
Ensure that all of your pointers are <i>const-correct</i>.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Unless a pointer is used to modify the pointed-to storage,
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
give it the <code>const</code> attribute. That way, the reader knows
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
up-front that this is a read-only pointer. Perhaps more
importantly, if we're diligent about this, when you see a non-const
pointer, you're guaranteed that it is used to modify the storage
it points to, or it is aliased to another pointer that is.
</p>
<h2><a name="memalloc">Low level memory management</a></h2>
<p>
Use of the malloc/free/realloc/calloc APIs is deprecated in the libvirt
codebase, because they encourage a number of serious coding bugs and do
not enable compile time verification of checks for NULL. Instead of these
alloc: make VIR_APPEND_ELEMENT safer VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression for 'size' had side effects. While no one in the current code base was trying to pass side effects, we might as well be robust and explicitly document our intentions. * src/util/viralloc.c (virInsertElementsN): Add special case. * src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it. (VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N) (VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT) (VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document which macros are safe in the presence of side effects. * docs/hacking.html.in: Document this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
routines, use the macros from viralloc.h.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</p>
<ul>
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>To allocate a single object:</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
virDomainPtr domain;
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Adapt to VIR_ALLOC and virAsprintf in docs/
2013-07-04 10:21:16 +00:00
if (VIR_ALLOC(domain) &lt; 0)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
return NULL;
</pre>
</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>To allocate an array of objects:</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
virDomainPtr domains;
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
size_t ndomains = 10;
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Adapt to VIR_ALLOC and virAsprintf in docs/
2013-07-04 10:21:16 +00:00
if (VIR_ALLOC_N(domains, ndomains) &lt; 0)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
return NULL;
</pre>
</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>To allocate an array of object pointers:</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
virDomainPtr *domains;
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
size_t ndomains = 10;
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Adapt to VIR_ALLOC and virAsprintf in docs/
2013-07-04 10:21:16 +00:00
if (VIR_ALLOC_N(domains, ndomains) &lt; 0)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
return NULL;
</pre>
</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
<li><p>To re-allocate the array of domains to be 1 element
longer (however, note that repeatedly expanding an array by 1
scales quadratically, so this is recommended only for smaller
arrays):</p>
<pre>
virDomainPtr domains;
size_t ndomains = 0;
Adapt to VIR_ALLOC and virAsprintf in docs/
2013-07-04 10:21:16 +00:00
if (VIR_EXPAND_N(domains, ndomains, 1) &lt; 0)
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
return NULL;
domains[ndomains - 1] = domain;
</pre></li>
<li><p>To ensure an array has room to hold at least one more
element (this approach scales better, but requires tracking
allocation separately from usage)</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<pre>
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
virDomainPtr domains;
size_t ndomains = 0;
size_t ndomains_max = 0;
Adapt to VIR_ALLOC and virAsprintf in docs/
2013-07-04 10:21:16 +00:00
if (VIR_RESIZE_N(domains, ndomains_max, ndomains, 1) &lt; 0)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
return NULL;
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
domains[ndomains++] = domain;
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
libvirtd: fix bug when shrinking number of clients * daemon/libvirtd.c (qemudRunLoop): Pass allocation size, not current count, to VIR_SHRINK_N. * docs/hacking.html.in: Update doc example. * HACKING: Regenerate.
2010-11-22 19:27:07 +00:00
<li><p>To trim an array of domains from its allocated size down
to the actual used size:</p>
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<pre>
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
virDomainPtr domains;
size_t ndomains = x;
size_t ndomains_max = y;
libvirtd: fix bug when shrinking number of clients * daemon/libvirtd.c (qemudRunLoop): Pass allocation size, not current count, to VIR_SHRINK_N. * docs/hacking.html.in: Update doc example. * HACKING: Regenerate.
2010-11-22 19:27:07 +00:00
VIR_SHRINK_N(domains, ndomains_max, ndomains_max - ndomains);
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
</pre></li>
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
<li><p>To free an array of domains:</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<pre>
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
virDomainPtr domains;
size_t ndomains = x;
size_t ndomains_max = y;
size_t i;
for (i = 0; i &lt; ndomains; i++)
VIR_FREE(domains[i]);
VIR_FREE(domains);
ndomains_max = ndomains = 0;
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
memory: make it easier to avoid quadratic scaling of arrays * src/util/memory.h (VIR_RESIZE_N): New macro. * src/util/memory.c (virResizeN): New function. * src/libvirt_private.syms: Export new helper. * docs/hacking.html.in: Document it. * HACKING: Regenerate.
2010-08-14 15:42:51 +00:00
</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</ul>
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
<h2><a name="file_handling">File handling</a></h2>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
<p>
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
Usage of the <code>fdopen()</code>, <code>close()</code>, <code>fclose()</code>
APIs is deprecated in libvirt code base to help avoiding double-closing of files
Various typos and misspellings
2012-10-11 16:31:20 +00:00
or file descriptors, which is particularly dangerous in a multi-threaded
application. Instead of these APIs, use the macros from virfile.h
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
</p>
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
<ul>
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>Open a file from a file descriptor:</p>
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
<pre>
if ((file = VIR_FDOPEN(fd, "r")) == NULL) {
virReportSystemError(errno, "%s",
_("failed to open file from file descriptor"));
return -1;
}
/* fd is now invalid; only access the file using file variable */
</pre></li>
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>Close a file descriptor:</p>
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
<pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
if (VIR_CLOSE(fd) &lt; 0) {
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
virReportSystemError(errno, "%s", _("failed to close file"));
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
}
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
</pre></li>
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>Close a file:</p>
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
<pre>
if (VIR_FCLOSE(file) &lt; 0) {
virReportSystemError(errno, "%s", _("failed to close file"));
}
</pre></li>
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<li><p>Close a file or file descriptor in an error path, without losing
the previous <code>errno</code> value:</p>
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
<pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
VIR_FORCE_CLOSE(fd);
deprecate fclose() and introduce VIR_{FORCE_}FCLOSE() Similarly to deprecating close(), I am now deprecating fclose() and introduce VIR_FORCE_FCLOSE() and VIR_FCLOSE(). Also, fdopen() is replaced with VIR_FDOPEN(). Most of the files are opened in read-only mode, so usage of VIR_FORCE_CLOSE() seemed appropriate. Others that are opened in write mode already had the fclose()< 0 check and I converted those to VIR_FCLOSE()< 0. I did not find occurrences of possible double-closed files on the way.
2010-11-17 02:13:29 +00:00
VIR_FORCE_FCLOSE(file);
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
</li>
Introduce VIR_CLOSE to be used rather than close() Since bugs due to double-closed file descriptors are difficult to track down in a multi-threaded system, I am introducing the VIR_CLOSE(fd) macro to help avoid mistakes here. There are lots of places where close() is being used. In this patch I am only cleaning up usage of close() in src/conf where the problems were. I also dare to declare close() as being deprecated in libvirt code base (HACKING).
2010-10-19 14:23:51 +00:00
</ul>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
<h2><a name="string_comparision">String comparisons</a></h2>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<p>
Do not use the strcmp, strncmp, etc functions directly. Instead use
one of the following semantically named macros
</p>
<ul>
<li><p>For strict equality:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
STREQ(a,b)
STRNEQ(a,b)
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
</li>
maint: fix spelling error in hacking * HACKING: STRCASEEQ is case insensitive. * docs/hacking.html.in: Likewise.
2010-01-27 13:33:58 +00:00
<li><p>For case insensitive equality:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
STRCASEEQ(a,b)
STRCASENEQ(a,b)
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
</li>
<li><p>For strict equality of a substring:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
STREQLEN(a,b,n)
STRNEQLEN(a,b,n)
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
</li>
maint: fix spelling error in hacking * HACKING: STRCASEEQ is case insensitive. * docs/hacking.html.in: Likewise.
2010-01-27 13:33:58 +00:00
<li><p>For case insensitive equality of a substring:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
STRCASEEQLEN(a,b,n)
STRCASENEQLEN(a,b,n)
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
</li>
<li><p>For strict equality of a prefix:</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
STRPREFIX(a,b)
Document STREQ_NULLABLE and STRNEQ_NULLABLE
2011-10-06 11:32:49 +00:00
</pre>
</li>
<li><p>To avoid having to check if a or b are NULL:</p>
<pre>
STREQ_NULLABLE(a, b)
STRNEQ_NULLABLE(a, b)
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
</li>
</ul>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
<h2><a name="string_copying">String copying</a></h2>
<p>
Do not use the strncpy function. According to the man page, it
does <b>not</b> guarantee a NULL-terminated buffer, which makes
it extremely dangerous to use. Instead, use one of the
functionally equivalent functions:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
virStrncpy(char *dest, const char *src, size_t n, size_t destbytes)
</pre>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
<p>
The first three arguments have the same meaning as for strncpy;
namely the destination, source, and number of bytes to copy,
respectively. The last argument is the number of bytes
available in the destination string; if a copy of the source
string (including a \0) will not fit into the destination, no
bytes are copied and the routine returns NULL. Otherwise, n
bytes from the source are copied into the destination and a
trailing \0 is appended.
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
virStrcpy(char *dest, const char *src, size_t destbytes)
</pre>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
<p>
Use this variant if you know you want to copy the entire src
string into dest. Note that this is a macro, so arguments could
be evaluated more than once. This is equivalent to
virStrncpy(dest, src, strlen(src), destbytes)
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
virStrcpyStatic(char *dest, const char *src)
</pre>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
<p>
Use this variant if you know you want to copy the entire src
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
string into dest <b>and</b> you know that your destination string is
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
a static string (i.e. that sizeof(dest) returns something
meaningful). Note that this is a macro, so arguments could be
evaluated more than once. This is equivalent to
virStrncpy(dest, src, strlen(src), sizeof(dest)).
</p>
virstring: Introduce VIR_STRDUP and VIR_STRNDUP The code adaptation is not done right now, but in subsequent patches. Hence I am not implementing syntax-check rule as it would break compilation. Developers are strongly advised to use these new macros. They are similar to VIR_ALLOC() logic: VIR_STRDUP(dst, src) returns zero on success, -1 otherwise. In case you don't want to report OOM error, use the _QUIET variant of a macro.
2013-04-03 12:51:20 +00:00
<pre>
VIR_STRDUP(char *dst, const char *src);
VIR_STRNDUP(char *dst, const char *src, size_t n);
</pre>
<p>
You should avoid using strdup or strndup directly as they do not report
string: make VIR_STRDUP easier to use While reviewing proposed VIR_STRDUP conversions, I've already noticed several places that do: if (str && VIR_STRDUP(dest, str) < 0) which can be simplified by allowing str to be NULL (something that strdup() doesn't allow). Meanwhile, code that wants to ensure a non-NULL dest regardless of the source can check for <= 0. Also, make it part of the VIR_STRDUP contract that macro arguments are evaluated exactly once. * src/util/virstring.h (VIR_STRDUP, VIR_STRDUP_QUIET, VIR_STRNDUP) (VIR_STRNDUP_QUIET): Improve contract. * src/util/virstring.c (virStrdup, virStrndup): Change return conventions. * docs/hacking.html.in: Document this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-07 02:42:44 +00:00
out-of-memory error, and do not allow a NULL source. Use
VIR_STRDUP or VIR_STRNDUP macros instead, which return 0 for
NULL source, 1 for successful copy, and -1 for allocation
failure with the error already reported. In very
virstring: Introduce VIR_STRDUP and VIR_STRNDUP The code adaptation is not done right now, but in subsequent patches. Hence I am not implementing syntax-check rule as it would break compilation. Developers are strongly advised to use these new macros. They are similar to VIR_ALLOC() logic: VIR_STRDUP(dst, src) returns zero on success, -1 otherwise. In case you don't want to report OOM error, use the _QUIET variant of a macro.
2013-04-03 12:51:20 +00:00
specific cases, when you don't want to report the out-of-memory error, you
can use VIR_STRDUP_QUIET or VIR_STRNDUP_QUIET, but such usage is very rare
and usually considered a flaw.
</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<h2><a name="strbuf">Variable length string buffer</a></h2>
<p>
If there is a need for complex string concatenations, avoid using
the usual sequence of malloc/strcpy/strcat/snprintf functions and
make use of the virBuffer API described in buf.h
</p>
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
<p>Typical usage is as follows:</p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
char *
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
somefunction(...)
{
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
virBuffer buf = VIR_BUFFER_INITIALIZER;
...
virBufferAddLit(&amp;buf, "&lt;domain&gt;\n");
maint: rename virBufferVSprintf to virBufferAsprintf We already have virAsprintf, so picking a similar name helps for seeing a similar purpose. Furthermore, the prefix V before printf generally implies 'va_list', even though this variant was '...', and the old name got in the way of adding a new va_list version. global rename performed with: $ git grep -l virBufferVSprintf \ | xargs -L1 sed -i 's/virBufferVSprintf/virBufferAsprintf/g' then revert the changes in ChangeLog-old.
2011-04-30 16:34:49 +00:00
virBufferAsprintf(&amp;buf, " &lt;memory&gt;%d&lt;/memory&gt;\n", memory);
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
...
virBufferAddLit(&amp;buf, "&lt;/domain&gt;\n");
Add virBufferFreeAndReset() and replace free() Replace free(virBufferContentAndReset()) with virBufferFreeAndReset(). Update documentation and replace all remaining calls to free() with calls to VIR_FREE(). Also add missing calls to virBufferFreeAndReset() and virReportOOMError() in OOM error cases.
2009-12-09 23:00:50 +00:00
...
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
if (virBufferError(&amp;buf)) {
Add virBufferFreeAndReset() and replace free() Replace free(virBufferContentAndReset()) with virBufferFreeAndReset(). Update documentation and replace all remaining calls to free() with calls to VIR_FREE(). Also add missing calls to virBufferFreeAndReset() and virReportOOMError() in OOM error cases.
2009-12-09 23:00:50 +00:00
virBufferFreeAndReset(&amp;buf);
Remove conn parameter from virReportOOMError
2010-02-04 18:19:08 +00:00
virReportOOMError();
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
return NULL;
}
return virBufferContentAndReset(&amp;buf);
}
</pre>
<h2><a name="includes">Include files</a></h2>
<p>
There are now quite a large number of include files, both libvirt
internal and external, and system includes. To manage all this
complexity it's best to stick to the following general plan for all
*.c source files:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
/*
* Copyright notice
* ....
* ....
* ....
*
*/
#include &lt;config.h&gt; Must come first in every file.
#include &lt;stdio.h&gt; Any system includes you need.
#include &lt;string.h&gt;
#include &lt;limits.h&gt;
Convert HAVE_NUMACTL to WITH_NUMACTL Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2012-09-20 12:41:15 +00:00
#if WITH_NUMACTL Some system includes aren't supported
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
# include &lt;numa.h&gt; everywhere so need these #if guards.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
#endif
#include "internal.h" Include this first, after system includes.
#include "util.h" Any libvirt internal header files.
#include "buf.h"
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
static int
myInternalFunc() The actual code.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
{
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
...
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
<p>
docs: Update HACKING To tell libvirt-{qemu,lxc}.h shouldn't be included either.
2013-04-17 10:19:20 +00:00
Of particular note: <b>Do not</b> include libvirt/libvirt.h,
libvirt/virterror.h, libvirt/libvirt-qemu.h, or libvirt/libvirt-lxc.h.
They are included by "internal.h" already and there are some special reasons
why you cannot include these files explicitly. One of the special cases,
"libvirt/libvirt.h" is included prior to "internal.h" in "remote_protocol.x",
to avoid exposing *_LAST enum elements.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</p>
<h2><a name="printf">Printf-style functions</a></h2>
<p>
Whenever you add a new printf-style function, i.e., one with a format
string argument and following "..." in its prototype, be sure to use
gcc's printf attribute directive in the prototype. For example, here's
the one for virAsprintf, in util.h:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
int virAsprintf(char **strp, const char *fmt, ...)
ATTRIBUTE_FORMAT(printf, 2, 3);
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</pre>
<p>
This makes it so gcc's -Wformat and -Wformat-security options can do
their jobs and cross-check format strings with the number and types
of arguments.
</p>
maint: avoid remaining sprintf uses * cfg.mk (sc_prohibit_sprintf): New rule. (sc_prohibit_asprintf): Avoid false positives. * docs/hacking.html.in (Printf-style functions): Document the policy. * HACKING: Regenerate. * .x-sc_prohibit_sprintf: New exemptions. * Makefile.am (syntax_check_exceptions): Ship new file. * src/vbox/vbox_tmpl.c (vboxStartMachine, vboxAttachUSB): Use virAsprintf instead. * src/uml/uml_driver.c (umlOpenMonitor): Use snprintf instead. * tools/virsh.c (cmdDetachInterface): Likewise. * src/security/security_selinux.c (SELinuxGenSecurityLabel): Likewise. * src/openvz/openvz_driver.c (openvzDomainDefineCmd): Likewise, and ensure large enough buffer.
2010-08-18 23:31:39 +00:00
<p>
When printing to a string, consider using virBuffer for
incremental allocations, virAsprintf for a one-shot allocation,
and snprintf for fixed-width buffers. Do not use sprintf, even
if you can prove the buffer won't overflow, since gnulib does
not provide the same portability guarantees for sprintf as it
does for snprintf.
</p>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
<h2><a name="goto">Use of goto</a></h2>
<p>
The use of goto is not forbidden, and goto is widely used
throughout libvirt. While the uncontrolled use of goto will
quickly lead to unmaintainable code, there is a place for it in
well structured code where its use increases readability and
maintainability. In general, if goto is used for error
recovery, it's likely to be ok, otherwise, be cautious or avoid
it all together.
</p>
<p>
The typical use of goto is to jump to cleanup code in the case
of a long list of actions, any of which may fail and cause the
entire operation to fail. In this case, a function will have a
single label at the end of the function. It's almost always ok
to use this style. In particular, if the cleanup code only
involves free'ing memory, then having multiple labels is
overkill. VIR_FREE() and every function named XXXFree() in
libvirt is required to handle NULL as its arg. Thus you can
safely call free on all the variables even if they were not yet
allocated (yes they have to have been initialized to NULL).
This is much simpler and clearer than having multiple labels.
</p>
<p>
There are a couple of signs that a particular use of goto is not
ok:
</p>
<ul>
<li>You're using multiple labels. If you find yourself using
multiple labels, you're strongly encouraged to rework your code
to eliminate all but one of them.</li>
<li>The goto jumps back up to a point above the current line of
code being executed. Please use some combination of looping
constructs to re-execute code instead; it's almost certainly
going to be more understandable by others. One well-known
exception to this rule is restarting an i/o operation following
EINTR.</li>
<li>The goto jumps down to an arbitrary place in the middle of a
function followed by further potentially failing calls. You
should almost certainly be using a conditional and a block
instead of a goto. Perhaps some of your function's logic would
be better pulled out into a helper function.</li>
</ul>
<p>
Although libvirt does not encourage the Linux kernel wind/unwind
style of multiple labels, there's a good general discussion of
the issue archived at
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<a href="http://kerneltrap.org/node/553/2131">KernelTrap</a>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
</p>
<p>
When using goto, please use one of these standard labels if it
makes sense:
</p>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
<pre>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
error: A path only taken upon return with an error code
cleanup: A path taken upon return with success code + optional error
no_memory: A path only taken upon return with an OOM error code
memory: make it safer to expand arrays * src/util/memory.h (VIR_REALLOC_N): Update docs. (VIR_EXPAND_N, VIR_SHRINK_N): New macros. (virAlloc, virAllocN, virReallocN, virAllocVar, virFree): Add some gcc attributes. * src/util/memory.c (virExpandN, virShrinkN): New functions. (virReallocN): Update docs. * src/libvirt_private.syms: Export new helpers. * docs/hacking.html.in: Prefer newer interfaces over VIR_REALLOC_N, since uninitialized memory can bite us. * HACKING: Regenerate.
2010-08-13 21:00:47 +00:00
retry: If needing to jump upwards (e.g., retry on EINTR)
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
</pre>
Update hacking.html.in * Added section on use of goto * Added missing content from HACKING document
2010-03-08 15:26:30 +00:00
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
doc: fix typos in hacking.html.in; mark HACKING as read-only * HACKING: Mark as read-only. Soon we'll generate it from... * docs/hacking.html.in: ... this file. More typo fixes.
2010-03-09 16:59:25 +00:00
<h2><a name="committers">Libvirt committer guidelines</a></h2>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<p>
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
The AUTHORS files indicates the list of people with commit access right
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
who can actually merge the patches.
</p>
<p>
doc: fix typos in hacking.html.in; mark HACKING as read-only * HACKING: Mark as read-only. Soon we'll generate it from... * docs/hacking.html.in: ... this file. More typo fixes.
2010-03-09 16:59:25 +00:00
The general rule for committing a patch is to make sure
it has been reviewed
properly in the mailing-list first, usually if a couple of people gave an
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
ACK or +1 to a patch and nobody raised an objection on the list it should
doc: fix typos in hacking.html.in; mark HACKING as read-only * HACKING: Mark as read-only. Soon we'll generate it from... * docs/hacking.html.in: ... this file. More typo fixes.
2010-03-09 16:59:25 +00:00
be good to go. If the patch touches a part of the code where you're not
the main maintainer, or where you do not have a very clear idea of
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
how things work, it's better
to wait for a more authoritative feedback though. Before committing, please
also rebuild locally, run 'make check syntax-check', and make sure you
don't raise errors. Try to look for warnings too; for example,
configure with
docs: <pre> cannot be nested in <p> xsltproc complained about this.
2010-03-13 14:04:34 +00:00
</p>
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
<pre>
docs: Prepare hacking.html.in to generate HACKING from it Tweak pre tags to achieve proper indentation of their plaintext representation. Also use more b/i/code tags.
2010-11-12 14:33:00 +00:00
--enable-compile-warnings=error
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
</pre>
docs: <pre> cannot be nested in <p> xsltproc complained about this.
2010-03-13 14:04:34 +00:00
<p>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
which adds -Werror to compile flags, so no warnings get missed
</p>
<p>
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
An exception to 'review and approval on the list first' is fixing failures
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
to build:
</p>
<ul>
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
<li>if a recently committed patch breaks compilation on a platform
or for a given driver, then it's fine to commit a minimal fix
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
directly without getting the review feedback first</li>
docs: Refer to virReportOOMError in the HACKING file Instead of refering to __virRaiseError(VIR_ERROR_NO_MEMORY).
2010-01-30 11:35:04 +00:00
<li>if make check or make syntax-check breaks, if there is
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
an obvious fix, it's fine to commit immediately.
The patch should still be sent to the list (or tell what the fix was if
hacking: fix typos * docs/hacking.html.in (committers): Fix spelling and grammar.
2010-03-09 00:02:44 +00:00
trivial), and 'make check syntax-check' should pass too, before committing
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
anything</li>
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
<li>
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
fixes for documentation and code comments can be managed
in the same way, but still make sure they get reviewed if non-trivial.
Add HACKING doc to the website
2009-06-29 11:09:17 +00:00
</li>
</ul>
</body>
</html>
Reference in New Issue Copy Permalink