Watch the step-by-step tutorial with screenshots...
xxm provides a number of libraries and executables. This is a description of their purpose and how to install them.
Depending on what you require some library or executable may be better than the other options. Please review all options to carefully select which option suits your needs best.
handlers:
configuration:
tools:
xxm.json (project registry) 1.2.5
xxm handlers resolve projects by name using the project registry file xxm.json, in the same directory as the xxm handler executable. An example xxm.json with a single project definition may look like this:
{
"projects": {
"demo": {
"path": "C:/xxm/demo/demo.xxl"
}
}
}
A project entry may have an "alias" attribute to have a project name map to the same library as another project.
{
"projects": {
"demo": {
"path": "C:/xxm/demo/demo.xxl"
},
"otherdemo": {
"alias": "demo"
}
}
}
To disable creating a copy of the .xxl file to load, add "loadCopy": false to the project entry.
If you want to override the default redirect on base URL's to /xxm/, Add "defaultProject": "myProject" to the top document, where "myProject" is the name of an element in the "projects" document.
If you want to host only one single xxm project, add "singleProject": "myProject" to the top document, where "myProject" is the name of an element in the "projects" document.
Use one of the xxmHttp installations to run xxm projects from a process that handles HTTP requests directly
xxmHttpDev.exe in a live environment.xxmHttpSvc /install" to install the service ("/uninstall" to uninstall)xxmHttpSvcAU /install" to install the service ("/uninstall" to uninstall)Specify following command line parameters to alter default behaviour (for services, define values in registry key HKEY_LOCAL_MACHINE\Software\xxm\service)
.xxl module for loading. (default enabled, use when debugging an xxm project with xxmHttp.exe as host application)Use an xxm ISAPI extension to load xxm projects with IIS. An ISAPI extension can be loaded in several ways, see below for a list of options.
There are a few options to configure IIS to use the xxmISAPI dll's
http://localhost/xxm/xxmIsapiEx.dll/demo/test.xxmIIS 7 requires ISAPI dll's to be added to the list of accepted plugins in the security administration
IIS 7.5 offers to add the dll to the allowed modules when you create a wildcard application mapping. On 64-bit machines, set the 'enable 32-bit applications' option in the application pool advanced settings. Also the folder containing the xxl module file(s) may need a security setting for IIS APPPOOL\DefaultAppPool or the approriate application pool (Don't look it up in the objects list, type it manually in the names box.)
IIS 7.5 shows its own error pages when xxm wants to report an error. Navigate the Server Manager to "Error Pages" and edit the feature settings to display 'Detailed pages' instead of the default 'Custom error pages' to show xxm's error page content in case of an error.
xxmAhttpd (mod_xxm, Apache httpd 2.2 module)
Use an xxm Apache httpd module to run xxm projects with Apache HTTP server.
To configure Apache httpd to use the xxm Apache httpd handler, add a section similar to the example below to the httpd.conf file.
Attention: use forward slash as path delimiter.
LoadModule xxm_module "C:/path/to/xxm/binaries/xxmAhttpd.dll" <Location /test> SetHandler xxm-handler </Location>
xxmHSys1 (HTTPAPI v1) 1.1.5 xxmHSys2 (HTTPAPI v2) 1.1.7
xxmHSys processes use HTTPAPI calls to respond to HTTP requests handled by http.sys within the Windows kernel.
xxmHSys1Dev.exe or xxmHSys2Dev.exe in a live environment.xxmHSys1Svc /install" to install the service ("/uninstall" to uninstall)xxmHSys1SvcAU /install" to install the service ("/uninstall" to uninstall)xxmHSys handlers are unable to adhere to a "singleProject" setting in xxm.json, if it is configured.
Start xxmHSys with one or more project names in the command line parameters to load.
xxmCGI/xxmHost (CGI with Apache httpd,IIS,...)
Using the library built for a specific web-server is preferred over using CGI. CGI creates a new process for each request, which has a negative effect on performance. Because these 'short' processes only exist for the time it takes to respond to a request, xxmCGI.exe patches request/response-data to/from a separate xxmHost process, so that projects and their session data can stay loaded.
xxmHostDev.exe in a live environment.xxmHostSvc /install" to install the service ("/uninstall" to uninstall)xxmHostSvcAU /install" to install the service ("/uninstall" to uninstall)follow these instructions to install xxmCGI.exe:
Apache httpd 2.2 ...
these are instructions to install xxmCGI/xxmHost with Apache httpd, for the xxm Apache httpd module see xxmAhttpd
The default httpd.conf contains a ScriptAlias /cgi-bin/ directive to a directory. Copy xxmCGI.exe to this directory and use URLs of this form:
http://myserver/cgi-bin/xxmCGI.exe/someproject/
to have shorter URLs, add this to httpd.conf: ...
<Location /someproject> SetHandler xxmcgi-handler Action xxmcgi-handler /cgi-bin/xxmCGI.exe virtual </Location>
and use URLs of this form:
http://myserver/someproject/
IIS ...
it is strongly advised to use xxmIsapi with IIS, see faq: 'how do I debug an xxm project?' for debugging options with xxmIsapi
Give the directory xxmCGI.exe is in execute permissions. Add a virtual directory to this directory (e.g. named "somefolder") and use URLs of this form:
http://myserver/somefolder/xxmCGI.exe/someproject/
to have shorter URLs, add a 'Wildcard' Application Mapping in the Application Configuration, mapping extension ".*" to xxmCGI.exe (uncheck 'Script engine' and 'Check that file exists') and use URLs of this form:
http://myserver/someproject/
running an xxmHost process
when using xxmCGI.exe, be sure to have an xxmHost process running. You can keep a process running (in order of recommendation):
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run **: assuming the computer has a user logged on to the console by default.
if xxmCGI.exe can't connect to a running xxmHost process, it responds to all requests with this message:
Error connecting to xxm request handler process
xxmSCGI (SCGI with nginx, Lighttpd, ...) 1.2.3
xxmSCGI handlers accept incoming SCGI connections to serve dynamic HTTP requests over.
xxmSCGIDev.exe in a live environment.follow these instructions to install xxmSCGI.exe:
nginx ...
Configure certain requests to be handled by the SCGI module, by adding code like this to nginx.conf:
location /test/ {
include scgi_params;
scgi_pass localhost:4000;
}
Be sure to start an xxmSCGI handler, optionally with a Port= parameter (default 4000).
Lighttpd ...
Configure certain requests to be handled by the SCGI module, by adding code like this to lighttpd.conf:
scgi.server = ( "/test/" =>
(( "host" => "127.0.0.1",
"port" => 4000,
"check-local" => "disable"
))
)
Be sure to start an xxmSCGI handler, optionally with a Port= parameter (default 4000).
xxmProject provides a basic interface to create a new project, or edit an existing project.
xxmConv is a minimal wrapper around the xxm parser engine that generates the compilable source code. Pass it a directory, the location of an xxmp or xxl file, and it will generate the project source code.
About installing side-by-side:
Though it is possible to install several of above options at once, it is strongly advised not to use more than one of them to run a certain xxm project simultaneously. Doing so may interfere normal operation when more than one process has a file-lock on the project library file (e.g. when compiling or updating).