Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

edits

  • Loading branch information...
commit 45fc20596ed7fa7c803ac09c0679cc80e98c7f22 1 parent 36d33c2
Jake Donham authored
View
49 External.markdown
@@ -0,0 +1,49 @@
+---
+layout: page
+title: Externally defined types
+---
+#Externally defined types
+
+It is possible to have marshalling functions (and tracing functions)
+generated for types defined outside an `orpc` interface file. This is
+useful if you want to use the same types in more than one RPC
+protocol, if you have some existing types which you would like to
+transmit over RPC without having to move them into the interface file,
+and if you would like to keep types abstract but still be able to
+marshal them (however `orpc` makes no attempt to enforce abstraction
+across the RPC interface).
+
+To use an external type in an interface, just refer to it by its
+module-qualified name. To generate the marshalling functions, build
+with Camlp4 and the `orpc-syntax` package, and define your types like
+
+{% highlight ocaml %}
+type foo = Bar | Baz of int with orpc(aux, trace)
+{% endhighlight %}
+
+Generators are given as a comma-separated list after `with orpc`; the
+available generators are as follows:
+
+| tag | generator |
+|----------|-------------------------------|
+| `aux` | marshalling for ONC RPC |
+| `js_aux` | marshalling for RPC over HTTP |
+| `trace` | tracing functions |
+
+See the `external` example for more details.
+
+You could also use external types to override the marshalling that
+`orpc` uses for a particular type. If you want to do this try dumping
+out the generated code for a type to see how it works; you can just
+replace the functions instead of calling the generator.
+
+If you want to use the same external type (defined in a single module)
+over both ONC RPC and RPC over HTTP, it is slightly tricky. The code
+for ONC RPC can't be generated when compiling with `ocamljs`, and the
+code for RPC over HTTP can't be generated when compiling with
+`ocamlc`/`ocamlopt`, because the libraries each depends on are not
+available. But there is only one `.cmi` file which is shared between
+the two compilations, so you can't just omit the unneeded
+functions. To get around this there is a special argument to Camlp4,
+`--ocamljs`, which you add when ccompiling with `ocamljs`, so that the
+unneeded functions are stubbed out.
View
1  Introduction.markdown
@@ -32,6 +32,7 @@ See more about
* [simple (ocamlrpcgen-style) interfaces] (SimpleInterfaces.html)
* [modules-style interfaces] (ModulesInterfaces.html)
* [tracing] (Tracing.html)
+ * [externally-defined types] (External.html)
* [RPC over HTTP] (RpcOverHttp.html)
Also included is lwt-equeue, a port of Lwt to run on top of Ocamlnet's
View
1  Types.markdown
@@ -25,6 +25,7 @@ equivalent of `'a`):
| `'a * 'b * ...` | `struct { [['a]] 0; [['b]] 1; ... }` |
| `{ foo : 'a; ... }` | `struct { [['a]] foo; ... }` |
| `Foo of 'a ...` | `union switch () { case 0: [['a]] 0; ... }` |
+| `` `foo of 'a ...`` | `union switch () { case 0: [['a]] 0; ... }` |
| `'a array` | `[['a]]<>` |
| `'a list` | `union switch () { case 0: void 0; case 1: [['a list]] 1 }` |
| `'a option` | `[['a]] *` |
View
2  index.markdown
@@ -10,7 +10,7 @@ you give orpc an OCaml signature instead of an RFC-1831/1832-format
file. Most OCaml types (including polymorphic types), exceptions, and
functions with labelled/optional arguments are supported.
-You can download Orpc at [http://github.com/jaked/orpc] (http://github.com/jaked/orpc).
+You can download Orpc at [http://github.com/jaked/orpc/downloads] (http://github.com/jaked/orpc/downloads).
See [Introduction] (Introduction.html) and [Installation] (Installation.html).
Please sign in to comment.
Something went wrong with that request. Please try again.