Changes between Initial Version and Version 1 of Developer/Mongoose_Web_Server

Timestamp:

01/02/16 00:07:04 (8 years ago)

Author:

Tan Gemicioglu

Comment:

Moved and fixed page from TBR/Delete

Developer/Mongoose_Web_Server

@@ +1 @@
+= Mongoose Web Server =
+
+
+This page aims to help application developers integrate the [https://github.com/valenok/mongoose/ Mongoose] Web / HTTP server into their RTEMS applications. Only a reasonably basic configuration is treated.
+
+It is assumed that:
+ *  the reader is using RTEMS 4.11 (the interface to Mongoose has changed significantly from 4.10), [wiki:TBR/UserManual/Quick_Start compiling it from source] and is comfortable doing so
+ *  networking is already configured and working in the application
+ *  a file-system (from which to serve web pages and write logs to) is already configured and working in the application
+=  What is it?  =
+
+Mongoose is a lightweight web server, one of two (the other being the [wiki:TBR/UserManual/Simple_HTTPD Simple HTTPD] server) available in RTEMS.
+=  Prerequisites  =
+
+RTEMS must have been configured (that is, with the GNU Configure tool), with the ''--enable-httpd'' and ''--enable-networking'' options. Because Mongoose uses the POSIX API, ''--disable-posix'' should ''not'' be specified.
+=  Library  =
+
+The Mongoose library must be pulled in for linking. To do so, ensure that ''-lmghttpd'' is passed to the linker.
+
+If you're using a ''Makefile'' based on the provided [http://git.rtems.org/rtems/tree/make/Templates/Makefile.leaf template] - available for RTEMS 4.11 in its ''share/rtems4.11/make/Templates/Makefile.leaf'' path - this can be accomplished by adding ''-lmghttpd'' to ''LD_LIBS''; e.g.:
+{{{
+LD_LIBS+=-lmghttpd
+}}}
+=  CONFIGURE / confdefs.h  =
+
+Mongoose uses the POSIX API and its mutex and condition variable features and thus resources must be allocated for it in the application's configuration. For example, add the following before including ''confdefs.h'' (with ''CONFIGURE_INIT'' #defined):
+{{{
+#define CONFIGURE_MAXIMUM_POSIX_THREADS 10
+#define CONFIGURE_MAXIMUM_POSIX_MUTEXES 10
+#define CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES 10
+}}}
+=  Initializing Mongoose  =
+
+{{{
+#include <mghttpd/mongoose.h
+}}}
+in the source file you'll initialize Mongoose from.
+
+''mg_start()'' is used to start Mongoose:
+{{{
+struct mg_context *mg_start(const struct mg_callbacks *callbacks, void *user_data, const char **options)
+}}}
+
+For the basic configuration described here, ''NULL'' can be passed for the ''user_data'' parameter, but ''callback'' '''must''' be provided. To initialise a structure with no callbacks enabled, use:
+  {{{
+struct mg_callbacks callbacks = { NULL };
+}}}
+
+The ''options'' parameter is a ''NULL''-terminated array of string pairs, each pair giving an option name and a value (see the Mongoose documentation for a [https://docs.cesanta.com/Options.shtml description of options]). By way of example, though, ''options'' might be defined as such:
+   {{{
+ const char *options[] = {
+   "document_root",   "/usr/www",
+   "listening_ports", "80",
+   "num_threads",     "1",
+   "thread_priority", "10",
+   "access_log_file", "/var/log/httpd-access.log",
+   "error_log_file",  "/var/log/httpd-error.log",
+   NULL
+ }
+}}}
+
+Calling ''mg_start()'' (after networking and the file-system are initialized) will return a "context" upon success, ''NULL'' upon failure (sadly, at the time of writing, not necessarily with an indication of the nature of the failure - configuring an error log (as in the example ''options'' above) is recommended for troubleshooting failures).
+
+This context is used for further operating on that Mongoose instance (for example, in calling ''mg_stop()'' to halt it).
+=  Done!  =
+
+Hopefully at this point, you've a working Mongoose server.
+
+Ensure there's a page for it to serve (e.g., ''/usr/www/index.html'') and test by browsing to ''!http://''<ip>''/'' (where ''<ip>'' is a resolvable name or IP address for your RTEMS target)!