caf1b633fe
This commit adds a documentation for the KIWI XML description. In contrast to the former auto generated code from the XML schema this document can now finally be used as a reference. Along with that new chapter all auto generated and static html content as been deleted. Also all helper scripts around the proprietary oxygen tool and our schema doc generator has been deleted. Auto generating this information does not lead to a reference guide people can really work with. As a consequence to these changes this commit also includes some changes of the structure such that no information written by other people in the past gets lost. This Fixes #1421 and Fixes #1474
148 lines
4.5 KiB
ReStructuredText
148 lines
4.5 KiB
ReStructuredText
Extending {kiwi} with Custom Operations
|
|
========================================
|
|
|
|
.. note:: **Abstract**
|
|
|
|
Users building images with {kiwi} need to implement their
|
|
own infrastructure if the image description does not
|
|
provide a way to embed custom information which is
|
|
outside of the scope of the general schema as it is
|
|
provided by {kiwi} today.
|
|
|
|
This document describes how to create an extension plugin
|
|
for the {kiwi} schema to add and validate additional information
|
|
in the {kiwi} image description.
|
|
|
|
Such a schema extension can be used in an additional {kiwi}
|
|
task plugin to provide a new subcommand for {kiwi}.
|
|
As of today there is no other plugin interface except for
|
|
providing additional {kiwi} commands implemented.
|
|
|
|
Depending on the demand for custom plugins, the interface
|
|
to hook in code into other parts of the {kiwi} processing
|
|
needs to be extended.
|
|
|
|
This description applies for version |version|.
|
|
|
|
The <extension> Section
|
|
-----------------------
|
|
|
|
The main {kiwi} schema supports an extension section which allows
|
|
to specify any XML structure and attributes as long as they are
|
|
connected to a namespace. According to this any custom XML
|
|
structure can be implemented like the following example shows:
|
|
|
|
.. code:: bash
|
|
|
|
<image>
|
|
...
|
|
<extension xmlns:my_plugin="http://www.my_plugin.com">
|
|
<my_plugin:my_feature>
|
|
<my_plugin:title name="cool stuff"/>
|
|
</my_plugin:my_feature>
|
|
</extension>
|
|
</image>
|
|
|
|
* Any toplevel namespace must exist only once
|
|
* Multiple different toplevel namespaces are allowed,
|
|
e.g my_plugin_a, my_plugin_b
|
|
|
|
RELAX NG Schema for the Extension
|
|
---------------------------------
|
|
|
|
If an extension section is found, {kiwi} looks up its namespace and asks
|
|
the main XML catalog for the schema file to validate the extension data.
|
|
The schema file must be a RELAX NG schema in the .rng format. We recommend
|
|
to place the schema as :file:`/usr/share/xml/kiwi/my_plugin.rng`
|
|
|
|
For the above example the RELAX NG Schema in the compressed format
|
|
:file:`my_plugin.rnc` would look like this:
|
|
|
|
.. there is no rnc syntax highlighting, try cpp
|
|
.. code:: cpp
|
|
|
|
namespace my_plugin = "http://www.my_plugin.com"
|
|
|
|
start =
|
|
k.my_feature
|
|
|
|
div {
|
|
k.my_feature.attlist = empty
|
|
k.my_feature =
|
|
element my_plugin:my_feature {
|
|
k.my_feature.attlist &
|
|
k.title
|
|
}
|
|
}
|
|
|
|
div {
|
|
k.title.name.attribute =
|
|
attribute name { text }
|
|
k.title.attlist = k.title.name.attribute
|
|
k.title =
|
|
element my_plugin:title {
|
|
k.title.attlist
|
|
}
|
|
}
|
|
|
|
In order to convert this schema to the .rng format just call:
|
|
|
|
.. code:: bash
|
|
|
|
$ trang -I rnc -O rng my_plugin.rnc /usr/share/xml/kiwi/my_plugin.rng
|
|
|
|
Extension Schema in XML catalog
|
|
-------------------------------
|
|
|
|
As mentioned above the mapping from the extension namespace to the
|
|
correct RELAX NG schema file is handled by a XML catalog file. The
|
|
XML catalog for the example use here looks like this:
|
|
|
|
.. code:: bash
|
|
|
|
<?xml version="1.0"?>
|
|
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
|
|
<system
|
|
systemId="http://www.my_plugin.com"
|
|
uri="file:////usr/share/xml/kiwi/my_plugin.rng"/>
|
|
</catalog>
|
|
|
|
For resolving the catalog {kiwi} uses the :command:`xmlcatalog` command
|
|
and the main XML catalog from the system which is :file:`/etc/xml/catalog`.
|
|
|
|
.. note::
|
|
|
|
It depends on the distribution and its version how the main catalog
|
|
gets informed about the existence of the {kiwi} extension catalog file.
|
|
Please consult the distribution manual about adding XML catalogs.
|
|
|
|
If the following command provides the information to the correct
|
|
RELAX NG schema file you are ready for a first test:
|
|
|
|
.. code:: bash
|
|
|
|
$ xmlcatalog /etc/xml/catalog http://www.my_plugin.com
|
|
|
|
Using the Extension
|
|
-------------------
|
|
|
|
In order to test your extension place the example extension section
|
|
from the beginning of this document into one of your image description's
|
|
:file:`config.xml` file
|
|
|
|
The following example will read the name attribute from the title
|
|
section of the my_feature root element and prints it:
|
|
|
|
.. code:: python
|
|
|
|
import logging
|
|
|
|
from kiwi.xml_description import XMLDescription
|
|
|
|
description = XMLDescription('path/to/kiwi/XML/config.xml')
|
|
description.load()
|
|
|
|
my_plugin = description.get_extension_xml_data('my_plugin')
|
|
|
|
print(my_plugin.getroot()[0].get('name'))
|