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:
tools:
The xxmLocal libraries enable Internet Explorer to load xxm projects directly using the "xxm:" URL scheme.
This is a direct way to run an xxm project, since the project runs inside of the iexplore.exe process.
%SystemRoot%\system32\regsvr32.exe to register the xxmLocal.dll file. This will add the "xxm:" URL scheme to the registry. This will also define the xxm file types (xxm,xxmi,xxmp,xxl).xxmLocal libraries resolve projects by name using the registry. Project definitions are stored here:
HKEY_CURRENT_USER\SOFTWARE\xxm\local
HKEY_LOCAL_MACHINE\SOFTWARE\xxm\local
Each project has a key with the default value containing the full path to the xxl file.
When an xxmLocal library is registered, the xxl file type registry also includes a context-menu item to add the project to the registry.
The xxmGecko libraries enable Firefox to load xxm projects directly using the "xxm:" URL scheme.
This is a direct way to run an xxm project, since the project runs inside of the firefox.exe process.
application/x-xpinstall). An install dialog box is displayed. After installing FireFox may request a restart, and xxmGecko will be listed with the installed add-ons.xxmGecko libraries resolve projects by name using the registry. Project definitions are stored here:
HKEY_CURRENT_USER\SOFTWARE\xxm\local
HKEY_LOCAL_MACHINE\SOFTWARE\xxm\local
Each project has a key with the default value containing the full path to the xxl file.
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.
xxm ISAPI extensions resolve projects by name using the projects definition file xxm.xml, in the same directory as the xxm ISAPI extension library. An example xxm.xml with a single project definition may look like this:
<ProjectRegistry>
<Project Name="demo">
<ModulePath>C:\xxm\demo\demo.xxl</ModulePath>
</Project>
</ProjectRegistry>
A project entry may have an Alias attribute to have a project name map to the same library as another project:
<Project Name="otherdemo" Alias="demo"></Project>
To disable creating a copy of the .xxl file to load, add attribute LoadCopy="0" to the project entry.
If you want to host only one single xxm project, add a SingleProject attribute to the ProjectRegistry document element, to refer to a project definition.
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>
xxm Apache httpd module resolves projects by name using the projects definition file xxm.xml, in the same directory as the xxm Apache httpd module library. An example xxm.xml with a single project definition may look like this:
<ProjectRegistry>
<Project Name="demo">
<ModulePath>C:\xxm\demo\demo.xxl</ModulePath>
</Project>
</ProjectRegistry>
A project entry may have an Alias attribute to have a project name map to the same library as another project:
<Project Name="otherdemo" Alias="demo"></Project>
To disable creating a copy of the .xxl file to load, add attribute LoadCopy="0" to the project entry.
If you want to host only one single xxm project, add a SingleProject attribute to the ProjectRegistry document element, to refer to a project definition.
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 uses a projects definition file xxm.xml, in the same directory as the xxmHSys executable. An example xxm.xml with a single project definition may look like this:
<ProjectRegistry>
<Project Name="demo">
<ModulePath>C:\xxm\demo\demo.xxl</ModulePath>
</Project>
</ProjectRegistry>
A project entry may have an Alias attribute to have a project name map to the same library as another project:
<Project Name="otherdemo" Alias="demo"></Project>
To disable creating a copy of the .xxl file to load, add attribute LoadCopy="0" to the project entry.
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)xxmHost resolves projects by name using the projects definition file xxm.xml, in the same directory as the xxmHost executable. An example xxm.xml with a single project definition may look like this:
<ProjectRegistry>
<Project Name="demo">
<ModulePath>C:\xxm\demo\demo.xxl</ModulePath>
</Project>
</ProjectRegistry>
A project entry may have an Alias attribute to have a project name map to the same library as another project:
<Project Name="otherdemo" Alias="demo"></Project>
To disable creating a copy of the .xxl file to load, add attribute LoadCopy="0" to the project entry.
If you want to host only one single xxm project, add a SingleProject attribute to the ProjectRegistry document element, to refer to a project definition.
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.xxmSCGI resolves projects by name using the projects definition file xxm.xml, in the same directory as the xxmSCGI executable. An example xxm.xml with a single project definition may look like this:
<ProjectRegistry>
<Project Name="demo">
<ModulePath>C:\xxm\demo\demo.xxl</ModulePath>
</Project>
</ProjectRegistry>
A project entry may have an Alias attribute to have a project name map to the same library as another project:
<Project Name="otherdemo" Alias="demo"></Project>
To disable creating a copy of the .xxl file to load, add attribute LoadCopy="0" to the project entry.
If you want to host only one single xxm project, add a SingleProject attribute to the ProjectRegistry document element, to refer to a project definition.
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).
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)xxmHttp resolves projects by name using the projects definition file xxm.xml, in the same directory as the xxmHttp executable. An example xxm.xml with a single project definition may look like this:
<ProjectRegistry>
<Project Name="demo">
<ModulePath>C:\xxm\demo\demo.xxl</ModulePath>
</Project>
</ProjectRegistry>
A project entry may have an Alias attribute to have a project name map to the same library as another project.
<Project Name="otherdemo" Alias="demo"></Project>
To disable creating a copy of the .xxl file to load, add attribute LoadCopy="0" to the project entry.
If you want to host only one single xxm project, add a SingleProject attribute to the ProjectRegistry document element, to refer to a project definition.
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.
use xxmRun to register xxmLocal, optionally other COM libraries and one or more xxm projects, only for the time of one browser session.
when xxmRun starts, the lines of xxmRun.ini in the same directory is parsed, if any processes are started (e.g. Internet Explorer), xxmRun waits silently until it ends, and then rolls back the definitions in xxmRun.ini in reverse order
lines in xxmRun.ini are of one of these forms:
example xxmRun.ini:
{78786D00-0000-0001-C000-000000000001}xxmLocal.dll
{A20016A7-685B-4554-A8B6-7A06E71D22FB}WikiEngine.dll
"demo"demo.xxl
!unpack.exe demomdb.zip %tmp%\
_pack.exe %tmp%\demo.mdb demomdb.zip
@xxm://demo
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).