README
README_custom
1You can use TclHTTPD "out of the box" to implement a basic Web server.
2However, if you want to create your own Web application, you'll want
3to integrate your own custom Tcl code with the server.
4
5*** Custom Code Directory ***
6
7The recommended way to do this is to create Tcl packages for your
8functionality and put them into a "custom code" directory.
9The "custom" directory of the distribution has some trivial examples.
10
11Specify the location of the custom code directory with the -library
12command line argument or the "library" .rc file Config specification.
13The files in this directory are sourced in alphabetical order.
14If you run with "-debug 1" then you'll see feedback as these are loaded.
15
16If you do not need to substantially change the way the default server
17works, but instead just add more stuff, then you are done. Otherwise...
18
19*** Modifing the server startup code ***
20
21The Tcl scripts that start up the server are divided into three files.
22You will end up modifying one or more of the following files:
23
24bin/httpd.tcl
25 (The main program)
26 This main script processes command line arguments,
27 loads the configuration file,
28 starts the Http server,
29 loads the per-thread httpdthread.tcl file,
30 and enters the event loop.
31
32 This file embodies assumptions about the installation directory
33 structure. If you repackage TclHttpd, you'll probably have
34 to modify this file.
35
36bin/tclhttpd.rc
37 (The Configuration File)
38 This script is sourced before the command line arguments are processed.
39 Its use is limited to setting simple parameters. Typically these
40 correspond to command line arguments. However, you are free to
41 add new Config parameters. If you have
42 Config foo "The value of foo"
43 in your .rc file, then you can access that value by using the
44 config::cget foo
45 command, or (if you haven't changed bin/httpd.tcl) by using the
46 global Config array:
47 global Config
48 set foovalue $Config(foo)
49
50bin/httpdthread.tcl
51 (The per-thread main program)
52 This file is sourced by the main interpreter, and again by
53 each worker thread if you are using threads.
54 This file starts up most of the packages associated with a normal
55 web server. At the very end it loads all the code from the custom
56 code directory described above.
57
58 If you need to disable some of the standard web server features,
59 you may need to edit this file. You can select a different version
60 of this file with the "-main" command line argument, or the
61 "main" .rc Config specification.
62
63*** Starting the server ***
64 If you have created copies of the configuration
65 file and per-thread startup file, you'll need to specify those
66 on the command line:
67
68 tclsh httpd.tcl -config my.rc -main mythread.tcl
69
70 or you can also create a modified copy of httpd.tcl that embeds the
71 names of the other custom files, so starting the server reduces to
72
73 tclsh myhttpd.tcl
74
75