Architecture Overview

Introduction

libvirt-node generates an interface and libvirt bindings from libvirt's exported api xml (eg. libvirt-api.xml).

In this document we a high level view of the processes involved.

Overview

1. Entry script Main
2. Using the Parser to get a JSON representation of the xml api, Main initialises the dispatcher
3. Dispatcher assigns each entity to a file descriptor.
4. Descriptor files emit an event for the required content.
5. Generators handle events emitted for content.
6. Dispatcher closes the descriptors which ultimately write to disk.

Main

main.js is the entry script for our generator.

• performs any filesystem setup
• bootstraps the generators
• initialises dispatchers to process the parsed APIs
• Defines the files to be generated:

  • const files = [
      "libvirt",
      "libvirt-connect",
      "libvirt-domain",
      "libvirt-domain-snapshot",
      "libvirt-interface",
      "libvirt-network",
      "libvirt-nodedev",
      "libvirt-nwfilter",
      "libvirt-secret",
      "libvirt-storage-pool",
      "libvirt-storage-vol",
      "libvirt-stream",
    ];
    

Parser

parser.js parses the libvirt api xmls

• uses xml2js to convert libvirt apis to json
• extracts functions and enums into separate objects
• performs any preliminary modifications to the API (eg. adds interface name)

Dispatcher

dispatcher.js dispatches api entities (eg. functions/enums) to the respective descriptors.

• Initialises the a file descriptor per file
• Assigns API entries to the respective descriptor
• Closes the descriptors

Descriptor

descriptors.js handles file contents and configuration

There are four types of descriptors:

• ImplDescriptor: Represents a binding implementation file
• HeaderDescriptor: Represents a binding header file
• WrapperDescriptor: Represents an interface file
• ExportDescriptor: Represents an exports binding implementation file

Responsibilities:

• Defines the output file attributes (eg. structure, name, location, etc.)
• Emits an event to retrieve the content for its api entity
• Flushes the data to a file upon closing the descriptor

Emitters

emitters.js is a "custom" event emitter.

There are four types of emitters:

• impl_emitter
• header_emitter
• wrapper_emitter
• export_emitter

Special properties:

• Allows RegExp names
• Callback results returned to the emitter (synchronous)
• Provides a default handler registration
• Throws if event is unhandled

Generators

generators/ contains event handlers that return the actual generated code

There is a default handler for each emitter, plus any additional overrides.