srcdeps-maven-configuration.adoc

srcdeps for Maven Configuration Guide

The behavior of srcdeps is controlled through two configuration files:

1. .mvn/extensions.xml - make Maven aware of srcdeps
2. srcdeps.yaml - the main srcdeps configuration file

Note that both files can be initialized by running our srcdeps-maven-plugin’s `init mojo the in the root directory of your project tree:

mvn org.srcdeps.mvn:srcdeps-maven-plugin:init

1. .mvn/extensions.xml

srcdeps-maven-local-repository needs to be declared as a Maven Core Extension in .mvn/extensions.xml of the maven project.

<?xml version="1.0" encoding="UTF-8"?>
<extensions>
  <extension>
    <groupId>org.l2x6.maven.srcdeps</groupId>
    <artifactId>srcdeps-maven-local-repository</artifactId>
    <version>4.0.0</version><!-- @srcdeps.version@ -->
  </extension>
  <extension>
    <groupId>org.srcdeps.mvn</groupId>
    <artifactId>srcdeps-maven-enforcer</artifactId><!-- to prevent srcdeps in releases -->
    <version>4.0.0</version><!-- @srcdeps.version@ -->
  </extension>
</extensions>

2. srcdeps.yaml

A few settings have to be configured in srcdeps.yaml file. Especially, the mapping from groupId’s of dependencies to SCM repositories where their sources reside. This is a minimal srcdeps.yaml file. Please refer to srcdeps.yaml reference for more details.

The srcdeps.yaml file has to be located in the root directory of a Maven source tree. Before version 3.1.0 of srcdeps-maven the location was .mvn/srcdeps.yaml and it is still supported as a fall back location in case there is no srcdeps.yaml in the root directory.

configModelVersion: 2.4
repositories:
  org.my-group:
    includes:
    - org.my-group:*:*  # if one of the includes matches the groupId of a -SRC- dependency,
                        # then the following urls will be used to build that dependency
    urls:
    - https://github.com/my-org/my-project.git  # If you list multiple SCM repos here then only
                                                # the first successful checkout will count

3. Setting dependency versions

There are two alternative ways how you can define which source repository reference should be used to build your dependency: in pom.xml or in srcdeps.yaml.

3.1 In pom.xml

Defining source repository refs in pom.xml is older and perhaps more straightforward:

    <dependency>
      <groupId>org.my-group</groupId>
      <artifactId>my-artifact</artifactId>
      <version>0.0.1-SRC-revision-66ea95d890531f4eaaa5aa04a9b1c69b409dcd0b</version>
    </dependency>

The -SRC- infix in the version makes srcdeps-maven-local-repository detect the dependency as source dependency. The part after the -SRC- infix is supposed to be a dash separated pair of refType and refName. refType is one of revision, branch or tag and the refName is the actual commitId, branch name or tag name.

Examples:

• 0.0.1-SRC-revision-66ea95d890531f4eaaa5aa04a9b1c69b409dcd0b

• 1.2.3-SRC-branch-1.2.x

• 2.0.1-SRC-tag-2.0.1

The part before -SRC- has no significance for srcdeps. It also has no significance for Maven. It may be important for Gradle when resolving version conflicts; Gradle prefers higher versions by default. A practical reason to keep it there is to have a mnemonic that helps a human reader to set her expectations about the compatibility of the dependency.

3.2 in srcdeps.yaml (since srcdeps-maven 3.3.0)

If you do not want or cannot change the pom.xml, you can achieve a similar result by using buildVersionPattern and buildRef of srcdeps.yaml.

configModelVersion: 2.4
repositories:
  org.my-group:
    includes:
    - org.my-group:*:*  # if one of the includes matches the groupId of a -SRC- dependency,
                        # then the following urls will be used to build that dependency
    urls:
    - https://github.com/my-org/my-project.git  # If you list multiple SCM repos here then only
                                                # the first successful checkout will count
    buildVersionPattern: .*-SNAPSHOT  # versions matching .*-SNAPSHOT pattern will be built
    buildRef: branch-1.2.x            # using branch 1.2.x from https://github.com/my-org/my-project.git

If you combine the above srcdeps.yaml with a pom.xml like the following

    <dependency>
      <groupId>org.my-group</groupId>
      <artifactId>my-artifact</artifactId>
      <version>0.0.1-SNAPSHOT</version>
    </dependency>

 `srcdeps` will build the snapshot
of `org.my-group:my-artifact` from the remote branch 1.2.x every time you build the dependent project.