The Foreign Function Interface

It is possible to call your own C and JavaScript code from Ur/Web applications, via the foreign function interface (FFI). The starting point for a new binding is a .urs signature file that presents your external library as a single Ur/Web module (with no nested modules). Compilation conventions map the types and values that you use into C and/or JavaScript types and values.

It is most convenient to encapsulate an FFI binding with a new .urp file, which applications can include with the library directive in their own .urp files. A number of directives are likely to show up in the library's project file.

• clientOnly Module.ident registers a value as being allowed only in client-side code.
• clientToServer Module.ident declares a type as OK to marshal between clients and servers. By default, abstract FFI types are not allowed to be marshalled, since your library might be maintaining invariants that the simple serialization code doesn't check.
• effectful Module.ident registers a function that can have side effects. This is the default for transaction-based types, and, actually, this directive is mostly present for legacy compatibility reasons, since it used to be required explicitly for each transactional function.
• ffi FILE.urs names the file giving your library's signature. You can include multiple such files in a single .urp file, and each file mod.urp defines an FFI module Mod.
• include FILE requests inclusion of a C header file.
• jsFunc Module.ident=name gives a mapping from an Ur name for a value to a JavaScript name.
• link FILE requests that FILE be linked into applications. It should be a C object or library archive file, and you are responsible for generating it with your own build process.
• script URL requests inclusion of a JavaScript source file within application HTML.
• serverOnly Module.ident registers a value as being allowed only in server-side code.