cstamas commented on code in PR #409: URL: https://github.com/apache/maven-resolver/pull/409#discussion_r1463215080
########## src/site/markdown/common-misconceptions.md: ########## @@ -0,0 +1,204 @@ +# Common Misconceptions +<!-- +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. +--> + +Due to smooth transitions from Maven2 into Maven3 (and soon +Maven4), and the fact that Maven2 plugins kept working with Maven3, maybe +even without change, there were some misconceptions crept in +as well. Despite the marvel of "compatibility", Maven3 resolution +differs quite much from Maven2, and the sole reason is actual improvement +in area of resolution, it became much more precise (and, due +that lost some "bad" habits present in Maven2). Here, we will try to +enumerate some of the most common misconceptions. + +## Misconception No1: How Resolver Works + +(Simplified) + +The most typical use case for Resolver is to "resolve transitively" +dependencies. Resolver, to achieve this, internally (but these are +exposed via API as distinguished API calls as well) performs 3 steps: +"collect", "transform" and "resolve". + +The "collect" step is first, where it builds the "dirty tree" (dirty graph) +of artifacts. It is important to remark, that in "collect" step, while +the graph is being built, Maven uses only POMs. Hence, if collecting an +Artifact that was never downloaded to your local repository, it will +download **the POMs only**. Using POMs resolver is able to build current +"node" of graph, but also figure outgoing vertices and adjacent nodes of +current node and so on. Which dependency is chosen to continue with from +the current node POM is decided by various criteria (configured). + +The "transform" step transforms the "dirty graph": this is where conflict resolution +happens. It is here when resolver applies various rules to resolve conflicting +versions, conflicting scopes, and so on. Here, if "verbose tree" is asked for, +conflict resolution does not remove graph nodes, merely marks the conflicts +and the conflict "winner". Thus, "verbose tree" cannot be resolved. + +Finally, the "resolve" step runs, when the (transformed) graph node artifacts +are being resolved, basically ensuring (and downloading if needed) their +correspondent files (i.e. JAR files) are present in local repository. + +It is important to state, that in "collect" step happens the selection of nodes +by various criteria, among other by the configured scope filters. And here we +come to the notion of "runtime classpath" vs "test classpath". + +In resolver, maybe un-intuitively, the "scope filter" is usually used (but does +not have to, this is just how it IS used in Maven Core, probably for historical +reasons) as "what should be omitted". The default session filter in Maven +is set up as this: + +``` + new ScopeDependencySelector("test", "provided") +``` + +This means, that "current dependency node" dependencies in "test" and "provided" scope +will be simply omitted from the graph. In other words, this filter builds +the "downstream runtime classpath" of supplied artifact (i.e. "what is needed by the +artifact at runtime when I depend on it"). + +With selector like this: + +``` + new ScopeDependencySelector("provided") +``` + +the "downstream dependency test classpath" would be built. Aside of giving example, +this selector is actually never used, as "test classpath" makes sense only in the +scope of "current project", but not for "downstream dependant projects". + +Note: these are NOT "Maven related" notions yet, there is nowhere Maven in picture here, +and these are not the classpath used by Compiler or Surefire plugins, merely just +a showcase how Resolver works. + + +## Misconception No2: "Test classpath" Is Superset of "Runtime classpath" Review Comment: ```suggestion ## Misconception No2: "Test classpath" Is Superset Of "Runtime classpath" ``` -- 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: issues-unsubscr...@maven.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
