+Tue Jan 31 19:12:19 CET 2006 Daniel Veillard <veillard@redhat.com>
+
+ * configure.in docs/examples/*: starting to add examples. the XSLT
+ still need to be fixed for web site
+
Tue Jan 31 11:22:51 CET 2006 Daniel Veillard <veillard@redhat.com>
* python/*: update of the python bindings, fix names, add
rm -f COPYING
AC_OUTPUT(Makefile src/Makefile include/Makefile docs/Makefile \
+ docs/examples/Makefile \
libvir.pc libvir.spec include/libvir.h python/Makefile)
--- /dev/null
+# Beware this is autogenerated by index.py
+INCLUDES = -I$(top_builddir)/include -I$(top_srcdir)/include -I@srcdir@/include
+DEPS = $(top_builddir)/src/libvir.la
+LDADDS = @STATIC_BINARIES@ $(top_builddir)/src/libvir.la
+
+rebuild: examples.xml index.html
+
+examples.xml: index.py *.c
+ -@($(srcdir)/index.py)
+
+index.html: examples.xml examples.xsl
+ -@(xsltproc examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html)
+
+install-data-local:
+ $(mkinstalldirs) $(DESTDIR)$(HTML_DIR)
+ -@INSTALL@ -m 0644 $(srcdir)/*.html $(srcdir)/*.c $(srcdir)/*.xml $(srcdir)/*.xsl $(srcdir)/*.res $(DESTDIR)$(HTML_DIR)
+
+EXTRA_DIST=examples.xsl index.py examples.xml
+
+noinst_PROGRAMS=info1
+
+info1_SOURCES=info1.c
+info1_LDFLAGS=
+info1_DEPENDENCIES= $(DEPS)
+info1_LDADD= $(LDADDS)
+
+valgrind:
+ $(MAKE) CHECKER='valgrind' tests
+
+tests: $(noinst_PROGRAMS)
+ @(echo '## examples regression tests')
+ @($(CHECKER) ./info1)
+
+
--- /dev/null
+<examples>
+ <example filename='info1.c'>
+ <synopsis>Extract informations about Xen domain 0</synopsis>
+ <purpose>Demonstrate the basic use of the library to connect to the hypervisor and extract domain informations.</purpose>
+ <usage>info1</usage>
+ <test>info1</test>
+ <author>Daniel Veillard</author>
+ <copy>see Copyright for the status of this software. </copy>
+ <section>Informations</section>
+ <includes>
+ </includes>
+ <uses>
+ <function line='43' file='libvir' name='virDomainGetInfo'/>
+ <function line='53' file='libvir' name='virDomainFree'/>
+ <function line='36' file='libvir' name='virDomainLookupByID'/>
+ <function line='55' file='libvir' name='virConnectClose'/>
+ <struct line='25' file='libvir' name='virDomainInfo'/>
+ <function line='29' file='libvir' name='virConnectOpenReadOnly'/>
+ </uses>
+ </example>
+ <symbols>
+ <symbol name='virConnectClose'>
+ <ref filename='info1.c'/>
+ </symbol>
+ <symbol name='virConnectOpenReadOnly'>
+ <ref filename='info1.c'/>
+ </symbol>
+ <symbol name='virDomainFree'>
+ <ref filename='info1.c'/>
+ </symbol>
+ <symbol name='virDomainGetInfo'>
+ <ref filename='info1.c'/>
+ </symbol>
+ <symbol name='virDomainInfo'>
+ <ref filename='info1.c'/>
+ </symbol>
+ <symbol name='virDomainLookupByID'>
+ <ref filename='info1.c'/>
+ </symbol>
+ </symbols>
+ <sections>
+ <section name='Informations'>
+ <example filename='info1.c'/>
+ </section>
+ </sections>
+</examples>
--- /dev/null
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:exsl="http://exslt.org/common"
+ extension-element-prefixes="exsl"
+ exclude-result-prefixes="exsl">
+
+ <xsl:import href="../site.xsl"/>
+
+ <xsl:variable name="href_base">../</xsl:variable>
+ <xsl:variable name="menu_name">Examples Menu</xsl:variable>
+
+ <xsl:variable name="toc">
+ <form action="../search.php"
+ enctype="application/x-www-form-urlencoded" method="get">
+ <input name="query" type="text" size="20" value=""/>
+ <input name="submit" type="submit" value="Search ..."/>
+ </form>
+ <ul><!-- style="margin-left: -1em" -->
+ <li><a href="{$href_base}index.html">Home</a></li>
+ <li><a style="font-weight:bold"
+ href="{$href_base}docs.html">Developer Menu</a></li>
+ <li><a style="font-weight:bold"
+ href="{$href_base}html/index.html">API Menu</a></li>
+ <xsl:for-each select="/examples/sections/section">
+ <li><a href="#{@name}"><xsl:value-of select="@name"/> Examples</a></li>
+ </xsl:for-each>
+ <li><a href="{$href_base}guidelines.html">XML Guidelines</a></li>
+ </ul>
+ </xsl:variable>
+
+ <xsl:template match="include">
+ <xsl:variable name="header" select="substring-before(substring-after(., '/'), '>')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', $header, 'tml')"/>
+ <li><a href="{$doc}"><xsl:value-of select="."/></a></li>
+ </xsl:template>
+
+ <xsl:template match="typedef">
+ <xsl:variable name="name" select="@name"/>
+ <xsl:variable name="header" select="concat(@file, '.h')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', @file, '.html#', $name)"/>
+ <li> line <xsl:value-of select="@line"/>: Type <a href="{$doc}"><xsl:value-of select="$name"/></a> from <xsl:value-of select="$header"/></li>
+ </xsl:template>
+
+ <xsl:template match="function">
+ <xsl:variable name="name" select="@name"/>
+ <xsl:variable name="header" select="concat(@file, '.h')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', @file, '.html#', $name)"/>
+ <li> line <xsl:value-of select="@line"/>: Function <a href="{$doc}"><xsl:value-of select="$name"/></a> from <xsl:value-of select="$header"/></li>
+ </xsl:template>
+
+ <xsl:template match="macro">
+ <xsl:variable name="name" select="@name"/>
+ <xsl:variable name="header" select="concat(@file, '.h')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', @file, '.html#', $name)"/>
+ <li> line <xsl:value-of select="@line"/>: Macro <a href="{$doc}"><xsl:value-of select="$name"/></a> from <xsl:value-of select="$header"/></li>
+ </xsl:template>
+
+ <xsl:template match="example">
+ <xsl:variable name="filename" select="string(@filename)"/>
+ <h3><a name="{$filename}" href="{$filename}"><xsl:value-of select="$filename"/></a>: <xsl:value-of select="synopsis"/></h3>
+ <p><xsl:value-of select="purpose"/></p>
+ <p>Includes:</p>
+ <ul>
+ <xsl:for-each select="includes/include">
+ <xsl:apply-templates select='.'/>
+ </xsl:for-each>
+ </ul>
+ <p>Uses:</p>
+ <ul>
+ <xsl:for-each select="uses/*">
+ <xsl:sort select="@line" data-type="number"/>
+ <xsl:apply-templates select='.'/>
+ </xsl:for-each>
+ </ul>
+ <p>Usage:</p>
+ <p><xsl:value-of select="usage"/></p>
+ <p>Author: <xsl:value-of select="author"/></p>
+ </xsl:template>
+
+ <xsl:template match="section">
+ <li><p> <a href="#{@name}"><xsl:value-of select="@name"/></a> :</p>
+ <ul>
+ <xsl:for-each select="example">
+ <xsl:sort select='.'/>
+ <xsl:variable name="filename" select="@filename"/>
+ <li> <a href="#{$filename}"><xsl:value-of select="$filename"/></a>: <xsl:value-of select="/examples/example[@filename = $filename]/synopsis"/></li>
+ </xsl:for-each>
+ </ul>
+ </li>
+ </xsl:template>
+
+ <xsl:template match="sections">
+ <p> The examples are stored per section depending on the main focus
+ of the example:</p>
+ <ul>
+ <xsl:for-each select="section">
+ <xsl:sort select='.'/>
+ <xsl:apply-templates select='.'/>
+ </xsl:for-each>
+ </ul>
+ <p> Getting the compilation options and libraries dependancies needed
+to generate binaries from the examples is best done on Linux/Unix by using
+the xml2-config script which should have been installed as part of <i>make
+install</i> step or when installing the libxml2 development package:</p>
+<pre>gcc -o example `xml2-config --cflags` example.c `xml2-config --libs`</pre>
+ </xsl:template>
+
+ <xsl:template name="sections-list">
+ <xsl:for-each select="sections/section">
+ <xsl:variable name="section" select="@name"/>
+ <h2> <a name="{$section}"></a><xsl:value-of select="$section"/> Examples</h2>
+ <xsl:apply-templates select='/examples/example[section = $section]'/>
+ </xsl:for-each>
+ </xsl:template>
+
+ <xsl:template match="examples">
+ <xsl:variable name="title">Libxml2 set of examples</xsl:variable>
+ <xsl:document href="index.html" method="xml" encoding="ISO-8859-1"
+ doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
+ doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+ <html>
+ <head>
+ <xsl:call-template name="style"/>
+ <xsl:element name="title">
+ <xsl:value-of select="$title"/>
+ </xsl:element>
+ </head>
+ <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
+ <xsl:call-template name="titlebox">
+ <xsl:with-param name="title" select="$title"/>
+ </xsl:call-template>
+ <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center">
+ <tr>
+ <td bgcolor="#8b7765">
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr>
+ <td valign="top" width="200" bgcolor="#8b7765">
+ <xsl:call-template name="toc"/>
+ </td>
+ <td valign="top" bgcolor="#8b7765">
+ <table border="0" cellspacing="0" cellpadding="1" width="100%">
+ <tr>
+ <td>
+ <table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000">
+ <tr>
+ <td>
+ <table border="0" cellpadding="3" cellspacing="1" width="100%">
+ <tr>
+ <td bgcolor="#fffacd">
+ <xsl:apply-templates select="sections"/>
+ <xsl:call-template name="sections-list"/>
+ <p><a href="../bugs.html">Daniel Veillard</a></p>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </body>
+ </html>
+ </xsl:document>
+ </xsl:template>
+
+</xsl:stylesheet>
--- /dev/null
+#!/usr/bin/python -u
+#
+# Indexes the examples and build an XML description
+#
+import string
+import glob
+import sys
+try:
+ import libxml2
+except:
+ sys.exit(1)
+sys.path.insert(0, "..")
+from apibuild import CParser, escape
+
+examples = []
+extras = ['examples.xsl', 'index.py']
+tests = []
+sections = {}
+symbols = {}
+api_dict = None
+api_doc = None
+
+def load_api():
+ global api_dict
+ global api_doc
+
+ if api_dict != None:
+ return
+ api_dict = {}
+ try:
+ print "loading ../libvir-api.xml"
+ api_doc = libxml2.parseFile("../libvir-api.xml")
+ except:
+ print "failed to parse ../libvir-api.xml"
+ sys.exit(1)
+
+def find_symbol(name):
+ global api_dict
+ global api_doc
+
+ if api_doc == None:
+ load_api()
+
+ if name == None:
+ return
+ if api_dict.has_key(name):
+ return api_dict[name]
+ ctxt = api_doc.xpathNewContext()
+ res = ctxt.xpathEval("/api/symbols/*[@name = '%s']" % (name))
+ if type(res) == type([]) and len(res) >= 1:
+ if len(res) > 1:
+ print "Found %d references to %s in the API" % (len(res), name)
+ node = res[0]
+ typ = node.name
+ file = node.xpathEval("string(@file)")
+ info = node.xpathEval("string(info)")
+ else:
+ print "Reference %s not found in the API" % (name)
+ return None
+ ret = (typ, file, info)
+ api_dict[name] = ret
+ return ret
+
+def parse_top_comment(filename, comment):
+ res = {}
+ lines = string.split(comment, "\n")
+ item = None
+ for line in lines:
+ while line != "" and (line[0] == ' ' or line[0] == '\t'):
+ line = line[1:]
+ while line != "" and line[0] == '*':
+ line = line[1:]
+ while line != "" and (line[0] == ' ' or line[0] == '\t'):
+ line = line[1:]
+ try:
+ (it, line) = string.split(line, ":", 1)
+ item = it
+ while line != "" and (line[0] == ' ' or line[0] == '\t'):
+ line = line[1:]
+ if res.has_key(item):
+ res[item] = res[item] + " " + line
+ else:
+ res[item] = line
+ except:
+ if item != None:
+ if res.has_key(item):
+ res[item] = res[item] + " " + line
+ else:
+ res[item] = line
+ return res
+
+def parse(filename, output):
+ global symbols
+ global sections
+
+ parser = CParser(filename)
+ parser.collect_references()
+ idx = parser.parse()
+ info = parse_top_comment(filename, parser.top_comment)
+ output.write(" <example filename='%s'>\n" % filename)
+ try:
+ synopsis = info['synopsis']
+ output.write(" <synopsis>%s</synopsis>\n" % escape(synopsis));
+ except:
+ print "Example %s lacks a synopsis description" % (filename)
+ try:
+ purpose = info['purpose']
+ output.write(" <purpose>%s</purpose>\n" % escape(purpose));
+ except:
+ print "Example %s lacks a purpose description" % (filename)
+ try:
+ usage = info['usage']
+ output.write(" <usage>%s</usage>\n" % escape(usage));
+ except:
+ print "Example %s lacks an usage description" % (filename)
+ try:
+ test = info['test']
+ output.write(" <test>%s</test>\n" % escape(test));
+ progname=filename[0:-2]
+ command=string.replace(test, progname, './' + progname, 1)
+ tests.append(command)
+ except:
+ pass
+ try:
+ author = info['author']
+ output.write(" <author>%s</author>\n" % escape(author));
+ except:
+ print "Example %s lacks an author description" % (filename)
+ try:
+ copy = info['copy']
+ output.write(" <copy>%s</copy>\n" % escape(copy));
+ except:
+ print "Example %s lacks a copyright description" % (filename)
+ try:
+ section = info['section']
+ output.write(" <section>%s</section>\n" % escape(section));
+ if sections.has_key(section):
+ sections[section].append(filename)
+ else:
+ sections[section] = [filename]
+ except:
+ print "Example %s lacks a section description" % (filename)
+ for topic in info.keys():
+ if topic != "purpose" and topic != "usage" and \
+ topic != "author" and topic != "copy" and \
+ topic != "section" and topic != "synopsis" and topic != "test":
+ str = info[topic]
+ output.write(" <extra topic='%s'>%s</extra>\n" % (
+ escape(topic), escape(str)))
+ output.write(" <includes>\n")
+ for include in idx.includes.keys():
+ if include.find("libxml") != -1:
+ output.write(" <include>%s</include>\n" % (escape(include)))
+ output.write(" </includes>\n")
+ output.write(" <uses>\n")
+ for ref in idx.references.keys():
+ id = idx.references[ref]
+ name = id.get_name()
+ line = id.get_lineno()
+ if symbols.has_key(name):
+ sinfo = symbols[name]
+ refs = sinfo[0]
+ # gather at most 5 references per symbols
+ if refs > 5:
+ continue
+ sinfo.append(filename)
+ sinfo[0] = refs + 1
+ else:
+ symbols[name] = [1, filename]
+ info = find_symbol(name)
+ if info != None:
+ type = info[0]
+ file = info[1]
+ output.write(" <%s line='%d' file='%s' name='%s'/>\n" % (type,
+ line, file, name))
+ else:
+ type = id.get_type()
+ output.write(" <%s line='%d' name='%s'/>\n" % (type,
+ line, name))
+
+ output.write(" </uses>\n")
+ output.write(" </example>\n")
+
+ return idx
+
+def dump_symbols(output):
+ global symbols
+
+ output.write(" <symbols>\n")
+ keys = symbols.keys()
+ keys.sort()
+ for symbol in keys:
+ output.write(" <symbol name='%s'>\n" % (symbol))
+ info = symbols[symbol]
+ i = 1
+ while i < len(info):
+ output.write(" <ref filename='%s'/>\n" % (info[i]))
+ i = i + 1
+ output.write(" </symbol>\n")
+ output.write(" </symbols>\n")
+
+def dump_sections(output):
+ global sections
+
+ output.write(" <sections>\n")
+ keys = sections.keys()
+ keys.sort()
+ for section in keys:
+ output.write(" <section name='%s'>\n" % (section))
+ info = sections[section]
+ i = 0
+ while i < len(info):
+ output.write(" <example filename='%s'/>\n" % (info[i]))
+ i = i + 1
+ output.write(" </section>\n")
+ output.write(" </sections>\n")
+
+def dump_Makefile():
+ for file in glob.glob('*.xml'):
+ extras.append(file)
+ for file in glob.glob('*.res'):
+ extras.append(file)
+ Makefile="""# Beware this is autogenerated by index.py
+INCLUDES = -I$(top_builddir)/include -I$(top_srcdir)/include -I@srcdir@/include
+DEPS = $(top_builddir)/src/libvir.la
+LDADDS = @STATIC_BINARIES@ $(top_builddir)/src/libvir.la
+
+rebuild: examples.xml index.html
+
+examples.xml: index.py *.c
+ -@($(srcdir)/index.py)
+
+index.html: examples.xml examples.xsl
+ -@(xsltproc examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html)
+
+install-data-local:
+ $(mkinstalldirs) $(DESTDIR)$(HTML_DIR)
+ -@INSTALL@ -m 0644 $(srcdir)/*.html $(srcdir)/*.c $(srcdir)/*.xml $(srcdir)/*.xsl $(srcdir)/*.res $(DESTDIR)$(HTML_DIR)
+
+"""
+ EXTRA_DIST=""
+ for extra in extras:
+ EXTRA_DIST = EXTRA_DIST + extra + " "
+ Makefile = Makefile + "EXTRA_DIST=%s\n\n" % (EXTRA_DIST)
+ noinst_PROGRAMS=""
+ for example in examples:
+ noinst_PROGRAMS = noinst_PROGRAMS + example + " "
+ Makefile = Makefile + "noinst_PROGRAMS=%s\n\n" % (noinst_PROGRAMS)
+ for example in examples:
+ Makefile = Makefile + "%s_SOURCES=%s.c\n%s_LDFLAGS=\n%s_DEPENDENCIES= $(DEPS)\n%s_LDADD= $(LDADDS)\n\n" % (example, example, example,
+ example, example)
+ Makefile = Makefile + "valgrind: \n\t$(MAKE) CHECKER='valgrind' tests\n\n"
+ Makefile = Makefile + "tests: $(noinst_PROGRAMS)\n"
+ Makefile = Makefile + "\t@(echo '## examples regression tests')\n"
+# Makefile = Makefile + "\t@(echo > .memdump)\n"
+ for test in tests:
+ Makefile = Makefile + "\t@($(CHECKER) %s)\n" % (test)
+# Makefile = Makefile + '\t@(grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0)\n'
+ Makefile = Makefile + "\n\n"
+ try:
+ old = open("Makefile.am", "r").read()
+ if old != Makefile:
+ n = open("Makefile.am", "w").write(Makefile)
+ print "Updated Makefile.am"
+ except:
+ print "Failed to read or save Makefile.am"
+ #
+ # Autogenerate the .cvsignore too ...
+ #
+ ignore = """.memdump
+Makefile.in
+Makefile
+"""
+ for example in examples:
+ ignore = ignore + "%s\n" % (example)
+ try:
+ old = open(".cvsignore", "r").read()
+ if old != ignore:
+ n = open(".cvsignore", "w").write(ignore)
+ print "Updated .cvsignore"
+ except:
+ print "Failed to read or save .cvsignore"
+
+if __name__ == "__main__":
+ load_api()
+ output = open("examples.xml", "w")
+ output.write("<examples>\n")
+
+ for file in glob.glob('*.c'):
+ parse(file, output)
+ examples.append(file[:-2])
+
+ dump_symbols(output)
+ dump_sections(output)
+ output.write("</examples>\n")
+ output.close()
+ dump_Makefile()
+
--- /dev/null
+/**
+ * section: Informations
+ * synopsis: Extract informations about Xen domain 0
+ * purpose: Demonstrate the basic use of the library to connect to the
+ * hypervisor and extract domain informations.
+ * usage: info1
+ * test: info1
+ * author: Daniel Veillard
+ * copy: see Copyright for the status of this software.
+ */
+
+#include <stdio.h>
+#include <libvir.h>
+
+/**
+ * getDomainInfo:
+ * @id: the id of the domain
+ *
+ * extract the domain 0 informations
+ */
+static void
+getDomainInfo(int id) {
+ virConnectPtr conn = NULL; /* the hypervisor connection */
+ virDomainPtr dom = NULL; /* the domain being checked */
+ virDomainInfo info; /* the informations being fetched */
+ int ret;
+
+ /* NULL means connect to local Xen hypervisor */
+ conn = virConnectOpenReadOnly(NULL);
+ if (conn == NULL) {
+ fprintf(stderr, "Failed to connect to hypervisor\n");
+ goto error;
+ }
+
+ /* Find the domain of the given id */
+ dom = virDomainLookupByID(conn, id);
+ if (dom == NULL) {
+ fprintf(stderr, "Failed to find Domain %d\n", id);
+ goto error;
+ }
+
+ /* Get the informations */
+ ret = virDomainGetInfo(dom, &info);
+ if (ret < 0) {
+ fprintf(stderr, "Failed to get informations for Domain %d\n", id);
+ goto error;
+ }
+
+ printf("Domains %d: %d CPUs\n", id, info.nrVirtCpu);
+
+error:
+ if (dom != NULL)
+ virDomainFree(dom);
+ if (conn != NULL)
+ virConnectClose(conn);
+}
+
+int main(int argc, char **argv) {
+
+ getDomainInfo(0);
+
+ return(0);
+}
projects / thirdparty / libvirt.git / commitdiff
