Deploying Carmenta Engine 5 Applications on Windows
This article describes how to deploy a Carmenta Engine 5 application that uses the C++, .NET or Java API on Windows.
An application can be deployed by creating a Windows Installer installation. This can be done with a simple deployment project in Visual Studio, or with some other third-party tool, like InstallShield, Wix or InnoSetup.
Regardless of which tool is used, the way to deploy the Carmenta Engine runtime with an application is the same: by adding the necessary Carmenta Engine merge modules to the installer. The merge modules contain DLLs and other runtime components needed to run the application on the target machine. Every Carmenta Engine application should be deployed with its own copy of the Carmenta Engine runtime, and the merge modules should be installed in the same directory as the application executable.
You may also want to include Microsoft Visual C++ Runtime library merge modules in your installer, see below.
The installer must supply a Carmenta Engine runtime license key, for instance by embedding it as a text resource in the application executable. See Using a Carmenta Engine 5 runtime license for details.
The runtime installation of Carmenta Engine does not require any elevated privileges, as it doesn't modify the system other than adding files to the application directory. Unless the application requires it for other reasons, it can be installed by a normal, non-administrator user.
Carmenta Engine merge modules
All redistributable Carmenta Engine merge modules are available in a Carmenta Engine SDK installation, under the redist directory, typically C:/Program Files/Carmenta Engine 5 SDK/redist. The following merge modules are available:
Merge module | Description |
|---|---|
Carmenta Engine 5 Runtime Core.msm | Contains all the core functionality. Must always be included. |
Carmenta Engine 5 Runtime C++.msm | Contains the C++ API wrappers. This must always be included for a C++ application, or if the application uses custom objects written in C++. |
Carmenta Engine 5 Runtime .NET.msm | Contains the .NET Framework API wrappers. This must always be included for a .NET application, or if the application uses custom objects written for .NET. |
Carmenta Engine 5 Runtime Java.msm | Contains the Java API wrappers. This must always be included for a Java application, or if the application uses custom objects written in Java. |
Carmenta Engine 5 Runtime Python.msm |
Contains the Python API wrappers. If the application uses
ScriptOperator with Python code in its configuration file,
this module must also be included. |
MrSID Runtime For Carmenta Engine 5.msm | Contains the MrSID runtime files, used by the MrSidDataSet. Include it if the application uses this dataset to read MrSID data. |
ECW Runtime For Carmenta Engine 5.msm |
Contains the ECW runtime files, used by the EcwDataSet.
Include it if the application uses this dataset to read ECW data. |
Microsoft Visual C++ Runtime
Carmenta Engine is built with Microsoft Visual Studio 2022, but also includes a few third-party components built with Visual Studio 2013 and 2017. When running a Carmenta Engine application, the Microsoft Visual C++ Runtime libraries for these versions must be available.
The SDK installer automatically installs these runtime libraries. However, they are not automatically included when you deploy your application to a target machine. If you build an installer for your application, or if you deploy your application as an XCOPY installation, you probably want to include the needed C++ runtime files.
There are several ways you do this, see Redistributing Visual C++ Files for more information.
Creating an XCOPY installer
Since the installation does not require any elevated privileges, it is possible to create an XCOPY installation, i.e. an installation where you just copy the application files, including the Carmenta Engine runtime files, into a directory, and run the application from there.
The Carmenta Engine SDK includes a small script CopyCarmentaEngineRuntime64 that can be used to copy the necessary Carmenta Engine runtime files for an XCOPY installation.
Running the script without any arguments shows a short help message, see the image below.
 |
To use the script do the following:
Open a Command Prompt.
Create an empty directory into which the files will be copied.
Change directory to the one created in the previous step.
Determine which API is used, cpp, dotnet, java or python (some applications use more than one).
Determine if any of the separately provided third-party components ecw or mrsid are used.
Call CopyCarmentaEngineRuntime with the arguments for the required APIs and components.
For example, the following command copies the Carmenta Engine Core runtime files, the Carmenta Engine .NET Framework API and the runtime files for the MrSidDataSet into the current directory:
CopyCarmentaEngineRuntime dotnet mrsid
For a .NET application, Microsoft .NET Framework version 4.0 or later needs to be installed.
For a Java application, a Java Runtime Environment (JRE) version 11 or later must be installed.
You also need to include the Microsoft Visual C++ Runtime libraries, see Microsoft Visual C++ Runtime.