migration.txt

== Migration from older tools

This section describes how to migrate packages that use older deprecated
tools to current ones.

=== add_maven_depmap macro

`%add_maven_depmap` macro was used to manually install Maven artifacts
that were built with Apache Ant or `mvn-rpmbuild`. It
is now deprecated and its invocations should be replaced with
`%mvn_artifact` and `%mvn_install`.

Artifact files, Maven POM files and their installation directories no
longer need to be manually installed, since that is done
during run of `%mvn_install`. The installed files also don't need to be
explicitly enumerated in `%files` section. Generated file `.mfiles`
should be used instead.

Relevant parts of specfile using `%add_maven_depmap`
[source,spec]
--------
BuildRequires:  javapackages-tools

Requires:       some-library
...

%build
ant test

%install
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -m 644 target/%{name}.jar $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -m 644 %{name}.pom $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom

# Note that the following call is equivalent to invoking the macro
# without any parameters
%add_maven_depmap JPP-%{name}.pom %{name}.jar

# javadoc
install -d -m 755 $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -pr api/* $RPM_BUILD_ROOT%{_javadocdir}/%{name}

%files
%{_javadir}/*
%{_mavenpomdir}/*
%{_mavendepmapfragdir}/*

%files javadoc
%doc %{_javadocdir}/%{name}
--------

The same specfile migrated to `%mvn_artifact` and `%mvn_install`
[source,spec]
--------
# mvn_* macros are located in javapackages-local package
BuildRequires:  javapackages-local

# Since XMvn generates requires automatically, it is no longer needed
# nor recommended to specify manual Requires tags, unless the dependency
# information in the POM is incomplete or you need to depend on non-java
# packages
...

%prep
# The default location for installing JAR files is %{_javadir}/%{name}/
# Because our original specfile put the JAR directly to %{_javadir}, we
# want to override this behavior. The folowing call tells XMvn to
# install the groupId:artifactId artifact as %{_javadir}/%{name}.jar
%mvn_file groupId:artifactId %{name}

%build
ant test

# Tell XMvn which artifact belongs to which POM
%mvn_artifact %{name}.pom target/%{name}.jar

%install
# It is not necessary to install directories and artifacts manually,
# mvn_install will take care of it

# Optionally use -J parameter to specify path to directory with built
# javadoc
%mvn_install -J api

# Use autogenerated .mfiles file instead of specifying individual files
%files -f .mfiles
%files javadoc -f mfiles-javadoc
--------

.Aliases and subpackages
`%add_maven_depmap` had `-a` switch to specify artifact aliases and `-f`
switch to support splitting artifacts across multiple subpackages. To
achieve the same things with `%mvn_*` macros, see <<mvn_alias, Additional Mappings>>
and <<mvn_package, Assignment of the Maven Artifacts to the Subpackages>>.

[TIP]
======
If project consists of multiple artifacts and parent POMs are among them, call `%mvn_artifact` on these parent POMs first.
======