To compile project P.urp, simply run
urweb PThe output executable is a standalone web server. Run it with the command-line argument -h to see which options it takes. If the project file lists a database, the web server will attempt to connect to that database on startup. See Section 10 for an explanation of the URI mapping convention, which determines how each page of your application may be accessed via URLs.
To time how long the different compiler phases run, without generating an executable, run
urweb -timing P
To stop the compilation process after type-checking, run
urweb -tc PIt is often worthwhile to run urweb in this mode, because later phases of compilation can take significantly longer than type-checking alone, and the type checker catches many errors that would traditionally be found through debugging a running application.
A related option is -dumpTypes, which, as long as parsing succeeds, outputs to stdout a summary of the kinds of all identifiers declared with con and the types of all identifiers declared with val or val rec. This information is dumped even if there are errors during type inference. Compiler error messages go to stderr, not stdout, so it is easy to distinguish the two kinds of output programmatically. A refined version of this option is -dumpTypesOnError, which only has an effect when there are compilation errors.
It may be useful to combine another option -unifyMore with -dumpTypes. Ur/Web type inference proceeds in a series of stages, where the first is standard Hindley-Milner type inference as in ML, and the later phases add more complex aspects. By default, an error detected in one phase cuts off the execution of later phases. However, the later phases might still determine more values of unification variables. These value choices might be ``misguided,'' since earlier phases have not come up with reasonable types at a coarser detail level; but the unification decisions may still be useful for debugging and program understanding. So, if a run with -dumpTypes leaves unification variables undetermined in positions where you would like to see best-effort guesses instead, consider -unifyMore. Note that -unifyMore has no effect when type inference succeeds fully, but it may lead to many more error messages when inference fails.
To output information relevant to CSS stylesheets (and not finish regular compilation), run
urweb -css PThe 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.
Ur/Web type inference can take a significant amount of time, so it can be helpful to cache type-inferred versions of source files. This mode can be activated by running
urweb daemon startFurther 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 stopCommunication happens via a UNIX domain socket in file .urweb_daemon in the working directory.
Some other command-line parameters are accepted:
A command sequence like this can initialize a Postgres database, using a file app.sql generated by the compiler:
createdb app psql -f app.sql app
A command sequence like this can initialize a MySQL database:
echo "CREATE DATABASE app" | mysql mysql -D app <app.sql
A command like this can initialize an SQLite database:
sqlite3 path/to/database/file <app.sql
Since Ur/Web treats paths in an unusual way, a configuration line like this one can be used to configure an application that was built with URL prefix /Hello:
ScriptAlias /Hello /path/to/hello.exe
A different method can be used for, e.g., a shared host, where you can only configure Apache via .htaccess files. Drop the generated executable into your web space and mark it as CGI somehow. For instance, if the script ends in .exe, you might put this in .htaccess in the directory containing the script:
Options +ExecCGI AddHandler cgi-script .exe
Additionally, make sure that Ur/Web knows the proper URI prefix for your script. For instance, if the script is accessed via http://somewhere/dir/script.exe, then include this line in your .urp file:
To access the foo function in the Bar module, you would then hit http://somewhere/dir/script.exe/Bar/foo.
If your application contains form handlers that read cookies before causing side effects, then you will need to use the sigfile .urp directive, too.
To configure a FastCGI program with Apache, one could combine the above ScriptAlias line with a line like this:
FastCgiServer /path/to/hello.exe -idle-timeout 99999The idle timeout is only important for applications that use message-passing. Client connections may go long periods without receiving messages, and Apache tries to be helpful and garbage collect them in such cases. To prevent that behavior, we specify how long a connection must be idle to be collected.
Also see the discussion of the prefix directive for CGI above; similar configuration is likely to be necessary for FastCGI. An Ur/Web application won't generally run correctly if it doesn't have a unique URI prefix assigned to it and configured with prefix.
Here is some lighttpd configuration for the same application.
fastcgi.server = ( "/Hello/" => (( "bin-path" => "/path/to/hello.exe", "socket" => "/tmp/hello", "check-local" => "disable", "docroot" => "/", "max-procs" => "1" )) )The least obvious requirement is setting max-procs to 1, so that lighttpd doesn't try to multiplex requests across multiple external processes. This is required for message-passing applications, where a single database of client connections is maintained within a multi-threaded server process. Multiple processes may, however, be used safely with applications that don't use message-passing.
A FastCGI process reads the environment variable URWEB_NUM_THREADS to determine how many threads to spawn for handling client requests. The default is 1.
There is an additional convenience method for invoking urweb. If the main argument is FOO, and FOO.ur exists but FOO.urp doesn't, then the invocation is interpreted as if called on a .urp file containing FOO as its only main entry, with an additional rewrite all FOO/* directive.