Building an Application

To compile project P.urp, simply run

urweb P

The 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 P

It 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 P

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.

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

Some other command-line parameters are accepted:

• -boot: Run Ur/Web from a build tree (and not from a system install). This is useful if you're testing the compiler and don't want to install it. It forces generation of statically linked executables.

• -ccompiler <PROGRAM>: Select an alternative C compiler to call with command lines in compiling Ur/Web applications. (It's possible to set the default compiler as part of the configure process, but it may sometimes be useful to override the default.)

• -db <DBSTRING>: Set database connection information, using the format expected by Postgres's PQconnectdb(), which is name1=value1 ... nameN=valueN. The same format is also parsed and used to discover connection parameters for MySQL and SQLite. The only significant settings for MySQL are host, hostaddr, port, dbname, user, and password. The only significant setting for SQLite is dbname, which is interpreted as the filesystem path to the database. Additionally, when using SQLite, a database string may be just a file path.

• -dbms [postgres|mysql|sqlite]: Sets the database backend to use.
  • postgres: This is PostgreSQL, the default. Among the supported engines, Postgres best matches the design philosophy behind Ur, with a focus on consistent views of data, even in the face of much concurrency. Different database engines have different quirks of SQL syntax. Ur/Web tends to use Postgres idioms where there are choices to be made, though the compiler translates SQL as needed to support other backends.

    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
    

  • mysql: This is MySQL, another popular relational database engine that uses persistent server processes. Ur/Web needs transactions to function properly. Many installations of MySQL use non-transactional storage engines by default. Ur/Web generates table definitions that try to use MySQL's InnoDB engine, which supports transactions. You can edit the first line of a generated .sql file to change this behavior, but it really is true that Ur/Web applications will exhibit bizarre behavior if you choose an engine that ignores transaction commands.

    A command sequence like this can initialize a MySQL database:

    echo "CREATE DATABASE app" | mysql
    mysql -D app <app.sql
    

  • sqlite: This is SQLite, a simple filesystem-based transactional database engine. With this backend, Ur/Web applications can run without any additional server processes. The other engines are generally preferred for large-workload performance and full admin feature sets, while SQLite is popular for its low resource footprint and ease of set-up.

    A command like this can initialize an SQLite database:

    sqlite3 path/to/database/file <app.sql
    

• -dumpSource: When compilation fails, output to stderr the complete source code of the last intermediate program before the compilation phase that signaled the error. (Warning: these outputs can be very long and aren't especially optimized for readability!)

• -explainEmbed: Trigger more verbose error messages about inability to embed server-side values in client-side code.

• -limit class num: Equivalent to the limit directive from .urp files

• -moduleOf FILENAME: Prints the Ur/Web module name corresponding to source file FILENAME, exiting immediately afterward.

• -output FILENAME: Set where the application executable is written.

• -path NAME VALUE: Set the value of path variable $NAME to VALUE, for use in .urp files.

• -prefix PREFIX: Equivalent to the prefix directive from .urp files

• -print-ccompiler: Print the C compiler being used.

• -print-cinclude: Print the name of the directory where C/C++ header files are installed.

• -protocol [http|cgi|fastcgi|static]: Set the protocol that the generated application speaks.
  • http: This is the default. It is for building standalone web servers that can be accessed by web browsers directly.

  • cgi: 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 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, 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:

    prefix /dir/script.exe/
    

    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.

  • fastcgi: This is a 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 the mod_fastcgis of Apache and lighttpd.

    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 99999
    

    The 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.

  • static: This protocol may be used to generate static web pages from Ur/Web code. The output executable 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 stdout.

• -root Name PATH: Trigger an alternate module convention for all source files found in directory PATH or any of its subdirectories. Any file PATH/foo.ur defines a module Name.Foo instead of the usual Foo. Any file PATH/subdir/foo.ur defines a module Name.Subdir.Foo, and so on for arbitrary nesting of subdirectories.

• -sigfile PATH: Same as the sigfile directive in .urp files

• -sql FILENAME: Set where a database set-up SQL script is written.

• -static: Link the runtime system statically. The default is to link against dynamic libraries.

• -stop PHASE: Stop compilation after the named phase, printing the intermediate program to stderr. This flag is mainly useful for debugging the Ur/Web compiler itself.

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.