cstamas commented on code in PR #1794: URL: https://github.com/apache/maven-resolver/pull/1794#discussion_r2798974923
########## src/site/markdown/how-resolver-works.md: ########## @@ -0,0 +1,130 @@ +# How Resolver Works +<!-- +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. +--> + +Maven Artifact Resolver (former Aether) is a central piece of Maven. +This document tries to explain how resolver works under the hood, and explain the main concepts +and building blocks of Resolver. + +Resolver alone is "incomplete". Integrating application, like Maven is +the one that provides the "glue" (models) and logic how to resolve versions, ranges, build effective models. +By itself, Resolver is unusable. One needs to complement it with models and implementations of missing +components. Historically, the Maven module completing Resolver is `org.apache.maven:maven-resolver-provider`. + + + +## Core Concepts + +At the core of Resolver are **artifacts** and **repositories**. An artifact is basically a +"symbolic coordinate" of some content. Usually it is a JAR, but it can be really anything, as long as it is +"addressable" using Maven coordinates: `<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>` (default value of +`extension` is `jar`, and default value for `classifier` is `""`, empty string). Repositories +are places where artifacts are stored and from where they can be retrieved. Resolver, by default operates +with one local repository (usually a directory on local filesystem) and zero or more remote repositories. + +The term "resolving" is a bit overloaded, but in general it involves following steps: +* **dependency graph collection** builds the "dependency graph" +* **conflict resolution** makes the graph free of cycles, conflicts and duplicates, resulting in "dependency tree" +* **flattening** transforms the tree into a flat list of artifacts, which also represents classpath ordering +* **artifact resolving** is the process of resolving (downloading and caching, if needed) the actual artifact payload + +We call an artifact "resolvable" if it can be resolved from any available (local or remote) repository. To make an artifact +"resolvable" from the local repository, one needs to "install" it. To make an artifact "resolvable" from a remote repository, +one needs to "deploy" it (this is over-simplification; publishing is new term, but it also involves deploy step). Review Comment: In "old times" you did deploy to remote repositories, even Central. But today, you "deploy" ONLY to your private repositories/MRM hosted ones, while to get something to Central you need publishing. Publishing is NOT anymore supported directly by Maven (and is NOT deploy, that is a lifecycle phase involved on each module, overlaid, publishing is very different today). So "deploy" -> is lifecycle phase, usually involves m-deploy-p, happens per each module (while we do support "at end"). "publish" -> is what one needs to perform to get artifacts available from Central, involves calling (proprietary) APIs, zipping/packaging of all artifacts being published, performing validation, etc. In Maven 3 there is no "logically equivalent" place to perform it, hence it usually needs extra extensions like https://maveniverse.eu/docs/njord/ In Maven 4 there is a new lifecycle `after:all` that may serve as a hook, but still, handling (proprietary) API and zipping is not handled there either. -- 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]
