Main Content

clibgen.buildInterface

定義ファイルなしで C++ ライブラリへのインターフェイスを作成

説明

clibgen.buildInterface(InterfaceGenerationFiles,Libraries=LibraryFiles) は、HeaderFiles および Libraries により定義された C++ ライブラリへの MATLAB® インターフェイスを作成します。

メモ

MATLAB が自動的に定義できないライブラリ内のクラス コンストラクター、メソッド、データ メンバーおよび関数はすべて破棄されます。欠落している機能を含めるには、関数 clibgen.generateLibraryDefinition および関数 build による 2 ステップのビルド ワークフローを使用します。

インターフェイス ファイルの名前は、プラットフォーム固有のファイル拡張子をもつ libNameInterface です。既定の設定では、libNameHeaderFiles で指定したファイルの名前です。

MATLAB でサポートされる C++ コンパイラが必要です。C++ ライブラリのビルドに使用したものと同じコンパイラを使って、インターフェイスをビルドしなければなりません。

clibgen.buildInterface(InterfaceGenerationFiles,SupportingSourceFiles=SourceFiles) は、複数のヘッダー ファイル、ソース ファイル、および必要な場合は、共有ライブラリ ファイルにより定義されたライブラリ用です。

clibgen.buildInterface(InterfaceGenerationFiles) は、HeaderFiles により完全に定義されたライブラリに対するインターフェイスを作成します。MATLAB でサポートされている任意の C++ コンパイラを選択してインターフェイスをビルドできます。

ライブラリに共有ライブラリ ファイルが含まれている場合、Libraries 引数を指定しなければなりません。

clibgen.buildInterface(___,Name=Value) は、1 つ以上の名前と値の引数を使用して、インターフェイスを生成します。このオプションは、前述の構文のすべての入力引数の組み合わせで使用できます。これらの引数の使用に関する詳細については、clibgen.generateLibraryDefinition を参照してください。

すべて折りたたむ

school.hpp ヘッダー ファイルを、書き込み可能なフォルダーにコピーします。

copyfile(fullfile(matlabroot,'extern','examples','cpp_interface','school.hpp'),'.','f')

インターフェイス schoolInterface.dll をビルドします。出力のパス名には、選択したフォルダーが反映されています。

clibgen.buildInterface("school.hpp")
Building interface file 'schoolInterface.dll' for clib package 'school'.
Interface file 'schoolInterface.dll' built in folder 'C:\Users\MATLAB\school'.

To use the library, add the interface file folder to the MATLAB path.
addpath('C:\Users\MATLAB\school')
1 constructs need further definition to be included in the interface. 
Use clibgen.generateLibraryDefinition to provide definitions.

addpath リンクをクリックしてインターフェイスをパスに追加します。

ライブラリを読み込んで、Person クラスのヘルプを表示します。

help clib.school.Person
Person -  clib.school.Person    Representation of C++ class Person.

ライブラリ内のヘルプを表示します。

help clib.school

この機能を、ヘッダー専用の HPP ファイルsummary(defineschool) コマンドの出力と比較します。このインターフェイスには、次が含まれていません。

Functions
  string clib.school.getName(clib.school.Person)

入力引数

すべて折りたたむ

インターフェイスを生成するためのファイル。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。現在のフォルダーまたは MATLAB のパスにない場合、引数にはファイルの絶対パスまたは相対パスが含まれます。詳細については、関数 clibgen.generateLibraryDefinitionInterfaceGenerationFiles引数を参照してください。

例: "sample.hpp"

データ型: char | string | cell

共有ライブラリ ファイル名。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。Libraries 引数と共に使用します。ライブラリが、InterfaceGenerationFiles 引数および SupportingSourceFiles 引数で指定されたファイルにより完全に定義されている場合を除いて、この値が必要です。詳細については、関数 clibgen.generateLibraryDefinitionLibraries引数を参照してください。

たとえば、次のステートメントを Windows® で実行すると、myLib.lib を使用して C:\myLib\sampleInterface.dll が作成され、現在のフォルダーのサブフォルダー sample に書き込まれます。

clibgen.buildInterface("sample.hpp",Libraries="C:\myLib\myLib.lib")

データ型: char | string | cell

C/C++ ソース ファイル。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。名前と値の引数 SupportingSourceFiles と共に使用します。サポートされているファイル拡張子は .c.cpp.cxx です。現在のフォルダーまたは MATLAB のパスにない場合、引数にはファイルの絶対パスまたは相対パスが含まれます。サポート ソース ファイルには C/C++ コードが含まれていなければなりません。

詳細については、ヒントの「ライブラリ内のファイル」を参照してください。

C ソース ファイルのビルドについては、CLinkage を参照してください。

ライブラリがヘッダー ファイルおよび C++ ソース ファイルにより完全に定義されている場合、コンパイル済みライブラリ ファイルは必要ありません。

例: "sample.cpp"

データ型: char | string | cell

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

例: clibgen.buildInterface("myHeader.hpp",Libraries="myHeader.lib",OutputFolder="C:\work");

含まれるヘッダー ファイルのフォルダー。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。IncludePath の各値は、ヘッダー ファイルのコンパイル中に含めるフォルダーへの絶対パス名でなければなりません。

さまざまなフォルダー内のヘッダー ファイルの #include ステートメントがメイン ヘッダー ファイルに含まれている場合は、IncludePath 引数を使用してこれらのパスを指定します。

データ型: char | string | cell

生成される定義ファイルのフォルダー名。string スカラーまたは文字ベクトルとして指定します。たとえば、次のステートメントは Windows の C:\work\myHeadermyHeaderInterface.dll を作成します。

clibgen.buildInterface("myHeader.hpp",OutputFolder="C:\work")

データ型: char | string | cell

生成されたインターフェイス パッケージ名。string スカラーまたは文字ベクトルとして指定します。1 つのヘッダー ファイルから作成されたインターフェイスの場合、既定値はヘッダー名です。複数のヘッダー ファイルの場合は、パッケージ名を有効な MATLAB 名として指定しなければなりません。たとえば、次のステートメントは、現在のフォルダーのサブフォルダー mylibmylibInterface ライブラリ ファイルを作成します。

clibgen.buildInterface(["h1.hpp","h2.hpp"],PackageName="mylib")

データ型: char | string | cell

生成メッセージの表示オプション。数値または logical 1 (true) または 0 (false) として指定します。true の場合、clibgen.buildInterface はインターフェイスの作成中に生成メッセージをコマンド ウィンドウに表示します。たとえば、次のステートメントは、h1Interface ライブラリ ファイルをサブフォルダー h1 に作成し、メッセージをコマンド ウィンドウに表示します。

clibgen.buildInterface("h1.hpp",Verbose=true)

詳細については、サポートされていない型についてのメッセージを参照してください。

データ型: logical

オブジェクト ポインターの形状指定子。数値または logical 1 (true) または 0 (false) として指定します。TreatObjectPointerAsScalartrue の場合、関数は SHAPE1 として指定してライブラリ内のすべてのオブジェクト ポインターをスカラーとして扱います。それ以外の場合、オブジェクト ポインターの形状は不明です。

R2019b で導入されました。

データ型: logical

const 文字ポインターの形状と MATLAB 型指定子。数値または logical 1 (true) または 0 (false) として指定します。TreatConstCharPointerAsCStringtrue の場合、関数は MLTYPEstringSHAPEnullTerminated として指定し、ライブラリ内のすべての const 文字ポインターを null で終了する C の文字列として扱います。それ以外の場合、MATLAB 型および const 文字ポインターの形状は不明です。サポートされているポインターの型は次のとおりです。

  • const char *

  • const wchar_t *

  • const char16_t *

  • const char32_t *

データ型: logical

ヘッダー ファイルを解析する際に使用するマクロ定義のリスト。空、スカラー string、またはスカラー string の行ベクトルとして指定します。マクロ名には 1 ~ 9、a ~ z、A ~ Z、および '_' の文字が含まれ、先頭を数字にすることはできません。

データ型: string

ヘッダー ファイルを解析する際に使用するマクロのキャンセルのリスト。空、スカラー string、またはスカラー string の行ベクトルとして指定します。マクロ名には 1 ~ 9、a ~ z、A ~ Z、および '_' の文字が含まれ、先頭を数字にすることはできません。

データ型: string

非オブジェクト C++ 配列を返す方法を指定するオプション。数値または logical 1 (true) または 0 (false) として指定します。ReturnCArraystrue の場合、関数は C++ 配列を MATLAB clib 配列型 (clib.array.*) に変換します。false の場合、関数は C++ 配列をネイティブ MATLAB 配列に変換します。

データ型: logical

C++ ファイルからドキュメンテーションを生成するオプション。数値または logical 1 (true) または 0 (false) として指定します。GenerateDocumentationFromHeaderFilestrue の場合、関数は MATLAB doc コマンドを使用して C++ ファイルのコメントから表示用のドキュメンテーションを生成します。false の場合、関数は C++ コメントを無視し、MATLAB のドキュメンテーションおよび C++ 型のマッピングのみを生成します。

詳細については、C++ ライブラリに対する MATLAB インターフェイスのヘルプ テキストのパブリッシュを参照してください。

データ型: logical

.h ヘッダー ファイルを解析およびビルドする方法を指定するオプション。数値または logical 1 (true) または 0 (false) として指定します。

CLinkagetrue の場合、関数は InterfaceGenerationFiles 引数内の .h ヘッダー ファイルを C ヘッダー ファイルとして扱います。C ヘッダー ファイルは、生成されたインターフェイス コード内の extern "C" ブロックに含められます。これにより、C ソース ファイルまたは C ライブラリに対してリンクする際に名前マングリングの問題が生じなくなります。

以下により定義されているライブラリのインターフェイスを作成する際に CLinkagetrue に設定します。

  • C ヘッダー ファイルおよびライブラリ ファイル。

  • C ヘッダー ファイルおよびソース ファイル。

  • CPP ファイルと C ファイルの組み合わせ。

CLinkagefalse の場合、関数は .h ヘッダー ファイルを CPP ファイルとして扱います。C への依存関係がある CPP ファイルからインターフェイスを作成する際には、既定 (CLinkagefalse) を使用します。この場合、C ファイルは、次の引数のいずれかで指定します。

  • C ヘッダー ファイルの場所を指す IncludePath

  • C ソース ファイルを指す SupportingSourceFiles

  • C コンパイル済みライブラリ ファイル .lib.dll.so、または .dylib を指す Libraries

clibgen.generateLibraryDefinition 引数で C ファイルを使用する方法を示した例については、ヒントの「ライブラリ内のファイル」を参照し、CLinkage を検索してください。

データ型: logical

インターフェイスをビルドするために使用されるコンパイラ フラグに追加するコンパイラ フラグのリスト。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。関数は、フラグを検証することなくコンパイラに直接渡します。

詳細については、C++ ライブラリ インターフェイスのビルドと内容の確認を参照してください。

例: clibgen.generateLibraryDefinition("A.hpp","AdditionalCompilerFlags","-std=c++20")

データ型: char | string | cell

インターフェイスをビルドするために使用されるリンカー フラグに追加するリンカー フラグのリスト。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。関数は、フラグを検証することなくリンカーに直接渡します。

詳細については、C++ ライブラリ インターフェイスのビルドと内容の確認を参照してください。

データ型: char | string | cell

制限

  • 一部のロケール設定では非 ASCII 文字がサポートされていないため、フォルダー名とファイル名にはこれらの文字を使用しないでください。ロケールの詳細については、国際化に向けたロケール設定の概念を参照してください。

代替機能

2 ステップのビルド プロセス

clibgen.buildInterface の代わりに、関数 clibgen.generateLibraryDefinition および関数 build を使用してインターフェイスで欠落している機能を定義します。

詳細については、C++ ライブラリ インターフェイスのビルドと内容の確認を参照してください。

バージョン履歴

R2019a で導入