---
name: "urweb"
section: "1"
platform: "linux"
package: "urweb"
version: "20170105+dfsg-2"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/urweb"
---

# urweb(1)

compiler for the Ur/Web programming language

## NAME

**urweb** - compiler for the Ur/Web programming language

## SYNOPSIS

**urweb** \[*option*\|*project-name*\]...\
 **urweb daemon** \[**start**\|**stop**\]

## DESCRIPTION

This manual page briefly documents the **urweb** compiler.  Extensive documentation is available in the Ur/Web reference manual.

**urweb** is an optimizing compiler for Ur/Web, a functional, pure, statically typed, strictly evaluated programming language designed for constructing dynamic Web applications backed by SQL databases.  **urweb** produces very efficient object code that does not use garbage collection; compiled programs will often be even more efficient than what most programmers would bother to write in C.

The first invocation described compiles an Ur/Web project (see **COMPILATION**), while the second invocation controls the type inference daemon (see **TYPE INFERENCE DAEMON**).  For simple projects, only familiarity with the first invocation is required.

## COMPILATION

**urweb** is a whole-program compiler (i.e., incremental compilation is not supported).  Thus, it operates at project granularity, and it is run from the command line with a collection of options and a project name.  The simplest case is to run **urweb foo**, where the file **foo.ur** contains a valid Ur/Web program, in which case **urweb** will compile the program to the file **foo.exe**.  (Despite the extension of the generated files, **urweb** does not necessarily produce COFF executables; rather, it produces the default object format of the default C compiler.)

Larger programs, spanning many files, may be compiled by specifying an **.urp** (i.e., an Ur/Web project) file.  The syntax of an **.urp** file is relatively simple; see section 3.1 of the Ur/Web reference manual for details.

With no arguments, **urweb** prints the version number and exits.

## Compiler options

- **-ccompiler** *program*

  Sets the executable name corresponding to the C compiler.  **urweb** uses **gcc** by default, but **clang** should also work.

- **-db** *name*=*value*,...

  Sets database information using the format expected by Postgres's *PQconnectdb*.  If the database backend is MySQL or SQLite, **urweb** will parse the information string to set connection parameters appropriately. For MySQL, the only relevant parameters are *host*, *hostaddr*, *port*, *dbname*, *user*, and *password*; for SQLite, the only relevant parameter is *dbname*, which is interpreted as the file system path to the database file.  All unrecognized parameters are silently ignored.

- **-dbms** (**postgres**\|**mysql**\|**sqlite**)

  Sets the database backend.  If requested, **urweb** will also emit initialization code for the selected backend; see the **-sql** option.

- **-debug**

  Instructs **urweb** to emit the generated C code as */tmp/webapp.c*. Additionally, **urweb** will print the command-line options it passes to the C compiler and linker as it executes.

- **-dumpSource**

  Instructs **urweb** to print a text-based form of the current intermediate representation (IR) when compilation fails.  Output will likely be extremely long and not very human-readable.

- **-dumpVerboseSource**

  Instructs **urweb** to print a text-based form of every intermediate representation it generates during compilation.  Output will likely be extremely long and not very human-readable.

- **-dumpTypes**

  If specified, **urweb** will print the types of all named values it finds during compilation.

- **-dumpTypesOnError**

  Identical to **-dumpTypes**, but only prints the types if compilation fails.

- **-explainEmbed**

  Enables verbose error messages when **urweb** is unable to embed server-side values in client-side code.

- **-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 clients that can be simultaneously blocked waiting for new** **messages (sent by** *Basis.send***)**

  - **database**

    **maximum size of database file (currently only used by SQLite), in units of** **database pages**

  - **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**

- **-output** *filename*

  **Sets where urweb will store the compiled executable.**

- **-path** *name* *value*

  **Defines a new path alias for use in .urp files.  In particular, this** **option specifies that all occurrences of $***name* **in any .urp files** **processed will be replaced with** *value***.  You may specify this option more** **than once.**

- **-prefix** *prefix*

  **Sets the application prefix.  This controls how Ur/Web functions are bound to** **URIs; in particular, if** *prefix* **is** */directory/myapp.exe/***, then URIs** **of the form** *//example.com/directory/myapp.exe/Module/function* **will** **resolve to the function** *Module.function* **in Ur/Web.**

- **-protocol (http\|cgi\|fastcgi\|static)**

  **Instructs urweb to produce an executable which speaks the specified** **protocol:**

  - **http**

    **HTTP 1.1.  urweb will generate a standalone server executable.**

  - **cgi**

    **The Common Gateway Interface, the classic protocol that Web servers use to** **generate dynamic content by spawning new processes.  While Ur/Web programs may** **in general use message-passing with the** *send* **and** *recv* **functions,** **that functionality is not yet supported in CGI, since CGI needs a fresh process** **for each request, and message-passing needs to use persistent sockets to** **deliver messages.**

    **Since Ur/Web treats paths in an unusual way, you will need to configure Ur/Web** **specially by setting the prefix directive in your .urp file or** **passing the -prefix option on the command line.  For example, if you** **deploy a Web application at** *//example.com/directory/myapp.exe***, you** **should specify** */directory/myapp.exe/* **as the application prefix.  See** **section 3.2 of the Ur/Web reference manual for more information.**

  - **fastcgi**

    **The faster, newer protocol inspired by CGI, wherein Web servers can start and** **reuse persistent external processes to generate dynamic content.  Ur/Web** **doesn't implement the whole protocol, but Ur/Web's support has been tested to** **work with both Apache and lighttpd.**

    **Applications which use message-passing, while supported, require special** **configuration.  In particular, if you're using Apache, be sure to specify a** **large idle-timout; if you're using lighttpd, be sure to set** **max-procs to 1.  The rationale for these configuration changes is** **detailed in section 3.2 of the Ur/Web reference manual.**

  - **static**

    **The simplest possible protocol.  urweb will generate an output executable** **which expects a single command-line argument giving the URI of a page to** **generate.  For instance, this argument might be** */main***, in which case a** **static HTTP response for that page will be written to standard output.**

- **-root** *Name* *path*

  **Triggers an alternate module convention for all source files found in directory** *path* **or any of its subdirectories.  In particular, any file** *path***/foo.ur will define a module called** *Name.Foo* **instead of the** **usual** *Foo***.  Any file** *path***/subdir/foo.ur will define a module called** *Name.Subdir.Foo***, and so on for arbitrary nesting of subdirectories. You** **may specify this option more than once.**

- **-sigfile** *path*

  **If specified, the compiled application will look at** *path* **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, the 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** *file*

  **Requests that urweb generate database initialization code for the** **selected database backend, storing it in** *file***.  If** *file* **already** **exists, urweb will overwrite it.**

  **Note that the generated instructions will not create the application database;** **you must do that yourself.**

- **-static**

  **Instructs urweb to statically link the generated executable.**

- **-timing**

  **If specified, urweb will print a timing report at the end of compilation** **showing the number of seconds required for each stage of the compilation** **process.**

- **-unifyMore**

  **Instructs urweb's type inference engine to make best-effort guesses** **rather than immediately failing when performing type inference.  If** **-dumpTypes shows unresolved unification variables in positions where you** **would like to see urweb make best-guesses effort instead, specify this** **option.**

  **Correct programs compiled with -unifyMore will be identical to their** **counterparts compiled without it; however, urweb will likely generate** **many more (and potentially more useful) error messages at a time when asked to** **compile an incorrect program with this flag.**

- **-verbose**

  **Instructs urweb to announce the stages of the compilation process as it** **performs them.**

## Options which inhibit compilation

**When run with any of these options, urweb will not produce executable** **output.**

- **-css**

  **Dumps generated CSS properties and classes.  The first output line is a list of** **categories of CSS properties that would be worth setting on the document body.** **The remaining lines are space-separated pairs of CSS class names and categories** **of properties that would be worth setting for that class.  The category codes** **are divided into two varieties.  Codes that reveal properties of a tag or its** **(recursive) children are**

  - **B**

    **for block-level elements,**

  - **C**

    **for table captions,**

  - **D**

    **for table cells,**

  - **L**

    **for lists, and**

  - **T**

    **for tables.**

  **Codes that reveal properties of the precise tag that uses a class are**

  - **b**

    **for block-level elements,**

  - **t**

    **for tables,**

  - **d**

    **for table cells,**

  - **-**

    **for table rows,**

  - **H**

    **for the possibility to set a height,**

  - **N**

    **for non-replaced inline-level elements,**

  - **R**

    **for replaced inline elements, and**

  - **W**

    **for the possibility to set a width.**

- **-moduleOf** *file*

  **Prints the Ur module name corresponding to the source file** *file***.**

- **-numeric-version**

  **Prints the version of the compiler executable without any associated English** **text.  Suitable for use in scripts.**

- **-print-ccompiler**

  **Prints the executable name of the compiler that urweb will use.**

- **-print-cinclude**

  **Prints the file system location in which urweb will look for C headers.**

- **-tc**

  **If specified, urweb will stop after the typechecking phase.  Liberal use** **of this option can substantially speed development, as urweb's** **optimization passes can take quite a while.**

- **-version**

  **Prints the version of the compiler executable.  Output is identical to** **urweb output when run without arguments.**

## Documentation options

**These options customize Ur/Web's documentation generator.**

- **-demo**

  **Performs demo-style formatting.**

- **-guided-demo**

  **Performs demo-style formatting, but sizes frames to allocate less space to** **explanatory text.  Useful for generating presentations.**

- **-noEmacs**

  **When used with -demo, causes urweb to** *not* **use Emacs to** **syntax-highlight code.  The resulting code will not be highlighted.**

- **-tutorial**

  **Performs tutorial-style formatting.**

## Internal options

**These options are not meant for users; they are used to build urweb** **releases and to debug the compiler.**

- **-boot**

  **Places urweb into bootstrap mode.  Used when building the standard** **library for the first time.**

  **-stop** *phase* **Causes urweb to exit after the specified phase of compilation.**

## TYPE INFERENCE DAEMON

**Since Ur/Web type inference can take a significant amount of time, it can be** **helpful to cache type-inferred versions of source files.  This mode can be** **activated by running**

**urweb daemon start**

**Further urweb invocations in the same working directory will send requests to a** **background daemon process that reuses type inference results whenever possible,** **tracking source file dependencies and modification times.**

**To stop the background daemon, run**

**urweb daemon stop**

**Communication happens via a Unix domain socket in file .urweb\_daemon in the** **working directory.**

## BUGS

**urweb is a product of research; while it is intended to be usable for** **real work, it may occasionally fail to produce optimal results.  If you believe** **you've found a bug (e.g., the compiler throws an unhandled exception), contact** **the Ur/Web mailing list,** *ur@impredicative.com***.**

## COPYRIGHT

**urweb is copyright © 2008-2017 Adam Chlipala and licensed under the** **3-clause BSD license \<http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5\>.**

**This manual page is copyright © 2013, 2015, 2016, 2017 Benjamin Barenblat and** **licensed under the Apache License, Version 2.0.**