Deploy Add-Ons

MATLAB^® deployment tools such as MATLAB Compiler™ and MATLAB Compiler SDK™ package MATLAB functions for deployment to environments external to the MATLAB desktop. These deployment tools can also package the proxy functions that MATLAB Production Server™ add-ons install to create deployable software components that require both the external environment and an active MATLAB Production Server instance.

For example, consider a deployable archive fractal.ctf that contains a MATLAB function mandelbrot hosted on a MATLAB Production Server instance.

You can install the fractal add-on on a client machine from the fractal archive using MATLAB Client for MATLAB Production Server. Installing the fractal add-on installs the proxy mandelbrot function on your machine. Then, you can write a client program in MATLAB that uses the proxy mandelbrot function.

You can also package the proxy mandelbrot function into a shared library, for example, fractal.dll, using MATLAB Compiler SDK. Then, you can write a C++ client program that uses fractal.dll.

The following diagram shows the MATLAB client (in blue) and the C++ client (in green) calling the same proxy mandlebrot function to communicate with the mandelbrot function deployed to a MATLAB Production Server instance.

The following examples show how to package installed proxy functions into a standalone executable, a shared library, and a deployable archive. The examples use files in the support_package_root\toolbox\mps\matlabclient\demo folder on your system. The demo folder contains the following folders:

• fractal — Contains mandelbrot and snowflake MATLAB functions. The mandelbrot function generates a Mandelbrot set and the snowflake function generates the outline of a Koch snowflake. You package these MATLAB functions into a MATLAB Production Server deployable archive.

• mandelflake — Contains the mandelflake MATLAB function that displays the Mandelbrot set and the Koch snowflake. You package the mandelflake function into a standalone executable.

• fractalViewer — Contains the twoFractals MATLAB function that displays the Mandelbrot set and the Koch snowflake based on input arguments that you specify. You package the twoFractals function into a shared library and a deployable archive.

Prerequisites

The examples require that you have the fractal MATLAB Production Server add-on available in your MATLAB session. The examples package the proxy functions from the fractal add-on into a standalone executable, a shared library, and a deployable archive. To make the fractal add-on available in MATLAB:

1. Package the mandelbrot and snowflake MATLAB functions from the \demo\fractal\ folder into a deployable archive called fractal using the Production Server Archive Compiler (MATLAB Compiler SDK) app. You must include a MATLAB function signature file when you create the archive. For more information about packaging archives, see Create Deployable Archive for MATLAB Production Server (MATLAB Compiler SDK).

2. Deploy the fractal archive to a MATLAB Production Server instance. For more information about deploying the archive, see Deploy Archive to MATLAB Production Server.

   Confirm with the server administrator that the discovery service is enabled on the server. For more information, see Discovery Service.

3. Install the fractal add-on in your MATLAB desktop. For more information about installing add-ons, see prodserver.addon.install. For a detailed example about installing MATLAB Production Server add-ons, see Execute Deployed MATLAB Functions.

You can verify that the fracatl add-on is available in your MATLAB session by running prodserver.addon.availableAddOns. To test your installation of the fractal add-on, you can run the example MATLAB function mandelflake that is in \demo\mandelflake at the MATLAB command prompt.

The standalone executable and shared library require MATLAB Runtime. Install MATLAB Runtime on your machine if you have not already done so. For more information, see MATLAB Runtime.

Create Standalone Executables That Use Add-Ons

This example shows how to package a proxy function that a MATLAB Production Server add-on installs, into a standalone executable to invoke a MATLAB function hosted on a MATLAB Production Server instance. This example requires MATLAB Compiler. You can run standalone executables on computers that do not have MATLAB installed.

1. For this example, copy the contents of the support_package_root\toolbox\mps\matlabclient\demo\mandelflake folder to a separate writable location on your system, for example, to a folder called mandelflake.

2. Navigate to the writable mandelflake folder from the MATLAB command prompt. The mandelflake folder contains a MATLAB function called mandelflake. Use the mcc (MATLAB Compiler) command to create a standalone executable called mandelflake from the mandelflake MATLAB function.

   >> cd mandelflake
   >> mcc -m mandelflake

   This command produces an executable file mandelflake.exe on a Windows^® system.

   On Linux^® and macOS, it produces an executable called mandelflake.

3. Run the executable at the system command prompt to display the Mandelbrot set and Koch snowflake.

   C:\mandelflake> mandelflake

   Two windows appear, one containing the Mandelbrot set and one displaying the Koch snowflake.

Create Shared Libraries or Software Components That Use Add-Ons

This example shows how to package a proxy function that a MATLAB Production Server add-on installs, into a shared library, then use the shared library in a C++ client to invoke a MATLAB function hosted on a MATLAB Production Server instance. This example requires MATLAB Compiler SDK and a supported C++ compiler. For a list of supported C++ compilers, see Supported and Compatible Compilers. MATLAB Compiler SDK creates software components, such as shared libraries, from MATLAB functions.

1. For this example, copy the contents of the support_package_root\toolbox\mps\matlabclient\demo\fractalViewer folder to a separate writable location on your system, for example, to a folder called fractalViewer. The fractalViewer folder contains the following:

   • A MATLAB function twoFractals that displays images of the Mandelbrot set and the Koch snowflake based on the input arguments to the function

   • A C++ application fractalViewer that invokes the twoFractals function with the required input arguments

2. Navigate to the writable fractalViewer folder from the MATLAB command prompt. Use the mcc (MATLAB Compiler) command to create a shared library called twoFractals.lib from the twoFractals.m MATLAB function.

   >> cd fractalViewer
   >> mcc -W cpplib:twoFractals twoFractals.m

3. The twoFractals shared library requires a client to utilize its public interface. Use the mbuild (MATLAB Compiler SDK) function to compile and link the fractalViewer C++ application against the twoFractals shared library. The fractalViewer C++ application invokes the twoFractals function with the appropriate inputs.

   >> mbuild fractalViewer.cpp twoFractals.lib

   This command produces an executable file fractalViewer.exe and a shared library twoFractals.dll on a Windows system.

   On Linux, it produces an executable twoFractals.so and a shared library fractalViewer. On macOS, it produces an executable twoFractals.dylib and a shared library fractalViewer.

4. Run the fractalViewer executable at the system command prompt to display the Mandelbrot set and Koch snowflake.

   C:\fractalViewer> fractalViewer

   Two windows appear, one containing the Mandelbrot set and one displaying the Koch snowflake.

Create Deployable Archives That Use Add-Ons

This example shows how to package a proxy function that is in one MATLAB Production Server add-on into a MATLAB Production Server archive, from which you can install a second MATLAB Production Server add-on. In this case, the proxy functions of the second add-on call the proxy functions of the first add-on, which in turn call the actual functions (functions hosted on the first MATLAB Production Server instance) of the first add-on. With this feature, you can chain together multiple MATLAB Production Server archives. However, longer chains require more network resources and run more slowly. Application access control is not supported for deployed archives that contain the add-on proxy functions.

This example requires MATLAB Compiler SDK.

1. For this example, copy the contents of the support_package_root\toolbox\mps\matlabclient\demo\fractalViewer folder to a separate writable location on your system, for example, to a folder called fractalViewer. The fractalViewer folder contains a MATLAB function twoFractals that displays images of the Mandelbrot set and the Koch snowflake.

2. Create a MATLAB function signature file twoFractalsFunctionSignatures.json in the writable fractalViewer folder. You require a MATLAB function signature file when you create a deployable archive of the twoFractals function. For more information, see MATLAB Function Signatures in JSON. A sample MATLAB function signature file follows.

    twoFractalsFunctionSignatures.json

   // Function Signatures
   // To optionally specify argument types and/or sizes, search for "type"
   // and insert the appropriate specifiers inside the brackets. For example:
   //
   //    "type": ["double", "size=1,1"]
   //
   // To modify function or parameter help text, search for "purpose" and edit
   // the values.
   //
   // JSON-formatted text below this line.
   {
       "_schemaVersion": "1.1.0",
       "twoFractals": {
           "inputs": [
               {
                   "name": "maxIterations",
                   "type": [],
                   "purpose": ""
               },
               {
                   "name": "width",
                   "type": [],
                   "purpose": ""
               },
               {
                   "name": "complexity",
                   "type": [],
                   "purpose": ""
               }
           ],
           "outputs": [],
           "purpose": " TWOFRACTALS Display Mandelbrot set and Koch snowflake.\n"
       }
   }

3. Navigate to the writable fractalViewer folder from the MATLAB command prompt. Use the mcc (MATLAB Compiler) command to create a deployable archive twoFractal.ctf from the twoFractals.m MATLAB function.

   >> cd fractalViewer
   >> mcc('-W','CTF:twoFractals,DISCOVERY:twoFractalsFunctionSignatures.json','-U','twoFractals.m')

4. Copy the resulting archive, twoFractals.ctf, to the auto_deploy folder of a MATLAB Production Server instance.

5. Then, install the twoFractals MATLAB Production Server add-on. For example, if your MATLAB Production Server instance has the network address localhost:9910, use the following command:

   >> prodserver.addon.install('twoFractals','localhost',9910)

6. Finally, invoke the twoFractals proxy function:

   >> twoFractals(300,600,5)

   Two windows appear, one containing the Mandelbrot set and one displaying the Koch snowflake.