xxm

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:

remarks

xxmLocal (Internet Explorer)

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.

xxmLocal.dll
Use %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).
xxmLocalDev.dll
xxmLocalDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Please don't use xxmLocalDev.dll in a live environment.
xxmLocalAU.dll
xxmLocalAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).

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.

xxmGecko (Firefox)

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.

xxmGecko.xpi
Open this file using FireFox (or download it, optionally marked as MIME-type 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.
xxmGeckoDev.xpi
xxmGeckoDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Please don't use xxmGeckoDev.dll in a live environment.
xxmGeckoAU.xpi
xxmGeckoAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).

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.

xxmIsapi (IIS)

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.

xxmIsapiEx.dll
The default ISAPI extension, loads xxm projects.
xxmIsapiDev.dll
xxmIsapiDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Attention: to compile a project, the current user may require access to common libraries and source files. Check as which user IIS runs, or which credentials are used to run the ISAPI extension (COM+).
Please don't use xxmIsapiDev.dll in a live environment.
xxmIsapiAU.dll
xxmIsapiAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).

There are a few options to configure IIS to use the xxmISAPI dll's

call directly
if the directory security settings allow scripting and running executables, an ISAPI extension can be called by a URL that maps to the dll file location, which may look like this:
http://localhost/xxm/xxmIsapiEx.dll/demo/test.xxm
extension mapping
IIS configuration allows to route files of a certain file-extension to an ISAPI extension. You could map ".xxm" to one of the xxmIsapi dlls, but this will not make any other requests go through the xxm project, which may form a security risk. This is the mail reason why the following option is preferred over this one.
wildcard application mapping
IIS 6 and above supports a mapping of ".*" to an ISAPI extension (wildcard mapping), and even provides an option to skip checking if the file exists the URL maps to. This enables all requests to pass through the xxm ISAPI extension, so the project may perform authentication, optionally based on user sessions.

IIS 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.

xxmAhttpd.dll
The default Apache httpd module to load xxm projects
xxmAhttpdDev.dll
xxmAhttpdDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Attention: to compile a project, the current user may require access to common libraries and source files. Check which credentials are used to run Apache.
Please don't use xxmAhttpdDev.dll in a live environment.
xxmAhttpdAU.dll
xxmAhttpdAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).

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.

xxmHSys1.exe, xxmHSys2.exe
The default xxm HTTPAPI handler.
xxmHSys1Dev.exe, xxmHSys2Dev.exe
xxmHSys?Dev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Please don't use xxmHSys1Dev.exe or xxmHSys2Dev.exe in a live environment.
xxmHSys1AU.exe, xxmHSys2AU.exe
xxmHSys?AU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).
xxmHSys1Svc.exe, xxmHSys2Svc.exe
similar to xxmHSys?.exe, but runs as an NT-service. call "xxmHSys1Svc /install" to install the service ("/uninstall" to uninstall)
xxmHSys1SvcAU.exe, xxmHSys2SvcAU.exe
similar to xxmHSys?AU.exe, but runs as an NT-service. call "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.

xxmCGI.exe
handles CGI requests by patching request and response data, to and from a running xxmHost process
xxmHost.exe
responds to requests patched through from xxmCGI processes, project libraries loaded can keep session data in memory
xxmHostDev.exe
xxmHostDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Please don't use xxmHostDev.exe in a live environment.
xxmHostAU.exe
xxmHostAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).
xxmHostSvc.exe
similar to xxmHost.exe, but runs as an NT-service. call "xxmHostSvc /install" to install the service ("/uninstall" to uninstall)
xxmHostSvcAU.exe
similar to xxmHostAU.exe, but runs as an NT-service. call "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):

*: 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.

xxmSCGI.exe
responds to requests over SCGI on a local post, project libraries loaded can keep session data in memory
xxmSCGIDev.exe
xxmSCGIDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Please don't use xxmSCGIDev.exe in a live environment.
xxmSCGIAU.exe
xxmSCGIAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).

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).

xxmHttp (stand-alone)

Use one of the xxmHttp installations to run xxm projects from a process that handles HTTP requests directly

xxmHttp.exe
handles HTTP requests on a TCP port (80 by default) using xxm projects
xxmHttpDev.exe
xxmHttpDev checks the project's xxmp file if any files have changed. If so, it unloads the project, generates source code where needed, compiles the project and reloads it. If files were added or removed, they are added to the xxmp file.
Please don't use xxmHttpDev.exe in a live environment.
xxmHttpAU.exe
xxmHttpAU checks if there is a .xxu file in the directory of the .xxl file, and if so, unloads the project, replaces the xxl file and reloads the project (auto-update).
xxmHttpSvc.exe
similar to xxmHttp, but runs as an NT-service. call "xxmHttpSvc /install" to install the service ("/uninstall" to uninstall)
xxmHttpSvcAU.exe
similar to xxmHttpAU, but runs as an NT-service. call "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)

Port=<TcpPort>
set the TCP port to listen on for requests (default 80)
LoadCopy=0
disable creating a copy of the .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

xxmProject provides a basic interface to create a new project, or edit an existing project.

xxmConv

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.

xxmRun

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:

{CLSID}PathToLibrary
Checks the registry if an object is defined with the CLSID, if not, calls DllRegisterServer on the library pointed to by PathToLibrary. On rollback, if the library was registered, DllUnregisterServer is called.
"ProjectName"PathToLibrary
Registers the library in the local xxm project registry. On rollback, removes the registration, or restores it if another library was registered with the project name
@URL
Opens Internet Explorer (expressly, even if another browser is configured as default) to open the URL. When all configuration lines are processed, xxmRun waits for the process to end.
 CommandLine
(Line starts with a space.) Executes the command line. When all configuration lines are processed, xxmRun waits for the process to end.
!CommandLine
Executes the command line and waits for the process to end before processing following configuration lines. Does nothing on rollback. Use this to perform tasks to prepare for other processes that xxmRun will wait on.
_CommandLine
Does nothing on reading the configuration lines. On rollback executes the command line and waits for the process to end before continuing the rollback. Use this to perform tasks to clean up. Pay attention to defining them in reverse order, since they act on rollback. Also, configuration lines that started a process to wait on later, will wait on their process to end on rollback.

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

remarks

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).