C++ MATLAB データ API 共有ライブラリの生成と C++ アプリケーションのビルド

サポートされるプラットフォーム: Windows^®、Linux^®、Mac

この例では、MATLAB^® 関数から C++ 共有ライブラリを作成する方法を説明します。生成されたライブラリは、C++ アプリケーションに統合できます。また、この例では、C++ アプリケーションから C++ 共有ライブラリを呼び出す方法も示します。このアプリケーションを実行するために、MATLAB のライセンスコピーがターゲットシステムにインストールされている必要はありません。

MATLAB での関数の作成

MATLAB で、パッケージ化対象の MATLAB コードを調べます。
MATLAB に付属している matrix フォルダーを作業フォルダーにコピーします。
```
copyfile(fullfile(matlabroot,'extern','examples','compilersdk','c_cpp','matrix'),'matrix')
```
作業フォルダー内の新しい matrix サブフォルダーに移動します。
関数 addmatrix.m、multiplymatrix.m、および eigmatrix.m を確認してテストします。

ライブラリコンパイラアプリを使用した C++ 共有ライブラリの作成

ライブラリコンパイラアプリを使用して関数を C++ 共有ライブラリにコンパイルします。あるいは、プログラムによる方法で MATLAB コマンドウィンドウから共有ライブラリを作成する場合は、compiler.build.cppSharedLibrary を使用した C++ 共有ライブラリの作成を参照してください。

[MATLAB アプリ] タブで、[アプリ] セクションの右端にある矢印をクリックします。[アプリケーションのデプロイ] で、[ライブラリコンパイラ] をクリックします。
または、MATLAB コマンドプロンプトで以下を入力して、[ライブラリコンパイラ] アプリを開きます。
```
libraryCompiler
```
ツールストリップの [タイプ] セクションで、[C++ 共有ライブラリ] をクリックします。
ライブラリコンパイラアプリのプロジェクトウィンドウで、デプロイする MATLAB アプリケーションのファイルを指定します。
1. ツールストリップの [エクスポートする関数] セクションで、をクリックします。
2. [ファイルの追加] ウィンドウで、サンプルのフォルダーを参照し、パッケージ化する関数を選択します。[開く] をクリックします。
エクスポートする関数ファイルのリストに関数が追加されます。同じアプリケーションに複数のファイルをパッケージ化するには、この手順を繰り返します。
addmatrix.m、multiplymatrix.m、および eigmatrix.m をメインファイルのリストに追加します。
ツールストリップの [パッケージ化オプション] セクションで次のオプションのいずれかを選択して、生成されるアプリケーションに MATLAB Runtime インストーラーを含めるかどうかを決定します。
- ランタイムを Web からダウンロード — MATLAB Runtime をダウンロードしてデプロイされた MATLAB アプリケーションと共にインストールするインストーラーを生成します。インストーラーのファイル名を指定できます。
- ランタイムをパッケージに含める — MATLAB Runtime インストーラーを含むアプリケーションを生成します。インストーラーのファイル名を指定できます。
  メモ
  このオプションを初めて選択したときに、MATLAB Runtime インストーラーをダウンロードするように求めるメッセージが表示されます。

共有ライブラリ設定の指定

[ライブラリ名] フィールドに、パッケージ化された共有ライブラリの名前として addmatrix が自動的に入力されます。この名前を libmatrix に変更します。同じ名前が、共有ライブラリの実装時にも使用されます。
生成される C++ 共有ライブラリの API の種類を選択します。下部の [API の選択] セクションで、[MATLAB データ API を使用するインターフェイスの作成] を選択します。既定のオプションのままにして両方のインターフェイスを作成することもできます。詳細については、C++ 共有ライブラリの API の選択を参照してください。

サンプルドライバーファイルの作成

関数を呼び出す MATLAB サンプルファイルを作成します。サンプルファイルを使用して、ターゲット言語のサンプルアプリケーションを生成します。プロジェクトの任意の MATLAB ファイルを使用して、サンプルコードを生成できます。サンプルファイルは共有ライブラリの作成に必須ではありませんが、独自のアプリケーションを実装するためのガイドとして使用できます。

パッケージ化手順で、サンプルドライバーファイルをまったく含めないことも選択できます。独自の C++ アプリケーションコードを作成する場合、MATLAB 関数のパッケージ化が完了してから mbuild を使用して適切なディレクトリに移動し、コンパイルできます。

プロジェクト内の各 MATLAB 関数のサンプルファイルを作成します。

たとえば、eigmatrix のサンプルファイルを作成するには、[サンプル] セクションで、[新規サンプルの作成] を選択して eigmatrix.m を選択します。MATLAB ファイルが編集用に開きます。

% Sample script to demonstrate execution of function e = eigmatrix(a1)
a1 = 0; % Initialize a1 here
e = eigmatrix(a1);

a1 = 0 を a1 = [1 4 7; 2 5 8; 3 6 9] に変更し、ファイルを保存して、[ライブラリコンパイラ] アプリに戻ります。

注意

目的の結果を出力するには MATLAB サンプルファイルを編集する "必要があります"。生成されたターゲット言語のサンプルファイルは、サンプル MATLAB ファイルと同じ入力と出力を使用します。

コンパイラにより、パッケージ化の際にこの MATLAB コードが C++ コードに変換されます。詳細と制限については、サンプルドライバーファイルの作成を参照してください。

アプリケーションとその外観のカスタマイズ

ライブラリコンパイラアプリでは、インストーラーをカスタマイズし、アプリケーションをカスタマイズし、アプリケーションについて情報を追加することができます。

ライブラリ情報 — デプロイされるアプリケーションに関する情報。また、アプリケーションアイコンとスプラッシュスクリーンを変更して、アプリケーションの外観をカスタマイズすることもできます。生成されるインストーラーはこの情報を使用して、インストールされるアプリケーションのメタデータを入力します。インストーラーのカスタマイズを参照してください。
追加インストーラーオプション — 生成されるインストーラーの既定のインストールパスと、カスタムロゴの選択。インストールパスの変更を参照してください。
ライブラリの実行に必要なファイル — 生成されるアプリケーションを実行するために必要な追加ファイル。これらのファイルは、生成されるアプリケーションインストーラーに含められます。コンパイラプロジェクトの必須ファイルの管理を参照してください。
エンドユーザー用にインストールされるファイル — アプリケーションと共にインストールされるファイル。
アプリケーションと共にインストールするファイルの指定を参照してください。

アプリケーションのパッケージ化

パッケージ化オプションの選択が終了したら、ライブラリコンパイラのプロジェクトを保存し、パッケージ化されたアプリケーションを生成します。

[パッケージ化] をクリックします。
[プロジェクトを保存] ダイアログボックスで、プロジェクトを保存する場所を指定します。
[パッケージ] ダイアログボックスで、[プロセスが完了したら出力フォルダーを開く] が選択されていることを確認します。
パッケージ化プロセスが完了したら、ターゲットフォルダー内の生成された出力を調べます。
- 3 つのフォルダー for_redistribution、for_redistribution_files_only、および for_testing が生成されます。
  これらのフォルダーに生成されるファイルの詳細については、MATLAB 関数のパッケージ化後に生成されるファイルを参照してください。
- ログファイル PackagingLog.html にはパッケージ化の結果が含まれています。

`compiler.build.cppSharedLibrary` を使用した C++ 共有ライブラリの作成

ライブラリコンパイラアプリの代わりに、プログラムによる方法を使用して C++ 共有ライブラリを作成できます。ライブラリコンパイラを使用してライブラリを既に作成している場合は、C++ MATLAB データ API 共有ライブラリをサンプルアプリケーションとともに実装を参照してください。

関数ファイルのリストを cell 配列に保存します。

functionfiles = {'addmatrix.m', 'multiplymatrix.m', 'eigmatrix.m'}

関数を呼び出す MATLAB サンプルコードを作成します。サンプルファイルを使用して、ターゲット言語のサンプルアプリケーションを生成します。詳細と制限については、サンプルドライバーファイルの作成を参照してください。
以下のコードを libmatrixSample.m という名前のサンプルファイルに保存します。
```
% Sample script to demonstrate execution of functions
% addmatrix, eigmatrix, and multiplymatrix
a1 = [1 4 7; 2 5 8; 3 6 9]; % Initialize a1 here
a2 = a1; % Initialize a2 here
a = addmatrix(a1, a2);
e = eigmatrix(a1);
m = multiplymatrix(a1, a2);
```
パッケージ化手順で、サンプルドライバーファイルをまったく含めないことも選択できます。独自の C++ アプリケーションコードを作成する場合、MATLAB 関数のパッケージ化が完了してから mbuild を使用して適切なディレクトリに移動し、コンパイルできます。
関数 compiler.build.cppSharedLibrary を使用して C++ 共有ライブラリをビルドします。名前と値の引数を使用してライブラリ名を指定し、サンプルファイルを追加します。
```
buildResults = compiler.build.cppSharedLibrary(functionfiles,...
'LibraryName','libmatrix',...
'SampleGenerationFiles','libmatrixSample.m');
```
compiler.build コマンドで名前と値の引数を使用して、追加オプションを指定できます。詳細については、compiler.build.cppSharedLibrary を参照してください。
compiler.build.Results オブジェクト buildResults には、ビルドタイプ、生成ファイル、含まれるサポートパッケージ、およびビルドオプションに関する情報が含まれています。
この構文により、現在の作業ディレクトリの libmatrixcppSharedLibrary という名前のフォルダー内に以下のファイルが生成されます。
- samples\libmatrixSample1_mda.cpp — 関数 addmatrix を呼び出す C++ サンプルアプリケーション。
- samples\libmatrixSample2_mda.cpp — 関数 eigmatrix を呼び出す C++ サンプルアプリケーション。
- samples\libmatrixSample3_mda.cpp — 関数 multiplymatrix を呼び出す C++ サンプルアプリケーション。
- v2\generic_interface\libmatrix.ctf — デプロイ可能なアーカイブが含まれるコンポーネントテクノロジーファイル。
- v2\generic_interface\readme.txt — パッケージ化情報が含まれるテキストファイル。
- GettingStarted.html — 共有ライブラリの統合に関する情報が含まれる HTML ファイル。
- includedSupportPackages.txt — ライブラリに含まれるすべてのサポートファイルをリストしたテキストファイル。
- mccExcludedFiles.log — アプリケーションに含まれていないすべてのツールボックス関数のリストが含まれるログファイル。サポートされていない関数の詳細については、MATLAB Compiler の制限を参照してください。
- readme.txt — パッケージ化およびインターフェイスの情報が含まれるテキストファイル。
- requiredMCRProducts.txt — MATLAB Runtime がアプリケーションを実行するために必要な製品の製品 ID が含まれるテキストファイル。
- unresolvedSymbols.txt — 未解決のシンボルに関する情報が含まれるテキストファイル。
メモ
生成されたライブラリに MATLAB Runtime やインストーラーは含まれていません。buildResults オブジェクトを使用してインストーラーを作成するには、compiler.package.installer を参照してください。

C++ MATLAB データ API 共有ライブラリをサンプルアプリケーションとともに実装

メモ

3 つすべての関数を呼び出してエラーを処理する、より高度なアプリケーションを使用してライブラリを呼び出すには、次のフォルダーに配置されている C++ アプリケーション matrix_mda.cpp を使用します。

matlabroot\extern\examples\compilersdk\c_cpp\matrix

詳細については、Integrate C++ Shared Libraries with MATLAB Data APIを参照してください。

開始する前に、MATLAB Runtime のインストールと構成が完了していて、C++ コンパイラがインストールされていることを確認してください。

C++ 共有ライブラリをパッケージ化した後、C++ アプリケーションから呼び出すことができます。samples フォルダーで生成された C++ コードは、作成したサンプル MATLAB ファイルを基にしています。

生成されたファイル libmatrix.ctf を v2\generic_interface フォルダーからコピーして、libmatrixSample1_mda.cpp を含む samples フォルダーに貼り付けます。

libmatrixSample1_mda.cpp のプログラムコードを以下に示します。

/*================================================================= * * ADDMATRIXSAMPLE1 * Sample driver code that uses the generic interface and * MATLAB Data API to call a C++ shared library created using * MATLAB Compiler SDK. * Refer to the MATLAB Compiler SDK documentation for more * information. * *=================================================================*/ // Include the header file required to use the generic // interface for the C++ shared library generated by the // MATLAB Compiler SDK. #include "MatlabCppSharedLib.hpp" #include <iostream> namespace mc = matlab::cpplib; namespace md = matlab::data; std::shared_ptr<mc::MATLABApplication> setup() { auto mode = mc::MATLABApplicationMode::IN_PROCESS; // Specify MATLAB startup options std::vector<std::u16string> options = {}; std::shared_ptr<mc::MATLABApplication> matlabApplication = mc::initMATLABApplication(mode, options); return matlabApplication; } int mainFunc(std::shared_ptr<mc::MATLABApplication> app, const int argc, const char * argv[]) { md::ArrayFactory factory; md::TypedArray<double> a1In = factory.createArray<double>({3, 3}, {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0}); md::TypedArray<double> a2In = factory.createArray<double>({3, 3}, {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0}); try { // The path to the CTF (library archive file) passed to // initMATLABLibrary or initMATLABLibraryAsync may be either absolute // or relative. If it is relative, the following will be prepended // to it, in turn, in order to find the CTF: // - the directory named by the environment variable // CPPSHARED_BASE_CTF_PATH, if defined // - the working directory // - the directory where the executable is located // - on Mac, the directory three levels above the directory // where the executable is located // If the CTF is not in one of these locations, do one of the following: // - copy the CTF // - move the CTF // - change the working directory ("cd") to the location of the CTF // - set the environment variable to the location of the CTF // - edit the code to change the path auto lib = mc::initMATLABLibrary(app, u"libmatrix.ctf"); std::vector<md::Array> inputs{a1In, a2In}; auto result = lib->feval(u"addmatrix", 1, inputs); } catch (const std::exception & exc) { std::cerr << exc.what() << std::endl; return -1; } return 0; } // The main routine. On the Mac, the main thread runs the system code, and // user code must be processed by a secondary thread. On other platforms, // the main thread runs both the system code and the user code. int main(const int argc, const char * argv[]) { int ret = 0; try { auto matlabApplication = setup(); ret = mc::runMain(mainFunc, std::move(matlabApplication), argc, argv); // Calling reset() on matlabApplication allows the user to control // when it is destroyed, which automatically cleans up its resources. // Here, the object would go out of scope and be destroyed at the end // of the block anyway, even if reset() were not called. // Whether the matlabApplication object is explicitly or implicitly // destroyed, initMATLABApplication() cannot be called again within // the same process. matlabApplication.reset(); } catch(const std::exception & exc) { std::cerr << exc.what() << std::endl; return -1; } return ret; }

MATLAB コマンドプロンプトまたはシステムコマンドプロンプトで、libmatrix.ctf のコピー先の samples フォルダーに移動します。
システムのコマンドプロンプトで mbuild を使用して、アプリケーションをコンパイルしてリンクします。
```
mbuild libmatrixSample1_mda.cpp
```
システムのコマンドプロンプトからアプリケーションを実行します。
```
addmatrixSample1_mda.exe
```
既定では、生成された C++ コードは出力を表示しません。
(オプション) mbuild を使用して、その他のサンプル C++ アプリケーションをコンパイルしてリンクします。生成された C++ コードは、独自のアプリケーションを作成するためのガイドとしても使用できます。
詳細については、Integrate C++ Shared Libraries with MATLAB Data APIを参照してください。

メモ

struct 配列、cell 配列、または文字ベクトルを feval の呼び出しから取得して表示する方法の例については、matlabroot\extern\examples\compilersdk\c_cpp\matrix の subtractmatrix.m ファイルおよび subtractmatrix_mda.cpp ファイルを参照してください。