Ur/Web: doc/manual.tex comparison

comparison doc/manual.tex @ 896:0ae8894d5c97

New command-line options; describe simple SQLite build in demo intro

author	Adam Chlipala <adamc@hcoop.net>
date	Sat, 18 Jul 2009 13:46:22 -0400
parents	41971801b62d
children	2faf558b2d05

comparison

equal deleted inserted replaced

-:ae9e22822ec5
+:0ae8894d5c97
 ./configure
 make
 sudo make install
 \end{verbatim}
-Some other packages must be installed for the above to work.  At a minimum, you need a standard UNIX shell, with standard UNIX tools like sed and GCC in your execution path; MLton, the whole-program optimizing compiler for Standard ML; and the mhash C library.  To build programs that access SQL databases, you also need libpq, the PostgreSQL client library.  As of this writing, in the ``testing'' version of Debian Linux, this command will install the more uncommon of these dependencies:
+Some other packages must be installed for the above to work.  At a minimum, you need a standard UNIX shell, with standard UNIX tools like sed and GCC in your execution path; MLton, the whole-program optimizing compiler for Standard ML; and the mhash C library.  As of this writing, in the ``testing'' version of Debian Linux, this command will install the more uncommon of these dependencies:
 \begin{verbatim}
-apt-get install mlton libmhash-dev libpq-dev
+apt-get install mlton libmhash-dev
 \end{verbatim}
+To build programs that access SQL databases, you also need one of these client libraries for supported backends.
+\begin{verbatim}
+apt-get install libpq-dev libmysqlclient15-dev libsqlite3-dev
+\end{verbatim}
 It is also possible to access the modules of the Ur/Web compiler interactively, within Standard ML of New Jersey.  To install the prerequisites in Debian testing:
 \begin{verbatim}
 apt-get install smlnj libsmlnj-smlnj ml-yacc ml-lpt
 \end{verbatim}
 To begin an interactive session with the Ur compiler modules, run \texttt{make smlnj}, and then, from within an \texttt{sml} session, run \texttt{CM.make "src/urweb.cm";}.  The \texttt{Compiler} module is the main entry point.
-To run an SQL-backed application, you will probably want to install the PostgreSQL server.  Version 8.3 or higher is required.
+To run an SQL-backed application with a backend besides SQLite, you will probably want to install one of these servers.
 \begin{verbatim}
-apt-get install postgresql-8.3
+apt-get install postgresql-8.3 mysql-server-5.0
 \end{verbatim}
 To use the Emacs mode, you must have a modern Emacs installed.  We assume that you already know how to do this, if you're in the business of looking for an Emacs mode.  The demo generation facility of the compiler will also call out to Emacs to syntax-highlight code, and that process depends on the \texttt{htmlize} module, which can be installed in Debian testing via:
 \begin{verbatim}
 To time how long the different compiler phases run, without generating an executable, run
 \begin{verbatim}
 urweb -timing P
 \end{verbatim}
+Some other command-line parameters are accepted:
+\begin{itemize}
+\item \texttt{-db <DBSTRING>}: Set database connection information, using the format expected by Postgres's \texttt{PQconnectdb()}, which is \texttt{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 \texttt{host}, \texttt{hostaddr}, \texttt{port}, \texttt{dbname}, \texttt{user}, and \texttt{password}.  The only significant setting for SQLite is \texttt{dbname}, which is interpreted as the filesystem path to the database.  Additionally, when using SQLite, a database string may be just a file path.
+\item \texttt{-dbms [postgres|mysql|sqlite]}: Sets the database backend to use.
+\begin{itemize}
+\item \texttt{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 \texttt{app.sql} generated by the compiler:
+\begin{verbatim}
+createdb app
+psql -f app.sql app
+\end{verbatim}
+\item \texttt{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 \texttt{.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:
+\begin{verbatim}
+echo "CREATE DATABASE app" | mysql
+mysql -D app <app.sql
+\end{verbatim}
+\item \texttt{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:
+\begin{verbatim}
+sqlite3 path/to/database/file <app.sql
+\end{verbatim}
+\end{itemize}
+\item \texttt{-output FILENAME}: Set where the application executable is written.
+\item \texttt{-protocol [http|cgi|fastcgi]}: Set the protocol that the generated application speaks.
+\begin{itemize}
+\item \texttt{http}: This is the default.  It is for building standalone web servers that can be accessed by web browsers directly.
+\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.
+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 \texttt{/Hello}:
+\begin{verbatim}
+ScriptAlias /Hello /path/to/hello.exe
+\end{verbatim}
+\item \texttt{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 \texttt{mod\_fastcgi}s of Apache and lighttpd.
+To configure a FastCGI program with Apache, one could combine the above \texttt{ScriptAlias} line with a line like this:
+\begin{verbatim}
+FastCgiServer /path/to/hello.exe -idle-timeout 99999
+\end{verbatim}
+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.
+Here is some lighttpd configuration for the same application.
+\begin{verbatim}
+fastcgi.server = (
+"/Hello/" =>
+(( "bin-path" => "/path/to/hello.exe",
+"socket" => "/tmp/hello",
+"check-local" => "disable",
+"docroot" => "/",
+"max-procs" => "1"
+))
+)
+\end{verbatim}
+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.
+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.
+\end{itemize}
+\item \texttt{-sql FILENAME}: Set where a database set-up SQL script is written.
+\end{itemize}
 \section{Ur Syntax}
 In this section, we describe the syntax of Ur, deferring to a later section discussion of most of the syntax specific to SQL and XML.  The sole exceptions are the declaration forms for relations, cookies, and styles.

Mercurial > urweb

comparison doc/manual.tex @ 896:0ae8894d5c97