compiler.package.DockerOptions

Create a Docker options object

Since R2020b

Syntax

opts = compiler.package.DockerOptions(results)

opts = compiler.package.DockerOptions(results,Name,Value)

opts = compiler.package.DockerOptions('ImageName',imageName)

opts = compiler.package.DockerOptions('ImageName',imageName,Name,Value)

Description

Caution

This function is only supported on Linux^® operating systems.

opts = compiler.package.DockerOptions(results) creates a DockerOptions object opts using the compiler.build.Results object results. The Results object is created by a compiler.build function. The DockerOptions object is passed as an input to the compiler.package.docker function to specify build options.

opts = compiler.package.DockerOptions(results,Name,Value) creates a DockerOptions object opts using the compiler.build.Results object results and additional options specified as one or more pairs of name-value arguments. Options include the build folder, entry point command, and image name.

opts = compiler.package.DockerOptions('ImageName',imageName) creates a default DockerOptions object with the image name specified by imageName.

opts = compiler.package.DockerOptions('ImageName',imageName,Name,Value) creates a default DockerOptions object with the image name specified by imageName and additional options specified as one or more pairs of name-value arguments.

Examples

Create a Docker Options Object Using Build Results

Create a DockerOptions object using the build results from a standalone application on a Linux system.

Create a standalone application using magicsquare.m and save the build results to a compiler.build.Results object.

appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
buildResults = compiler.build.standaloneApplication(appFile);

Create a DockerOptions object using the build results from the compiler.build.standaloneApplication function.

opts = compiler.package.DockerOptions(buildResults);

You can modify property values of an existing DockerOptions object using dot notation. For example, set the build folder.

opts.DockerContext = 'myDockerFiles';

The DockerOptions and Results objects are passed as inputs to the compiler.package.docker function to build the Docker^® image.

compiler.package.docker(buildResults,'Options',opts);

Customize Docker Options Object Using Build Results

Create a DockerOptions object using build results from a standalone application and customize it using name-value arguments.

Create a standalone application using magicsquare.m and save the build results to a compiler.build.Results object.

appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');
buildResults = compiler.build.standaloneApplication(appFile);

Create a DockerOptions object using the build results from the compiler.build.standaloneApplication function. Use name-value arguments to specify the image name and build folder.

opts = compiler.package.DockerOptions(buildResults,...
    'DockerContext','Docker/MagicSquare',...
    'ImageName','magic-square-');

opts = 

  DockerOptions with properties:

                EntryPoint: 'magicsquare'
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
                 ImageName: 'magic-square-'
             DockerContext: './Docker/MagicSquare/magic-square-docker'

Create Docker Options Object Using Image Name

Create a default DockerOptions object to specify the image name.

Create a DockerOptions object.

opts = compiler.package.DockerOptions('ImageName','helloworld')

opts = 

  DockerOptions with properties:

                EntryPoint: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
                 ImageName: 'helloworld'
             DockerContext: './helloworlddocker'

You can modify property values of an existing DockerOptions object using dot notation. For example, populate the DockerContext folder without calling 'docker build'.

opts.ExecuteDockerBuild = 'Off';

opts = 

  DockerOptions with properties:

                EntryPoint: ''
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: off
                 ImageName: 'helloworld'
             DockerContext: './helloworlddocker'

Customize Docker Options Object Using Image Name

Create a DockerOptions object using the image name and customize it using name-value arguments.

Create a DockerOptions object. Use name-value arguments to specify the build folder and entry point command.

opts = compiler.package.DockerOptions('ImageName','myapp-',...
'DockerContext','Docker/MyDockerApp',...
'EntryPoint',"exec top -b")

opts = 

  DockerOptions with properties:

                EntryPoint: 'exec top -b'
    AdditionalInstructions: {}
        AdditionalPackages: {}
        ExecuteDockerBuild: on
                 ImageName: 'myapp-'
             DockerContext: './Docker/MyDockerApp'

Input Arguments

results — Build results

compiler.build.Results object

Build results created by a compiler.build function, specified as a compiler.build.Results object.

imageName — Name of Docker image

character vector | string scalar

Name of the Docker image. It must comply with Docker naming rules.

Example: 'hello-world'

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'ExecuteDockerBuild','on'

AdditionalCommands — Additional commands to pass to Docker image

'' (default) | character vector | string scalar | cell array of character vectors

Additional commands to pass to the Docker image, specified as a character vector, a string scalar, or a cell array of character vectors. Commands are added to the Dockerfile and execute during image generation.

Example: 'AdditionalCommands','top'

Data Types: char | string

AdditionalPackages — Additional packages to install into Docker image

'' (default) | character vector | string scalar | cell array of character vectors

Additional Ubuntu^® 20.04 packages to install into the Docker image, specified as a character vector, a string scalar, or a cell array of character vectors.

Example: 'AdditionalPackages,'syslog-ng'

Data Types: char | string

DockerContext — Path to build folder

'ImageNamedocker' (default) | character vector | string scalar

Path to the build folder where the Docker image is built, specified as a character vector or a string scalar. The path can be relative to the current working directory or absolute.

If no path is specified, the function creates a build folder named ImageNamedocker in the current working directory.

Example: 'DockerContext','/home/mluser/Documents/MATLAB/docker/magicsquaredocker'

Data Types: char | string

EntryPoint — Command executed at image start-up

'' (default) | character vector | string scalar

The command to be executed at image start-up, specified as a character vector or a string scalar.

Example: 'EntryPoint',"exec top -b"

Data Types: char | string

ExecuteDockerBuild — Flag to build Docker image

'on' (default) | on/off logical value

Flag to build the Docker image, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• If you set this property to 'on', then the function will build the Docker image.

• If you set this property to 'off', then the function will populate the DockerContext folder without calling 'docker build'.

Example: 'ExecuteDockerBuild','Off'

Data Types: logical

ImageName — Name of Docker image

'' (default) | character vector | string scalar

Name of the Docker image, specified as a character vector or a string scalar. The name must comply with Docker naming rules. Docker repository names must be lowercase. If the main executable or archive file is named using uppercase letters, then the uppercase letters are replaced with lowercase letters in the Docker image name.

Example: 'ImageName','magicsquare'

Data Types: char | string

Output Arguments

opts — Docker options object

DockerOptions object

Docker image build options, returned as a DockerOptions object.

Limitations

• Only standalone applications can be packaged into Docker images as of R2020b.

Version History

Introduced in R2020b