CMake: 変数を見やすく整理したい？「mark_as_advanced」で詳細設定を非表示にするテクニック

mark_as_advanced()コマンドは、CMakeのキャッシュされた変数を「詳細」としてマークするために使用されます。詳細変数は、CMake GUI（ccmakeやcmake-guiなど）で「詳細オプションを表示」が有効になっていない限り、表示されません。

このコマンドは、ユーザーが頻繁に変更する必要のない、専門的な設定や高度なオプションを隠すために役立ちます。

構文

mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])

VAR: 詳細変数としてマークする変数の名前を1つ以上指定します。
FORCE: 指定された変数を詳細変数として強制的にマークします。
CLEAR: すべての詳細変数を標準の表示に戻します。

オプション

FORCEオプションを指定しない場合、新しい値は詳細変数としてマークされますが、既存の変数の詳細設定は変更されません。
CLEARとFORCEオプションは互いに排他的です。

例

# 変数 "MY_ADVANCED_OPTION" を詳細変数としてマークします。
mark_as_advanced MY_ADVANCED_OPTION

# すべての詳細変数を標準の表示に戻します。
mark_as_advanced CLEAR

CMAKE_ADVANCED_VARIABLES変数を使用して、詳細変数のリストをカスタマイズすることもできます。
詳細変数は、CMake GUIだけでなく、cmake --buildコマンドラインツールでも非表示になります。
mark_as_advanced()コマンドは、CMake 3.0以降で使用できます。

詳細変数の使用方法については、CMakeドキュメントまたはチュートリアルを参照してください。
プロジェクト設定を構成する場合は、set()コマンドなどの他のCMakeコマンドを使用する方が適切な場合があります。
mark_as_advanced()コマンドは、主にCMake GUIでのユーザーエクスペリエンスを向上させるために使用されます。

例 1: 詳細変数の設定

この例では、MY_ADVANCED_OPTION という名前の変数を詳細変数としてマークします。この変数は、CMake GUI で「詳細オプションを表示」が有効になっていない限り、表示されません。

cmake_minimum_required(VERSION 3.0)

project(MyProject)

set(MY_OPTION "This is a normal option")
mark_as_advanced(MY_ADVANCED_OPTION)
set(MY_ADVANCED_OPTION "This is an advanced option")

例 2: 詳細変数のクリア

この例では、すべての詳細変数を標準の表示に戻します。

cmake_minimum_required(VERSION 3.0)

project(MyProject)

set(MY_OPTION "This is a normal option")
mark_as_advanced(MY_ADVANCED_OPTION)
set(MY_ADVANCED_OPTION "This is an advanced option")

mark_as_advanced(CLEAR)

例 3: 強制的に詳細変数を設定

この例では、MY_ADVANCED_OPTION という名前の変数を詳細変数として強制的にマークします。この変数は、既存の詳細設定に関わらず、常に非表示になります。

cmake_minimum_required(VERSION 3.0)

project(MyProject)

set(MY_OPTION "This is a normal option")
mark_as_advanced(MY_ADVANCED_OPTION)
set(MY_ADVANCED_OPTION "This is an advanced option")

mark_as_advanced(FORCE MY_ADVANCED_OPTION)

説明

mark_as_advanced(FORCE MY_ADVANCED_OPTION) コマンドを使用して、MY_ADVANCED_OPTION 変数を詳細変数として強制的にマークします。
mark_as_advanced(CLEAR) コマンドを使用して、すべての詳細変数を標準の表示に戻します。
mark_as_advanced() コマンドを使用して、MY_ADVANCED_OPTION 変数を詳細変数としてマークします。
set() コマンドを使用して、2 つの変数 MY_OPTION と MY_ADVANCED_OPTION を設定しています。
project() コマンドを使用して、プロジェクトの名前を MyProject に設定しています。
上記の例では、cmake_minimum_required() コマンドを使用して、CMake の最小バージョン要件を 3.0 に設定しています。

これらの例は、mark_as_advanced() 関数の基本的な使用方法を示しています。詳細については、CMake ドキュメントを参照してください。

CMAKE_ADVANCED_VARIABLES 変数を使用する

CMAKE_ADVANCED_VARIABLES 変数を使用して、詳細変数のリストを定義できます。この変数は、CMake GUI で「詳細オプションを表示」が有効な場合にのみ、これらの変数を表示します。

set(CMAKE_ADVANCED_VARIABLES MY_ADVANCED_OPTION1 MY_ADVANCED_OPTION2)

上記の例では、MY_ADVANCED_OPTION1 と MY_ADVANCED_OPTION2 変数が詳細変数としてマークされます。

キャッシュ変数のコメントを使用する

キャッシュ変数のコメントを使用して、変数が詳細設定であることを示すことができます。CMake GUI は、これらのコメントをヒントとして使用して、変数を詳細オプションとして表示します。

cmake_minimum_required(VERSION 3.0)

project(MyProject)

set(MY_OPTION "This is a normal option")
set(MY_ADVANCED_OPTION "This is an advanced option"
    CACHE "Advanced option" "")

上記の例では、MY_ADVANCED_OPTION 変数にコメントが追加され、それが詳細オプションであることが示されます。

カスタムヘルパー関数を使用する

独自のヘルパー関数を作成して、詳細変数を管理することもできます。この関数は、CMAKE_ADVANCED_VARIABLES 変数設定やコメントの追加など、必要なロジックを実行できます。

例

function mark_as_advanced(VAR)
    set(CMAKE_ADVANCED_VARIABLES ${CMAKE_ADVANCED_VARIABLES} ${VAR})
    set("${VAR}_COMMENT" "This is an advanced option"
        CACHE "Advanced option" "")
endfunction

mark_as_advanced(MY_ADVANCED_OPTION)

上記の例では、mark_as_advanced() という名前のヘルパー関数が定義されています。この関数は、CMAKE_ADVANCED_VARIABLES 変数に新しい変数を追加し、コメントを追加します。

GUI ツールに固有のオプションを使用する

一部の CMake GUI ツールには、詳細変数を設定するための独自オプションが用意されています。これらのオプションは、ツールのドキュメントを参照してください。

推奨事項

新しいプロジェクトの場合は、CMAKE_ADVANCED_VARIABLES 変数を使用して詳細変数を設定することをお勧めします。これは、シンプルでわかりやすい方法です。既存のプロジェクトで mark_as_advanced() コマンドを使用している場合は、徐々に上記の代替方法に移行していくことができます。

上記の代替方法は、互いに排他的ではありません。必要に応じて、複数の方法を組み合わせて使用できます。
mark_as_advanced() コマンドは、CMake 3.30 以降では非推奨とされています。新しいプロジェクトではこのコマンドの使用を避けてください。