Provided by: urweb_20170720+dfsg-2build1_amd64 bug


       urweb - compiler for the Ur/Web programming language


       urweb [option ...] [project-name]
       urweb daemon (start|stop)


       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,  while  the  second  invocation
       controls the type inference daemon (see TYPE INFERENCE DAEMON).  For simple projects, only
       familiarity with the first invocation is required.


       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(1)  by
              default, but clang(1) 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

              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.

              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

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

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

              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:

                     maximum number of cleanup operations (e.g., entries recording  the  need  to
                     deallocate certain temporary objects) that may be active at once per request

                     maximum number of clients that can be simultaneously blocked waiting for new
                     messages (sent by Basis.send)

                     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

                     maximum number of global variables that FFI libraries may set  in  a  single
                     request context

                     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

                     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

                     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

                     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
              //  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, 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  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 //, you  should  specify
                     /directory/myapp.exe/  as  the  application  prefix.  See section 3.2 of the
                     Ur/Web reference manual for more information.

                     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.

              Instructs urweb to statically link the generated executable.

              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.

              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.

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

   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.

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

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

              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.

              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.

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

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

              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.


       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


       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,


       urweb is copyright © 2008-2017 Adam Chlipala and licensed under the 3-clause BSD license

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

                                            2017-07-20                                   URWEB(1)