compiler.build.excelAddIn

创建 Microsoft Excel 加载项

自 R2021a 起

全页折叠

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

语法

compiler.build.excelAddIn(FunctionFiles)

compiler.build.excelAddIn(FunctionFiles,Name,Value)

compiler.build.excelAddIn(opts)

results = compiler.build.excelAddIn(___)

说明

compiler.build.excelAddIn(FunctionFiles) 使用 FunctionFiles 指定的 Excel^® 函数创建一个 MATLAB^® 加载项。在创建 Excel 加载项之前，请安装支持的编译器。

示例

compiler.build.excelAddIn(FunctionFiles,Name,Value) 使用一个或多个名称-值参量指定选项来创建一个 Excel 加载项。选项包括加载项名称、输出目录以及是否生成 Microsoft^® Visual Basic^® 文件。

示例

compiler.build.excelAddIn(opts) 使用 compiler.build.excelAddInOptions 对象 opts 指定选项创建一个 Excel 加载项。不能使用名称-值参量指定任何其他选项。

示例

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

示例

全部折叠

创建 Excel 加载项

使用生成幻方的函数文件在 Excel 系统上创建 Windows 加载项。

确保已安装以下软件：

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

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

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

使用 compiler.build.excelAddIn 命令构建 Excel 加载项。

compiler.build.excelAddIn(appFile);

该函数会在当前工作目录中名为 magicsquareexcelAddIn 的文件夹中生成以下文件：

dlldata.c
GettingStarted.html
includedSupportPackages.txt
magicsquare.def
magicsquare.bas（仅当您启用 'GenerateVisualBasicFile' 选项时）
magicsquare.rc
magicsquare.xla（仅当您启用 'GenerateVisualBasicFile' 选项时）
magicsquare_1_0.dll
magicsquare_dll.cpp
magicsquare_idl.h
magicsquare_idl.idl
magicsquare_idl.tlb
magicsquare_idl_i.c
magicsquare_idl_p.c
magicsquareClass_com.cpp
magicsquareClass_com.hpp
mccExcludedFiles.log
mwcomtypes.h
mwcomtypes_i.c
mwcomtypes_p.c
readme.txt
requiredMCRProducts.txt
unresolvedSymbols.txt

自定义 Excel 加载项

在 Excel 系统上创建一个 Windows 加载项并使用名称-值参量对其进行自定义。

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

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

使用 compiler.build.excelAddIn 命令构建 Excel 加载项。使用名称-值参量指定加载项名称和版本，生成 Microsoft Visual Basic 文件并启用详尽输出。

compiler.build.excelAddIn(appFile,'AddInName','MyMagicSquare', ...
'AddInVersion','2.0', ...
'GenerateVisualBasicFile','on', ...
'Verbose','on');

该函数会在当前工作目录中名为 MyMagicSquareexcelAddIn 的文件夹中生成以下文件：

dlldata.c
GettingStarted.html
includedSupportPackages.txt
magicsquareClass_com.cpp
magicsquareClass_com.hpp
mccExcludedFiles.log
mwcomtypes.h
mwcomtypes_i.c
mwcomtypes_p.c
MyMagicSquare.bas
MyMagicSquare.def
MyMagicSquare.rc
MyMagicSquare.xla
MyMagicSquare_2_0.dll
MyMagicSquare_dll.cpp
MyMagicSquare_idl.h
MyMagicSquare_idl.idl
MyMagicSquare_idl.tlb
MyMagicSquare_idl_i.c
MyMagicSquare_idl_p.c
readme.txt
requiredMCRProducts.txt
unresolvedSymbols.txt

使用选项对象创建多个加载项

使用 compiler.build.ExcelAddInOptions 对象在 Excel 系统上创建多个 Windows 加载项。

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

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

使用 appFile 创建 ExcelAddInOptions 对象。使用名称-值参量指定一个公共输出目录，生成一个 Visual Basic 文件，并启用详尽输出。

opts = compiler.build.excelAddInOptions(appFile, ...
'OutputDir','D:\Documents\MATLAB\work\ExcelAddInBatch', ...
'GenerateVisualBasicFile','on', ...
'Verbose','on');

使用 ExcelAddInOptions 对象构建加载项。

compiler.build.excelAddIn(opts);

要使用具有相同选项的函数文件 myMagic2.m 创建新的加载项，请在再次运行构建函数之前使用点符号修改现有 ExcelAddInOptions 对象的 FunctionFiles 参量。

opts.FunctionFiles = 'myMagic2.m';
compiler.build.excelAddIn(opts);

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

从 Excel 加载项获取编译信息

创建一个 Excel 加载项并将有关构建类型、生成的文件、包含的支持包和构建选项的信息保存到 compiler.build.Results 对象中。

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

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

results = 

  Results with properties:

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

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

magicsquare_1_0.dll
GettingStarted.html

注意

仅当您在构建命令中启用 magicsquare.bas 选项时，文件 magicsquare.xla 和 Files 才会包含在 'GenerateVisualBasicFile' 中。

输入参数

全部折叠

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

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

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

数据类型: char | string | cell

`opts` — Excel 加载项编译选项
`compiler.build.ExcelAddInOptions` 对象

Excel 加载项构建选项，指定为 compiler.build.ExcelAddInOptions 对象。

名称-值参数

全部折叠

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

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

示例: 'Verbose','on'

`AddInName` — Excel 加载项的名称
字符向量 | 字符串标量

Excel 加载项的名称，指定为字符向量或字符串标量。生成的加载项的默认名称是 FunctionFiles 参量的第一个条目。名称必须以字母开头，并且只能包含字母字符和下划线。

示例: 'AddInName','myAddIn'

数据类型: char | string

`AddInVersion` — 加载项版本
`'1.0.0.0'` (默认) | 字符向量 | 字符串标量

加载项版本，指定为字符向量或字符串标量。

示例: 'AddInVersion','4.0'

数据类型: char | string

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

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

示例: '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）的输入提供的数据文件将自动包含在加载项中。
如果将此属性设置为 'off'，则必须使用 AdditionalFiles 属性将数据文件添加到加载项。

示例: 'AutoDetectDataFiles','Off'

数据类型: logical

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

类的名称，指定为字符向量或字符串标量。类名必须符合 Excel 加载项类名要求。

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

示例: 'ClassName','magicsquareClass'

数据类型: 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'，则不会包含调试符号。这是默认选项。

示例: 'DebugSymbols','on'

数据类型: logical

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

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

如果将此属性设置为 'on'，则该函数会将可部署存档嵌入到 Excel 加载项中。
如果将此属性设置为 '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

`GenerateVisualBasicFile` — 生成 Visual Basic 文件的标志
`'off'` (默认) | on/off 逻辑值

用于生成 Visual Basic 文件 (.bas) 和 Excel 加载项文件 (.xla) 的标志，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，值 'off' 等效于 false。因此，可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on'，则该函数将生成一个 Excel 加载项 XLA 文件和一个 Visual Basic BAS 文件，其中包含加载项的 Microsoft Excel 公式函数接口。
如果将此属性设置为 'off'，则该函数不会生成 Visual Basic 文件或 Excel 加载项文件。

注意

要生成 Excel 加载项文件 (.xla)，您必须启用 Excel 设置中的“信任对 VBA 工程对象模型的访问”。

示例: 'GenerateVisualBasicFile','on'

数据类型: logical

`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` — 输出目录路径
字符向量 | 字符串标量

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

构建文件夹的默认名称是加载项名称加上 excelAddIn。

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

数据类型: 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 对象包含：

编译类型，即 'excelAddIn'
以下文件的路径：
- GettingStarted.html
- AddInName_AddInVersion.dll
- AddInName.bas（如果启用 'GenerateVisualBasicFile' 选项）
- AddInName.xla（如果启用 'GenerateVisualBasicFile' 选项）
包含的支持包的列表
构建选项，指定为 ExcelAddInOptions 对象
必需和可选依赖项的列表，指定为 Dependencies 对象

版本历史记录

在 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.ExcelAddInOptions | Excel 加载项编译器 | mcc

主题

从 MATLAB 创建 Excel 加载项

compiler.build.excelAddIn

语法

说明

示例

创建 Excel 加载项

自定义 Excel 加载项

使用选项对象创建多个加载项

从 Excel 加载项获取编译信息

输入参数

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

opts — Excel 加载项编译选项 compiler.build.ExcelAddInOptions 对象

名称-值参数

AddInName — Excel 加载项的名称 字符向量 | 字符串标量

AddInVersion — 加载项版本 '1.0.0.0' (默认) | 字符向量 | 字符串标量

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

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

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

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

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

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

GenerateVisualBasicFile — 生成 Visual Basic 文件的标志 'off' (默认) | on/off 逻辑值

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

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

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

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

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

输出参量

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

版本历史记录

R2024b: 指定加密密钥

R2024b: 打包包含机密的代码

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

R2021b: 指定支持包

另请参阅

主题

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

`opts` — Excel 加载项编译选项
`compiler.build.ExcelAddInOptions` 对象

`AddInName` — Excel 加载项的名称
字符向量 | 字符串标量

`AddInVersion` — 加载项版本
`'1.0.0.0'` (默认) | 字符向量 | 字符串标量

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

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

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

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

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

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

`GenerateVisualBasicFile` — 生成 Visual Basic 文件的标志
`'off'` (默认) | on/off 逻辑值

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

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

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

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

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

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