# HG changeset patch
# User Adam Chlipala <adamc@hcoop.net>
# Date 1247939182 14400
# Node ID 0ae8894d5c97c229af94cd6911e843f46c095748
# Parent  ae9e22822ec5f33bfcd25ade510148a854e190f5
New command-line options; describe simple SQLite build in demo intro

diff -r ae9e22822ec5 -r 0ae8894d5c97 demo/prose
--- a/demo/prose	Sat Jul 18 12:53:26 2009 -0400
+++ b/demo/prose	Sat Jul 18 13:46:22 2009 -0400
@@ -1,6 +1,6 @@
 <p><b>Ur/Web</b> is a domain-specific language for programming web applications backed by SQL databases.  It is (strongly) statically-typed (like ML and Haskell) and purely functional (like Haskell).  <b>Ur</b> is the base language, and the web-specific features of Ur/Web (mostly) come only in the form of special rules for parsing and optimization.  The Ur core looks a lot like <a href="http://sml.sourceforge.net/">Standard ML</a>, with a few <a href="http://www.haskell.org/">Haskell</a>-isms added, and kinder, gentler versions added of many features from dependently-typed languages like the logic behind <a href="http://coq.inria.fr/">Coq</a>.  The type system is much more expressive than in ML and Haskell, such that well-typed web applications cannot "go wrong," not just in handling single HTTP requests, but across their entire lifetimes of interacting with HTTP clients.  Beyond that, Ur is unusual in using ideas from dependent typing to enable very effective metaprogramming, or programming with explicit analysis of type structure.  Many common web application components can be built by Ur/Web functions that operate on types, where it seems impossible to achieve similar code re-use in more established statically-typed languages.</p>
 
-<p>This demo is built automatically from Ur/Web sources and supporting files.  If you unpack the Ur/Web source distribution, then the following steps will build you a local version of this demo:
+<p>This demo is built automatically from Ur/Web sources and supporting files.  If you unpack the Ur/Web source distribution, then the following steps will (if you're lucky) build you a local version of this demo.  If you're not lucky, you can consult the beginning of <a href="http://www.impredicative.com/ur/manual.pdf">the manual</a> for more detailed instructions.
 
 <blockquote><pre>./configure
 make
@@ -24,6 +24,14 @@
 
 <p>Building the demo also generates a <tt>demo.sql</tt> file, giving the SQL commands to run to define all of the tables and sequences that the applications expect to see.  The file <tt>demo.urp</tt> contains a <tt>database</tt> line with the PostgreSQL database that the demo web server will try to connect to.</p>
 
+<p>The easiest way to get a demo running locally is probably with this alternate command sequence:
+
+<blockquote><pre>urweb -dbms sqlite -db /path/to/database/file -demo /Demo demo
+sqlite3 /path/to/database/file &lt;demo/demo.sql
+demo/demo.exe</pre></blockquote></p>
+
+<p>Then you can skip the static content and connect directly to the demo server at <tt>http://localhost:8080/Demo/Demo/main</tt>, which contains links to the individual demos.</p>
+
 <p>The rest of the demo focuses on the individual applications.  Follow the links in the lefthand frame to visit the applications, commentary, and syntax-highlighted source code.  (An Emacs mode is behind the syntax highlighting.)  I recommend visiting the applications in the order listed, since that is the order in which new concepts are introduced.</p>
 
 hello.urp
diff -r ae9e22822ec5 -r 0ae8894d5c97 doc/manual.tex
--- a/doc/manual.tex	Sat Jul 18 12:53:26 2009 -0400
+++ b/doc/manual.tex	Sat Jul 18 13:46:22 2009 -0400
@@ -56,24 +56,27 @@
 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
+\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 mlton libmhash-dev libpq-dev
+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:
@@ -165,6 +168,77 @@
 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}