ovsdb-doc: Distinguish hyphens and minus signs in nroff output.
[sliver-openvswitch.git] / 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 .SS "Commands"
43 .IP "\fBannotate\fI schema annotations\fR"
44 Reads \fIschema\fR, which should be a file in JSON format (ordinarily
45 an OVSDB schema file), then reads and executes the Python syntax
46 fragment in \fIannotations\fR.  The Python syntax fragment is passed
47 the JSON object as a local variable named \fBs\fR.  It may modify this
48 data in any way.  After the Python code returns, the object as
49 modified is re-serialized as JSON on standard output.
50 .
51 .IP "\fBc\-idl\-header\fI idl\fR"
52 Reads \fIidl\fR and prints on standard output a C header file that
53 defines a structure for each table defined by the schema.
54 .
55 .IP "\fBc\-idl\-source\fI idl\fR"
56 Reads \fIidl\fR and prints on standard output a C source file that
57 implements C bindings for the database defined by the schema.
58 .
59 .IP "\fBdoc\fI idl\fR"
60 Reads \fIidl\fR and prints on standard output a text file that
61 documents the schema.  The output may have very long lines, so it
62 makes sense to pipe it through, e.g. \fBfmt \-s\fR.
63 .
64 .SS "Options"
65 .so lib/common.man
66 .
67 .SH "BUGS"
68 \fBovsdb\-idlc\fR is more lenient about the format of OVSDB schemas
69 than other OVSDB tools.  It may successfully parse schemas that, e.g.,
70 \fBovsdb\-tool\fR rejects.
71 .
72 .SH "SEE ALSO"
73 The OVSDB specification.