From 7871d455b3d94fb59acba532504483f24db6ab64 Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Tue, 31 Jan 2006 18:13:27 +0000 Subject: [PATCH] * configure.in docs/examples/*: starting to add examples. the XSLT still need to be fixed for web site Daniel --- ChangeLog | 5 + configure.in | 1 + docs/examples/Makefile.am | 34 +++++ docs/examples/examples.xml | 46 ++++++ docs/examples/examples.xsl | 174 ++++++++++++++++++++++ docs/examples/index.py | 298 +++++++++++++++++++++++++++++++++++++ docs/examples/info1.c | 63 ++++++++ 7 files changed, 621 insertions(+) create mode 100644 docs/examples/Makefile.am create mode 100644 docs/examples/examples.xml create mode 100644 docs/examples/examples.xsl create mode 100755 docs/examples/index.py create mode 100644 docs/examples/info1.c diff --git a/ChangeLog b/ChangeLog index ac2af04b07..b9fd2cefe5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Jan 31 19:12:19 CET 2006 Daniel Veillard + + * 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 * python/*: update of the python bindings, fix names, add diff --git a/configure.in b/configure.in index 53a60911b3..835b8c631a 100644 --- a/configure.in +++ b/configure.in @@ -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) diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am new file mode 100644 index 0000000000..cca0d2a125 --- /dev/null +++ b/docs/examples/Makefile.am @@ -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) + + diff --git a/docs/examples/examples.xml b/docs/examples/examples.xml new file mode 100644 index 0000000000..ab0e51fb61 --- /dev/null +++ b/docs/examples/examples.xml @@ -0,0 +1,46 @@ + + + Extract informations about Xen domain 0 + Demonstrate the basic use of the library to connect to the hypervisor and extract domain informations. + info1 + info1 + Daniel Veillard + see Copyright for the status of this software. +

Informations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +

+ + diff --git a/docs/examples/examples.xsl b/docs/examples/examples.xsl new file mode 100644 index 0000000000..74aaaa20cb --- /dev/null +++ b/docs/examples/examples.xsl @@ -0,0 +1,174 @@ + + + + + + ../ + Examples Menu + + + +

Examples

XML Guidelines

+ + + + + +

+ + + + + + +

line : Type

from

+ + + + + + +

line : Function

from

+ + + + + + +

line : Macro

from

+ + + + +

:

Includes:

+ +

Uses:

+ + +

Usage:

Author:

+ + + +

+ + +

+ + + +

The examples are stored per section depending on the main focus + of the example:

+ + +

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 make +install step or when installing the libxml2 development package:

gcc -o example `xml2-config --cflags` example.c `xml2-config --libs`

+ + + + + +

Examples

+ + + + + + Libxml2 set of examples + + + + + + + + + + + + + + + + +

+ + + + + +

+ +

+ + + + +

+ + +

Daniel Veillard

+ + + + + + diff --git a/docs/examples/index.py b/docs/examples/index.py new file mode 100755 index 0000000000..7a1632c748 --- /dev/null +++ b/docs/examples/index.py @@ -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(" \n" % filename) + try: + synopsis = info['synopsis'] + output.write(" %s\n" % escape(synopsis)); + except: + print "Example %s lacks a synopsis description" % (filename) + try: + purpose = info['purpose'] + output.write(" %s\n" % escape(purpose)); + except: + print "Example %s lacks a purpose description" % (filename) + try: + usage = info['usage'] + output.write(" %s\n" % escape(usage)); + except: + print "Example %s lacks an usage description" % (filename) + try: + test = info['test'] + output.write(" %s\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(" %s\n" % escape(author)); + except: + print "Example %s lacks an author description" % (filename) + try: + copy = info['copy'] + output.write(" %s\n" % escape(copy)); + except: + print "Example %s lacks a copyright description" % (filename) + try: + section = info['section'] + output.write("

\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(" %s\n" % ( + escape(topic), escape(str))) + output.write(" \n") + for include in idx.includes.keys(): + if include.find("libxml") != -1: + output.write(" %s\n" % (escape(include))) + output.write(" \n") + output.write(" \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(" \n") + output.write(" \n") + + return idx + +def dump_symbols(output): + global symbols + + output.write(" \n") + keys = symbols.keys() + keys.sort() + for symbol in keys: + output.write(" \n" % (symbol)) + info = symbols[symbol] + i = 1 + while i < len(info): + output.write(" \n" % (info[i])) + i = i + 1 + output.write(" \n") + output.write(" \n") + +def dump_sections(output): + global sections + + output.write(" \n") + keys = sections.keys() + keys.sort() + for section in keys: + output.write("

\n" % (section)) + info = sections[section] + i = 0 + while i < len(info): + output.write(" \n" % (info[i])) + i = i + 1 + output.write("

\n") + output.write(" \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("\n") + + for file in glob.glob('*.c'): + parse(file, output) + examples.append(file[:-2]) + + dump_symbols(output) + dump_sections(output) + output.write("\n") + output.close() + dump_Makefile() + diff --git a/docs/examples/info1.c b/docs/examples/info1.c new file mode 100644 index 0000000000..be635bfc41 --- /dev/null +++ b/docs/examples/info1.c @@ -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 +#include + +/** + * 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); +} -- 2.47.2