[clang] C++20 Modules: document how to perform automated reductions

[mizvekov]

No description provided.

[llvmbot]

@llvm/pr-subscribers-clang-modules

Author: Matheus Izvekov (mizvekov)

Changes

---

Full diff: https://github.com/llvm/llvm-project/pull/124997.diff

1 Files Affected:

• (modified) clang/docs/StandardCPlusPlusModules.rst (+23-1)

diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 93edce0cf90b76..5154b632fba3a7 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -710,7 +710,7 @@ Before Clang 19, a change in BMI of any (transitive) dependency would cause the
 outputs of the BMI to change. Starting with Clang 19, changes to non-direct
 dependencies should not directly affect the output BMI, unless they affect the
 results of the compilations. We expect that there are many more opportunities
-for this optimization than we currently have realized and would appreaciate 
+for this optimization than we currently have realized and would appreaciate
 feedback about missed optimization opportunities. For example,
 
 .. code-block:: c++
@@ -2072,3 +2072,25 @@ Interoperability with Clang Modules
 We **wish** to support Clang modules and standard C++ modules at the same time,
 but the mixing them together is not well used/tested yet. Please file new
 GitHub issues as you find interoperability problems.
+
+Finding reduced test cases
+--------------------------
+
+When the user encounters a problem with the implementation of standard modules,
+it's helpful to attach a reduced test case to the issue report.
+
+This reduction is hard, as it can't avoid the dependency on multiple files,
+unlike most issues which can be reproduced within a single translation unit.
+
+If you are familiar with performing automated reductions using tools like
+c-reduce, you can use `cvise <https://github.com/marxin/cvise>`_ to accomplish this
+reduction.
+
+Much in the same way as creduce, cvise takes an interestingness test
+in addition to the source code. In the latter case, you can create an
+interestingness test which uses your project's build system to perform
+the build part, and cvise will accept multiple source files or directories,
+and will take turns reducing each, which is something creduce does not support.
+
+Be aware that this can be highly compute intensive, but on the upside no manual
+intervention is required.

[llvmbot]

@llvm/pr-subscribers-clang

Author: Matheus Izvekov (mizvekov)

Changes

---

Full diff: https://github.com/llvm/llvm-project/pull/124997.diff

1 Files Affected:

• (modified) clang/docs/StandardCPlusPlusModules.rst (+23-1)

diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 93edce0cf90b76..5154b632fba3a7 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -710,7 +710,7 @@ Before Clang 19, a change in BMI of any (transitive) dependency would cause the
 outputs of the BMI to change. Starting with Clang 19, changes to non-direct
 dependencies should not directly affect the output BMI, unless they affect the
 results of the compilations. We expect that there are many more opportunities
-for this optimization than we currently have realized and would appreaciate 
+for this optimization than we currently have realized and would appreaciate
 feedback about missed optimization opportunities. For example,
 
 .. code-block:: c++
@@ -2072,3 +2072,25 @@ Interoperability with Clang Modules
 We **wish** to support Clang modules and standard C++ modules at the same time,
 but the mixing them together is not well used/tested yet. Please file new
 GitHub issues as you find interoperability problems.
+
+Finding reduced test cases
+--------------------------
+
+When the user encounters a problem with the implementation of standard modules,
+it's helpful to attach a reduced test case to the issue report.
+
+This reduction is hard, as it can't avoid the dependency on multiple files,
+unlike most issues which can be reproduced within a single translation unit.
+
+If you are familiar with performing automated reductions using tools like
+c-reduce, you can use `cvise <https://github.com/marxin/cvise>`_ to accomplish this
+reduction.
+
+Much in the same way as creduce, cvise takes an interestingness test
+in addition to the source code. In the latter case, you can create an
+interestingness test which uses your project's build system to perform
+the build part, and cvise will accept multiple source files or directories,
+and will take turns reducing each, which is something creduce does not support.
+
+Be aware that this can be highly compute intensive, but on the upside no manual
+intervention is required.

[Endilll]

I find the doc somewhat hand-wavy, but that's fine.

[cor3ntin]

This is an excellent idea.

But I think this needs to be a bit more specific and describe how to write an interestingness test specific to modules.

(I thought we had non-modules documentation for creduce but apparently not)

[mizvekov]

Yes, we don't have a generic document on automated reduction without modules.

The idea of this document here is to inform developers who already know how to perform such reductions, so that they can target modules as well.

The key piece of information here that surprises most people is that cvise supports multiple source files, and handling directories recursively, so you can just write an interestingness test that targets building a whole project using its own build system.

[ChuanqiXu9]

I like the idea. There are a lot of people suffering not able to send issue reports for modules.

[Bigcheese]

While I agree it would be good to full documentation on how to reduce test cases, I think this subset is very useful for modules issues.

I think this is fine with or without the changes I suggested.

[mizvekov]

@cor3ntin do you sustain an objection due to the lack of a full beginner-friendly test case reduction tutorial?

[Endilll]

@cor3ntin do you sustain an objection due to the lack of a full beginner-friendly test case reduction tutorial?

I think this PR is improvement over status quo, but I see where Corentin is coming from with his objection. Maybe the middle ground would be to explicitly acknowledge somewhere that full tutorial is yet to be written, so that less people are confused whether such tutorial exists elsewhere in our documentation?