【CMake】Windows向けクロスコンパイルでヘッダー名を大文字小文字区別！ CMAKE_CLANG_VFS_OVERLAY徹底解説

CMAKE_CLANG_VFS_OVERLAY は CMake 3.19 以降で導入された変数で、Windows 向けのクロスコンパイル時に clang-cl コンパイラで Windows ヘッダー名の解決を大文字小文字を区別して行うために使用されます。

詳細

従来、Windows 向けのクロスコンパイルでは、clang-cl コンパイラは Windows ヘッダー名の解決で大文字小文字を区別せずに行っていました。これは、Windows ファイルシステムは大文字小文字を区別しないためです。しかし、近年では大文字小文字を区別するファイルシステムも増えており、このような場合、clang-cl コンパイラはヘッダーファイルを正しく解決できなくなる可能性があります。

CMAKE_CLANG_VFS_OVERLAY 変数は、この問題を解決するために使用されます。この変数に、clang 仮想ファイルシステム (VFS) YAML ファイルの絶対パスを設定すると、clang-cl コンパイラは VFS ファイルを使用してヘッダー名を解決し、大文字小文字を区別することができます。

使用方法

CMAKE_CLANG_VFS_OVERLAY 変数は、CMake のプロジェクト設定ファイル (CMakeLists.txt) で次のように設定できます。

set(CMAKE_CLANG_VFS_OVERLAY "/path/to/clang-vfs-overlay.yaml")

ここで、/path/to/clang-vfs-overlay.yaml は VFS ファイルの絶対パスです。

例

次の例は、CMAKE_CLANG_VFS_OVERLAY 変数を使用して、Windows 向けのクロスコンパイルプロジェクトを設定する方法を示します。

cmake_minimum_required(VERSION 3.19)

project(myproject)

set(CMAKE_TOOLCHAIN_FILE "path/to/toolchain.cmake")

set(CMAKE_C_COMPILER "clang-cl")
set(CMAKE_CXX_COMPILER "clang-cl")

set(CMAKE_CLANG_VFS_OVERLAY "/path/to/clang-vfs-overlay.yaml")

add_executable(myprogram myprogram.c)

この例では、toolchain.cmake ファイルは、clang-cl コンパイラと VFS ファイルへのパスを定義する CMake ツールチェーンファイルです。myprogram.c は、コンパイルする C ソースコードファイルです。

VFS ファイルの詳細については、clang ドキュメントを参照してください。
VFS ファイルを作成するには、clang コンパイラ付属の vfsgen ツールを使用する必要があります。
CMAKE_CLANG_VFS_OVERLAY 変数は、Windows 向けのクロスコンパイル時にのみ使用できます。他のプラットフォームでは、この変数は効果がありません。

VFS ファイルの詳細については、clang ドキュメントを参照してください。
VFS ファイルは、clang コンパイラ付属の vfsgen ツールを使用して作成する必要があります。
CMAKE_CLANG_VFS_OVERLAY 変数は、Windows 向けのクロスコンパイル時にのみ使用できます。他のプラットフォームでは、この変数は効果がありません。
CMAKE_CLANG_VFS_OVERLAY 変数は、CMake 3.19 以降でのみ使用できます。それ以前のバージョンの CMake では、この変数は使用できません。

cmake_minimum_required(VERSION 3.19)

project(myproject)

set(CMAKE_TOOLCHAIN_FILE "path/to/toolchain.cmake")

set(CMAKE_C_COMPILER "clang-cl")
set(CMAKE_CXX_COMPILER "clang-cl")

set(CMAKE_CLANG_VFS_OVERLAY "/path/to/clang-vfs-overlay.yaml")

add_executable(myprogram myprogram.c)

この例では、次のファイルが必要です。

clang-vfs-overlay.yaml: VFS ファイル。このファイルは、clang コンパイラ付属の vfsgen ツールを使用して作成する必要があります。
myprogram.c: コンパイルする C ソースコードファイル
toolchain.cmake: CMake ツールチェーンファイル。このファイルは、clang-cl コンパイラと VFS ファイルへのパスを定義する必要があります。
CMakeLists.txt: 上記の CMake 設定ファイル

例 2: 複数の VFS ファイルを使用する

この例では、myproject という名前のプロジェクトを設定し、Windows 向けのクロスコンパイルを行います。プロジェクトは myprogram.c と mylib.c という 2 つの C ソースコードファイルをコンパイルし、myprogram という名前の実行ファイルと mylib.lib という名前のライブラリを作成します。

cmake_minimum_required(VERSION 3.19)

project(myproject)

set(CMAKE_TOOLCHAIN_FILE "path/to/toolchain.cmake")

set(CMAKE_C_COMPILER "clang-cl")
set(CMAKE_CXX_COMPILER "clang-cl")

set(CMAKE_CLANG_VFS_OVERLAY_LIST "/path/to/vfs-overlay1.yaml;/path/to/vfs-overlay2.yaml")

add_executable(myprogram myprogram.c mylib.c)
add_library(mylib STATIC mylib.c)

target_link_libraries(myprogram mylib)

clang-vfs-overlay2.yaml: VFS ファイル
clang-vfs-overlay1.yaml: VFS ファイル
mylib.c: コンパイルする C ソースコードファイル
myprogram.c: コンパイルする C ソースコードファイル
toolchain.cmake: CMake ツールチェーンファイル。このファイルは、clang-cl コンパイラと VFS ファイルへのパスを定義する必要があります。
CMakeLists.txt: 上記の CMake 設定ファイル

VFS ファイルの詳細については、clang ドキュメントを参照してください。
VFS ファイルを作成するには、clang コンパイラ付属の vfsgen ツールを使用する必要があります。

代替方法

以下に、CMAKE_CLANG_VFS_OVERLAY 変数の代替方法をいくつか紹介します。

CMake の add_custom_command コマンドを使用する

add_custom_command コマンドを使用して、clang-cl コンパイラに VFS ファイルを指定するカスタムコマンドを作成することができます。

add_custom_command(
    TARGET myprogram
    COMMAND ${CMAKE_C_COMPILER} -fvfs-overlay ${CMAKE_CURRENT_SOURCE_DIR}/clang-vfs-overlay.yaml
)

この方法は、CMAKE_CLANG_VFS_OVERLAY 変数よりも柔軟性がありますが、設定が複雑になる場合があります。

CLANG_ENV 環境変数を設定する

CLANG_ENV 環境変数を設定して、clang-cl コンパイラに VFS ファイルを指定することができます。

set CLANG_ENV="VFS_OVERLAY=${CMAKE_CURRENT_SOURCE_DIR}/clang-vfs-overlay.yaml"

この方法は、簡単に設定できますが、CLANG_ENV 環境変数を設定する必要があるため、すべての環境で動作するとは限りません。

clang コンパイラの -fvfs-overlay オプションを使用する

clang コンパイラの -fvfs-overlay オプションを使用して、VFS ファイルを指定することができます。

set(CMAKE_C_COMPILER "clang ${CMAKE_C_FLAGS} -fvfs-overlay ${CMAKE_CURRENT_SOURCE_DIR}/clang-vfs-overlay.yaml")

この方法は、最もシンプルですが、clang コンパイラがサポートしている必要があります。

Windows 向けのネイティブコンパイラを使用する

Windows 向けのネイティブコンパイラを使用すると、CMAKE_CLANG_VFS_OVERLAY 変数は必要ありません。

どの方法を選択するかは、プロジェクトの要件と環境によって異なります。

VFS ファイルの詳細については、clang ドキュメントを参照してください。
VFS ファイルを作成するには、clang コンパイラ付属の vfsgen ツールを使用する必要があります。
上記の代替方法は、すべて Windows 向けのクロスコンパイル時にのみ使用できます。他のプラットフォームでは、これらの方法は効果がありません。