path: root/debian/urweb.1

.\" Copyright 2013, 2015-2017, 2020 Benjamin Barenblat <bbaren@mit.edu>
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License"); you may not
.\" use this file except in compliance with the License.  You may obtain a copy
.\" of the License at
.\"
.\"     http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.\" WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
.\" License for the specific language governing permissions and limitations
.\" under the License.
.mso www.tmac
.TH URWEB 1 2020-02-09
.SH NAME
urweb \- compiler for the Ur/Web programming language
.SH SYNOPSIS
.B urweb
.RI [\| option
\&...\|]
.RI [\| project-name \|]
.br
.B urweb daemon
.RB (\| start \||\| stop \||\| restart \|)
.SH DESCRIPTION
This manual page briefly documents the
.B urweb
compiler.
Extensive documentation is available in the Ur/Web reference manual.
.PP
.B 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.
.B 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.
.PP
The first invocation described compiles an Ur/Web project, while the second invocation controls the type inference daemon (see
.BR "TYPE INFERENCE DAEMON" ).
For simple projects, only familiarity with the first invocation is required.
.SH OPTIONS
.B 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
.B urweb
.IR foo ,
where the file
.IR foo .ur
contains a valid Ur/Web program, in which case
.B urweb
will compile the program to the file
.IR foo .exe.
(Despite the extension of the generated files,
.B urweb
does not necessarily produce COFF executables; rather, it produces the default object format of the default C compiler.)
.PP
Larger programs, spanning many files, may be compiled by specifying an
.B .urp
(i.e., an Ur/Web project) file.
The syntax of an
.B .urp
file is relatively simple; see section 3.1 of the Ur/Web reference manual for details.
.PP
With no arguments,
.B urweb
prints the version number and exits.
.SS "Compiler options"
.TP
.B \-ccompiler \fIprogram\fR
Sets the executable name corresponding to the C compiler.
.B urweb
uses
.BR gcc (1)
by default, but
.BR clang (1)
should also work.
.TP
.B \-db \fIname\fR=\fIvalue\fR,...
Sets database information using the format expected by Postgres's
.IR PQconnectdb .
If the database backend is MySQL or SQLite,
.B urweb
will parse the information string to set connection parameters appropriately.
For MySQL, the only relevant parameters are
.IR host ,
.IR hostaddr ,
.IR port ,
.IR dbname ,
.IR user ,
and
.IR password ;
for SQLite, the only relevant parameter is
.IR dbname ,
which is interpreted as the file system path to the database file.
All unrecognized parameters are silently ignored.
.TP
.BR \-dbms " (\|" postgres \||\| mysql \||\| sqlite \|)
Sets the database backend.  If requested,
.B urweb
will also emit initialization code for the selected backend; see the
.B \-sql
option.
.TP
.B \-debug
Instructs
.B urweb
to emit the generated C code as
.RI /tmp/ webapp .c.
Additionally,
.B urweb
will print the command-line options it passes to the C compiler and linker as it executes.
.TP
.B \-dumpSource
Instructs
.B 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.
.TP
.B \-dumpVerboseSource
Instructs
.B 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.
.TP
.B \-dumpTypes
If specified,
.B urweb
will print the types of all named values it finds during compilation.
.TP
.B \-dumpTypesOnError
Identical to
.BR \-dumpTypes ,
but only prints the types if compilation fails.
.TP
.B \-explainEmbed
Enables verbose error messages when
.B urweb
is unable to embed server-side values in client-side code.
.TP
.B \-limit \fIclass\fR \fInum\fR
Sets a resource usage limit for generated applications.
The limit
.I class
will be set to the non-negative integer
.IR num .
The classes are:
.RS
.IP \fBcleanup\fR
maximum number of cleanup operations (e.g., entries recording the need to deallocate certain temporary objects) that may be active at once per request
.IP \fBclients\fR
maximum number of clients that can be simultaneously blocked waiting for new messages (sent by
.IR Basis.send )
.IP \fBdatabase\fR
maximum size of database file (currently only used by SQLite), in units of database pages
.IP \fBdeltas\fR
maximum number of messages sendable in a single request handler with
.I Basis.send
.IP \fBglobals\fR
maximum number of global variables that FFI libraries may set in a single request context
.IP \fBheaders\fR
maximum size (in bytes) of per-request buffer used to hold HTTP headers for generated pages
.IP \fBheap\fR
maximum size (in bytes) of per-request heap for dynamically allocated data
.IP \fBinputs\fR
maximum number of top-level form fields per request
.IP \fBmessages\fR
maximum size (in bytes) of per-request buffer used to hold a single outgoing
message sent with
.I Basis.send
.IP \fBpage\fR
maximum size (in bytes) of per-request buffer used to hold HTML content of generated pages
.IP \fBscript\fR
maximum size (in bytes) of per-request buffer used to hold JavaScript content of generated pages
.IP \fBsubinputs\fR
maximum number of form fields per request, excluding top-level fields
.IP \fBtime\fR
maximum running time of a single page request, in units of approximately 0.1 seconds
.IP \fBtransactionals\fR
maximum number of custom transactional actions (e.g., sending an e-mail) that may be run in a single page generation
.RE
.TP
.B \-output \fIfilename\fR
Sets where
.B urweb
will store the compiled executable.
.TP
.B \-path \fIname\fR \fIvalue\fR
Defines a new path alias for use in
.B .urp
files.
In particular, this option specifies that all occurrences of
.RI $ name
in any
.B .urp
files processed will be replaced with
.IR value .
You may specify this option more than once.
.TP
.B \-prefix \fIprefix\fR
Sets the application prefix.
This controls how Ur/Web functions are bound to URIs; in particular, if
.I prefix
is
.IR /directory/myapp.exe/ ,
then URIs of the form
.I //example.com/directory/myapp.exe/Module/function
will resolve to the function
.I Module.function
in Ur/Web.
.TP
.BR \-protocol " (\|" http \||\| cgi \||\| fastcgi \||\| static )
Instructs
.B urweb
to produce an executable which speaks the specified protocol:
.RS
.IP \fBhttp\fR
HTTP 1.1.
.B urweb
will generate a standalone server executable.
.IP \fBcgi\fR
The Common Gateway Interface,
.BR cgi (5).
This is 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
.I send
and
.I 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.
.IP
Since Ur/Web treats paths in an unusual way, you will need to configure Ur/Web specially by setting the
.B prefix
directive in your
.B .urp
file or passing the
.B \-prefix
option on the command line.
For example, if you deploy a Web application at
.IR //example.com/directory/myapp.exe ,
you should specify
.I /directory/myapp.exe/
as the application prefix.
See section 3.2 of the Ur/Web reference manual for more information.
.IP \fBfastcgi\fR
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.
.IP
Applications which use message-passing, while supported, require special configuration.
In particular, if you're using Apache, be sure to specify a large
.BR idle-timout ;
if you're using lighttpd, be sure to set
.B max-procs
to 1.
The rationale for these configuration changes is detailed in section 3.2 of the Ur/Web reference manual.
.IP \fBstatic\fR
The simplest possible protocol.
.B 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
.IR /main ,
in which case a static HTTP response for that page will be written to standard output.
.RE
.TP
.B \-root \fIName\fR \fIpath\fR
Triggers an alternate module convention for all source files found in directory
.I path
or any of its subdirectories.
In particular, any file
.IR path / foo .ur
will define a module called
.IR Name . Foo
instead of the usual
.IR Foo .
Any file
.IR path / subdir / foo .ur
will define a module called
.IR Name . Subdir . Foo ,
and so on for arbitrary nesting of subdirectories.
You may specify this option more than once.
.TP
.B \-sigfile \fIpath\fR
If specified, the compiled application will look at
.I 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.
.TP
.B \-sql \fIfile\fR
Requests that
.B urweb
generate database initialization code for the selected database backend, storing it in
.IR file .
If
.I file
already exists,
.B urweb
will overwrite it.
.IP
Note that the generated instructions will not create the application database; you must do that yourself.
.TP
.B \-static
Instructs
.B urweb
to statically link the generated executable.
.TP
.B \-timing
If specified,
.B urweb
will print a timing report at the end of compilation showing the number of seconds required for each stage of the compilation process.
.TP
.B \-unifyMore
Instructs
.BR urweb 's
type inference engine to make best-effort guesses rather than immediately failing when performing type inference.
If
.B \-dumpTypes
shows unresolved unification variables in positions where you would like to see
.B urweb
make best-guesses effort instead, specify this option.
.IP
Correct programs compiled with
.B \-unifyMore
will be identical to their counterparts compiled without it; however,
.B 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.
.TP
.B \-verbose
Instructs
.B urweb
to announce the stages of the compilation process as it performs them.
.SS "Options which inhibit compilation"
When run with any of these options,
.B urweb
will not produce executable output.
.TP
.B \-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
.RS
.IP \fBB\fR
for block-level elements,
.IP \fBC\fR
for table captions,
.IP \fBD\fR
for table cells,
.IP \fBL\fR
for lists, and
.IP \fBT\fR
for tables.
.RE
.IP
Codes that reveal properties of the precise tag that uses a class are
.RS
.IP \fBb\fR
for block-level elements,
.IP \fBt\fR
for tables,
.IP \fBd\fR
for table cells,
.IP \fB\-\fR
for table rows,
.IP \fBH\fR
for the possibility to set a height,
.IP \fBN\fR
for non-replaced inline-level elements,
.IP \fBR\fR
for replaced inline elements, and
.IP \fBW\fR
for the possibility to set a width.
.RE
.TP
.B \-endpoints \fIfile\fR
Populates the specified
.I file
with a JSON description of all the HTTP endpoints that the compiled application will support, with information on MIME content type, for static resources.
.TP
.B \-moduleOf \fIfile\fR
Prints the Ur module name corresponding to the source file
.IR file .
.TP
.B \-numeric\-version
Prints the version of the compiler executable without any associated English text.
Suitable for use in scripts.
.TP
.B \-print\-ccompiler
Prints the executable name of the compiler that
.B urweb
will use.
.TP
.B \-print\-cinclude
Prints the file system location in which
.B urweb
will look for C headers.
.TP
.B \-startLspServer
Starts a
.URL https://microsoft.github.io/language-server-protocol/ "Language Server Protocol"
server.
.TP
.B \-tc
If specified,
.B urweb
will stop after the typechecking phase.
Liberal use of this option can substantially speed development, as
.BR urweb 's
optimization passes can take quite a while.
.TP
.B \-version
Prints the version of the compiler executable.
Output is identical to
.B urweb
output when run without arguments.
.SS "Documentation options"
These options customize Ur/Web's documentation generator.
.TP
.B \-demo
Performs demo-style formatting.
.TP
.B \-guided\-demo
Performs demo-style formatting, but sizes frames to allocate less space to explanatory text.
Useful for generating presentations.
.TP
.B \-noEmacs
When used with
.BR \-demo ,
causes
.B urweb
to
.I not
use Emacs to syntax-highlight code.
The resulting code will not be highlighted.
.TP
.B \-tutorial
Performs tutorial-style formatting.
.SS "Internal options"
These options are not meant for users; they are used to build
.B urweb
releases and to debug the compiler.
.TP
.B \-boot
Places
.B urweb
into bootstrap mode.
Used when building the standard library for the first time.
.TP
.B \-stop \fIphase\fR
Causes
.B urweb
to exit after the specified phase of compilation.
.SH "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
.RS
.B urweb daemon start
.RE
Further
.B 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.
.PP
To stop the background daemon, run
.RS
.B urweb daemon stop
.RE
and to restart it, run
.RS
.B urweb daemon restart
.RE
Communication happens via a Unix domain socket in file .urweb_daemon in the working directory.
.SH BUGS
.B 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,
.MTO ur@impredicative.com "" .
.SH COPYRIGHT
.B urweb
is copyright \(co 2008-2020 Adam Chlipala and licensed under the
.URL http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5 "3-clause BSD license" .
.PP
This manual page is copyright \(co 2013, 2015\(em2017, 2020 Benjamin Barenblat and licensed under the Apache License, Version 2.0.