[libvirt] [jenkins-ci PATCH 8/8] guests: Update documentation
The usage has once again changed slightly; additionally,
a few concrete examples are now provided.
Signed-off-by: Andrea Bolognani <abologna(a)redhat.com>
---
guests/README.markdown | 38 ++++++++++++++++++++++++++++++++------
1 file changed, 32 insertions(+), 6 deletions(-)
diff --git a/guests/README.markdown b/guests/README.markdown
index 4a40619..ddf0149 100644
--- a/guests/README.markdown
+++ b/guests/README.markdown
@@ -4,22 +4,48 @@ libvirt CI - guest management tools
The tools contained in this directory simplify and automate the management
of the guests used by the Jenkins-based libvirt CI environment.
+
+Usage and examples
+------------------
+
There are two steps to bringing up a guest:
-* `./lcitool -a install -h $guest` will perform an unattended installation
+* `lcitool -a install -h $guest` will perform an unattended installation
of `$guest`. Not all guests can be installed this way: see the "FreeBSD"
section below;
-* `./lcitool -a update -h $guest` will go through all the post-installation
- configuration steps required to make the newly-created guest usable;
+* `lcitool -a update -h $guest -p $project` will go through all the
+ post-installation configuration steps required to make the newly-created
+ guest usable and ready to be used for building `$project`;
Once those steps have been performed, maintainance will involve running:
-* `./lcitool -a update -h $guest`
+ lcitool -a update -h $guest -p $project
periodically to ensure the guest configuration is sane and all installed
packages are updated.
+To get a list of known guests and projects, run
+
+ lcitool -a hosts
+
+and
+
+ lcitool -a projects
+
+respectively. You can run operations involving multiple guests and projects
+at once by providing a list on the command line: for example, running
+
+ lcitool -a update -h '*fedora*' -p '*osinfo*'
+
+will update all Fedora guests and get them ready to build libosinfo and
+related projects, while running
+
+ lcitool -a update -h all -p libvirt,libvirt+mingw
+
+will update all hosts and prepare them to build libvirt both as a native
+library and, where supported, as a Windows library using MinGW.
+
Host setup
----------
@@ -40,13 +66,13 @@ you'll want to use the `libvirt_guest` variant of the plugin.
To keep guests up to date over time, it's recommended to have an entry
along the lines of
- 0 0 * * * cd ~/libvirt-jenkins-ci/guests && ./lcitool -a update -h all
+ 0 0 * * * ~/libvirt-jenkins-ci/guests/lcitool -a update -h all -p all
in your crontab.
Test use
----------------
+--------
If you are a developer trying to reproduce a bug on some OS you don't
have easy access to, you can use these tools to create a suitable test
--
2.17.1