Project Files

The basic inputs to the urweb compiler are project files, which have the extension .urp. Here is a sample .urp file.

database dbname=test
sql crud1.sql

crud
crud1

The database line gives the database information string to pass to libpq. In this case, the string only says to connect to a local database named test.

The sql line asks for an SQL source file to be generated, giving the commands to run to create the tables and sequences that this application expects to find. After building this .urp file, the following commands could be used to initialize the database, assuming that the current UNIX user exists as a Postgres user with database creation privileges:

createdb test
psql -f crud1.sql test

A blank line separates the named directives from a list of modules to include in the project. Any line may contain a shell-script-style comment, where any suffix of a line starting at a hash character # is ignored.

For each entry M in the module list, the file M.urs is included in the project if it exists, and the file M.ur must exist and is always included.

Here is the complete list of directive forms. ``FFI'' stands for ``foreign function interface,'' Ur's facility for interaction between Ur programs and C and JavaScript libraries.

• [allow|deny] [url|mime|requestHeader|responseHeader|env] PATTERN registers a rule governing which URLs, MIME types, HTTP request headers, HTTP response headers, or environment variable names are allowed to appear explicitly in this application. The first such rule to match a name determines the verdict. If PATTERN ends in *, it is interpreted as a prefix rule. Otherwise, a string must match it exactly.
• alwaysInline PATH requests that every call to the referenced function be inlined. Section 10 explains how functions are assigned path strings.
• benignEffectful Module.ident registers an FFI function or transaction as having side effects. The optimizer avoids removing, moving, or duplicating calls to such functions. Every effectful FFI function must be registered, or the optimizer may make invalid transformations. This version of the effectful directive registers that this function only has side effects that remain local to a single page generation.
• clientOnly Module.ident registers an FFI function or transaction that may only be run in client browsers.
• clientToServer Module.ident adds FFI type Module.ident to the list of types that are OK to marshal from clients to servers. Values like XML trees and SQL queries are hard to marshal without introducing expensive validity checks, so it's easier to ensure that the server never trusts clients to send such values. The file include/urweb/urweb_cpp.h shows examples of the C support functions that are required of any type that may be marshalled. These include attrify, urlify, and unurlify functions.
• coreInline TREESIZE sets how many nodes the AST of a function definition may have before the optimizer stops trying hard to inline calls to that function. (This is one of two options for one of two intermediate languages within the compiler.)
• database DBSTRING sets the string to pass to libpq to open a database connection.
• debug saves some intermediate C files, which is mostly useful to help in debugging the compiler itself.
• effectful Module.ident registers an FFI function or transaction as having side effects. The optimizer avoids removing, moving, or duplicating calls to such functions. This is the default behavior for transaction-based types.
• exe FILENAME sets the filename to which to write the output executable. The default for file P.urp is P.exe.
• ffi FILENAME reads the file FILENAME.urs to determine the interface to a new FFI module. The name of the module is calculated from FILENAME in the same way as for normal source files. See the files include/urweb/urweb_cpp.h and src/c/urweb.c for examples of C headers and implementations for FFI modules. In general, every type or value Module.ident becomes uw_Module_ident in C.
• html5 activates work-in-progress support for generating HTML5 instead of XHTML. For now, this option only affects the first few tokens on any page, which are always the same.
• include FILENAME adds FILENAME to the list of files to be #included in C sources. This is most useful for interfacing with new FFI modules.
• jsFunc Module.ident=name gives the JavaScript name of an FFI value.
• library FILENAME parses FILENAME.urp and merges its contents with the rest of the current file's contents. If FILENAME.urp doesn't exist, the compiler also tries FILENAME/lib.urp.
• limit class num sets a resource usage limit for generated applications. The limit class will be set to the non-negative integer num. The classes are:
  • cleanup: maximum number of cleanup operations (e.g., entries recording the need to deallocate certain temporary objects) that may be active at once per request
  • clients: maximum number of simultaneous connections to one application by web clients waiting for new asynchronous messages sent with Basis.send
  • database: maximum size of a database file (currently only used by SQLite, which interprets the parameter as a number of pages, where page size is itself a quantity configurable in SQLite)
  • deltas: maximum number of messages sendable in a single request handler with Basis.send
  • globals: maximum number of global variables that FFI libraries may set in a single request context
  • headers: maximum size (in bytes) of per-request buffer used to hold HTTP headers for generated pages
  • heap: maximum size (in bytes) of per-request heap for dynamically allocated data
  • inputs: maximum number of top-level form fields per request
  • messages: maximum size (in bytes) of per-request buffer used to hold a single outgoing message sent with Basis.send
  • page: maximum size (in bytes) of per-request buffer used to hold HTML content of generated pages
  • script: maximum size (in bytes) of per-request buffer used to hold JavaScript content of generated pages
  • subinputs: maximum number of form fields per request, excluding top-level fields
  • time: maximum running time of a single page request, in units of approximately 0.1 seconds
  • transactionals: maximum number of custom transactional actions (e.g., sending an e-mail) that may be run in a single page generation
• link FILENAME adds FILENAME to the list of files to be passed to the linker at the end of compilation. This is most useful for importing extra libraries needed by new FFI modules.
• linker CMD sets CMD as the command line prefix to use for linking C object files. The command line will be completed with a space-separated list of .o and .a files, -L and -l flags, and finally with a -o flag to set the location where the executable should be written.
• minHeap NUMBYTES sets the initial size for thread-local heaps used in handling requests. These heaps grow automatically as needed (up to any maximum set with limit), but each regrow requires restarting the request handling process.
• monoInline TREESIZE sets how many nodes the AST of a function definition may have before the optimizer stops trying hard to inline calls to that function. (This is one of two options for one of two intermediate languages within the compiler.)
• neverInline PATH requests that no call to the referenced function be inlined. Section 10 explains how functions are assigned path strings.
• noMangleSql avoids adding a uw_ prefix in front of each identifier in SQL. With this experimental feature, the burden is on the programmer to avoid naming tables or columns after SQL keywords!
• noXsrfProtection URIPREFIX turns off automatic cross-site request forgery protection for the page handler identified by the given URI prefix. This will avoid checking cryptographic signatures on cookies, which is generally a reasonable idea for some pages, such as login pages that are going to discard all old cookie values, anyway.
• onError Module.var changes the handling of fatal application errors. Instead of displaying a default, ugly error 500 page, the error page will be generated by calling function Module.var on a piece of XML representing the error message. The error handler should have type $\mathsf{xbody} \to \mathsf{transaction} \; \mathsf{page}$ . Note that the error handler cannot be in the application's main module, since that would register it as explicitly callable via URLs.
• path NAME=VALUE creates a mapping from NAME to VALUE. This mapping may be used at the beginnings of filesystem paths given to various other configuration directives. A path like $NAME/rest is expanded to VALUE/rest. There is an initial mapping from the empty name (for paths like $/list) to the directory where the Ur/Web standard library is installed. If you accept the default configure options, this directory is /usr/local/lib/urweb/ur.
• prefix PREFIX sets the prefix included before every URI within the generated application. The default is /.
• profile generates an executable that may be used with gprof.
• rewrite KIND FROM TO gives a rule for rewriting canonical module paths. For instance, the canonical path of a page may be Mod1.Mod2.mypage, while you would rather the page were accessed via a URL containing only page. The directive rewrite url Mod1/Mod2/mypage page would accomplish that. The possible values of KIND determine which kinds of objects are affected. The kind all matches any object, and url matches page URLs. The kinds table, sequence, and view match those sorts of SQL entities, and relation matches any of those three. cookie matches HTTP cookies, and style matches CSS class names. If FROM ends in /*, it is interpreted as a prefix matching rule, and rewriting occurs by replacing only the appropriate prefix of a path with TO. The TO field may be left empty to express the idea of deleting a prefix. For instance, rewrite url Main/* will strip all Main/ prefixes from URLs. While the actual external names of relations and styles have parts separated by underscores instead of slashes, all rewrite rules must be written in terms of slashes. An optional suffix of [-] for a rewrite directive asks to additionally replace all _ characters with - characters, which can be handy for, e.g., interfacing with an off-the-shelf CSS library that prefers hyphens over underscores.
• safeGet URI asks to allow the page handler assigned this canonical URI prefix to cause persistent side effects, even if accessed via an HTTP GET request.
• script URL adds URL to the list of extra JavaScript files to be included at the beginning of any page that uses JavaScript. This is most useful for importing JavaScript versions of functions found in new FFI modules.
• serverOnly Module.ident registers an FFI function or transaction that may only be run on the server.
• sigfile PATH sets a path where your application should look for a key to use in cryptographic signing. This is used to prevent cross-site request forgery attacks for any form handler that both reads a cookie and creates side effects. If the referenced file doesn't exist, an application will create it and read its saved data on future invocations. You can also initialize the file manually with any contents at least 16 bytes long; the first 16 bytes will be treated as the key.
• sql FILENAME sets where to write an SQL file with the commands to create the expected database schema. The default is not to create such a file.
• timeFormat FMT accepts a time format string, as processed by the POSIX C function strftime(). This controls the default rendering of $\mathsf{time}$ values, via the $\mathsf{show}$ instance for $\mathsf{time}$ .
• timeout N sets to N seconds the amount of time that the generated server will wait after the last contact from a client before determining that that client has exited the application. Clients that remain active will take the timeout setting into account in determining how often to ping the server, so it only makes sense to set a high timeout to cope with browser and network delays and failures. Higher timeouts can lead to more unnecessary client information taking up memory on the server. The timeout goes unused by any page that doesn't involve the recv function, since the server only needs to store per-client information for clients that receive asynchronous messages.