ovsdb/ovsdb-idlc.1

   1 .\" -*- nroff -*-
   2 .TH ovsdb\-idlc 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
   3 .ds PN ovsdb\-idlc
   4 .
   5 .SH NAME
   6 ovsdb\-idlc \- Open vSwitch IDL (Interface Definition Language) compiler
   7 .
   8 .SH SYNOPSIS
   9 \fBovsdb\-idlc \fBannotate\fI schema annotations\fR
  10 .br
  11 \fBovsdb\-idlc \fBc\-idl\-header\fI idl\fR
  12 .br
  13 \fBovsdb\-idlc \fBc\-idl\-source\fI idl\fR
  14 .br
  15 \fBovsdb\-idlc --help\fR
  16 .br
  17 \fBovsdb\-idlc --version\fR
  18 .
  19 .SH DESCRIPTION
  20 The \fBovsdb\-idlc\fR program is a command-line tool for translating
  21 Open vSwitch database interface definition language (IDL) schemas into
  22 other formats.  It is used while building Open vSwitch, not at
  23 installation or configuration time.  Thus, it is not normally
  24 installed as part of Open vSwitch.
  25 .
  26 .PP
  27 The \fIidl\fR files used as input for most \fBovsdb\-idlc\fR commands
  28 have the same format as the OVSDB schemas, specified in the OVSDB
  29 specification, with a few additions:
  30 .
  31 .IP "\fB""\fBidlPrefix\fR"" member of <database-schema>"
  32 This member, which is required, specifies a string that is prefixed to
  33 top-level names in C bindings.  It should probably end in an
  34 underscore.
  35 .
  36 .IP "\fB""\fBidlHeader\fR"" member of <database-schema>"
  37 This member, which is required, specifies the name of the IDL header.
  38 It will be output on an \fB#include\fR line in the source file
  39 generated by the C bindings.  It should include the bracketing
  40 \fB""\fR or \fB<>\fR.
  41 .
  42 .IP "\fB""\fBkeyRefTable\fR"" member of <type>"
  43 A <type> whose \fBkey\fR is \fB"uuid"\fR may have an additional member
  44 named \fB"keyRefTable"\fR, whose value is a table name.  This
  45 expresses the constraint that keys of the given <type> are UUIDs that
  46 reference rows in the named table.  This allows the IDL to supply a
  47 structure pointer in place of a raw UUID in its marshalled version of
  48 the given type.
  49 .
  50 .IP "\fB""valueRefTable""\fR member of <type>"
  51 Analogous to \fB"keyRefTable"\fR in meaning and effect, except that it
  52 applies to the \fB"value"\fR member of the <type>.
  53 .SS "Commands"
  54 .IP "\fBannotate\fI schema annotations\fR"
  55 Reads \fIschema\fR, which should be a file in JSON format (ordinarily
  56 an OVSDB schema file), then reads and executes the Python syntax
  57 fragment in \fIannotations\fR.  The Python syntax fragment is passed
  58 the JSON object as a local variable named \fBs\fR.  It may modify this
  59 data in any way.  After the Python code returns, the object as
  60 modified is re-serialized as JSON on standard output.
  61 .
  62 .IP "\fBc\-idl\-header\fI idl\fR"
  63 Reads \fIidl\fR and prints on standard output a C header file that
  64 defines a structure for each table defined by the schema.
  65 .
  66 .IP "\fBc\-idl\-source\fI idl\fR"
  67 Reads \fIidl\fR and prints on standard output a C source file that
  68 implements C bindings for the database defined by the schema.
  69 .
  70 .IP "\fBdoc\fI idl\fR"
  71 Reads \fIidl\fR and prints on standard output a text file that
  72 documents the schema.  The output may have very long lines, so it
  73 makes sense to pipe it through, e.g. \fBfmt \-s\fR.
  74 .
  75 .SS "Options"
  76 .so lib/common.man
  77 .
  78 .SH "BUGS"
  79 \fBovsdb\-idlc\fR is more lenient about the format of OVSDB schemas
  80 than other OVSDB tools.  It may successfully parse schemas that, e.g.,
  81 \fBovsdb\-tool\fR rejects.
  82 .
  83 .SH "SEE ALSO"
  84 The OVSDB specification.