| |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title></title> |
| <link rel="stylesheet" href="style.css"> |
| </head> |
| <body> |
| |
| |
| <!-- $Id$ --> |
| <h2 align="center">mod_dtcl Installation</h2> |
| |
| <ol> |
| <li><b>Check dependencies</b><br> |
| |
| To install mod_dtcl, you will need <b>Tcl 8.2</b> or greater |
| and <b>Apache 1.3.xx</b>. It is known to run on Linux, |
| FreeBSD, OpenBSD, and Solaris and HPUX. NT is also possible - |
| please see the directions in the distribution. |
| </li> |
| |
| <li><b>Get mod_dtcl</b><br> |
| If you are running a Debian or FreeBSD system, there |
| are pre-built packages available at: |
| <a target="_top" href="http://www.debian.org/Packages/unstable/web/libapache-mod-dtcl.html">http://www.debian.org/Packages/unstable/web/libapache-mod-dtcl.html</a> |
| |
| or |
| |
| <a |
| target="_top" href="http://www.freebsd.org/cgi/ports.cgi?query=mod_dtcl">http://www.freebsd.org/cgi/ports.cgi?query=mod_dtcl</a>.<br> |
| |
| Otherwise, download the sources at <a target="_top" |
| href="download/">http://tcl.apache.org/mod_dtcl/download/</a>. |
| <br> |
| </li> |
| <li><b>Uncompress the sources</b><br> |
| <code> |
| gunzip apache-1.3.X.tar.gz<br> |
| tar -xvf apache-1.3.X.tar.gz<br> |
| </code> |
| You don't need the Apache sources if you are building a shared |
| object module. You do, however, need the header files. |
| Some systems, such as Debian GNU/Linux, provide these |
| independently - otherwise, you probably still need the sources.<br> |
| <code> |
| gunzip mod_dtcl-X.X.X.tar.gz<br> |
| tar -xvf mod_dtcl-X.X.X.tar.gz<br> |
| </code> |
| </li> |
| |
| <li><b>Configuring, builddtcl.sh, etc...</b><br> |
| |
| Do you want to build mod_dtcl as a shared object (such as a |
| .so file on Linux, or a .dll on windows), or compile it |
| directly as a part of the Apache executable? The Apache |
| Software Foundation has put together a nice <a target="_top" |
| href="http://httpd.apache.org/docs/dso.html">manual</a> which |
| explains things in detail. |
| |
| <ul> |
| <li><b>For shared objects</b><br> |
| |
| <code>cd ../mod_dtcl/<br></code> |
| Edit the <code>builddtcl.sh</code> script. The 3 |
| variables you may need to change are: |
| <ul> |
| <li><code>TCLSH</code><br> |
| Name of the tclsh program on your computer. |
| </li> |
| <li><code>APACHE</code><br> |
| Location of the Apache sources (for static builds only). |
| </li> |
| <li><code>INC</code><br> |
| Location of the Apache headers (you will need this even |
| for building shared objects). |
| </li> |
| </ul> |
| |
| <code> |
| ./builddtcl.sh shared |
| </code><br> |
| |
| <code> |
| cp mod_dtcl.so |
| /usr/lib/apache/wherever/the/other/shared/objects/reside |
| </code> For shared object builds, you need to copy the |
| object into the directory where the other shared |
| objects are kept for your Apache build. On Debian |
| GNU/Linux systems, for instance, this is in |
| <code>/usr/lib/apache/1.3/</code>. |
| |
| </li> |
| |
| <li><b>For static builds</b><br> |
| <code> |
| cd apache-1.3.X/<br> |
| ./configure<br> |
| </code> |
| |
| <code>cd ../mod_dtcl/<br></code> |
| Edit the <code>builddtcl.sh</code> script. The 3 |
| variables you may need to change are: |
| <ul> |
| <li><code>TCLSH</code><br> |
| Name of the tclsh program on your computer. |
| </li> |
| <li><code>APACHE</code><br> |
| Location of the Apache sources (for static builds only). |
| </li> |
| <li><code>INC</code><br> |
| Location of the Apache headers (you will need this even |
| for building shared objects). |
| </li> |
| </ul> |
| |
| <code> |
| ./builddtcl.sh static |
| </code><br> |
| |
| <code> |
| ./builddtcl.sh install |
| </code><br> |
| |
| <code>cd ../apache-1.3.X<br></code> |
| <code>./configure |
| --activate-module=src/modules/mod_dtcl/mod_dtcl.a [ other configure |
| options ]<br></code> |
| <code>export EXTRA_LIBS="-ltcl8.X -lm"</code><br> |
| <code>make -e<br></code> |
| <code>make install<br></code> |
| |
| </li> |
| </ul> |
| </li> |
| <li><b>Configure Apache<br></b> |
| <ul> |
| <li> |
| <b>http.conf</b><br> <code>LoadModule dtcl_module |
| /usr/lib/apache/1.3/mod_dtcl.so</code><br> |
| This points Apache to the shared object if |
| mod_dtcl is being used as a loadable module. |
| </li> |
| <li> |
| <b>srm.conf</b><br> |
| <code>AddType application/x-httpd-tcl .ttml</code><br> |
| <code>AddType application/x-dtcl-tcl .tcl</code> |
| (optional)<br> |
| These add the .ttml and .tcl (if desired) types to |
| Apache, so that they are processed by mod_dtcl. |
| </li> |
| </ul> |
| </li> |
| </ol> |
| |
| <h2 align="center">mod_dtcl Apache directives</h2> |
| |
| <ul> |
| <li> |
| <code><b>Dtcl_Script GlobalInitScript <i>"script"</i></code></b><br> |
| Tcl script that is run when each interpreter is |
| initialized. <code>"script"</code> is actual Tcl |
| script, so to run a file, you would do |
| <code>Dtcl_Script GlobalInitScript "source /var/www/foobar.tcl"</code>. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_Script ChildInitScript <i>"script"</i></b></code><br> |
| Script to be evaluated when each apache child is |
| initialized. This is the best place to load modules. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_Script ChildExitScript <i>"script"</i></b></code><br> |
| Script to be evaluated when each apache child exits. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_Script BeforeScript <i>"script"</i></b></code><br> |
| Script to be evaluated before each .ttml page. |
| <strong>Note</strong> that you cannot use |
| <code>hputs</code> in the BeforeScript, but must |
| instead use <code>buffer_add</code>. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_Script AfterScript <i>"script"</i></b></code><br> |
| Script to be called after each .ttml page. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_Script ErrorScript <i>"script"</i></b></code><br> |
| This code is called in place of the standard 'error' pages |
| generated for mod_dtcl. This directive may be useful if you |
| have sensitive logic that you wish to protect. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_CacheSize <i>cachesize</i></b></code><br> |
| Number of ttml scripts to cache as Tcl Objects. |
| Default is MaxRequestsPerChild / 2, or 50, if |
| MaxRequestsPerChild is 0. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_UploadFilesToVar <i>on/off</i></b></code><br> If |
| on, files will be uploaded to the variable UPLOAD(data). Be |
| careful with this, as large files could use up your memory. |
| </li> |
| |
| <li> |
| <code><b>Dtcl_SeperateVirtualInterps |
| <i>on/off</i></b></code><br> If on, each VirtualHost will have |
| its own Tcl interpreter. |
| </li> |
| |
| </ul> |
| |
| <h2 align="center">mod_dtcl specific Tcl commands and variables</h2> |
| |
| <ul> |
| <li> |
| <code><b>buffer_add <i>string</i></b></code><br> |
| Add text to output_buffer for later printing. Used |
| internally. |
| </li> |
| |
| <li> |
| <code><b>hputs <i>?-error? text</i></b></code><br> |
| The mod_dtcl version of "puts". Outputs to the |
| client, instead of to stdout. |
| The error option permits you to send an 'error message' to the |
| apache log file, at the NOTICE level. |
| </li> |
| <li><code><b>var</b></code><br> These commands retrieve or |
| retrieve information about "CGI" variables that are passed to |
| the dtcl script via GET or POST operations. |
| </li> |
| <li> |
| <code><b>var get <i>varname</i></b></code><br> Returns the |
| value of variable 'varname' as a string (even if there are |
| multiple values). |
| </li> |
| <li> |
| <code><b>var list <i>varname</i></b></code><br> |
| Returns the value of variable 'varname' as a list, if there |
| are multiple values. |
| </li> |
| <li> |
| <code><b>var exists <i>varname</i></b></code><br> |
| Returns 1 if <i>varname</i> exists, 0 if it doesn't. |
| </li> |
| <li> |
| <code><b>var number</b></code><br> |
| Returns the number of variables. |
| </li> |
| <li> |
| <code><b>var all</b></code><br> |
| Return a list of variable names and values. |
| </li> |
| |
| <li><code><b>upload</b></code><br> These commands retrieve or |
| retrieve information about files that have been uploaded to |
| the server. They replace the <code>UPLOAD</code> variable. |
| </li> |
| <li> |
| <code><b>upload get <i>varname</i> channel</b></code><br> |
| Returns a Tcl channel that can be used to access the uploaded file. |
| </li> |
| <li> |
| <code><b>upload get <i>varname</i> save <i>name</i></b></code><br> |
| Moves the uploaded file to the give name. |
| </li> |
| <li> |
| <code><b>upload get <i>varname</i> data</b></code><br> |
| Returns data uploaded to the server. This is binary clean. |
| </li> |
| |
| <li> |
| <code><b>upload info <i>varname</i> exists</b></code><br> |
| Returns 1 if the variable exists, 0 if not. |
| </li> |
| <li> |
| <code><b>upload info <i>varname</i> size</b></code><br> |
| Returns the size of the file uploaded. |
| </li> |
| <li> |
| <code><b>upload info <i>varname</i> type</b></code><br>If the |
| Content-type is set, it is returned, otherwise, an empty |
| string. |
| </li> |
| <li> |
| <code><b>upload info <i>varname</i> filename</b></code><br> |
| Returns the filename on the remote host that uploaded the file. |
| </li> |
| <li> |
| <code><b>upload names</b></code><br> Returns the variable |
| names, as a list, of all the files uploaded. |
| </li> |
| |
| <li> |
| <code><b>hgetvars</b></code><br> Get environmental, and Cookie |
| variables. This is in a seperate command so as not to make the |
| server do this every time you load a .ttml file. <code>ENVS</code> and |
| <code>COOKIES</code> are the associative arrays created. <code>ENVS</code> contains |
| environmental variables, and <code>COOKIES</code> contains any cookies |
| recieved from the client. |
| </li> |
| <li> |
| <code><b>include <i>filename</i></b></code><br> |
| Include a file without parsing it. This is the best |
| way to include an HTML file or any other static content. |
| </li> |
| <li> |
| <code><b>parse <i>filename</i></b></code><br> |
| "Source" a .ttml file. This is the way to include |
| other .ttml files. |
| </li> |
| <li> |
| <code><b>hflush</b></code><br> |
| Flush the output buffers to the client. Use this if |
| you want to incrementally update a page. |
| </li> |
| <li> |
| <code><b>headers redirect <i>uri</i></b></code><br> |
| |
| Redirect from the current page to a new |
| URI. <b>Must</b> be done in the first block of TCL code. |
| </li> |
| <li> |
| <code><b>headers setcookie <i>-name cookie-name |
| -value cookie-value ?-expires date/time? ?-domain domain? |
| ?-path path? ?-secure?</i></b></code><br> |
| |
| This command is for setting cookies. Cookie-name is |
| the name of the cookie, cookie-value is the data |
| associated with the variable. Expires sets an |
| expiration date for the cookie, and must be in the |
| format 'DD-Mon-YY HH:MM:SS', path sets the path for |
| which the cookie is valid, and secure specifies that |
| the cookie is only to be transmitted if the connection |
| is secure (HTTPS). |
| </li> |
| <li> |
| <code><b>headers type |
| <i>content-type</i></b></code><br> |
| |
| This command sets the "Content-type:" header returned |
| by the script, which is useful if you wish to create a |
| PNG (image), for example, with mod_dtcl. |
| </li> |
| <li> |
| <code><b>headers set <i>headername value</i></b></code><br> |
| |
| Set arbitrary header names and values. |
| </li> |
| |
| <li> |
| <code><b>makeurl <i>filename</i></b></code><br> |
| |
| Create a self referencing URL from a filename. For example: |
| <code>makeurl /tclp.gif</code> returns |
| http://[hostname]:[port]/tclp.gif. |
| </li> |
| |
| <li> |
| <code><b>dtcl_info</b></code><br> |
| |
| Prints information on the internals of the module in |
| HTML. Currently, only the PID and size of the object |
| cache are reported. |
| </li> |
| <!-- |
| <li> |
| Note that these variables may be lists if more than one file |
| is uploaded at a time.<br> |
| <code><b>$::request::UPLOAD(filename)</b></code><br> |
| The filename of the uploaded file.<br> |
| |
| <code><b>$::request::UPLOAD(name)</b></code><br> |
| The form variable name of the upload.<br> |
| |
| <code><b>$::request::UPLOAD(size)</b></code><br> |
| The size of the uploaded file.<br> |
| |
| <code><b>$::request::UPLOAD(type)</b></code><br> |
| The content type of the file upload. <i>Not always available!</i><br> |
| |
| <code><b>$::request::UPLOAD(channelname)</b></code><br> The |
| name of a Tcl channel which may be used to manipulate the |
| uploaded file. If Dtcl_UploadFilesToVar is set, this |
| variable doesn't get created. If no file is passed to the |
| server, this variable does not exist! Be sure to check for |
| this.<br> |
| |
| <code><b>$::request::UPLOAD(data)</b></code><br> |
| Contents of the uploaded file, if Dtcl_UploadFilesToVar is |
| set.<br> |
| </li> |
| --> |
| </ul> |
| <h2>Other mod_dtcl Documentation</h2> |
| |
| <h3>Internals</h3> |
| <ul> |
| <li><b>Read the code!</b></li> |
| <li> |
| <b>Initialization</b><br> |
| |
| When Apache is started, (or when child Apache |
| processes are started if a threaded Tcl is used), |
| <code>tcl_init_stuff</code> is called, which creates |
| a new interpreter, and initializes various things, |
| like the <code>apache_channel</code> channel system. |
| The caching system is also set up, and if there is a |
| GlobalScript, it is run. |
| </li> |
| <li><b>Achan/apache_channel</b><br> |
| |
| The "Apache Channel" system was created so that it is |
| possible to have an actual Tcl channel that we could |
| redirect standard output to. This lets us use, for |
| instance, the regular "puts" command in .ttml pages. |
| It works by creating commands that write to memory |
| that is slated to be sent to the client. |
| </li> |
| |
| <li><b>Page parsing/execution</b><br> |
| |
| In <code>send_parsed_file</code> Each .ttml file is |
| loaded and run within its own namespace. No new |
| interpreter is created for each page. This lets you |
| share variables, and most importantly, loaded modules, |
| from a common parent (such as one of the InitScripts). |
| When a file is loaded, it is transformed into a Tcl |
| script by putting everything outside of <? and |
| ?> into large hputs statements. When the script is |
| complete, it is then inserted into the cache, for |
| future use. In fact, if the file modification |
| information doesn't change, mod_dtcl will execute the |
| cached version of the script the next time it is |
| encountered. |
| </li> |
| <li><b>Binary data</b><br> |
| mod_dtcl is capable of outputing binary data, such as |
| images, or loading binary data with 'include'. |
| </li> |
| </ul> |
| |
| <h3>Upgrading From Older (< 0.9.3) Versions</h3> |
| <ul> |
| <li><b>New tags</b><br> As of version 0.9.4, mod_dtcl uses |
| <? and ?> instead of <+ and +> to delimit |
| sections of Tcl code. By default, dtcl is still compiled |
| with code to parse the <? ?> tags, but it will run |
| faster if <code>USE_OLD_TAGS</code> is set to 0 in |
| <code>mod_dtcl.h</code>. You can automatically change your |
| .ttml files to the new format by using the |
| <code>newtags.sh</code> script in the contrib/ directory. |
| Run it at the top level of your DocumentRoot. |
| </li> |
| <li><b>headers setcookie</b><br> |
| The <code>headers setcookie</code> command now uses the |
| <code>-name</code> and <code>-value</code> flags for those |
| arguments, whereas this was not necessary in the past. |
| </li> |
| </ul> |
| |
| <h3>Getting Help</h3> |
| <ul> |
| <li><b>Mailing list</b><br> |
| <p> |
| The mod_dtcl mailing list is the best place to go for help |
| when you have problems. |
| </p> |
| <p> |
| See the <a |
| target="_top" href="http://tcl.apache.org/mod_dtcl/contact.html">Contact</a> |
| page for information on sending |
| mail/subscribing. |
| </p> |
| <p> |
| Mailing list archives are also available at <a |
| target="_top" href="http://archive.covalent.net">http://archive.covalent.net</a>, |
| at the bottom of the page. |
| </p> |
| </li> |
| </ul> |
| |
| </body> |
| </html> |
| |