pidl/README

   1 Introduction:
   2 =============
   3 This directory contains the source code of the pidl (Perl IDL)
   4 compiler for Samba 4.
   5
   6 The main sources for pidl are available using Git as part of
   7 the Samba source tree. Use:
   8 git clone git://git.samba.org/samba.git
   9
  10 Pidl works by building a parse tree from a .pidl file (a simple
  11 dump of it's internal parse tree) or a .idl file
  12 (a file format mostly like the IDL file format midl uses).
  13 The IDL file parser is in idl.yp (a yacc file converted to
  14 perl code by yapp)
  15
  16 Standalone installation:
  17 ========================
  18 Run Makefile.PL to generate the Makefile.
  19
  20 Then run "make install" (as root) to install.
  21
  22 Internals overview:
  23 ===================
  24
  25 After a parse tree is present, pidl will call one of it's backends
  26 (which one depends on the options given on the command-line). Here is
  27 a list of current backends:
  28
  29 -- Generic --
  30 Parse::Pidl::Dump - Converts the parse tree back to an IDL file
  31 Parse::Pidl::Samba4::Header - Generates header file with data structures defined in IDL file
  32 Parse::Pidl::NDR - Generates intermediate datastructures for use by NDR parses/generators
  33 Parse::Pidl::ODL - Generates IDL structures from ODL structures for use in the NDR parser generator
  34 Parse::Pidl::Test - Utility functions for use in pidl's testsuite
  35
  36 -- Samba NDR --
  37 Parse::Pidl::Samba4::NDR::Client - Generates client call functions in C using the NDR parser
  38 Parse::Pidl::Samba4::NDR::Parser - Generates pull/push functions for parsing NDR
  39 Parse::Pidl::Samba4::NDR::Server - Generates server side implementation in C
  40 Parse::Pidl::Samba4::TDR - Parser generator for the "Trivial Data Representation"
  41 Parse::Pidl::Samba4::Template - Generates stubs in C for server implementation
  42 Parse::Pidl::Samba4::Python - Generates bindings for Python
  43
  44 -- Samba COM / DCOM --
  45 Parse::Pidl::Samba4::COM::Proxy - Generates proxy object for DCOM (client-side)
  46 Parse::Pidl::Samba4::COM::Stub - Generates stub call handler for DCOM (server-side)
  47 Parse::Pidl::Samba4::COM::Header - Generates headers for COM
  48
  49 -- Wireshark --
  50 Parse::Pidl::Wireshark::NDR - Generates a parser for the Wireshark network sniffer
  51 Parse::Pidl::Wireshark::Conformance - Reads conformance files containing additional data for generating Wireshark parsers
  52
  53 -- Utility modules --
  54 Parse::Pidl::Util - Misc utility functions used by *.pm and pidl.pl
  55 Parse::Pidl::Typelist - Utility functions for keeping track of known types and their representation in C
  56
  57 Tips for hacking on pidl:
  58  - Inspect pidl's parse tree by using the --keep option and looking at the
  59    generated .pidl file.
  60  - The various backends have a lot in common, if you don't understand how one
  61    implements something, look at the others.
  62  - See pidl(1) and the documentation on midl
  63  - See 'info bison' and yapp(1) for information on the file format of idl.yp
  64  - Run the tests (all in tests/)