https://github.com/ChuanqiXu9 updated https://github.com/llvm/llvm-project/pull/200994
>From 75b4db9622aec2aab55e410b3eeefa92eb53421b Mon Sep 17 00:00:00 2001 From: Chuanqi Xu <[email protected]> Date: Tue, 2 Jun 2026 11:17:01 +0800 Subject: [PATCH 1/2] [docs] Asking to test serialization/deserialization for new C++ feature --- clang/docs/InternalsManual.rst | 70 ++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index 2dab979dac3e4..d98c79b60741c 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -3908,6 +3908,76 @@ directives: // since-cxx17-note@#cwg92-p {{use 'noexcept(false)' instead}} // cxx98-14-error@#cwg92-p {{target exception specification is not superset of source}} + +Testing Modules (Serialization/Deserialization) When implementing a new C++ syntax +---------------------------------------------------------------------------------- + +When we implement a new C++ syntax, we need to make sure that it works correctly with modules. +This means that we need to test that the syntax can be serialized and deserialized (if needed) +correctly when used in a module. Otherwise, we can't claim the new C++ syntax is supported. + +To test a syntax that can be serialized, we can use the syntax in a module interface unit. +(For ease of description, we use contracts as the example here) + +.. code-block:: c++ + + export module m; + void func(int x) pre(x > 0) {} + void func(int x, int y) pre(x > 0) pre(x > 0) {} + int func(int x, int y, int z) pre(x > 0) pre(y > 0) pre(z > 0) post(r: r > 0) { return 1; } + +And to test a syntax can be deserialized, we can import the module and use the entity (if any) +defined with the syntax in the module interface. + +.. code-block:: c++ + + import m; + int test() { + func(1); + func(1, 2); + int x = func(1, 2, 3); + return x; + } + +These tests should be put into ``clang/test/Modules`` directory. We can use ``split-file`` tool +to put multiple files into a single test file. To serialize a module interface unit to a BMI (built +module interface), we can use the ``-emit-reduced-module-interface`` option. To deserialize the +corresponding module interface unit, we can use ``-fmodule-file=<module-name>=<bmi-file-path>`` option. + +Put the above things together, we have + +.. code-block:: c++ + + // RUN: rm -rf %t + // RUN: mkdir -p %t + // RUN: split-file %s %t + // + // RUN: %clang_cc1 -std=c++26 %t/m.cppm -emit-reduced-module-interface -o %t/m.pcm + // RUN: %clang_cc1 -std=c++26 %t/use.cc -fmodule-file=m=%t/m.pcm -verify -syntax-only + + //--- m.cppm + export module m; + void func(int x) pre(x > 0) {} + void func(int x, int y) pre(x > 0) pre(x > 0) {} // test we can serialize multiple pre conditions. + int func(int x, int y, int z) pre(x > 0) pre(y > 0) pre(z > 0) post(r: r > 0) { return 1; } + + //--- use.cc + // expected-no-diagnostics + import m; + int test() { + func(1); + func(1, 2); + int x = func(1, 2, 3); + return x; + } + +We don't have to test all possible syntax combinations, which would be impractical. +It is fine to test that the syntax construct can be serialized and deserialized. + +For example, for contracts, if we choose to implement it as a member of ``FunctionDecl``, +and if the data structure of contracts is not affected by whether the FunctionDecl is a +CXXMethodDecl or not we don't have to test the contracts in the case of member functions. + Feature Test Macros =================== Clang implements several ways to test whether a feature is supported or not. >From 58c722ba0a1de44fc179e499c3d885963bf21975 Mon Sep 17 00:00:00 2001 From: Chuanqi Xu <[email protected]> Date: Thu, 4 Jun 2026 13:50:56 +0800 Subject: [PATCH 2/2] Update --- clang/docs/InternalsManual.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index d98c79b60741c..18d269c657df5 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -3912,12 +3912,12 @@ directives: Testing Modules (Serialization/Deserialization) When implementing a new C++ syntax ---------------------------------------------------------------------------------- -When we implement a new C++ syntax, we need to make sure that it works correctly with modules. -This means that we need to test that the syntax can be serialized and deserialized (if needed) -correctly when used in a module. Otherwise, we can't claim the new C++ syntax is supported. +When implementing C++ functionality, it must work correctly with modules before +claiming the feature is fully supported. This may require adding test coverage for +serialization and deserialization of C++ modules using the feature. -To test a syntax that can be serialized, we can use the syntax in a module interface unit. -(For ease of description, we use contracts as the example here) +To test serialization, the feature can be tested in a module interface unit. +(For ease of description, contracts are used as the example here.) .. code-block:: c++ @@ -3926,8 +3926,8 @@ To test a syntax that can be serialized, we can use the syntax in a module inter void func(int x, int y) pre(x > 0) pre(x > 0) {} int func(int x, int y, int z) pre(x > 0) pre(y > 0) pre(z > 0) post(r: r > 0) { return 1; } -And to test a syntax can be deserialized, we can import the module and use the entity (if any) -defined with the syntax in the module interface. +To test deserialization, the serialized module can be imported to validate the behavior +of the feature in the module interface. .. code-block:: c++ @@ -3939,10 +3939,11 @@ defined with the syntax in the module interface. return x; } -These tests should be put into ``clang/test/Modules`` directory. We can use ``split-file`` tool -to put multiple files into a single test file. To serialize a module interface unit to a BMI (built -module interface), we can use the ``-emit-reduced-module-interface`` option. To deserialize the -corresponding module interface unit, we can use ``-fmodule-file=<module-name>=<bmi-file-path>`` option. +These tests should be put into ``clang/test/Modules`` directory. The ``split-file`` tool +can be used to split a single test file into multiple logical files To serialize a module +interface unit to a BMI (built module interface), we the ``-emit-reduced-module-interface`` +option can be used. To deserialize the corresponding module interface unit, the +``-fmodule-file=<module-name>=<bmi-file-path>`` option can be used. Put the above things together, we have _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
