desruisseaux commented on code in PR #976: URL: https://github.com/apache/maven-compiler-plugin/pull/976#discussion_r2430050146
########## src/site/markdown/module-info-patch.md: ########## @@ -0,0 +1,137 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Module-info patch + +For white box testing, it is necessary to use compiler options such as +`--patch-module`, `--add-modules`, `--add-reads`, `--add-exports` and `--add-opens`. +Writing these options inside the Maven `<compilerArgs>` XML element is tedious, redundant +(the name of the module to patch is repeated in every occurrence of some options), error prone, +and must be repeated in every plugins that depends on the tests (Surefire, Javadoc for test documentation, _etc._). +An alternative is to put a `module-info.java` file in the tests which *replace* the `module-info.java` file of the main code. +However, it forces the developer to repeat all the content of the main `module-info.java` +into the test `module-info.java` before to add test-specific statements. +This is tedious if the main `module-info.java` is large, and risky if the two files become out of sync. + +Instead of defining a `module-info.java` file in test, Maven projects can define a `module-info-patch.maven`. +The content of `module-info-patch.maven` uses the same syntax as Java, C/C++, JavaScript, Groovy, _etc._ +(comments between `/*` … `*/` or after `//`, blocks between `{` … `}`, statements ending with `;`) +but is not Java, hence the `.maven` file suffix. +The general principles are: + +* Everything that a developer would like to change in a `module-info.java` file for testing purposes is declared in `module-info-patch.maven`. +* Everything that is not in `module-info.java` is not in `module-info-patch.maven` neither. + In particular, everything that specify paths to JAR files or paths to source code stay in the `pom.xml` file. +* All keywords except `patch-module`, `SUBPROJECT-MODULES` and `TEST-MODULE-PATH` + map directly to Java compiler or Java launcher options. + +Compared to declaring options in `<compilerArgs>` XML elements, the `module-info-patch.maven` file is more readable, +keep the options in separated files for each module on which the options are applied, is less redundant as it avoids +the need to repeat the module name in every `--add-reads`, `--add-exports` and `--add-opens` options, +and is more flexibly as it is translated in slightly different options for compilation and test executions +(e.g. `TEST-MODULE-PATH` means modules having `test` and `test-only` Maven's scope at compilation time, +but means modules having `test` and `test-runtime` Maven's scope at execution time). + + +## Syntax +The syntax is: Review Comment: Done, thanks -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
