strepsirrhini/office-gobmx
9
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
office-gobmx/unoidl/README
Stephan Bergmann 6db34b6b33 Directly build UNOIDL .rdb files from .idl files 
...via unoidl-write and the new source-format registry provicers, instead of
using idlc to produce .urd files, regmerge to merge them into legacy .rdb files,
and unoidl-write to translate those to new UNOIDL .rdb files.

gb_UnoApi and gb_InternalUnoApi ctors take an additional argument now that is
the path (below $(SRCDIR)) of the source-format registry from which to obtain
UNOIDL entity definitions.  It can either be an .idl file (in which case no
*_add_idlfiles calls should be used and the resulting .rdb will contain all the
entities from that one .idl file; used in some tests to conveniently define all
test-specific entities in a single file) or a directory denoting the root of an
.idl file tree (in which case *_add_idlfiles calls specify the entites to
include in the resulting .idl file).  (In the first case, the generated .rdb
file needs to depend on that single .idl file, so the gb_UnoApiTarget ctor
contains a dependency on that additional argument, which happens, as a side
effect, to trigger rebuilds in the second, tree-based case when addition/removal
of .idl files in the tree causes updates of directory time-stamps.)

UnoApiPartTarget and all the dependency-tracking logic based on .urd files in
solenv/gbuild/UnoApiTarget.mk is gone.  Generation of an .rdb file now depends
on its source registry (see previous paragraph) and all the .idl files specified
with *_add_idlfiles (in the second, tree-based case above).

A consequence of that is that gb_UnoApi_add_idlfile, -_nohdl, and -_noheader all
do the same now.  I left them in for now anyway, maybe they become relevant
again when the use of cppumaker is changed to read directly from a source-format
registry instead of going via a .rdb registry.

The legacy tools idlc, regcompare, regmerge, and regview are still contained in
the URE or SDK for now.

cb344cd59e "Revert 'Looks like idlc resolved
typedefs inside sequence<...>'" is re-reverted as now "the current offapi.rdb is
generated via unoidl-write instead of idlc."

Change-Id: I3d9d92f17326bc9f49dd934c85aab6a17951d06d
2013-09-19 15:50:04 +02:00

283 lines
9.4 KiB
Text
Raw Blame History

Support for UNOIDL registry formats
Library_unoidl contains the unoidl::Manager and unoidl::Provider implementations
for the following registry formats:
* The new UNOIDL binary types.rdb format.
* The old legacy binary types.rdb format (based on modules [[store]] and
[[registry]]).
* A source-file format, reading (multiple) UNOIDL entity definitions directly
from a single .idl source file.
* A source-tree format, reading UNOIDL entity definitions directly from a tree
of .idl source files rooted at a given directory. (Where an entity named
foo.bar.Baz is expected in a file named foo/bar/Baz.idl within that tree.)
(While .idl files still contain #include directives for legacy idlc, the source-
based formats ignore any preprocessing directives starting with "#" in the .idl
files.) unoidl::loadProvider transparently detects the registry format for a
given URI and instantiates the corresponding provider implementation.
Executable_unoidl-write is a helper tool to convert from any of the registry
formats to the UNOIDL format. It is used at build-time to compile UNOIDL format
.rdb files (that are used at build-time only, or included in installation sets
in URE or program/types/ or as part of bundled extensions that are created
during the build and not merely included as pre-built .oxt files) from source
.idl files. (The SDK still uses idlc and generates legacy format .rdb files for
now.)
Executable_unoidl-read is a helper tool to convert from any of the registry
formats to the source-file format. It can be used manually after a LibreOffice
version update to create new reference registries for Executable_unoidl-check.
Executable_unoidl-check is a helper tool to check that one registry is
backwards-compatible with another registry. It is used at build-time to detect
inadvertent breakage of the udkapi and offapi APIs.
== Specification of the new UNOIDL types.rdb format ==
The format uses byte-oriented, platform-independent, binary files. Larger
quantities are stored LSB first, without alignment requirements. Offsets are
32 bit, effectively limiting the overall file size to 4GB, but that is not
considered a limitation in practice (and avoids unnecessary bloat compared to
64 bit offsets).
Annotations can be added for (non-module) entities and certain parts of such
entities (e.g., both for an interface type definition and for a direct method of
an interface type definition; the idea is that it can be added for direct parts
that forma a "many-to-one" relationship; there is a tradeoff between generality
of concept and size of representation, esp. for the C++ representation types in
namespace unoidl) and consist of arbitrary sequences of name/value strings.
Each name/value string is encoded as a single UTF-8 string containing a name (an
arbitrary sequence of Unicode code points not containing U+003D EQUALS SIGN),
optionally followed by U+003D EQUALS SIGN and a value (an abritrary sequence of
Unicode code points). The only annotation name currently in use is "deprecated"
(without a value).
The following definitions are used throughout:
* UInt16: 2-byte value, LSB first
* UInt32: 4-byte value, LSB first
* UInt64: 8-byte value, LSB first
* Offset: UInt32 value, counting bytes from start of file
* NUL-Name: zero or more non-NUL US-ASCII bytes followed by a NUL byte
* Len-String: UInt32 number of characters, with 0x80000000 bit 0, followed by
that many US-ASCII (for UNOIDL related names) resp. UTF-8 (for annotations)
bytes
* Idx-String: either an Offset (with 0x80000000 bit 1) of a Len-String, or a
Len-String
* Annotations: UInt32 number N of annotations followed by N * Idx-String
* Entry: Offset of NUL-Name followed by Offset of payload
* Map: zero or more Entries
The file starts with an 8 byte header, followed by information about the root
map (unoidl-write generates files in a single depth-first pass, so the root map
itself is at the end of the file):
* 7 byte magic header "UNOIDL\xFF"
* version byte 0
* Offset of root Map
* UInt32 number of entries of root Map
...
Files generated by unoidl-write follow that by a
"\0** Created by LibreOffice " LIBO_VERSION_DOTTED " unoidl-write **\0"
banner (cf. config_host/config_version.h.in), as a debugging aid. (Old versions
used "reg2unoidl" instead of "unoidl-write" in that banner.)
Layout of per-entry payload in the root or a module Map:
* kind byte:
** 0: module
*** followed by:
**** UInt32 number N1 of entries of Map
**** N1 * Entry
** otherwise:
*** 0x80 bit: 1 if published
*** 0x40 bit: 1 if annotated
*** 0x20 bit: flag (may only be 1 for certain kinds, see below)
*** remaining bits:
**** 1: enum type
***** followed by:
****** UInt32 number N1 of members
****** N1 * tuple of:
******* Idx-String
******* UInt32
******* if annotated: Annotations
**** 2: plain struct type (with base if flag is 1)
***** followed by:
****** if "with base": Idx-String
****** UInt32 number N1 of direct members
****** N1 * tuple of:
******* Idx-String name
******* Idx-String type
******* if annotated: Annotations
**** 3: polymorphic struct type template
***** followed by:
****** UInt32 number N1 of type parameters
****** N1 * Idx-String
****** UInt32 number N2 of members
****** N2 * tuple of:
******* kind byte: 0x01 bit is 1 if parameterized type
******* Idx-String name
******* Idx-String type
******* if annotated: Annotations
**** 4: exception type (with base if flag is 1)
***** followed by:
****** if "with base": Idx-String
****** UInt32 number N1 of direct members
****** N1 * tuple of:
******* Idx-String name
******* Idx-String type
******* if annotated: Annotations
**** 5: interface type
***** followed by:
****** UInt32 number N1 of direct mandatory bases
****** N1 * tuple of:
******* Idx-String
******* if annotated: Annotations
****** UInt32 number N2 of direct optional bases
****** N2 * tuple of:
******* Idx-String
******* if annotated: Annotations
****** UInt32 number N3 of direct attributes
****** N3 * tuple of:
******* kind byte:
******** 0x02 bit: 1 if read-only
******** 0x01 bit: 1 if bound
******* Idx-String name
******* Idx-String type
******* UInt32 number N4 of get exceptions
******* N4 * Idx-String
******* UInt32 number N5 of set exceptions
******* N5 * Idx-String
******* if annotated: Annotations
****** UInt32 number N6 of direct methods
****** N6 * tuple of:
******* Idx-String name
******* Idx-String return type
******* UInt32 number N7 of parameters
******* N7 * tuple of:
******** direction byte: 0 for in, 1 for out, 2 for in-out
******** Idx-String name
******** Idx-String type
******* UInt32 number N8 of exceptions
******* N8 * Idx-String
******* if annotated: Annotations
**** 6: typedef
***** followed by:
****** Idx-String
**** 7: constant group
***** followed by:
****** UInt32 number N1 of entries of Map
****** N1 * Entry
**** 8: single-interface--based service (with default constructor if flag is 1)
***** followed by:
****** Idx-String
****** if not "with default constructor":
******* UInt32 number N1 of constructors
******* N1 * tuple of:
******** Idx-String
******** UInt32 number N2 of parameters
******** N2 * tuple of
********* kind byte: 0x04 bit is 1 if rest parameter
********* Idx-String name
********* Idx-String type
******** UInt32 number N3 of exceptions
******** N3 * Idx-String
******** if annotated: Annotations
**** 9: accumulation-based service
***** followed by:
****** UInt32 number N1 of direct mandatory base services
****** N1 * tuple of:
******* Idx-String
******* if annotated: Annotations
****** UInt32 number N2 of direct optional base services
****** N2 * tuple of:
******* Idx-String
******* if annotated: Annotations
****** UInt32 number N3 of direct mandatory base interfaces
****** N3 * tuple of:
******* Idx-String
******* if annotated: Annotations
****** UInt32 number N4 of direct optional base interfaces
****** N4 * tuple of:
******* Idx-String
******* if annotated: Annotations
****** UInt32 number N5 of direct properties
****** N5 * tuple of:
******* UInt16 kind:
******** 0x0100 bit: 1 if optional
******** 0x0080 bit: 1 if removable
******** 0x0040 bit: 1 if maybedefault
******** 0x0020 bit: 1 if maybeambiguous
******** 0x0010 bit: 1 if readonly
******** 0x0008 bit: 1 if transient
******** 0x0004 bit: 1 if constrained
******** 0x0002 bit: 1 if bound
******** 0x0001 bit: 1 if maybevoid
******* Idx-String name
******* Idx-String type
******* if annotated: Annotations
**** 10: interface-based singleton
***** followed by:
****** Idx-String
**** 11: service-based singleton
***** followed by:
****** Idx-String
*** if annotated, followed by: Annotations
Layout of per-entry payload in a constant group Map:
* kind byte:
** 0x80 bit: 1 if annotated
** remaining bits:
*** 0: BOOLEAN
**** followed by value byte, 0 represents false, 1 represents true
*** 1: BYTE
**** followed by value byte, representing values with two's complement
*** 2: SHORT
**** followed by UInt16 value, representing values with two's complement
*** 3: UNSIGNED SHORT
**** followed by UInt16 value
*** 4: LONG
**** followed by UInt32 value, representing values with two's complement
*** 5: UNSIGNED LONG
**** followed by UInt32 value
*** 6: HYPER
**** followed by UInt64 value, representing values with two's complement
*** 7: UNSIGNED HYPER
**** followed by UInt64 value
*** 8: FLOAT
**** followed by 4-byte value, representing values in ISO 60599 binary32 format,
LSB first
*** 9: DOUBLE
**** followed by 8-byte value, representing values in ISO 60599 binary64 format,
LSB first
* if annotated, followed by: Annotations
Reference in a new issue View git blame Copy permalink