Mercurial > urweb

comparison doc/manual.tex @ 1127:f93dc2ea30c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update manual for last two changesets
author Adam Chlipala <adamc@hcoop.net>
date Tue, 12 Jan 2010 11:19:02 -0500
parents 81ddb010751e
children a8921f5ef6bd
comparison
equal deleted inserted replaced
1126:c01fb6f1b31f 1127:f93dc2ea30c1
203 \end{verbatim} 203 \end{verbatim}
204 \end{itemize} 204 \end{itemize}
205 205
206 \item \texttt{-output FILENAME}: Set where the application executable is written. 206 \item \texttt{-output FILENAME}: Set where the application executable is written.
207 207
208 \item \texttt{-path NAME VALUE}: Set the value of path variable \texttt{\$NAME} to \texttt{VALUE}, for use in \texttt{.urp} files.
209
208 \item \texttt{-protocol [http|cgi|fastcgi]}: Set the protocol that the generated application speaks. 210 \item \texttt{-protocol [http|cgi|fastcgi]}: Set the protocol that the generated application speaks.
209 \begin{itemize} 211 \begin{itemize}
210 \item \texttt{http}: This is the default. It is for building standalone web servers that can be accessed by web browsers directly. 212 \item \texttt{http}: This is the default. It is for building standalone web servers that can be accessed by web browsers directly.
211 213
212 \item \texttt{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 \texttt{send} and \texttt{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. 214 \item \texttt{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 \texttt{send} and \texttt{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.
238 \end{verbatim} 240 \end{verbatim}
239 The least obvious requirement is setting \texttt{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. 241 The least obvious requirement is setting \texttt{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.
240 242
241 A FastCGI process reads the environment variable \texttt{URWEB\_NUM\_THREADS} to determine how many threads to spawn for handling client requests. The default is 1. 243 A FastCGI process reads the environment variable \texttt{URWEB\_NUM\_THREADS} to determine how many threads to spawn for handling client requests. The default is 1.
242 \end{itemize} 244 \end{itemize}
245
246 \item \texttt{-root Name PATH}: Trigger an alternate module convention for all source files found in directory \texttt{PATH} or any of its subdirectories. Any file \texttt{PATH/foo.ur} defines a module \texttt{Name.Foo} instead of the usual \texttt{Foo}. Any file \texttt{PATH/subdir/foo.ur} defines a module \texttt{Name.Subdir.Foo}, and so on for arbitrary nesting of subdirectories.
243 247
244 \item \texttt{-sql FILENAME}: Set where a database set-up SQL script is written. 248 \item \texttt{-sql FILENAME}: Set where a database set-up SQL script is written.
245 249
246 \item \texttt{-static}: Link the runtime system statically. The default is to link against dynamic libraries. 250 \item \texttt{-static}: Link the runtime system statically. The default is to link against dynamic libraries.
247 \end{itemize} 251 \end{itemize}
1975 \end{array}$$ 1979 \end{array}$$
1976 1980
1977 1981
1978 \section{The Structure of Web Applications} 1982 \section{The Structure of Web Applications}
1979 1983
1980 A web application is built from a series of modules, with one module, the last one appearing in the \texttt{.urp} file, designated as the main module. The signature of the main module determines the URL entry points to the application. Such an entry point should have type $\mt{unit} \to \mt{transaction} \; \mt{page}$, where $\mt{page}$ is a type synonym for top-level HTML pages, defined in $\mt{Basis}$. If such a function is at the top level of main module $M$, it will be accessible at URI \texttt{/M/f}, and so on for more deeply-nested functions, as described in Section \ref{tag} below. 1984 A web application is built from a series of modules, with one module, the last one appearing in the \texttt{.urp} file, designated as the main module. The signature of the main module determines the URL entry points to the application. Such an entry point should have type $\mt{t1} \to \ldots \to \mt{tn} \to \mt{transaction} \; \mt{page}$, for any integer $n \geq 0$, where $\mt{page}$ is a type synonym for top-level HTML pages, defined in $\mt{Basis}$. If such a function is at the top level of main module $M$, with $n = 0$, it will be accessible at URI \texttt{/M/f}, and so on for more deeply-nested functions, as described in Section \ref{tag} below. Arguments to an entry-point function are deserialized from the part of the URI following \texttt{f}.
1981 1985
1982 When the standalone web server receives a request for a known page, it calls the function for that page, ``running'' the resulting transaction to produce the page to return to the client. Pages link to other pages with the \texttt{link} attribute of the \texttt{a} HTML tag. A link has type $\mt{transaction} \; \mt{page}$, and the semantics of a link are that this transaction should be run to compute the result page, when the link is followed. Link targets are assigned URL names in the same way as top-level entry points. 1986 When the standalone web server receives a request for a known page, it calls the function for that page, ``running'' the resulting transaction to produce the page to return to the client. Pages link to other pages with the \texttt{link} attribute of the \texttt{a} HTML tag. A link has type $\mt{transaction} \; \mt{page}$, and the semantics of a link are that this transaction should be run to compute the result page, when the link is followed. Link targets are assigned URL names in the same way as top-level entry points.
1983 1987
1984 HTML forms are handled in a similar way. The $\mt{action}$ attribute of a $\mt{submit}$ form tag takes a value of type $\$\mt{use} \to \mt{transaction} \; \mt{page}$, where $\mt{use}$ is a kind-$\{\mt{Type}\}$ record of the form fields used by this action handler. Action handlers are assigned URL patterns in the same way as above. 1988 HTML forms are handled in a similar way. The $\mt{action}$ attribute of a $\mt{submit}$ form tag takes a value of type $\$\mt{use} \to \mt{transaction} \; \mt{page}$, where $\mt{use}$ is a kind-$\{\mt{Type}\}$ record of the form fields used by this action handler. Action handlers are assigned URL patterns in the same way as above.
1985 1989