10. Resources
*************

*AWS* support embedded resources. It means that it is possible to
build a fully self dependent executable. This is useful when
distributing a server. The server program contains the code but also
the images (*PNG*, *JPEG*, *GIF*), the templates, the *HTML* pages…
more generally any file the Web Server must serve to clients.


10.1. Building resources
========================

To embbed the files into the executable you must build a resource
tree. This task is greatly simplified using "AWSRes" tool. For example
let’s say that you want to build a simple server with a single page
containing some text and one PNG image. The text is handled directly
in the callback procedure and contain a reference to the image
"logo.png". To build the resource tree:

   $ awsres logo.png

This will create a set of packages whose root is the unit *res* by
default. The resource tree is created. See awsres tool for the
complete AWS’s usage description.

*awsres* can also compress the resource files. This can be done by
using *awsres*’s *-z* option. Compressed resources are handled
transparently. If the Web client supports compression the resource is
sent as-is otherwise a decompression stream will be created for the
resource to be decompressed on-the-fly while sending it.


10.2. Using resources
=====================

This is really the simplest step. The resource tree must be linked
with your executable, to do so you just have to ‘with’ the resource
tree root into one of your program unit. This will ensure that the
resource tree will be compiled and linked into the executable. *AWS*
and *Templates_Parser know* about resource files and will pick them up
if available.

Note that this is transparent to users. It is possible to build the
very same server based on standard files or resources files. The only
change in the code is to ‘with’ or not the resource tree.

Note that *AWS* supports only a single resource tree. If more than one
resource tree is included into a program only one will be seen.


10.3. Stream resources
======================

Users can build a response directly from a stream. In this case the
callback answer is built using *AWS.Response.Stream*. It creates a
resource object whose operations have been inherited from
*AWS.Resource.Stream.Stream_Type* and redefined by the user. So the
*Read* operation can dynamically create the result stream data, the
*End_Of_File* operation must returns *True* when the stream data is
out and so on. This feature is useful to let users completely create
and control dynamically *AWS*’s response content.

See AWS.Resources.Streams.


10.4. awsres tool
=================

*AWSRes* is a tool to build resource files. It creates a root package
named "res" by default and a child package for each resource file:

   Usage: awsres [-hopqrRuz] file1/dir1 [-uz] [file2/dir2...]

*-a*
   packages are named after the actual filenames

*-h*
   Display help message.

*-o*
   Specify the output directory, by default it is the current
   directory.

*-p name*
   Append the specified prefix to the resource names.

*-q*
   Quiet mode.

*-R*
   Activate recursive behavior. In this mode "awsres" will parse
   recursively all subdirectories. If a directory is specified on the
   command line then all files in this directory and sub-directories
   will be added. If a file (possibly a pattern) is specificed on the
   command line then only files matching in directroy and sub-
   directories will be added.

*-r name*
   Set the root unit name. Default is *res*.

*-u*
   Add following files as uncompressed resources.

*-z*
   Add following files as compressed resources.
