#include ディレクティブに関するガイドライン

以下のインクルード順序は、|Gromacs|で使用され、``clang-format``によって強制されます。各グループの間には空行を設け、各グループ内のヘッダーはアルファベット順に並べます。

  1. 各 ソース ファイルは、最初に gmxpre.h を含める必要があります。

  2. ソースファイルに対応するヘッダーがある場合、次にそれをインクルードする必要があります。ヘッダーがソースファイルと同じディレクトリにある場合、パスなしでインクルードされます（つまり、ソースファイルに対する相対パス）。そうでない場合は、``libraryname/modulename/header.h``という標準的なインクルードパスが使用されます。

  3. もしファイルが config.h からの定義に依存している場合は、その手順に進んでください。

  4. その後は、標準のC/C++ヘッダーが、以下のグループで記述されます。

    1. 標準のCヘッダー（例：<stdio.h>）

    2. 上記のC++バージョン（例：<cstdio>）

    3. 標準 C++ ヘッダー (例: <vector>)

    理想的には、最初の2つのグループのうち、いずれか1つだけが存在しますが、これは強制されません。

  5. その後、他のシステムヘッダーが記述されます。これには、``<unistd.h>``のようなプラットフォーム固有のヘッダー、および``<gtest/gtest.h>``のような外部ライブラリが含まれます。

  6. GROMACS-「src/external/」ディレクトリにある、特定のGromacsライブラリ、例えば「thread_mpi/threads.h」など。

  7. GROMACS 含まれるモジュールに属さないヘッダー。

  8. 公開 GROMACS ヘッダーファイルで、インクルディングモジュールの一部として含まれるもの。

  9. 最後に、インクルードモジュール、実行可能ファイル、またはテストターゲット内の|Gromacs|ヘッダー（通常はソースファイルの同じパスにある）。

すべての GROMACS ヘッダーには引用符で囲まれた名前（例："gromacs/utility/path.h"）が使用されます。その他のヘッダーには、角括弧（例：<stdio.h>）が使用されます。 src/external/ の下にあるヘッダーは、通常、引用符で囲まれた名前が使用されます（インクルードパスが src/ に相対的な場合、およびスレッド-MPI と TNG の場合）。ただし、より大きなサードパーティのライブラリは、システムから提供されているかのように扱われます。 現在、このグループには gtest/gmock が含まれます。

一部のケースでは、ビルドターゲットで利用可能なインクルードパスが、不適切にヘッダーの可視性を漏らす可能性があります。これは、通常、#include で使用できる、または非常に長いパスを持つヘッダーとして発生します。ヘッダーが上記のようにインクルードできない場合は、適切な CMake ターゲットが target_link_libraries() コマンドによって参照されていることを確認してください。多くのモジュールは、独自の CMake ターゲットを提供しています。また、以下の点に注意してください。

  • common CMake ターゲットは、gmxpre.h、config.h、gmxpre-config.h、buildinfo.h、および contributors.h へのアクセスを提供します。

  • legacy_api は、gromacs/modulename ヘッダーの、api/legacy/include に存在する、古い API にアクセスするための機能を提供します。

  • legacy_modules は、インクルードパスに src/ を追加し、gromacs/ および gromacs/*/ に存在するすべてのヘッダーを公開します。これにより、上記のガイドラインに準拠するように見える #include の行を使用できますが、これらのヘッダーは「公開」用途ではない可能性があります。 (この機能は、Issue 3288 に向けて作業する際の、一時的な手段として導入されました。)

もし、条件付きでインクルードされるヘッダー（通常は、config.h からの #define が設定されている場合にのみ）がある場合、それらはそれぞれのグループの最後にインクルードする必要があります。 自動チェッカー/ソータースクリプトは、これらのヘッダーや、#include ステートメントの間に記述されたコメントには影響を与えません。 したがって、コードの作成者は、これらのヘッダーを適切な順序に配置する必要があります。 #include ステートメントと同じ行の末尾にあるコメントは保持され、チェッカー/ソーターには影響しません。

「適切なAPIを構築するための取り組みの一環として、ヘッダーファイルにおける公開、ライブラリ、およびモジュール機能の分離に関する新しい仕組みが計画されています。詳細は、スクリプトによるソースツリーのチェック および https://gitlab.com/gromacs/gromacs/-/issues?label_name[]=API+restructuring の「APIの再構成に関する問題」を参照してください。

一貫した順序とスタイルを適用することには、いくつかの利点があります:

  • これにより、長い、整理されていないインクルードリストをスキャンする必要なく、ファイルの依存関係を素早く確認できます。

  • ソースファイルに対応するヘッダーを最初にインクルードすることで、一部のソースファイルで最も多くインクルードされるヘッダーが最初に表示され、ヘッダーがコンパイルされない可能性のある問題を最初に発見しやすくなります。 この順序で作業することで、ヘッダーの作成者は、他の人が後で関連のないコードをリファクタリングする際に問題を発見するよりも、これらの問題を最初に発見する可能性が高くなります。

  • #include ディレクティブでパスを一貫して使用することで、ヘッダーファイルのすべての使用箇所や、2つのモジュール間のすべてのインクルード依存関係を grep を使用して簡単に見つけることができます。

  • 自動スクリプトを使用すると、sed などの半自動的なリファクタリング（例えば、インクルードファイルの名前を変更する）によって生じる不要な変更を回避しながら、コードをクリーンな状態に再構成することができます。