INSTALL.TXT -- Building and Installing the Mbedthis AppWeb Source Code.
--------------------------------------------------------------------------------

This file describes how to get and build the Mbedthis AppWeb source code.
You can read more about building from source and other topics in the HTML 
documentation under:

    doc/appWeb/index.html


Getting the Source Code
-----------------------

You can get the source code from the Mbedthis web site at:

    http://www.mbedthis.com/downloads/appWeb/

The web site contains source code for the latest stable or development builds. 
Alternatively, you can check out the current source code from the main 
Mbedthis Subversion source code repository. This will contain the latest 
features but in an untested and ongoing development status. See "Building
from the Repository" at the end of this document more details.

If you are wanting to build on a supported platform, use the following steps 
to build the source code. If you are wanting to port to a new platform, please
read doc/appWeb/source/porting.html.


Development Environment Platform Support
----------------------------------------

If you wish to build the samples or rebuild Mbedthis AppWeb from source code, 
you will need to use a C++ compiler and associated development tools. Several 
development environments are supported. You may choose any of the following 
to compile and build samples and source code.

    * Linux GNU tools
    * Windows Visual Studio 6 or Windows Visual Studio .NET
    * Windows Cygwin GNU emulation

On Windows, you can use the supplied Microsoft Visual Studio projects under the 
VisualStudio directory for building and debugging, but the projects cannot
alter the configured features or modules. To use the "./configure" program,
you will need to install the Cygwin GNU emulation software.

The Mbedthis build system is a cross-platform build mechanism that supports 
Unix and Windows. To use the build system on Windows requires that the Cygwin 
UNIX emulation environment be installed. The build system still uses the 
Microsoft Visual Studio compiler and debugger, but it relies on the cygwin 
make and other utilities to perform batch compiles and to control which
modules are built. To get Cygwin, go to:

    http://www.cygwin.com

On windows, AppWeb requires Microsoft Visual Studio 6.0 service pack 5 or later.
AppWeb will build on any Linux 2.4 or later release.


Setup the Environment
---------------------

On UNIX, you will need to setup your environment if you wish to debug programs
directly in your build tree. If you only wish to build and install without
running in the build tree, you do not need to modify your environment.

Set the LD_LIBRARY_PATH environment variable to include the bin directory in
the source directory. This overrides the library search path compiled into the
various AppWeb executables which is normally set to the build prefix
(/etc/appWeb). LD_LIBRARY_PATH has a format similar to PATH and can be set via 
the command:

    export LD_LIBRARY_PATH=/usr/src/appWeb-VERSION/bin:$LD_LIBRARY_PATH

This command may vary if you specify a non-default source installation
directory, but normally this is location is:

    /usr/src/appWeb-VERSION/bin

If you have installed AppWeb in a non-default location, replace the path with
the current installation directory for the source. You may wish to include
these commands in your .profile or .bashrc login script to the environment is
correctly setup each time you login.


Configuring the Build
---------------------

If you are using Linux or the GNU/Cygwin tools on Windows, you have the
options of configuring and controlling the build process via the configure
script. This script is similar to the Linux autoconf and libtools configure
programs. We do not use the GNU tools, as we support operating systems that do
not easily run them (e.g. Windows). The configure script will create and
modify the build control files config.make, config.sh and config.h. These 
"magic" files are included by make files, shell scripts and also by C/C++ 
source files to control the build process. To read more about the Mbedthis
build system, read doc/appWeb/source/building.html.

To create the build control files, the configure program will parse the
template.config.make, template.config.sh and template.config.h files which
serve as templates for the resulting config control files. These template
files may be edited if required when porting the source to a new platform.

If you are using Windows Visual Studio, you will need to manually edit the
config.* configuration files if you wish to modify the configuration defaults. 
NOTE: this should not be necessary unless you wish to customize the feature 
set. If you are using Microsoft Visual Studio please see the Hand Editing 
section at the end of these notes. Also note that if you are building using 
the supplied Microsoft Visual Studio project files, some configuration options 
are restricted such as the ability to create statically linked libraries and
executables.


Running Configure
-----------------

The "configure" program is the master AppWeb configuration tool. It is a
script that will create/modify the AppWeb configuration files that conrol the
build settings. You may run configure with no options to accept the "factory"
defaults, which is a good starting point.

To run the configure program, type:

    configure

or supply options, for example:

    configure --type=RELEASE --enable-static --host=sparc-sun-solaris2 \
        --disable-access-log 

Configure will remember the settings each time it is run in a a cache file,
called conf/config.cache file and it will reuse these settings if a feature 
or option is not explicitly mentioned on the next invocation.

For full details on all the configure options, type:

	configure --help

Some example configuration options follow. To enable multi-threaded operation:

	configure --enable-multi-thread

To set an alternative installation directory:

	configure --prefix=/home/myDir

To enable storing all web pages and configuration files in ROM:

	configure --enable-rom-fs

To build a fully static AppWeb:

	configure --disable-shared --enable-static

If you wish to cross-compile (Canadian-cross), configure will also listen to
the settings of the AR, CC, CC_FOR_BUILD, LD, LD_FOR_BUILD, RANLIB, CFLAGS,
IFLAGS and LDFLAGS environment variables and will pass their values into the
build system. You can define the architecture of the hosting system via the
--host switch. For example:

    CC=gccPPC configure

Configure will remember the environment variable settings for subsequent
builds. The build system will ignore environment if these variables are passed 
directly into make. You must define them via configure.

The configure program will use the default configuration supplied in the
conf/config.default file when first configuring your build. After running, it
will save the current configuration in the config/config.cache file and will
save the command line used to invoke configure in the config/config.args file.
You can edit the config.default file to modify the defaults to suit your
requirements. Once modified, run configure --reset to reparse the defaults
file and update your configuration.

When configure runs, it uses template files to create the config.make,
config.sh and config.h files. These template files are stored in
conf/template.config.*. You should not edit these files unless you are porting
AppWeb to a new platform.

For full details about the configure program run configure --help or read the
documentation under: doc/appWeb/source/building.html.


Building on Linux
-----------------

Once the build configuration is complete, you can proceed to build by typing:

	make 

This will first build the bootstrap utilities and will then generate the make 
dependencies before compiling the code.

Other make targets of interest are: "make clean", "make depend", and 
"make compile", "make install", "make uninstall".

To install the built product at its configured location (see the configure
switch --prefix), use "make install". To uninstall, use "make uninstall".

To understand more about the make system, read about the AppWeb make system
below.


Building on Windows
-------------------

Mbedthis AppWeb is supplied with both Visual Studio 6.0 project files. These 
can also be read and upgraded by Visual Studio.NET. If you are using the 
Cygwin environment please consult the Running Configure section above.


Building with Visual Studio
---------------------------

AppWeb includes several project files for building various sections of the
AppWeb server.

    * appWebServer     Builds all files necessary for the appWeb program. 
                       Includes building all loadable modules.
    * appWebClient     Builds the HTTP client.
    * appWebUtils      Builds various utilities.

To build using Visual Studio 6 open the workspace files located in the
visualStudio directory with a "dsw" extension. To build using Visual
Studio.NET, open the workspace files and upgrade them to Visual Studio.NET
solution files.

The appWebServer project will build a command line version of the server
called appWeb. It will also build a windows executable called winAppWeb if
you set it as the active project under Visual Studio.


Building on Windows with Cygwin
-------------------------------

The procedure for building with Cygwin is the same as the Linux procedure.


Hand Editing Configuration Files
--------------------------------

For Microsoft Visual Studio users who wish to customize the features of the
AppWeb server, you will need to edit the config.make, config.sh and config.h
header files. Key constants and settings are defined here and these files are
included by C source, Makefiles and scripts. Many constants are repeated in
two or three of the configuration files so be very careful and make sure you
change each setting in every place it is mentioned. You must maintain
consistency between the files. When editing be very careful to preserve quotes
where they appear. Any changes made to the configuration files may also require
manual changes to the build projects.

It is recommended that if you wish to change the configuration, that you
install the cygwin environment.


Building from the Repository
----------------------------

To get a latest copy of AppWeb source code, you will need to have installed
the Subversion source code control client. Subversion is similar to CVS, only
better. Most major linux distributions now include the client. To download a
copy, go to:

    http://subversion.tigris.org/

Once you have the Subversion client installed, you will need to send email
to dev@mbedthis.com to receive a login name and password so you can access
the repository. Once you have these details, you can checkout a copy of the
AppWeb source code via:

    svn checkout https://209.180.205.165/svn/appWeb/main


Initializing the Tree
---------------------

Before making the first time, you must initialize the tree with the correct
configuration defaults. To do this, run:

	./configure

This will ask you to select a default configuration. A safe choice is 
appWebNormal.defaults. You can also supply configure command line options
to tailor your build. To see the list of possible options, use:

	./configure --help | more

Once configured, you can use "make" or "make compile" to build. Other 
useful targets include "make depend" to refresh the makefile dependencies, 
"make clean" to remove all generated objects, executables, libraries and 
intermediate files, "make install" to install the product on the local system,
"make packge" to make a new installable package.


See Also
--------
Other important files to read:

README.TXT -- Introductory readme.
LICENSE.TXT -- License details.
PORTING.HTML -- License details.


--------------------------------------------------------------------------------
Copyright (c) 2003-2004 Mbedthis Software, LLC. All Rights Reserved.
Mbedthis and AppWeb are trademarks of Mbedthis Software, LLC. Other 
brands and their products are trademarks of their respective holders.

See LICENSE.TXT for software license details.

--------------------------------------------------------------------------------
# Local variables:
# tab-width: 4
# c-basic-offset: 4
# End:
# vim:tw=78
# vim600: sw=4 ts=4 fdm=marker
# vim<600: sw=4 ts=4
