Mercurial > urweb

comparison doc/manual.tex @ 1523:52fbd8534ef3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Remove some GCC-specific identifier choice and documentation
author Adam Chlipala <adam@chlipala.net>
date Tue, 02 Aug 2011 14:45:19 -0400
parents 4d0b80dd4c37
children 09c56e03beaf
comparison
equal deleted inserted replaced
1522:4d0b80dd4c37 1523:52fbd8534ef3
54 ./configure 54 ./configure
55 make 55 make
56 sudo make install 56 sudo make install
57 \end{verbatim} 57 \end{verbatim}
58 58
59 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 development files for the OpenSSL C library. As of this writing, in the ``testing'' version of Debian Linux, this command will install the more uncommon of these dependencies: 59 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 (or an alternate C compiler) in your execution path; MLton, the whole-program optimizing compiler for Standard ML; and the development files for the OpenSSL C library. As of this writing, in the ``testing'' version of Debian Linux, this command will install the more uncommon of these dependencies:
60 \begin{verbatim} 60 \begin{verbatim}
61 apt-get install mlton libssl-dev 61 apt-get install mlton libssl-dev
62 \end{verbatim} 62 \end{verbatim}
63 63
64 To build programs that access SQL databases, you also need one of these client libraries for supported backends. 64 To build programs that access SQL databases, you also need one of these client libraries for supported backends.
85 apt-get install emacs-goodies-el 85 apt-get install emacs-goodies-el
86 \end{verbatim} 86 \end{verbatim}
87 87
88 If you don't want to install the Emacs mode, run \texttt{./configure} with the argument \texttt{--without-emacs}. 88 If you don't want to install the Emacs mode, run \texttt{./configure} with the argument \texttt{--without-emacs}.
89 89
90 Even with the right packages installed, configuration and building might fail to work. After you run \texttt{./configure}, you will see the values of some named environment variables printed. You may need to adjust these values to get proper installation for your system. To change a value, store your preferred alternative in the corresponding UNIX environment variable, before running \texttt{./configure}. For instance, here is how to change the list of extra arguments that the Ur/Web compiler will pass to GCC on every invocation. Some older GCC versions need this setting to mask a bug in function inlining. 90 Even with the right packages installed, configuration and building might fail to work. After you run \texttt{./configure}, you will see the values of some named environment variables printed. You may need to adjust these values to get proper installation for your system. To change a value, store your preferred alternative in the corresponding UNIX environment variable, before running \texttt{./configure}. For instance, here is how to change the list of extra arguments that the Ur/Web compiler will pass to the C compiler and linker on every invocation. Some older GCC versions need this setting to mask a bug in function inlining.
91 91
92 \begin{verbatim} 92 \begin{verbatim}
93 GCCARGS=-fno-inline ./configure 93 CCARGS=-fno-inline ./configure
94 \end{verbatim} 94 \end{verbatim}
95 95
96 Since the author is still getting a handle on the GNU Autotools that provide the build system, you may need to do some further work to get started, especially in environments with significant differences from Linux (where most testing is done). The variables \texttt{PGHEADER}, \texttt{MSHEADER}, and \texttt{SQHEADER} may be used to set the proper C header files to include for the development libraries of PostgreSQL, MySQL, and SQLite, respectively. To get libpq to link, one OS X user reported setting \texttt{GCCARGS="-I/opt/local/include -L/opt/local/lib/postgresql84"}, after creating a symbolic link with \texttt{ln -s /opt/local/include/postgresql84 /opt/local/include/postgresql}. 96 Since the author is still getting a handle on the GNU Autotools that provide the build system, you may need to do some further work to get started, especially in environments with significant differences from Linux (where most testing is done). The variables \texttt{PGHEADER}, \texttt{MSHEADER}, and \texttt{SQHEADER} may be used to set the proper C header files to include for the development libraries of PostgreSQL, MySQL, and SQLite, respectively. To get libpq to link, one OS X user reported setting \texttt{CCARGS="-I/opt/local/include -L/opt/local/lib/postgresql84"}, after creating a symbolic link with \texttt{ln -s /opt/local/include/postgresql84 /opt/local/include/postgresql}.
97 97
98 The Emacs mode can be set to autoload by adding the following to your \texttt{.emacs} file. 98 The Emacs mode can be set to autoload by adding the following to your \texttt{.emacs} file.
99 99
100 \begin{verbatim} 100 \begin{verbatim}
101 (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/urweb-mode") 101 (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/urweb-mode")
161 \item \texttt{script}: maximum size (in bytes) of per-request buffer used to hold JavaScript content of generated pages 161 \item \texttt{script}: maximum size (in bytes) of per-request buffer used to hold JavaScript content of generated pages
162 \item \texttt{subinputs}: maximum number of form fields per request, excluding top-level fields 162 \item \texttt{subinputs}: maximum number of form fields per request, excluding top-level fields
163 \item \texttt{time}: maximum running time of a single page request, in units of approximately 0.1 seconds 163 \item \texttt{time}: maximum running time of a single page request, in units of approximately 0.1 seconds
164 \item \texttt{transactionals}: maximum number of custom transactional actions (e.g., sending an e-mail) that may be run in a single page generation 164 \item \texttt{transactionals}: maximum number of custom transactional actions (e.g., sending an e-mail) that may be run in a single page generation
165 \end{itemize} 165 \end{itemize}
166 \item \texttt{link FILENAME} adds \texttt{FILENAME} to the list of files to be passed to the GCC linker at the end of compilation. This is most useful for importing extra libraries needed by new FFI modules. 166 \item \texttt{link FILENAME} adds \texttt{FILENAME} to the list of files to be passed to the linker at the end of compilation. This is most useful for importing extra libraries needed by new FFI modules.
167 \item \texttt{minHeap NUMBYTES} sets the initial size for thread-local heaps used in handling requests. These heaps grow automatically as needed (up to any maximum set with \texttt{limit}), but each regrow requires restarting the request handling process. 167 \item \texttt{minHeap NUMBYTES} sets the initial size for thread-local heaps used in handling requests. These heaps grow automatically as needed (up to any maximum set with \texttt{limit}), but each regrow requires restarting the request handling process.
168 \item \texttt{noXsrfProtection URIPREFIX} turns off automatic cross-site request forgery protection for the page handler identified by the given URI prefix. This will avoid checking cryptographic signatures on cookies, which is generally a reasonable idea for some pages, such as login pages that are going to discard all old cookie values, anyway. 168 \item \texttt{noXsrfProtection URIPREFIX} turns off automatic cross-site request forgery protection for the page handler identified by the given URI prefix. This will avoid checking cryptographic signatures on cookies, which is generally a reasonable idea for some pages, such as login pages that are going to discard all old cookie values, anyway.
169 \item \texttt{onError Module.var} changes the handling of fatal application errors. Instead of displaying a default, ugly error 500 page, the error page will be generated by calling function \texttt{Module.var} on a piece of XML representing the error message. The error handler should have type $\mt{xbody} \to \mt{transaction} \; \mt{page}$. Note that the error handler \emph{cannot} be in the application's main module, since that would register it as explicitly callable via URLs. 169 \item \texttt{onError Module.var} changes the handling of fatal application errors. Instead of displaying a default, ugly error 500 page, the error page will be generated by calling function \texttt{Module.var} on a piece of XML representing the error message. The error handler should have type $\mt{xbody} \to \mt{transaction} \; \mt{page}$. Note that the error handler \emph{cannot} be in the application's main module, since that would register it as explicitly callable via URLs.
170 \item \texttt{path NAME=VALUE} creates a mapping from \texttt{NAME} to \texttt{VALUE}. This mapping may be used at the beginnings of filesystem paths given to various other configuration directives. A path like \texttt{\$NAME/rest} is expanded to \texttt{VALUE/rest}. There is an initial mapping from the empty name (for paths like \texttt{\$/list}) to the directory where the Ur/Web standard library is installed. If you accept the default \texttt{configure} options, this directory is \texttt{/usr/local/lib/urweb/ur}. 170 \item \texttt{path NAME=VALUE} creates a mapping from \texttt{NAME} to \texttt{VALUE}. This mapping may be used at the beginnings of filesystem paths given to various other configuration directives. A path like \texttt{\$NAME/rest} is expanded to \texttt{VALUE/rest}. There is an initial mapping from the empty name (for paths like \texttt{\$/list}) to the directory where the Ur/Web standard library is installed. If you accept the default \texttt{configure} options, this directory is \texttt{/usr/local/lib/urweb/ur}.
171 \item \texttt{prefix PREFIX} sets the prefix included before every URI within the generated application. The default is \texttt{/}. 171 \item \texttt{prefix PREFIX} sets the prefix included before every URI within the generated application. The default is \texttt{/}.
2380 2380
2381 The program is translated to what is more or less a subset of C. If any use of functions as data remains at this point, the compiler will complain. 2381 The program is translated to what is more or less a subset of C. If any use of functions as data remains at this point, the compiler will complain.
2382 2382
2383 \subsection{C Compilation and Linking} 2383 \subsection{C Compilation and Linking}
2384 2384
2385 The output of the last phase is pretty-printed as C source code and passed to GCC. 2385 The output of the last phase is pretty-printed as C source code and passed to the C compiler.
2386 2386
2387 2387
2388 \end{document} 2388 \end{document}