Needs better documentation about mongoose HOT 18 CLOSED

I should add that I have read the current manual (available on Google Code:
Mongoose). My comments do include that manual. It is too brief, relying on a 
user's
previous experience with Web browsers. Examples of incomplete areas: ways to run
mongoose.exe; examples of serving Web pages that include PHP code or code using 
other
major preprocessors; a complete, step-by-step cookbook for getting Mongoose up 
and
running as a standard Port 80 server, including how to set up Web directories;
Mongoose equivalents to .htaccess files (if any); specific documentation of the
config file format instead of orienting the documentation around command options
(which are not very useful in Windows); a tutorial document on how to set up 
pages
that use SSL and basic authentication; the link to documentation on embedding
Mongoose is mangled and does not work and only points to a brief description on 
the
home page anyway (while I have not tried to write a C++ program that uses 
Mongoose, I
believe I would benefit from more detailed instructions and a test case).

David Spector
Springtime Software

Hi David, thanks for the feedback!
Documentation is to be extended.
I will specifically focus on
  a) embedding. Starting from the next release, DLL will be built on Windows platform
allowing using Mongoose from programs written in other languages (e.g. Visual 
Basic)
  b) novice user
Current manual is targeting experienced UNIX users indeed.

Hi. Thanks for the quick and helpful response.

Thanks for listing the novice user as a future area of expansion for the 
manual. Some
of these folks have never worked with a Web server before. There are lots of 
things
an informal server can do that benefit people using computers (browsers) for all
sorts of things (some working examples would be very useful).

For example, I created a server (using any Web server that can run PHP including
Apache, shttpd, and Mongoose) to run a an important program installed on 
machine A
from machine B located in another city, with security via hashed password. This 
makes
it seem that the program is installed on machine B even though machine B is
prohibited by a too-broad management policy from installing the program 
themselves.
The input is sent from B to A and then the output is sent from A to B. It 
solves a
real-world problem very nicely and securely.

A whole series of servers for various requests can be made. Each is a Web page 
served
by Mongoose (or they can be combined on one Web page). This makes it easy to run
demonstrations, for example, on any computer connected to the Web. They don't 
even
need firewall or other protection, since they use a unique port and only 
respond to
clients who present the proper passwords.

Of course, standalone programs written in server-side programming like PHP 
and/or
Ajax can be run using Mongoose for fast-installing applications or 
demonstrations.
Such applications can run on any expected computer and browser and are easy to
program. These are some of the points, I think, that should be illustrated in 
depth
in a good manual, with a subdirectory of examples.

Embedding is actually not as interesting, since fewer people do it (besides, 
it's not
hard to create a simple Web server in C++ oneself by opening a socket and 
handling
the socket events or messages using the appropriate socket API).

Concerning embedding, it might be good to try to avoid adding a DLL unless you 
truly
need to write code that must run in any process. Anything a simple DLL can do 
can
also be done in the EXE, including (I'm pretty sure) creating an Apartment-type
server with an Automation interface for use from various languages. DLLs almost
always introduce complications in installing, using, uninstalling, and porting 
back
to Linux.

Since I'm giving free advice, try to avoid using the Windows Registry. It makes 
it
harder to move a Mongoose application from computer to computer. Of course, the
Registry must be used when creating an Automation interface, but you could 
easily
make that optional at installation and/or embedding time. Not many embedded
applications really need an Automation interface, or any COM interface at all.

David Spector
Springtime Software

Could you comment on http://code.google.com/p/mongoose/wiki/WindowsUsage , 
please?
I also put together pages documenting API, and embedding strategies, with 
examples.
From now on (since version 2.1), installer creates a README.txt file that 
points to
the WindowsUsage wiki page.
I guess, the wiki page could be a place where people may leave comments with
suggestions, and real life use cases.

Comment on http://code.google.com/p/mongoose/wiki/WindowsUsage: The first 
section, on
installation, is understandable. The second section, on advanced tips, is 
totally
obscure and should be deleted if it can't be turned into clear English.

The manual needs a section on the configuration file, listing each directive 
with
complete description. It also needs either a description of .htaccess files, or 
an
explanation why such files are not supported (such as, to keep Mongoose small). 
It
needs a listing of all detected server error codes and how the user can provide 
a
custom error page.

It needs a detailed list of MIME headers that are accepted by the server.

That's all that comes to mind immediately. Generally, the documentation still 
needs
much more improvement if Mongoose is to be attractive for use by average Web 
programmers.

David Spector
Springtime Software

Five months later: the documentation is much better, particularly for Windows, 
where
Mongoose runs like a charm, either standalone or as a service. Here are some 
suggestions:

1. Publicize it. This tiny file is amazing. It does most of what we use Apache 
for.
It is extremely useful for writing PHP/browser applications. You could also 
supply as
an example a configuration that returns an empty page--this can be used with the
HOSTS file to eliminate embedded ads on Web pages (see details at the Wikipedia
article "Hosts file").

2. Remove the blocks of zeros in the exe file, to make it even smaller. The 
zeros are
not necessary.

3. Provide support for a user file returned on any supported HTTP error.

Thanks for the feedback.

To reduce the size radically, a static linkage against libc.lib must be changed 
to
dynamic linkage msvcrt.dll, which will bring the exe size from ~150 kb down to 
~45-50 kb.

For custom per-HTTP error files an request
http://code.google.com/p/mongoose/issues/detail?id=48 has been filed recently. 
I plan
to work on that, too.

Manually removing the six blocks of zeros from the Windows version of
mongoose-2.6.exe reduced its size from 151KB to 148KB. And that doesn't include 
the
blocks of garbage left behind by the compiler. There may be compiler and linker
options to optimize for space.

Some Windows users will not have msvcrt.dll available (because they are running 
a
portable or embedded system), but if you are currently statically linking with
libc.lib, you can reduce the size simply by copying the runtime library sources 
or
linked modules that you actually call to your development directory. Then all 
library
calls will be resolved without needing the entire runtime library linked in.

The smaller the executable, the more impressive to prospective users. But, of 
course,
it's up to you whether you want to go to all this trouble.

Yeah, thanks for the hints.
As far as I know, all Windows systems do have msvcrt.dll, since it is one of 
the core
libraries - a C runtime DLL. Not sure about Windows CE, will check on that 
later.

Nice. A 60KB executable will be very impressive. How will this work on Linux?

On UNIXes, mongoose is already 40-50kb large.
Example, on my FreeBSD box it is ~40 kb:

devnull@news:~/mongoose$ ls -l mongoose
-rwxr-xr-x  1 devnull  wheel  *39628*  8 фев 22:27 mongoose

On my Linux box, it is also about 40kb:
baton~/mongoose$ ls -l mongoose
-rwxr-x--- 1 lsm eng *41004* 2009-05-22 10:03 mongoose

I don't know if you realize it, but Mongoose is probably the best tiny 
webserver in
existence (the others in Google Code are run in interpreters like Java). See 
also
http://en.wikipedia.org/wiki/Comparison_of_lightweight_web_servers.

I have just overhauled http://en.wikipedia.org/wiki/Mongoose_(server) to 
describe
Mongoose better. Let me know here if there are any errors or omissions.

Thanks!

The executable compressor utility UPX was able to compress the mongoose-2.6.exe 
by
47% from 154624 bytes to 73216 bytes.  It has some drawbacks, but anyone who is
interested in smaller executable size could apply it themselves.

See http://upx.sourceforge.net/

Ah, cool, I will use it for released executables, thanks for the hint!