From feeb4029f89a09f44f054a08ab61fe71005308fa Mon Sep 17 00:00:00 2001 From: Adam Chlipala Date: Sat, 18 Jul 2009 13:46:22 -0400 Subject: New command-line options; describe simple SQLite build in demo intro --- doc/manual.tex | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 79 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/manual.tex b/doc/manual.tex index 3b57dc1b..c28d9610 100644 --- a/doc/manual.tex +++ b/doc/manual.tex @@ -56,24 +56,27 @@ 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 +\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 @@ To time how long the different compiler phases run, without generating an execut urweb -timing P \end{verbatim} +Some other command-line parameters are accepted: +\begin{itemize} +\item \texttt{-db }: 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 + (( "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} -- cgit v1.2.3