* configure.in docs/examples/*: starting to add examples. the XSLT

still need to be fixed for web site
Daniel
This commit is contained in:
Daniel Veillard 2006-01-31 18:13:27 +00:00
parent b6022c2ad3
commit 7871d455b3
7 changed files with 621 additions and 0 deletions

View File

@ -1,3 +1,8 @@
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

View File

@ -191,4 +191,5 @@ fi
rm -f COPYING
AC_OUTPUT(Makefile src/Makefile include/Makefile docs/Makefile \
docs/examples/Makefile \
libvir.pc libvir.spec include/libvir.h python/Makefile)

34
docs/examples/Makefile.am Normal file
View File

@ -0,0 +1,34 @@
# 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)

View File

@ -0,0 +1,46 @@
<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>

174
docs/examples/examples.xsl Normal file
View File

@ -0,0 +1,174 @@
<?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(., '/'), '&gt;')"/>
<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>

298
docs/examples/index.py Executable file
View File

@ -0,0 +1,298 @@
#!/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()

63
docs/examples/info1.c Normal file
View File

@ -0,0 +1,63 @@
/**
* 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);
}