3:50 a.m.
The pathches used as an example for the api_extension manual don't hold
up to the current standards any more. Carefully remove links and
mentions of the patches from the docs.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/api_extension.html.in | 96 +++++++++-------------------------------------
1 file changed, 18 insertions(+), 78 deletions(-)
diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in
index 9beec07602..b473d09b17 100644
--- a/docs/api_extension.html.in
+++ b/docs/api_extension.html.in
@@ -8,14 +8,9 @@
<p>
This document walks you through the process of implementing a new
- API in libvirt. It uses as an example the addition of an API for
- separating maximum from current vcpu usage of a domain, over
- the course of a fifteen-patch series.
- Remember that new API consists of any new public functions, as
- well as the addition of flags or extensions of XML used by
- existing functions. The example in this document adds both new
- functions and an XML extension. Not all libvirt API additions
- require quite as many patches.
+ API in libvirt. Remember that new API consists of any new public
+ functions, as well as the addition of flags or extensions of XML used by
+ existing functions.
</p>
<p>
@@ -27,12 +22,7 @@
added to libvirt. Someone may already be working on the feature you
want. Also, recognize that everything you write is likely to undergo
significant rework as you discuss it with the other developers, so
- don't wait too long before getting feedback. In the vcpu example
- below, list feedback was first requested
- <a
href="https://www.redhat.com/archives/libvir-list/2010-September/msg...
- and resulted in several rounds of improvements before coding
- began. In turn, this example is slightly rearranged from the actual
- order of the commits.
+ don't wait too long before getting feedback.
</p>
<p>
@@ -81,14 +71,13 @@
</p>
<p>
- Submit new code in the form shown in the example code: one patch
- per step. That's not to say submit patches before you have working
- functionality--get the whole thing working and make sure you're happy
- with it. Then use git or some other version control system that lets
- you rewrite your commit history and break patches into pieces so you
- don't drop a big blob of code on the mailing list in one go.
- Also, you should follow the upstream tree, and rebase your
- series to adapt your patches to work with any other changes
+ Submit new code in the form of one patch per step. That's not to say
+ submit patches before you have working functionality--get the whole thing
+ working and make sure you're happy with it. Then use git or some other
+ version control system that lets you rewrite your commit history and
+ break patches into pieces so you don't drop a big blob of code on the
+ mailing list in one go. Also, you should follow the upstream tree, and
+ rebase your series to adapt your patches to work with any other changes
that were accepted upstream during your development.
</p>
@@ -101,8 +90,6 @@
separately.
</p>
- <p>With that said, let's begin.</p>
-
<h2><a name='publicapi'>Defining the public
API</a></h2>
<p>The first task is to define the public API. If the new API
@@ -133,10 +120,6 @@
rework it as you go through the process of implementing it.
</p>
- <p class="example">See <a
href="api_extension/0001-add-to-xml.patch">0001-add-to-xml.patch</a>
- and <a
href="api_extension/0002-add-new-public-API.patch">0002-add-new-public-API.patch</a>
- for example code.</p>
-
<h2><a name='internalapi'>Defining the internal
API</a></h2>
<p>
@@ -164,8 +147,6 @@
provide a <code>NULL</code> stub for the new function.
</p>
- <p class="example">See <a
href="api_extension/0003-define-internal-driver-API.patch">0003-define-internal-driver-API.patch</a></p>
-
<h2><a name='implpublic'>Implementing the public
API</a></h2>
<p>
@@ -197,22 +178,16 @@
<p>The public API calls are implemented in:</p>
- <p><code>src/libvirt.c</code></p>
-
- <p class="example">See <a
href="api_extension/0004-implement-the-public-APIs.patch">0004-implement-the-public-APIs.patch</a></p>
+ <p><code>src/libvirt-$SECTION.c</code></p>
<h2><a name='remoteproto'>Implementing the remote
protocol</a></h2>
<p>
Implementing the remote protocol is essentially a
straightforward exercise which is probably most easily
- understood by referring to the existing code and the example
- patch. It involves several related changes, including the
- regeneration of derived files, with further details below.
+ understood by referring to the existing code.
</p>
- <p class="example">See <a
href="api_extension/0005-implement-the-remote-protocol.patch">0005-implement-the-remote-protocol.patch</a></p>
-
<h3><a name='wireproto'>Defining the wire protocol
format</a></h3>
<p>
@@ -298,8 +273,6 @@
existing lines probably imply a backwards-incompatible API change.
</p>
- <p class="example">See <a
href="api_extension/0005-implement-the-remote-protocol.patch">0005-implement-the-remote-protocol.patch</a></p>
-
<h2><a id="internaluseapi">Use the new API
internally</a></h2>
<p>
@@ -312,8 +285,6 @@
not necessary if the new API has no relation to existing API.
</p>
- <p class="example">See <a
href="api_extension/0006-make-old-API-trivially-wrap-to-new-API.patch">0006-make-old-API-trivially-wrap-to-new-API.patch</a></p>
-
<h2><a id="virshuseapi">Expose the new API in
virsh</a></h2>
<p>
@@ -343,8 +314,6 @@
tools/virsh.pod
</code></p>
- <p class="example">See <a
href="api_extension/0007-add-virsh-support.patch">0007-add-virsh-support.patch</a></p>
-
<h2><a id="driverimpl">Implement the driver
methods</a></h2>
<p>
@@ -371,8 +340,6 @@
the same way as the older API wrappers.
</p>
- <p class="example">See <a
href="api_extension/0008-support-new-xml.patch">0008-support-new-xml.patch</a></p>
-
<h3><a id="drivercode">Implement driver
handling</a></h3>
<p>
@@ -384,41 +351,14 @@
</p>
<p>
- In the example patches, three separate drivers are supported:
- test, qemu, and xen. It is always a good idea to patch the test
- driver in addition to the target driver, to prove that the API
- can be used for more than one driver. The example updates the
- test driver in one patch:
+ It is always a good idea to patch the test driver in addition to the
+ target driver, to prove that the API can be used for more than one
+ driver.
</p>
- <p class="example">See <a
href="api_extension/0009-support-all-flags-in-test-driver.patch">0009-support-all-flags-in-test-driver.patch</a></p>
-
- <p>
- The qemu changes were easier to split into two phases, one for
- updating the mapping between the new XML and the hypervisor
- command line arguments, and one for supporting all possible
- flags of the new API:
- </p>
-
- <p class="example">See <a
href="api_extension/0010-improve-vcpu-support-in-qemu-command-line.patch">0010-improve-vcpu-support-in-qemu-command-line.patch</a>
- and <a
href="api_extension/0011-complete-vcpu-support-in-qemu-driver.patch">0011-complete-vcpu-support-in-qemu-driver.patch</a></p>
-
- <p>
- Finally, the example breaks the xen driver changes across four
- patches. One maps the XML changes to the hypervisor command,
- the next two are independently implementing the getter and
- setter APIs, and the last one provides cleanup of code that was
- rendered dead by the new API.
- </p>
-
- <p class="example">See <a
href="api_extension/0012-improve-vcpu-support-in-xen-command-line.patch">0012-improve-vcpu-support-in-xen-command-line.patch</a>,
- <a
href="api_extension/0013-improve-getting-xen-vcpu-counts.patch">0013-improve-getting-xen-vcpu-counts.patch</a>,
- <a
href="api_extension/0014-improve-setting-xen-vcpu-counts.patch">0014-improve-setting-xen-vcpu-counts.patch</a>,
- and <a
href="api_extension/0015-remove-dead-xen-code.patch">0015-remove-dead-xen-code.patch</a></p>
-
<p>
- The exact details of the example code are probably uninteresting
- unless you're concerned with virtual cpu management.
+ Any cleanups resulting from the changes should be added as separate
+ patches at the end of the series.
</p>
<p>
--
2.16.2