compiler.build.comComponent

创建 COM 组件以在 MATLAB 之外部署

自 R2021a 起

全页折叠

语法

compiler.build.comComponent(Files)

compiler.build.comComponent(Files,Name,Value)

compiler.build.comComponent(ClassMap)

compiler.build.comComponent(ClassMap,Name,Value)

compiler.build.comComponent(opts)

results = compiler.build.comComponent(___)

说明

小心

该函数仅支持 Windows^® 操作系统。

compiler.build.comComponent(Files) 使用 Files 指定的 MATLAB^® 函数创建一个 COM 组件。

示例

compiler.build.comComponent(Files,Name,Value) 使用一个或多个名称-值参量指定附加选项来创建一个 COM 组件。选项包括类名、输出目录和要包含的附加文件。

示例

compiler.build.comComponent(ClassMap) 使用 container.Map 对象 ClassMap 指定类映射来创建 COM 组件。

示例

compiler.build.comComponent(ClassMap,Name,Value) 使用 ClassMap 和使用一个或多个名称-值参量指定的附加选项创建一个 COM 组件。选项包括组件名称、输出目录和要包含的附加文件。

示例

compiler.build.comComponent(opts) 使用 compiler.build.COMComponentOptions 对象 opts 指定选项创建一个 COM 组件。不能使用名称-值参量指定任何其他选项。

示例

results = compiler.build.comComponent(___) 使用以上语法中的任意参量组合以 compiler.build.Results 对象形式返回编译信息。编译信息包括编译类型、编译文件的路径以及编译选项。

示例

全部折叠

使用文件创建 COM 组件

使用生成幻方的函数文件在 Windows 系统上创建 COM 组件。

确保已安装以下软件：

Windows SDK。有关详细信息，请参阅 Windows SDK。
MinGW-w64。要从 MathWorks^® 文件交换中心安装它，请参阅 MATLAB 对 MinGW-w64 C/C++ 编译器的支持。
使用 mbuild -setup -client mbuild_com 确保 MATLAB 能够创建 COM 组件。

在 MATLAB 中，定位要部署为 COM 组件的 MATLAB 函数。对于此示例，使用 matlabroot\extern\examples\compiler 中的文件 magicsquare.m。

copyfile(fullfile(matlabroot,'extern','examples','compiler','magicsquare.m'));
appFile = which('magicsquare.m')

使用 compiler.build.comComponent 命令构建 COM 组件。

compiler.build.comComponent(appFile);

该编译函数会在当前工作目录中名为 magicsquarecomComponent 的文件夹中创建以下文件：

dlldata.c - 包含 DLL 类工厂所需的入口点和数据结构的 C 源代码文件。
GettingStarted.html - 包含安装 COM 组件步骤的 HTML 文件。
includedSupportPackages.txt - 列出组件中包含的所有支持文件的文本文件。
magicsquare.def - 模块定义文件，定义哪些函数包含在 DLL 导出表中。
magicsquare.rc - 描述组件使用的资源的资源脚本文件。
magicsquare_1_0.dll - 动态链接库文件。
magicsquare_dll.cpp - 包含辅助函数的 C++ 源代码文件。
magicsquare_idl.h - C++ 头文件。
magicsquare_idl.idl - 接口定义语言文件。
magicsquare_idl.tlb - 包含有关 COM 对象属性和方法的信息的类型库文件。
magicsquare_idl_i.c - 包含 IDL 接口的 IID 和 CLSID 的 C 源代码文件。
magicsquare_idl_p.c - 包含 IDL 接口的代理桩件代码的 C 源代码文件。
magicsquareClass_com.cpp - 定义类的 C++ 源代码文件。
magicsquareClass_com.hpp - 定义类的 C++ 头文件。
mccExcludedFiles.log - 包含应用程序中未包含的任何工具箱函数列表的日志文件。有关不支持的函数的信息，请参阅 MATLAB Compiler 限制。
mwcomtypes.h - 包含接口定义的 C++ 头文件。
mwcomtypes_i.c - 包含 IID 和 CLSID 的 C 源代码文件。
mwcomtypes_p.c - 包含代理桩件代码的 C 源代码文件。
readme.txt - 包含部署信息的文本文件。
requiredMCRProducts.txt - 包含 MATLAB Runtime 运行应用程序所需产品的产品 ID 的文本文件。
unresolvedSymbols.txt - 包含有关未解析符号的信息的文本文件。

有关如何将此组件集成到独立的 Microsoft^® Visual Basic^® 应用程序中的示例，请参阅将 Magic Square 集成到 COM 应用程序中。

有关构建 COM 对象和映射到其他语言的 IDL 和 C++ 编码规则的详细信息，请参阅 Microsoft 文档。

自定义 COM 组件

在 Windows 系统上创建一个 COM 组件并使用名称-值参量对其进行自定义。

对于此示例，使用 matlabroot\extern\examples\compiler 中的文件 flames.m 和 flames.mat。

appFile = fullfile(matlabroot,'extern','examples','compiler','flames.m');
MATFile = fullfile(matlabroot,'extern','examples','compiler','flames.mat');

使用 compiler.build.comComponent 命令构建 COM 组件。使用名称-值参量指定组件名称和版本，添加 MAT 文件并启用详尽输出。

compiler.build.comComponent(appFile, ...
'ComponentName','MyFlames','ComponentVersion','2.0', ...
'AdditionalFiles',MATFile,'Verbose','on');

有关如何将此组件集成到独立的 Microsoft Visual Basic 应用程序中的示例，请参阅将 Magic Square 集成到 COM 应用程序中。

使用类映射创建 COM 组件

使用类映射和多个函数文件在 Windows 系统上创建 COM 组件。

创建一个 containers.Map 对象，其键是类名，其值是函数文件的位置。

cmap = containers.Map;
cmap('Class1') = {'exampleFcn1.m'};
cmap('Class2') = {'exampleFcn2.m','exampleFcn3.m'};

使用 compiler.build.comComponent 命令构建 COM 组件。使用名称-值参量指定组件名称和版本。

compiler.build.comComponent(cmap, ...
'ComponentName','MyComponent', ...
'ComponentVersion','2.0');

有关如何将此组件集成到独立的 Microsoft Visual Basic 应用程序中的示例，请参阅将 Magic Square 集成到 COM 应用程序中。

使用选项对象创建多个组件

使用 compiler.build.COMComponentOptions 对象在 Windows 系统上创建多个 COM 组件。

对于此示例，使用 matlabroot\extern\examples\compiler 中的文件 magicsquare.m。

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

使用 appFile 创建一个 COMComponentOptions 对象。使用名称-值参量指定一个公共输出目录，单独生成程序集存档，并启用详尽输出。

opts = compiler.build.COMComponentOptions(appFile,...
'OutputDir','D:\Documents\MATLAB\work\COMComponentBatch',...
'EmbedArchive','off',...
'Verbose','on')

opts = 

  COMComponentOptions with properties:

                 ClassMap: [1×1 containers.Map]
            ComponentName: 'magicsquare'
         ComponentVersion: '1.0.0.0'
               DebugBuild: off
             EmbedArchive: off
          AdditionalFiles: {}
      AutoDetectDataFiles: on
    ExternalEncryptionKey: [0×0 struct]
         ObfuscateArchive: off
          SecretsManifest: ''
          SupportPackages: {'autodetect'}
                  Verbose: on
                OutputDir: 'D:\Documents\MATLAB\work\COMComponentBatch'

   Class Map Information
         magicsquareClass: {'C:\Program Files\MATLAB\R2025a\extern\examples\compiler\magicsquare.m'}

使用 COMComponentOptions 对象构建 COM 组件。

compiler.build.comComponent(opts);

要使用具有相同选项的函数文件 myMagic2.m 进行编译，请在再次运行构建函数之前使用点符号修改现有 COMComponentOptions 对象的 ClassMap。

remove(opts.ClassMap, keys(opts.ClassMap));
opts.ClassMap('myMagic2Class') = 'myMagic2.m';
compiler.build.comComponent(opts);

通过修改 ClassMap 参量并重新编译，您可以使用相同的选项对象创建多个组件。

从 COM 组件获取构建信息

在 Windows 系统上创建一个 COM 组件，并将有关构建类型、生成的文件、包含的支持包和构建选项的信息保存到 compiler.build.Results 对象中。

使用文件 magicsquare.m 进行编译。

results = compiler.build.comComponent('magicsquare.m')

results = 

  Results with properties:

              BuildType: 'comComponent'
                  Files: {2×1 cell}
IncludedSupportPackages: {}
                Options: [1×1 compiler.build.COMComponentOptions]
    RuntimeDependencies: [1×1 compiler.runtime.Dependencies]

Files 属性包含以下已编译文件的路径：

magicsquare_1_0.dll
GettingStarted.html

输入参数

全部折叠

`Files` — 实现 MATLAB 函数的文件
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

实现 MATLAB 函数的文件，指定为字符向量、字符串标量、字符串数组或字符向量元胞数组。文件路径可以是相对于当前工作目录的路径，也可以是绝对路径。文件必须具有以下扩展名之一：.m、.p、.mlx 或 .mexa64。

示例: ["myfunc1.m","myfunc2.m"]

数据类型: char | string | cell

`ClassMap` — 类映射
`containers.Map` 对象

类映射，指定为 containers.Map 对象。映射键是类名，每个值是映射到相应类的文件集合。文件必须具有以下扩展名之一：.m、.p、.mlx 或 .mexa64。

示例: cmap

`opts` — COM 组件构建选项
`compiler.build.COMComponentOptions` 对象

COM 组件构建选项，指定为 compiler.build.COMComponentOptions 对象。

名称-值参数

全部折叠

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

如果使用的是 R2021a 之前的版本，请使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: 'EmbedArchive','on'

`AdditionalFiles` — 其他文件
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

要包含在 COM 组件中的附加文件和文件夹，指定为字符向量、字符串标量、字符串数组或字符向量元胞数组。路径可以是相对于当前工作目录的路径，也可以是绝对路径。

示例: 'AdditionalFiles',["myvars.mat","data.txt"]

数据类型: char | string | cell

`AutoDetectDataFiles` — 自动包含数据文件的标志
`'on'` (默认) | on/off 逻辑值

自动包含数据文件的标志，指定为 'on' 或 'off'，或者指定为数值或逻辑 1 (true) 或 0 (false)。值 'on' 等效于 true，值 'off' 等效于 false。因此，可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on'，则您作为某些函数（例如 load 和 fopen）的输入提供的数据文件将自动包含在 COM 组件中。
如果将此属性设置为 'off'，则必须使用 AdditionalFiles 属性将数据文件添加到组件。

示例: 'AutoDetectDataFiles','off'

数据类型: logical

`ClassName` — COM 类的名称
字符向量 | 字符串标量

COM 类的名称，指定为字符向量或字符串标量。如果使用 ClassMap 输入，则无法指定此选项。类名称必须符合 COM 类名称要求。

默认值是 Files 参量中列出的第一个文件的名称加上 Class。

示例: 'ClassName','magicsquareClass'

数据类型: char | string

`ComponentName` — COM 组件的名称
字符向量 | 字符串标量

COM 组件的名称，指定为字符向量或字符串标量。该值充当输入到 Windows 注册表中的程序 ID。生成的组件的默认名称是 Files 参量的第一个条目。名称必须以字母开头，并且只能包含字母字符和句点。

示例: 'ComponentName','mycomponent'

数据类型: char | string

`ComponentVersion` — 组件版本
`'1.0.0.0'` (默认) | 字符向量 | 字符串标量

组件版本，指定为字符向量或字符串标量。有关使用 MATLAB Compiler SDK™ 进行版本控制的信息，请参阅版本控制。

示例: 'ComponentVersion','4.0'

数据类型: char | string

`DebugBuild` — 启用调试符号的标志
`'off'` (默认) | on/off 逻辑值

标志以包含调试符号，指定为 'on' 或 'off'，或者指定为数字或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，值 'off' 等效于 false。因此，可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on'，则调试符号信息将包含在编译的工件中。此选项还会使 mbuild 将相应的调试标志传递到系统编译器。通过调试选项，您可以回溯到能够确定故障是发生在 MATLAB Runtime 初始化、函数调用还是终止例程中的时间点。此选项不允许您使用外部调试器调试 MATLAB 文件。
如果将此属性设置为 'off'，则不会包含调试符号。这是默认选项。

示例: 'DebugBuild','on'

数据类型: logical

`EmbedArchive` — 嵌入可部署存档的标志
`'on'` (默认) | on/off 逻辑值

嵌入可部署存档的标志，指定为 'on' 或 'off'，或指定为数值或逻辑 1 (true) 或 0 (false)。值 'on' 等效于 true，值 'off' 等效于 false。因此，可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on'，则该函数会将可部署存档嵌入到 COM 组件中。
如果将此属性设置为 'off'，则此函数会将可部署存档生成为单独的文件。

示例: 'EmbedArchive','off'

数据类型: logical

`ExternalEncryptionKey` — 加密密钥和加载程序文件路径
标量结构体

自 R2024b 起

外部 AES 加密密钥和 MEX 密钥加载程序文件的路径，指定为标量结构体，其中恰好有两个分别名为 EncryptionKeyFile 和 RuntimeKeyLoaderFile 的行字符向量或字符串标量字段。两个结构体字段都是必需的。文件路径可以是相对于当前工作目录的路径，也可以是绝对路径。

例如，使用结构体 keyValueStruct 将加密密钥指定为 encrypt.key，将加载程序文件指定为 loader.mexw64。

keyValueStruct.EncryptionKeyFile='encrypt.key'; keyValueStruct.RuntimeKeyLoaderFile='loader.mexw64'

加密密钥文件必须采用以下受支持的格式之一：

二进制 256 位 AES 密钥，文件大小为 32 字节
十六进制编码的 AES 密钥，文件大小为 64 字节

MEX 文件加载程序在运行时检索解密密钥，并且必须是具有以下参量的接口：

prhs[0] - 输入，指定为静态值 'get' 的字符数组
prhs[1] - 输入，指定为 CTF 组件 UUID 的字符数组
plhs[0] - 输出，32 字节 UINT8 数字数组或 64 字节十六进制编码字符数组，具体取决于密钥格式

请勿在多个 CTF 之间共享同一个密钥。

示例: 'ExternalEncryptionKey',keyValueStruct

数据类型: struct

`ObfuscateArchive` — 混淆处理可部署存档的标志
`'off'` (默认) | on/off 逻辑值

混淆可部署存档的标志，指定为 'on'/1/true 或 'off'/0/false。该值存储为 matlab.lang.onoffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on'，则会对最终用户混淆可部署存档中的文件夹结构和文件名，并且 .m、.mlapp、.p、.mat、MLX 文件、SFX 文件和 MEX 文件中包含的用户代码和数据将被放入存档内的用户包中。另外，所有 .m 文件在打包前会转换为 P 文件。

在运行时，系统会从用户包直接解密和加载 MATLAB 代码和数据，而不是将其提取到文件系统。在加载之前，系统会从用户包中临时提取 MEX 文件。

要在用户包中手动包含其他文件类型，请将每种文件类型以单独的扩展标记的形式添加到文件 matlabroot/toolbox/compiler/advanced_package_supported_files.xml 中。

以下内容不受支持：

ver 函数
调用外部库，例如 DLL
进程外 MATLAB Runtime（用于 MATLAB Data Array 的 C++ 共享库）
进程外 MEX 文件执行（mexhost、feval、matlab.mex.MexHost）
在 R2023b 之前的版本中: v7.3 之外的 .mat 文件

启用此选项等效于在指定了 -j 和 -s 的情况下使用 mcc。

如果将此属性设置为 'off'，则不会混淆可部署存档。这是默认行为。

示例: 'ObfuscateArchive','on'

数据类型: logical

`OutputDir` — 输出目录路径
字符向量 | 字符串标量

保存编译文件的输出目录的路径，指定为字符向量或字符串标量。该路径可以是相对于当前工作目录的路径，也可以是绝对路径。

构建文件夹的默认名称是组件名称加上 comComponent。

示例: 'OutputDir','D:\Documents\MATLAB\work\mycomponentcomComponent'

数据类型: char | string

`SecretsManifest` — JSON 清单文件路径
字符向量 | 字符串标量

自 R2024b 起

机密清单 JSON 文件的路径，该文件指定要嵌入在可部署存档中的密钥，指定为字符向量或字符串标量。该路径可以是相对于当前工作目录的路径，也可以是绝对路径。

如果您的 MATLAB 代码调用 getSecret、getSecretMetadata 或 isSecret 函数，您必须在 JSON 机密清单文件中指定要嵌入可部署存档的密钥。如果您的代码调用 getSecret 并且您未指定 SecretsManifest 选项，则 MATLABCompiler™ 会发出警告，并在名为 <component_name>_secrets_manifest.json 的输出文件夹中生成一个模板 JSON 文件。通过在嵌入字段中指定密钥名称来修改此文件。

setSecret 函数不可部署。要将密钥嵌入在可部署存档中，您必须在构建存档之前在 MATLAB 中调用 setSecret。

有关使用密钥进行部署的详细信息，请参阅处理已部署 App 中的敏感信息。

示例: 'SecretsManifest','D:\Documents\MATLAB\work\mycomponent\mycomponent_secrets_manifest.json'

数据类型: char | string

`SupportPackages` — 支持包
`'autodetect'` (默认) | `'none'` | 字符串标量 | 字符向量元胞数组 | 字符串数组

要包含的支持包，指定为以下选项之一：

'autodetect'（默认值）- 依赖关系分析过程会自动检测并包含所需的支持包。
'none' - 不包括任何支持包。使用此选项可能会导致运行时错误。
字符串标量、字符向量或字符向量元胞数组 - 仅包含指定的支持包。要列出已安装的支持包或特定文件使用的那些支持包，请参阅 compiler.codetools.deployableSupportPackages。

示例: 'SupportPackages',{'Deep Learning Toolbox Converter for TensorFlow Models','Deep Learning Toolbox Model for Places365-GoogLeNet Network'}

数据类型: char | string | cell

`Verbose` — 控制编译详细程度的标志
`'off'` (默认) | on/off 逻辑值

控制编译详细程度的标志，指定为 'on' 或 'off'，或者指定为数值或逻辑 1 (true) 或 0 (false)。值 'on' 等效于 true，值 'off' 等效于 false。因此，可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on'，则 MATLAB 命令行窗口会显示进度信息，指示编译过程期间的编译器输出。
如果将此属性设置为 'off'，则命令行窗口不会显示进度信息。

示例: 'Verbose','on'

数据类型: logical

输出参量

全部折叠

`results` — 编译结果
`compiler.build.Results` 对象

编译结果，以 compiler.build.Results 对象形式返回。Results 对象包含：

编译类型，即 'comComponent'
以下文件的路径：
- ComponentName_ComponentVersion.dll
- GettingStarted.html
包含的支持包
编译选项，指定为 COMComponentOptions 对象
必需和可选依赖项的列表，指定为 Dependencies 对象

限制

该函数仅支持 Windows 操作系统。

版本历史记录

在 R2021a 中推出

全部展开

R2024b: 指定加密密钥

使用 ExternalEncryptionKey 选项指定 256 位 AES 加密密钥和 MEX 文件加载程序接口，以在运行时检索解密密钥。此选项等效于 mcc -k 选项。

R2024b: 打包包含机密的代码

使用 SecretsManifest 选项包括一个 JSON 文件，该文件指定要嵌入可部署代码存档中的机密。此选项等效于 mcc -J 选项。

R2023a: 混淆文件结构和 MATLAB 代码

使用 ObfuscateArchive 选项混淆文件夹结构和文件名，并将 MATLAB 文件数据和用户代码放入存档内的用户包中。另外，所有 .m 文件在打包前会转换为 P 文件。此选项等效于在指定了 -j 和 -s 的情况下使用 mcc。

R2021b: 指定支持包

使用 SupportPackages 选项指定要包含在可部署代码存档中的支持包。

另请参阅

compiler.build.COMComponentOptions | mcc

主题

将 Magic Square 集成到 COM 应用程序中

compiler.build.comComponent

语法

说明

示例

使用文件创建 COM 组件

自定义 COM 组件

使用类映射创建 COM 组件

使用选项对象创建多个组件

从 COM 组件获取构建信息

输入参数

Files — 实现 MATLAB 函数的文件 字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

ClassMap — 类映射 containers.Map 对象

opts — COM 组件构建选项 compiler.build.COMComponentOptions 对象

名称-值参数

AdditionalFiles — 其他文件 字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

AutoDetectDataFiles — 自动包含数据文件的标志 'on' (默认) | on/off 逻辑值

ClassName — COM 类的名称 字符向量 | 字符串标量

ComponentName — COM 组件的名称 字符向量 | 字符串标量

ComponentVersion — 组件版本 '1.0.0.0' (默认) | 字符向量 | 字符串标量

DebugBuild — 启用调试符号的标志 'off' (默认) | on/off 逻辑值

EmbedArchive — 嵌入可部署存档的标志 'on' (默认) | on/off 逻辑值

ExternalEncryptionKey — 加密密钥和加载程序文件路径 标量结构体

ObfuscateArchive — 混淆处理可部署存档的标志 'off' (默认) | on/off 逻辑值

OutputDir — 输出目录路径 字符向量 | 字符串标量

SecretsManifest — JSON 清单文件路径 字符向量 | 字符串标量

SupportPackages — 支持包 'autodetect' (默认) | 'none' | 字符串标量 | 字符向量元胞数组 | 字符串数组

Verbose — 控制编译详细程度的标志 'off' (默认) | on/off 逻辑值

输出参量

results — 编译结果 compiler.build.Results 对象

限制

版本历史记录

R2024b: 指定加密密钥

R2024b: 打包包含机密的代码

R2023a: 混淆文件结构和 MATLAB 代码

R2021b: 指定支持包

另请参阅

主题

`Files` — 实现 MATLAB 函数的文件
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

`ClassMap` — 类映射
`containers.Map` 对象

`opts` — COM 组件构建选项
`compiler.build.COMComponentOptions` 对象

`AdditionalFiles` — 其他文件
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

`AutoDetectDataFiles` — 自动包含数据文件的标志
`'on'` (默认) | on/off 逻辑值

`ClassName` — COM 类的名称
字符向量 | 字符串标量

`ComponentName` — COM 组件的名称
字符向量 | 字符串标量

`ComponentVersion` — 组件版本
`'1.0.0.0'` (默认) | 字符向量 | 字符串标量

`DebugBuild` — 启用调试符号的标志
`'off'` (默认) | on/off 逻辑值

`EmbedArchive` — 嵌入可部署存档的标志
`'on'` (默认) | on/off 逻辑值

`ExternalEncryptionKey` — 加密密钥和加载程序文件路径
标量结构体

`ObfuscateArchive` — 混淆处理可部署存档的标志
`'off'` (默认) | on/off 逻辑值

`OutputDir` — 输出目录路径
字符向量 | 字符串标量

`SecretsManifest` — JSON 清单文件路径
字符向量 | 字符串标量

`SupportPackages` — 支持包
`'autodetect'` (默认) | `'none'` | 字符串标量 | 字符向量元胞数组 | 字符串数组

`Verbose` — 控制编译详细程度的标志
`'off'` (默认) | on/off 逻辑值

`results` — 编译结果
`compiler.build.Results` 对象