libIDL README
			~~~~~~~~~~~~~

Introduction
~~~~~~~~~~~~

libIDL is a library licensed under the GNU LGPL for creating trees of
CORBA Interface Definition Language (IDL) files, which is a
specification for defining portable interfaces.  libIDL was initially
written for ORBit (the ORB from the GNOME project, and the primary
means of libIDL distribution).  However, the functionality was
designed to be as reusable and portable as possible.

It is written in C, and the aim is to retain the ability to compile it
on a system with a standard C compiler.  Preprocessed parser files are
included so you are not forced to rebuild the parser, however an
effort is made to keep the parser and lexer compatible with standard
Unix yacc.  Currently, flex is required to generate the lexical
scanner.

With libIDL, you can parse an IDL file which will be automatically run
through the C preprocessor (on systems with one available), and have
detailed error and warning messages displayed.  On a compilation
without errors, the tree is returned to the custom application.
libIDL performs compilation phases from lexical analysis to nearly
full semantic analysis with some optimizations, and will attempt to
generate meaningful errors and warnings for invalid or deprecated IDL.

libIDL exports functionality used to generate detailed conforming
error and warning messages in gcc-like format, and also comes with a
default backend to generate IDL into a file or string (useful for
customized messages or comments in the output).  The IDL backend is
complete enough that most generated IDL can be reparsed by libIDL
without errors. libIDL returns separate syntax and namespace trees,
and includes functionality to hide syntactical information from the
primary tree, while keeping it accessible through the namespace for
type information and name lookup.

Optional extensions to standard IDL can be enabled using parse flags.
These include node properties, embedded code fragments, and XPIDL.
Nodes can also have declarations tags which assign particular
attributions to certain IDL constructs to further facilitate custom
applications.

If you are upgrading to a new version, please see the NEWS file for
any changes which may affect code.


Emacs Syntax Highlighting for IDL Code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are using Emacs 20.x and do not have decent syntax highlighting
in your IDL mode, you can use the following Emacs lisp to add
IDL-specific highlighting using font-lock mode:

(font-lock-add-keywords
 'idl-mode
 `(("^#[ 	]*error[ 	]+\\(.+\\)" 1 'font-lock-warning-face prepend)
   ("^#[ 	]*\\(include\\)[ 	]+\\(<[^>\"\n]*>?\\)" 2 'font-lock-string-face)
   ("^#[ 	]*define[ 	]+\\(\\sw+\\)(" 1 'font-lock-function-name-face)
   ("^#[ 	]*\\(elif\\|if\\)\\>"
    ("\\<\\(defined\\)\\>[ 	]*(?\\(\\sw+\\)?" nil nil
     (1 'font-lock-reference-face)
     (2 'font-lock-variable-name-face nil t)))
   ("\\(__declspec\\)[ 	]*(\\([^)]+\\))"
    (1 'font-lock-reference-face)
    (2 'font-lock-variable-name-face))
   ("^#[ 	]*\\(\\sw+\\)\\>[ 	]*\\(\\sw+\\)?"
    (1 'font-lock-reference-face)
    (2 'font-lock-variable-name-face nil t))
   ("\\<\\(raises\\)\\>" 1 'font-lock-keyword-face)
   ("[ 	]*\\([A-Za-z][A-Za-z0-9_]*\\)[ 	]*(" 1 'font-lock-function-name-face)
   ("\\<\\(any\\|boolean\\|char\\|const\\|double\\|enum\\|fixed\\|float\\|interface\\|long\\|module\\|native\\|octet\\|Object\\|sequence\\|short\\|string\\|struct\\|unsigned\\|union\\|void\\|wchar\\|wstring\\)\\>" 1 'font-lock-type-face)
   ("\\<\\(attribute\\|case\\|context\\|default\\|exception\\|FALSE\\|in\\|inout\\|oneway\\|out\\|readonly\\|switch\\|TRUE\\|typedef\\)\\>" 1 'font-lock-keyword-face)) 'set)
(add-hook 'idl-mode-hook '(lambda () (font-lock-mode 1)))

Using libIDL for Win32
~~~~~~~~~~~~~~~~~~~~~~

Win32 libIDL support is mostly here, but currently requires the use of
IDL_parse_filename_with_input, since there is no C preprocessor
generally available under Windows. To compile this, you will also need
to obtain GLib and pkg-config for Windows, which you should be able to
obtain from http://www.gtk.org/download-windows.html

Building
~~~~~~~~

You can build either with the GNU toolchain (mingw) or one of
Microsoft's compiler (any recent version should work). With mingw you
use the normal configure script and make. pkg-config is used in the
normal way to find out the compiler command-line options.

With Microsoft's compiler you run nmake -f Makefile.msc. Also the
Makefile.msc uses pkg-config to find out the compiler flags. The
commands to use pkg-config output in the Makefile.msc are somewhat
convoluted, but nothing simpler seems to work, given the lack of
backticks in cmd.exe or something similar in nmake. If you use an
older Microsoft compiler you will have to edit out the
manifest-related commands from Makefile.msc.

When built with gcc libIDL will also use gcc as a preprocessor (it
will run "gcc -E -P"), and when built with Microsoft's compiler it
will correspondingly use the Microsoft compiler as preprocessort (it
will run "cl -EP"). Thus users of libIDL, especially users of the
ORBit2 IDL compiler orbit-idl-2, need to make sure that they have the
necessary folders in PATH so that gcc or cl are found when orbit-idl-2
is run.

Using the Library
~~~~~~~~~~~~~~~~~

After building, all you need are the files IDL.h and the DLL and
related import library.  Place the header in a place where it can be
found with libIDL/IDL.h, the DLL somewhere in PATH, and the import
library somewhere where your compiler will find it.

--
Andrew T. Veliath <andrewtv@usa.net>
Tor Lillqvist <tml@iki.fi>