(maven-site) branch deps created (now 6ad69ecd)

[el...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

elharo pushed a change to branch deps
in repository https://gitbox.apache.org/repos/asf/maven-site.git


      at 6ad69ecd Add dependencies page

This branch includes the following new commits:

     new 6ad69ecd Add dependencies page

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

(maven-site) 01/01: Add dependencies page

[el...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

elharo pushed a commit to branch deps
in repository https://gitbox.apache.org/repos/asf/maven-site.git

commit 6ad69ecd1d0fe8e1910c4af49fa5cfb36ca13b92
Author: Elliotte Rusty Harold <el...@ibiblio.org>
AuthorDate: Wed Feb 5 13:47:30 2025 -0500

    Add dependencies page
---
 content/markdown/repositories/dependencies.md | 205 ++++++++++++++++++++++++++
 1 file changed, 205 insertions(+)

diff --git a/content/markdown/repositories/dependencies.md b/content/markdown/repositories/dependencies.md
new file mode 100644
index 00000000..e9aff8f8
--- /dev/null
+++ b/content/markdown/repositories/dependencies.md
@@ -0,0 +1,205 @@
+# Maven Dependencies
+
+<!--
+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.
+-->
+
+A dependency is a connection between a Maven project and an artifact that Maven
+adds to some classpaths. It is defined by a `dependency`
+element in the project's pom.xml file that provides the
+coordinates of the artifact to depend on and the scope in which that dependency applies.
+For example,
+
+
+```xml
+<dependency>
+  <groupId>com.google.guava</groupId>
+  <artifactId>guava</artifactId>
+  <version>33.4.0-jre</version>
+  <scope>test</scope>
+</dependency>
+```
+
+This element says that the artifact com.google.guava:guava:33.4.0-jre should
+be loaded from the Maven repository system and added to the classpath used to 
+run tests.
+
+Maven defines these dependency scopes:
+
+copy table from other page????
+
+Note that Maven does not have a compileOnly scope that is available at compile time 
+but not at runtime. Compile scope dependencies are available in all classpaths.
+
+Occasionally, the group ID, artifact ID, and version do not uniquely identify an artifact.
+Sometimes you also need to add an extension and/or a classifier. Classifiers can be added
+directly to the dependency element as in this dependency on the
+io.netty:netty-transport-native-epoll native library for Linux 64-bit X86 chips:
+
+```xml
+    <dependency>
+      <groupId>io.netty</groupId>
+      <artifactId>netty-transport-native-epoll</artifactId>
+      <version>4.1.192</version>
+      <classifier>linux-x86_64</classifier>
+    </dependency>
+```
+
+Extensions are a little more complicated. The `dependency` element does not have an extension
+child element. Instead it has a `type` element which maps to an extension and
+sometimes a classifier. For example, here is a dependency with type test-jar:
+
+
+```xml
+<dependency>
+  <groupId>org.example</groupId>
+  <artifactId>reusable-test-support</artifactId>
+  <version>2.3</version>
+  <type>test-jar</type>
+</dependency>
+```
+
+This element says that the artifact org.example:reusable-test-support:2.3::jar should
+be loaded from the Maven repository systems. Although the type is
+`test-jar`, the extension is `jar`. Dependency types do not one-to-one match
+artifact extensions.
+
+
+The classifier, type, and scope elements all have defaults and are often omitted. 
+The default classifier is the empty string. The default type is jar.
+The default scope is compile. Thus this dependency element adds the artifact nu.xom:xom:1.3.9::jar 
+to all of the project's classpaths:
+
+```xml
+<dependency>
+  <groupId>nu.xom</groupId>
+  <artifactId>xom</artifactId>
+  <version>1.3.9</version>
+</dependency>
+```
+
+A dependency element does not say in which repository to look for the corresponding artifact.
+That is determined by ????
+
+## Dependency Scopes
+
+Every dependency has a scope that determines which classpaths the artifact referenced by the dependency
+will be added to. For example, should it be added to compile-time classpath,
+the test classpath, or both? The default scope when none is explicitly
+specified is `compile`. 
+
+Different projects may assign different scopes to the same artifact. For instance, one
+project might use com.google.guava:34.4.0-jre only for tests and thus set the scope to `test`.
+Another might need it at runtime but not whee the project is compiled, and thus
+set the scope to `runtime`. A third project might need it for compiling, running, and testing
+and thus set the scope to `compile`.
+
+Unlike the other elements, the scope does not have any effect on which artifact is loaded
+from the Maven repository system. It only determines whether the artifact is loaded and
+added to a given classpath for the project.
+
+## Dependency Types
+
+Every dependency has a type that indicates the extension and the classifier
+for the artifact, though the type-specified classifier can be overridden by
+an explicit classifier element.
+The type is set by the `type` element.
+The default type when no `type` element is present is `jar`. 
+Different projects may assign different types to the same artifact. 
+
+This dependency element retrieves com.google.guava:guava:31.0.0::pom.
+
+```xml
+<dependency>
+  <groupId>com.google.guava</groupId>
+  <artifactId>guava</artifactId>
+  <version>31.0.0</version>
+  <type>pom</type>
+</dependency>
+```
+
+Here the type of the dependency and the extension of the artifact are the same,
+but that is not always the case.
+For instance, the test-jar type maps selects an artifact with the extension `jar`.
+
+Out of the box, Maven defines 11 dependency types:
+
+
+|  Type Name   | Extension |  Classifier  |
+|--------------|-----------|--------------|
+| jar          | `jar`     |              |
+| pom          | `pom`     |              |
+| maven-plugin | `jar`     |              |
+| ear          | `ear`     |              |
+| ejb          | `jar`     |              |
+| ejb-client   | `jar`     | `ejb-client` |
+| javadoc      | `jar`     | `javadoc`    |
+| java-source  | `jar`     | `sources`    |
+| rar          | `rar`     |              |
+| test-jar     | `jar`     | `tests`      |
+| war          | `war`     |              |
+
+From the table above, you can see that if the dependency type is "war", Maven retrieves
+an artifact with the `war` extension. If the dependency type is "test-jar", Maven retrieves
+an artifact with the `jar` extension and the classifier `tests`. 
+
+Finally, if Maven does not recognize a type, then the type becomes the extension and the 
+classifier is empty.  For example.
+if the dependency type is `<type>tar.gz</type>`, the extension will also be `tar.gz`.
+These mappings may be extended by plugins and extensions used in the build.
+
+Also, this has "interesting" consequences. Consider the artifact
+`org.project:reusable-test-support:1.0:tests:jar`. With the type handlers above, maybe surprisingly, the dependency to
+this very same artifact can be described in two ways:
+
+```xml
+<dependency>
+  <groupId>org.project</groupId>
+  <artifactId>reusable-test-support</artifactId>
+  <version>1.0</version>
+  <classifier>tests</classifier>
+</dependency>
+```
+
+and a completely equivalent dependency is:
+
+```xml
+<dependency>
+  <groupId>org.project</groupId>
+  <artifactId>reusable-test-support</artifactId>
+  <version>1.0</version>
+  <type>test-jar</type>
+</dependency>
+```
+
+The obvious difference is presence of `classifier` in the first case, 
+and the lack of it in the second. However, in the second the `type` "test-jar"
+implies a classifier of "tests". In both cases, the extension is "jar".
+The first uses the default value for this property, while the second infers it from the type.
+
+Note: In this very case, the first way is somewhat "explicit", and is recommended. Not so for the
+cases when type handler carries some important extra information (like some custom packaging), where using `type`
+is more appropriate. Simply put, in this case the type "test-jar" is like an alias for ordinary JARs with the "tests"
+classifier.
+
+Plugins and extensions may define new dependency types. This is usually required for
+plugins that introduce a "packaging" (lifecycle mapping) by providing an `ArtifactHandler`
+component with a name corresponding to the type name.
+
+
+