Commit Graph

115 Commits

Author SHA1 Message Date
Andrea Bolognani
f34fdd5ab6 python: Don't hardcode interpreter path
This is particularly useful on operating systems that don't ship
Python as part of the base system (eg. FreeBSD) while still working
just as well as it did before on Linux.

While at it, make it explicit that our scripts are only going to
work with Python 2, and remove the usage of unbuffered I/O, which
as far as I can tell has no effect on the output files.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
2017-09-19 16:04:53 +02:00
Michal Privoznik
6efdd94dbc apibuild.py: Handle enum comments properly
After f4cb85c6af we only have two options for placing enum
values descriptions. It's either:

    typedef enum {
        /* Some long description. Therefore it's placed before
         * the value. */
        VIR_ENUM_A_VAL = 1,
    } virEnumA;

or:

    typedef enum {
        VIR_ENUM_B_VAL = 1, /* Some short description */
    } virEnumB;

However, our apibuild.py script is not able to deal with the
former one. It messes up comments. To fix this couple of things
needs to be done:

a) DO NOT reset self.comment in parseEnumBlock(). This is a
result from our tokenizer. Upon calling token() if it finds a
comment block it stores it in self.comment and returns the next
token (which is not comment). Therefore, if we reset self.comment
we might lose the first comment in the enum block.

b) we need a variable to track if the current enum block uses
value descriptions before or after values. That is if it's type
virEnumA or virEnumB. Depending on that, it we're dealing with
virEnumA type and the current token is a comma ',' we can add the
value into the list as we already have everything needed:
comment, name and value.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2017-07-24 12:03:33 +02:00
Guido Günther
214c226f9e Unbreak rebuilding docs with release tarballs
Release tarballs ship the include/libvirt/libvirt-common.h.

when srcdir != builddir we end up including libvirt-common.h twice: from
$top_srcdir/include/libvirt-common.h and from
$builddir/include/libvirt-common.h leading to

  function virTypedParamsGetUInt from /tmp/buildd/libvirt-2.4.0/debian/build/docs/../include/libvirt/libvirt-common.h redeclared in /tmp/buildd/libvirt-2.4.0/docs/../include/libvirt/libvirt-common.h
  function virTypedParamsAddBoolean from /tmp/buildd/libvirt-2.4.0/debian/build/docs/../include/libvirt/libvirt-common.h redeclared in /tmp/buildd/libvirt-2.4.0/docs/../include/libvirt/libvirt-common.h
   …

Only add the builddir to the search list if there is no pregenerated
libvirt-common.h.

Reuse the existing check that predates the libvirt.h → libvirt-common.h
split and that probably was meant for exactly that.

References: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=842452
2016-11-07 20:04:28 +01:00
Ján Tomko
ad9e72f5fa hvsupport: use a regex instead of XML::XPath
When generating the hvsupport.html.in file, we parse the -api.xml
files generated by apibuild.py to know in which HTML file the API
function is.

Doing an XPath query for every single 'function' element in the
file is inefficient.

Since the XML file is generated by another of our build scripts
(apibuild.py, using Python's standard 'output.write' XML library),
just find the function name->file mapping by a regex upfront.

Also add a note about this next to the line that generates it
in apibuild.py and do not check if XML::XPath is installed in
bootstrap since we no longer use it.
2016-07-19 18:42:44 +02:00
Michal Privoznik
3864d86385 apibuild: Substitute only pure number tokens
In 38df47c9af I've tried to prepare our apibuild.py script for
change made in 0628f3498c (1U << 31). What I've done in the
former commit was to replace \d+U in parsed tokens with \d.
Problem was, my regular expression there was not quite right as
it also translated VIR_123U_VAL into VIR_123_VAL.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-05-30 15:38:07 +02:00
Michal Privoznik
38df47c9af docs: Teach apibuild to deal with (1U << 31) too
The apibuild script is a terrifying beast that parses some source
files of ours and produces an XML representation of them. When it
comes to parsing enums we have in some header files, it tries to
be clever and detect a value that an enum member has (or if it is
an alias for a different member). Whilst doing that it has to
deal with values we give to the members in many formats. At some
places we just pass the value in decimal:

    VIR_DOMAIN_BLOCK_JOB_TYPE_PULL = 1,

in other places, we use the aliasing:

    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE = VIR_CONNECT_LIST_DOMAINS_ACTIVE,

and in other places bitwise shifts are used:

    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1 << 31, /* enforce requested stats */

The script tries to parse all of these resulting in the following
tokens: "1", "VIR_CONNECT_LIST_DOMAINS_ACTIVE", "1<<31"; Then, the
script tries to turn these into integers using python's eval()
function. This function succeeds on the first and the last
tokens. But, if we were to modify the last example so that it's
of the following form:

    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1U << 31, /* enforce requested stats */

the token representing enum's member value will then be "1U<<31".
So our parsing is good. Unfortunately, python is not aware of the
difference between signed and unsigned C types, therefore eval()
fails over this token and the parser falls back thinking it's an
alias to another enum member. Well it's not.

The solution is to transform [0-9]U into [0-9] as for our
purposes here it's the same thing.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-05-28 13:21:43 +02:00
Andrea Bolognani
cb44737165 apibuild: Fix method call 2016-04-26 09:20:12 +02:00
Andrea Bolognani
4a98ebb07c apibuild: Introduce app class
All top-level functions have been moved to this class.

On top of that, the app.warning() method has been defined,
so that calls to it - already present in rebuild() - can
actually succeed.
2016-04-26 09:20:12 +02:00
Andrea Bolognani
ccaceab7bd apibuild: Add index.warning() method
This method is used in eg. index.merge(), but is not defined
anywhere. The implementation has been copied from docBuilder.
2016-04-26 09:20:12 +02:00
Peter Krempa
d195cffa2e docs: apibuild: Fix VPATH build
libvirt-common.h is generated into builddir/include/libvirt. apibuild.py
only operated on srcdir/inlcude/libvirt. With VPATH build
srcdir/docs/libvirt-libvirt-common.html would not get generated and make
RPM failed.
2016-04-25 08:49:30 +02:00
Peter Krempa
2f745b63fd docs: apibuild: Fix for python 2.6
Ancient python didn't like the new list added in 99283874. Convert it to
a dict.
2016-04-22 10:14:13 +02:00
Peter Krempa
9928387473 api: Generate docs for libvirt-common.h
Since commit f5d9c5d00c moved the virTypedParam stuff into
libvirt-common we did not generate any docs for them and neither did we
populate them into libvirt-api.xml. This broke the sanity check in
libvirt python. Fix it by generating docs for libvirt-common.h too.
2016-04-21 15:39:08 +02:00
Peter Krempa
a253396a47 apibuild: Allow completely skipping certain macros
Some macros don't make sense to be documented at all. Add infrastructure
to the web/api generator and add VIR_DEPRECATED and VIR_EXPORT_VAR as
macros we should not document.
2016-04-21 15:39:08 +02:00
Jiri Denemark
9d0a2af6c2 Introduce virErrorCopyNew
A helper function for copying error objects.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2015-07-10 11:47:13 +02:00
Martin Kletzander
878bf2a3c9 Add XML files with admin API specification
No online docs are build from it since it doesn't really fit into our
document structure and new page will need to be created for it, but this
is at least a heads-up commit for easier parsing in order to build some
documentation (or python bindings) later on.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
2015-06-16 13:46:20 +02:00
Jiri Denemark
b6a2639bd2 apibuild: Generate macro/@string attribute
If a macro has a string value, the @string attribute will contain the
value. Otherwise @string attribute will be missing.

For example, the following macro definition from libvirt-domain.h:

 /**
  * VIR_MIGRATE_PARAM_URI:
  * ...
  */
 # define VIR_MIGRATE_PARAM_URI               "migrate_uri"

will result in

 <macro name='VIR_MIGRATE_PARAM_URI' file='libvirt-domain' string='migrate_uri'>
   <info><![CDATA[...]]></info>
 </macro>

https://bugzilla.redhat.com/show_bug.cgi?id=1229199

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2015-06-11 13:52:52 +02:00
Jiri Denemark
ee3b344d60 apibuild: Fix indentation
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2015-06-11 13:52:52 +02:00
Daniel P. Berrange
64702ac367 Fix handling of whitespae in preprocessor macros for API generator
The apibuild.py script did not handle whitespace in preprocessor
macros, so it failed to detect constants declared with '# define'
instead of '#define'. Since we now correctly indent our public
header files, we have silently lost all constants from
libvirt-api.xml. This also caused us to not detect formatting
errors in constant docs
2014-12-04 15:00:30 +00:00
Daniel P. Berrange
47fb613873 Fix API docs for header file re-organization
The API docs generators were broken by the header file
re-organization. Specifically

 * html/libvirt-libvirt.html was empty (and should be deleted)
 * Makefile.am didn't install html/libvirt-libvirt-*.html
 * hvsupport.html was mostly empty
 * sitemap.html.in didn't list the new html/*.html files
2014-11-13 10:20:26 +00:00
Daniel P. Berrange
bcec07b9f0 Move virConnect related APIs out of libvirt.h.in
Create a new libvirt-host.h file to hold the public
API definitions for the virConnect type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:23:51 +01:00
Daniel P. Berrange
653a5e4939 Move virDomain related APIs out of libvirt.h.in
Create a new libvirt-domain.h file to hold the public
API definitions for the virDomain type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:23:32 +01:00
Daniel P. Berrange
6d9c5f3735 Move virEvent related APIs out of libvirt.h.in
Create a new libvirt-event.h file to hold the public
API definitions for the virEvent type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:23:17 +01:00
Daniel P. Berrange
c9456e1a7f Move virStoragePool/Vol related APIs out of libvirt.h.in
Create a new libvirt-storage.h file to hold the public
API definitions for the virStorage/Vol type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:22:57 +01:00
Daniel P. Berrange
2805ddb29a Move virStream related APIs out of libvirt.h.in
Create a new libvirt-stream.h file to hold the public
API definitions for the virStream type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Note the definition of virStreamPtr is not moved, since that
must be declared early for all other libvirt APIs to be able
to reference it.
2014-10-24 17:22:38 +01:00
Daniel P. Berrange
75ff42fe7c Move virSecret related APIs out of libvirt.h.in
Create a new libvirt-secret.h file to hold the public
API definitions for the virSecret type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:22:20 +01:00
Daniel P. Berrange
0147d6b88f Move virNodeDevice related APIs out of libvirt.h.in
Create a new libvirt-nodedev.h file to hold the public
API definitions for the virNodeDevice type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:21:59 +01:00
Daniel P. Berrange
40741984fc Move virNWFilter related APIs out of libvirt.h.in
Create a new libvirt-nwfilter.h file to hold the public
API definitions for the virNWFilter type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:21:34 +01:00
Daniel P. Berrange
fc964bfc27 Move virInterface related APIs out of libvirt.h.in
Create a new libvirt-interface.h file to hold the public
API definitions for the virInterface type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:21:15 +01:00
Daniel P. Berrange
5c9789d2d1 Move virNetwork related APIs out of libvirt.h.in
Create a new libvirt-network.h file to hold the public
API definitions for the virNetwork type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:20:52 +01:00
Daniel P. Berrange
84783d9d1c Move virDomainSnapshot related APIs out of libvirt.h.in
Create a new libvirt-domain-snapshot.h file to hold the public
API definitions for the virDomainSnapshot type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:20:20 +01:00
Daniel P. Berrange
0399b188ac Move virConnect/virNode related APIs out of libvirt.c
Introduce a src/libvirt-host.c file to hold all the
methods related to the virConnect type.
2014-10-24 16:59:58 +01:00
Daniel P. Berrange
67c08fccdc Move virDomain related APIs out of libvirt.c
Introduce a src/libvirt-domain.c file to hold all the
methods related to the virDomain type.
2014-10-24 16:59:56 +01:00
Daniel P. Berrange
8444015446 Make virTypedParameterValidateSet non-static
The virTypedParameterValidateSet method will need to be used
from several libvirt-*.c files so must be non-static

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2014-10-24 16:54:48 +01:00
Daniel P. Berrange
36b5d006c1 Move virStorage{Pool,Vol} related APIs out of libvirt.c
Introduce a src/libvirt-storage.c file to hold all the
methods related to the virStorage{Pool,Vol} types.
2014-10-24 16:49:10 +01:00
Daniel P. Berrange
0c94d78bb5 Move virStream related APIs out of libvirt.c
Introduce a src/libvirt-stream.c file to hold all the
methods related to the virStream type.
2014-10-24 16:42:49 +01:00
Daniel P. Berrange
d83ccd6e61 Move virSecret related APIs out of libvirt.c
Introduce a src/libvirt-secret.c file to hold all the
methods related to the virSecret type.
2014-10-24 16:39:05 +01:00
Daniel P. Berrange
e33ed8cdfe Move virNodeDevice related APIs out of libvirt.c
Introduce a src/libvirt-nodedev.c file to hold all the
methods related to the virNodeDevice type.
2014-10-24 16:26:55 +01:00
Daniel P. Berrange
35ed98755f Move virNWFilter related APIs out of libvirt.c
Introduce a src/libvirt-nwfilter.c file to hold all the
methods related to the virNWFilter type.
2014-10-24 16:15:46 +01:00
Daniel P. Berrange
6e01ef230b Move virInterface related APIs out of libvirt.c
Introduce a src/libvirt-interface.c file to hold all the
methods related to the virInterface type.
2014-10-24 16:08:28 +01:00
Daniel P. Berrange
4e00b6bc6a Move virNetwork related APIs out of libvirt.c
Introduce a src/libvirt-network.c file to hold all the
methods related to the virNetwork type.
2014-10-24 16:00:21 +01:00
Daniel P. Berrange
62cf32d0c9 Move virDomainSnapshot related APIs out of libvirt.c
Introduce a src/libvirt-domain-snapshot.c file to hold all the
methods related to the virDomainSnapshot type.
2014-10-24 15:59:22 +01:00
Eric Blake
9b291bbe20 docs: publish correct enum values
We publish libvirt-api.xml for others to use, and in fact, the
libvirt-python bindings use it to generate python constants that
correspond to our enum values.  However, we had an off-by-one bug
that any enum that relied on C's rules for implicit initialization
of the first enum member to 0 got listed in the xml as having a
value of 1 (and all later members of the enum were equally
botched).

The fix is simple - since we add one to the previous value when
encountering an enum without an initializer, the previous value
must start at -1 so that the first enum member is assigned 0.

The python generator code has had the off-by-one ever since DV
first wrote it years ago, but most of our public enums were immune
because they had an explicit = 0 initializer.  The only affected
enums are:
- virDomainEventGraphicsAddressType (such as
VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV4), since commit 987e31e
(libvirt v0.8.0)
- virDomainCoreDumpFormat (such as VIR_DOMAIN_CORE_DUMP_FORMAT_RAW),
since commit 9fbaff0 (libvirt v1.2.3)
- virIPAddrType (such as VIR_IP_ADDR_TYPE_IPV4), since commit
03e0e79 (not yet released)

Thanks to Nehal J Wani for reporting the problem on IRC, and
for helping me zero in on the culprit function.

* docs/apibuild.py (CParser.parseEnumBlock): Fix implicit enum
values.

Signed-off-by: Eric Blake <eblake@redhat.com>
2014-06-26 15:25:05 -06:00
Michal Privoznik
0f1a0fff0e apibuild: Disallow 'returns' return description
Our documentation generator is a bit messy, to say the least. For
instance, the description to return values of a function is
searched within C comment. Currently, all lines that start with
'returns' or 'Returns' are viewed as return value description.
However, there are some valid uses where the 'returns' word is in
the middle of a sentence describing function behavior not the
return value. And there are no places where 'returns' is used to
describe return values.  For instance:
virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and
virDomainGetDiskErrors. This leads to HTML documemtation being
generated incorrectly.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2014-05-13 08:51:11 +02:00
Daniel P. Berrange
2835c1e730 Add virLogSource variables to all source files
Any source file which calls the logging APIs now needs
to have a VIR_LOG_INIT("source.name") declaration at
the start of the file. This provides a static variable
of the virLogSource type.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2014-03-18 14:29:22 +00:00
Claudio Bley
2a40951148 Test for object identity when checking for None in Python
Consistently use "is" or "is not" to compare variables to None,
because doing so is preferrable, as per PEP 8
(http://www.python.org/dev/peps/pep-0008/#programming-recommendations):

> Comparisons to singletons like None should always be done with is or
> is not, never the equality operators.
2013-08-23 08:12:26 +02:00
Yuri Chornoivan
5b4c035b08 Fix minor typos in messages and docs
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-30 07:07:33 -06:00
Jiri Denemark
c0762b6518 New internal migration APIs with extensible parameters
This patch implements extensible variants of all internal migration APIs
used for v3 migration.
2013-06-25 01:13:16 +02:00
Jiri Denemark
d0d5acb511 Introduce virTypedParamsCopy internal API 2013-06-25 00:38:25 +02:00
Jiri Denemark
fefb0d5464 Introduce VIR_TYPED_PARAMS_DEBUG macro for dumping typed params
All APIs that take typed parameters are only using params address in
their entry point debug messages. With the new VIR_TYPED_PARAMS_DEBUG
macro, all functions can easily log all individual typed parameters
passed to them.
2013-06-25 00:38:24 +02:00
Jiri Denemark
637a7c865a Introduce virTypedParamsCheck internal API
This API is useful for checking whether only a specific subset of
supported typed parameters were passed.
2013-06-25 00:38:24 +02:00