Provided by: urweb_20160213+dfsg-1build1_amd64 
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-2016 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 Benjamin Barenblat and licensed under the
Apache License, Version 2.0.
February 13, 2016 urweb(1)