commit 61015ad85f1d0e77e91b6440c657a057aa9b28f4 Author: Stanislav Ochotnicky sochotnicky@redhat.com Date: Wed Mar 6 16:14:15 2013 +0100
Initial try to create a nice fedora Java packaging docs
.gitignore | 1 + doc/Makefile | 10 ++ doc/README | 9 + doc/images/icons/README | 5 + doc/images/icons/callouts/1.png | Bin 0 -> 329 bytes doc/images/icons/callouts/10.png | Bin 0 -> 361 bytes doc/images/icons/callouts/11.png | Bin 0 -> 565 bytes doc/images/icons/callouts/12.png | Bin 0 -> 617 bytes doc/images/icons/callouts/13.png | Bin 0 -> 623 bytes doc/images/icons/callouts/14.png | Bin 0 -> 411 bytes doc/images/icons/callouts/15.png | Bin 0 -> 640 bytes doc/images/icons/callouts/2.png | Bin 0 -> 353 bytes doc/images/icons/callouts/3.png | Bin 0 -> 350 bytes doc/images/icons/callouts/4.png | Bin 0 -> 345 bytes doc/images/icons/callouts/5.png | Bin 0 -> 348 bytes doc/images/icons/callouts/6.png | Bin 0 -> 355 bytes doc/images/icons/callouts/7.png | Bin 0 -> 344 bytes doc/images/icons/callouts/8.png | Bin 0 -> 357 bytes doc/images/icons/callouts/9.png | Bin 0 -> 357 bytes doc/images/icons/caution.png | Bin 0 -> 2734 bytes doc/images/icons/example.png | Bin 0 -> 2599 bytes doc/images/icons/home.png | Bin 0 -> 1340 bytes doc/images/icons/important.png | Bin 0 -> 2980 bytes doc/images/icons/next.png | Bin 0 -> 1302 bytes doc/images/icons/note.png | Bin 0 -> 2494 bytes doc/images/icons/prev.png | Bin 0 -> 1348 bytes doc/images/icons/tip.png | Bin 0 -> 2718 bytes doc/images/icons/up.png | Bin 0 -> 1320 bytes doc/images/icons/warning.png | Bin 0 -> 3214 bytes doc/images/xmvn.svg | 108 +++++++++++++ doc/index.txt | 306 ++++++++++++++++++++++++++++++++++++++ 31 files changed, 439 insertions(+), 0 deletions(-) --- diff --git a/.gitignore b/.gitignore index 9881fec..dcbffbb 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ *.tar.* +*.html diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..407793f --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,10 @@ +all: index.html + +index.html: index.txt + asciidoc -b html5 -a icons -a toc2 -a theme=flask index.txt + +upload: index.html + scp -r index.html images/ fedorapeople.org:public_html/java-packaging-howto/ + +clean: + rm *html diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..644bcae --- /dev/null +++ b/doc/README @@ -0,0 +1,9 @@ + +This needs asciidoc with html5 support so if you want to build the docs on +Fedora right now: + + hg clone https://asciidoc.googlecode.com/hg/ asciidoc + ln -s $(pwd)/asciidoc/a2x.py ~/bin/a2x + ln -s $(pwd)/asciidoc/asciidoc.py ~/bin/asciidoc + +And of course add ~/bin to your PATH before running make diff --git a/doc/images/icons/README b/doc/images/icons/README new file mode 100644 index 0000000..f12b2a7 --- /dev/null +++ b/doc/images/icons/README @@ -0,0 +1,5 @@ +Replaced the plain DocBook XSL admonition icons with Jimmac's DocBook +icons (http://jimmac.musichall.cz/ikony.php3). I dropped transparency +from the Jimmac icons to get round MS IE and FOP PNG incompatibilies. + +Stuart Rackham diff --git a/doc/images/icons/callouts/1.png b/doc/images/icons/callouts/1.png new file mode 100644 index 0000000..7d47343 Binary files /dev/null and b/doc/images/icons/callouts/1.png differ diff --git a/doc/images/icons/callouts/10.png b/doc/images/icons/callouts/10.png new file mode 100644 index 0000000..997bbc8 Binary files /dev/null and b/doc/images/icons/callouts/10.png differ diff --git a/doc/images/icons/callouts/11.png b/doc/images/icons/callouts/11.png new file mode 100644 index 0000000..ce47dac Binary files /dev/null and b/doc/images/icons/callouts/11.png differ diff --git a/doc/images/icons/callouts/12.png b/doc/images/icons/callouts/12.png new file mode 100644 index 0000000..31daf4e Binary files /dev/null and b/doc/images/icons/callouts/12.png differ diff --git a/doc/images/icons/callouts/13.png b/doc/images/icons/callouts/13.png new file mode 100644 index 0000000..14021a8 Binary files /dev/null and b/doc/images/icons/callouts/13.png differ diff --git a/doc/images/icons/callouts/14.png b/doc/images/icons/callouts/14.png new file mode 100644 index 0000000..64014b7 Binary files /dev/null and b/doc/images/icons/callouts/14.png differ diff --git a/doc/images/icons/callouts/15.png b/doc/images/icons/callouts/15.png new file mode 100644 index 0000000..0d65765 Binary files /dev/null and b/doc/images/icons/callouts/15.png differ diff --git a/doc/images/icons/callouts/2.png b/doc/images/icons/callouts/2.png new file mode 100644 index 0000000..5d09341 Binary files /dev/null and b/doc/images/icons/callouts/2.png differ diff --git a/doc/images/icons/callouts/3.png b/doc/images/icons/callouts/3.png new file mode 100644 index 0000000..ef7b700 Binary files /dev/null and b/doc/images/icons/callouts/3.png differ diff --git a/doc/images/icons/callouts/4.png b/doc/images/icons/callouts/4.png new file mode 100644 index 0000000..adb8364 Binary files /dev/null and b/doc/images/icons/callouts/4.png differ diff --git a/doc/images/icons/callouts/5.png b/doc/images/icons/callouts/5.png new file mode 100644 index 0000000..4d7eb46 Binary files /dev/null and b/doc/images/icons/callouts/5.png differ diff --git a/doc/images/icons/callouts/6.png b/doc/images/icons/callouts/6.png new file mode 100644 index 0000000..0ba694a Binary files /dev/null and b/doc/images/icons/callouts/6.png differ diff --git a/doc/images/icons/callouts/7.png b/doc/images/icons/callouts/7.png new file mode 100644 index 0000000..472e96f Binary files /dev/null and b/doc/images/icons/callouts/7.png differ diff --git a/doc/images/icons/callouts/8.png b/doc/images/icons/callouts/8.png new file mode 100644 index 0000000..5e60973 Binary files /dev/null and b/doc/images/icons/callouts/8.png differ diff --git a/doc/images/icons/callouts/9.png b/doc/images/icons/callouts/9.png new file mode 100644 index 0000000..a0676d2 Binary files /dev/null and b/doc/images/icons/callouts/9.png differ diff --git a/doc/images/icons/caution.png b/doc/images/icons/caution.png new file mode 100644 index 0000000..9a8c515 Binary files /dev/null and b/doc/images/icons/caution.png differ diff --git a/doc/images/icons/example.png b/doc/images/icons/example.png new file mode 100644 index 0000000..1199e86 Binary files /dev/null and b/doc/images/icons/example.png differ diff --git a/doc/images/icons/home.png b/doc/images/icons/home.png new file mode 100644 index 0000000..37a5231 Binary files /dev/null and b/doc/images/icons/home.png differ diff --git a/doc/images/icons/important.png b/doc/images/icons/important.png new file mode 100644 index 0000000..be685cc Binary files /dev/null and b/doc/images/icons/important.png differ diff --git a/doc/images/icons/next.png b/doc/images/icons/next.png new file mode 100644 index 0000000..64e126b Binary files /dev/null and b/doc/images/icons/next.png differ diff --git a/doc/images/icons/note.png b/doc/images/icons/note.png new file mode 100644 index 0000000..7c1f3e2 Binary files /dev/null and b/doc/images/icons/note.png differ diff --git a/doc/images/icons/prev.png b/doc/images/icons/prev.png new file mode 100644 index 0000000..3e8f12f Binary files /dev/null and b/doc/images/icons/prev.png differ diff --git a/doc/images/icons/tip.png b/doc/images/icons/tip.png new file mode 100644 index 0000000..f087c73 Binary files /dev/null and b/doc/images/icons/tip.png differ diff --git a/doc/images/icons/up.png b/doc/images/icons/up.png new file mode 100644 index 0000000..2db1ce6 Binary files /dev/null and b/doc/images/icons/up.png differ diff --git a/doc/images/icons/warning.png b/doc/images/icons/warning.png new file mode 100644 index 0000000..d41edb9 Binary files /dev/null and b/doc/images/icons/warning.png differ diff --git a/doc/images/xmvn.svg b/doc/images/xmvn.svg new file mode 100644 index 0000000..9b0aba3 --- /dev/null +++ b/doc/images/xmvn.svg @@ -0,0 +1,108 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> +<svg width="36cm" height="27cm" viewBox="18 3 712 532" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <g> + <rect style="fill: #ffffff" x="20" y="60" width="480" height="420"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 20; stroke: #000000" x="20" y="60" width="480" height="420"/> + </g> + <g> + <rect style="fill: #ffffff" x="40" y="200" width="380" height="220"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #000000" x="40" y="200" width="380" height="220"/> + </g> + <g> + <rect style="fill: #ffffff" x="540" y="60" width="180" height="420"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 20; stroke: #000000" x="540" y="60" width="180" height="420"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="630" y="273.9"> + <tspan x="630" y="273.9"></tspan> + </text> + </g> + <g> + <path style="fill: #ffcccc" d="M 593.333 120 L 646.667,120 C 654.03,120 660,128.954 660,140 C 660,151.046 654.03,160 646.667,160 L 593.333,160 C 585.97,160 580,151.046 580,140 C 580,128.954 585.97,120 593.333,120z"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 593.333 120 L 646.667,120 C 654.03,120 660,128.954 660,140 C 660,151.046 654.03,160 646.667,160 L 593.333,160 C 585.97,160 580,151.046 580,140 C 580,128.954 585.97,120 593.333,120"/> + <text style="fill: #000000;text-anchor:middle;font-size:14.6756;font-family:sanserif;font-style:normal;font-weight:700" x="620" y="144.586"> + <tspan x="620" y="144.586">xmvn</tspan> + </text> + </g> + <g> + <path style="fill: #ffcccc" d="M 101.4 220 L 267,220 C 289.865,220 308.4,228.954 308.4,240 C 308.4,251.046 289.865,260 267,260 L 101.4,260 C 78.5354,260 60,251.046 60,240 C 60,228.954 78.5354,220 101.4,220z"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 101.4 220 L 267,220 C 289.865,220 308.4,228.954 308.4,240 C 308.4,251.046 289.865,260 267,260 L 101.4,260 C 78.5354,260 60,251.046 60,240 C 60,228.954 78.5354,220 101.4,220"/> + <text style="fill: #000000;text-anchor:middle;font-size:14.6756;font-family:sanserif;font-style:normal;font-weight:700" x="184.2" y="244.586"> + <tspan x="184.2" y="244.586">javapackages-tools</tspan> + </text> + </g> + <g> + <path style="fill: #ffcccc" d="M 586.85 380 L 648,380 C 656.443,380 663.288,388.954 663.288,400 C 663.288,411.046 656.443,420 648,420 L 586.85,420 C 578.407,420 571.562,411.046 571.562,400 C 571.562,388.954 578.407,380 586.85,380z"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 586.85 380 L 648,380 C 656.443,380 663.288,388.954 663.288,400 C 663.288,411.046 656.443,420 648,420 L 586.85,420 C 578.407,420 571.562,411.046 571.562,400 C 571.562,388.954 578.407,380 586.85,380"/> + <text style="fill: #000000;text-anchor:middle;font-size:14.6756;font-family:sanserif;font-style:normal;font-weight:700" x="617.425" y="404.586"> + <tspan x="617.425" y="404.586">maven</tspan> + </text> + </g> + <g> + <path style="fill: #ffcccc" d="M 86.525 360 L 192.625,360 C 207.274,360 219.15,368.954 219.15,380 C 219.15,391.046 207.274,400 192.625,400 L 86.525,400 C 71.8756,400 60,391.046 60,380 C 60,368.954 71.8756,360 86.525,360z"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 86.525 360 L 192.625,360 C 207.274,360 219.15,368.954 219.15,380 C 219.15,391.046 207.274,400 192.625,400 L 86.525,400 C 71.8756,400 60,391.046 60,380 C 60,368.954 71.8756,360 86.525,360"/> + <text style="fill: #000000;text-anchor:middle;font-size:14.6756;font-family:sanserif;font-style:normal;font-weight:700" x="139.575" y="384.586"> + <tspan x="139.575" y="384.586">maven-local</tspan> + </text> + </g> + <g> + <path style="fill: #ffffff" d="M 289.85 80 L 412.65,80 C 429.605,80 443.35,88.9543 443.35,100 C 443.35,111.046 429.605,120 412.65,120 L 289.85,120 C 272.895,120 259.15,111.046 259.15,100 C 259.15,88.9543 272.895,80 289.85,80z"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 289.85 80 L 412.65,80 C 429.605,80 443.35,88.9543 443.35,100 C 443.35,111.046 429.605,120 412.65,120 L 289.85,120 C 272.895,120 259.15,111.046 259.15,100 C 259.15,88.9543 272.895,80 289.85,80"/> + <text style="fill: #000000;text-anchor:middle;font-size:14.6756;font-family:sanserif;font-style:normal;font-weight:700" x="351.25" y="104.586"> + <tspan x="351.25" y="104.586">jpackage-utils</tspan> + </text> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="40" y="440"> + <tspan x="40" y="440">javapackages-tools</tspan> + </text> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="326.199" y1="120.995" x2="216.713" y2="212.751"/> + <polygon style="fill: #000000" points="210.965,217.569 215.418,207.313 216.713,212.751 221.841,214.978 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="210.965,217.569 215.418,207.313 216.713,212.751 221.841,214.978 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="146.267" y1="359.005" x2="174.551" y2="270.271"/> + <polygon style="fill: #000000" points="176.829,263.125 178.556,274.171 174.551,270.271 169.028,271.135 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="176.829,263.125 178.556,274.171 174.551,270.271 169.028,271.135 "/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="619.792" y1="160.979" x2="617.729" y2="369.285"/> + <polygon style="fill: #000000" points="617.655,376.785 612.754,366.736 617.729,369.285 622.754,366.835 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="617.655,376.785 612.754,366.736 617.729,369.285 622.754,366.835 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="560" y="440"> + <tspan x="560" y="440">Upstream Maven</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="580" y="100"> + <tspan x="580" y="100">Local Extensions</tspan> + <tspan x="580" y="116">for Maven</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="240" y="380"> + <tspan x="240" y="380">used by packages</tspan> + <tspan x="240" y="396">built with Maven</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="180" y="280"> + <tspan x="180" y="280">used by packages</tspan> + <tspan x="180" y="296">not built with Maven</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="320" y="140"> + <tspan x="320" y="140">Generic Java utilities</tspan> + <tspan x="320" y="156">(not related to Maven)</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="540" y="500"> + <tspan x="540" y="500">system-independent</tspan> + <tspan x="540" y="516">(pure Java)</tspan> + </text> + <text style="fill: #000000;text-anchor:start;font-size:12.7998;font-family:sanserif;font-style:normal;font-weight:normal" x="100" y="500"> + <tspan x="100" y="500">Fedora-specific</tspan> + <tspan x="100" y="516">(RPM macros, shell scripts,</tspan> + <tspan x="100" y="532">distro-specific config files)</tspan> + </text> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 198.809,359.586 A 1812.55,1812.55 0 0 0 582.162,165.85"/> + <polygon style="fill: #000000" points="588.4,161.686 582.892,171.416 582.176,165.872 577.311,163.118 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="588.4,161.686 582.892,171.416 582.176,165.872 577.311,163.118 "/> + </g> + <text style="fill: #000000;text-anchor:start;font-size:39.5105;font-family:sanserif;font-style:normal;font-weight:normal" x="20" y="40"> + <tspan x="20" y="40">Structure of XMvn-related packages</tspan> + </text> +</svg> diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 0000000..90a9423 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,306 @@ +Java Packaging HOWTO +==================== +Stanislav Ochotnický sochotnicky@redhat.com +v1.0, 2013-05-03 + + +:numbered!: +[abstract] +== Abstract +This document aims to help developers create and maintain Java packages in +Fedora. It *does not* supersede or replace +link:https://fedoraproject.org/wiki/Packaging:Java%5BJava Packaging Guidelines], +but rather aims to document tools and techniques used for packaging Java +software on Fedora. + +:numbered: +== The Basics +This section includes basic introduction to Java world, describes `jar` file +contents and basically describes to people unfamiliar with Java world enough to +understand Java packaging later on. + + +== Packaging principles + +Packaging Java has certain specifics that will be covered in this section which +will cover basic packaging principles such as: + + * No bundling + * Working with upstreams + * Commenting workarounds + * Links to other appropriate documents + +[[helper_macros]] +=== Java helper functions + +Many repeating tasks when packaging Java software can be automated. Most of the +time they are RPM macros or shell scripts. + +==== Macros for pom.xml modification + +Sometimes Maven `pom.xml` files need to be patched before they are used to build +packages. One could use traditional patches to maintain changes, but package +maintainers should use `%pom_*` macros developed specially to ease this +task. + +These macros are designed to be called from `%prep` section of spec files. There +are documented in `/etc/rpm/macros.fjava` configuration file, which is also +link:http://git.fedorahosted.org/git/?p=javapackages.git;a=blob_plain;f=macros.fj... online]. See the documentation for technical details how to use these +macros. Below are some examples added for convenience. + +Often dependencies specified in Maven `pom.xml` files need to be removed because of different reasons. `%pom_remove_dep` macro can be used to ease this task: + +.Removing dependencies from pom.xml files +[source,bash] +-------- +# Removes dependency on groupId:artifactId from ./pom.xml +%pom_remove_dep groupId:artifactId + +# Removes dependency on groupId:artifactId from ./submodule/pom.xml +%pom_remove_dep groupId:artifactId submodule + +# Removes dependency on groupId:artifactId from ./full/path/to/file.pom +%pom_remove_dep groupId:artifactId full/path/to/file.pom + +# Removes dependency on all artifacts in group groupId from ./pom.xml +%pom_remove_dep groupId: + +# Removes all dependencies from ./pom.xml +%pom_remove_dep : +-------- + +`%pom_remove_plugin` macro works exactly as `%pom_remove_dep`, except it removes Maven plugin invocations. Some examples: + +.Removing Maven plugins from pom.xml files +[source,bash] +-------- +# Disables maven-jar-plugin so that classpath isn't included in manifests +%pom_remove_plugin :maven-jar-plugin + +# Disable a proprietary plugin that isn't packaged for Fedora +%pom_remove_plugin com.example.mammon:useless-proprietary-plugin submodule +-------- + +Sometimes some submodules of upstream project cannot be built for various +reasons and there is a need to disable them. This can be achieved by using +`%pom_disable_module`, for example: + +.Disabling specific project modules +[source,bash] +-------- +# Disables child-module-1, a submodule of the main pom.xml file +%pom_disable_module child-module-1 + +# Disables grandchild-module, a submodule of child-module-2/pom.xml +%pom_disable_module grandchild-module child-module-2 +-------- + +The above macros cover the most common cases of modifying `pom.xml` files, +however if there is a need to apply some less-common patches there are also two +generic macros for modifying `pom.xml` files. `%pom_xpath_remove` can be used to +remove arbitrary XML nodes, described by link:http://www.w3.org/TR/xpath/%5BXPath] +expressions. `%pom_xpath_inject` macro is capable of injecting arbitrary +link:http://www.w3.org/TR/xml/%5BXML] code to any `pom.xml` file. Below you can find +some examples for these macros. + +.Less common pom.xml modifications +[source,bash] +-------- +# Removes parent definition +%pom_xpath_remove "pom:parent" + +# Removes extensions from the build +%pom_xpath_remove "pom:build/pom:extensions" module/pom.xml + +# Adds new dependency +%pom_xpath_inject "pom:dependencies" " + <dependency> + <groupId>org.example.project</groupId> + <artifactId>awesomeproject</artifactId> + <version>1.0.0.GA</version> + </dependency>" +-------- + +.Handling XML namespaces +[NOTE] +======= +POM files use a specific namespace - http://maven.apache.org/POM/4.0.0. The +easiest way to respect this namespace in XPath expressions is prefixing all node +names with `pom:`. For example, `pom:environment/pom:os` will work because it +selects nodes from `pom` namespace, but `environment/os` won't find anything +because it looks for nodes that don't belong to any XML namespace. +======= +Using `%pom_*` macros not only increases readability of the spec file, but also improves maintainability of the package as there are no patches that would need to be rebased with each upstream release. + +==== add_maven_depmap macro + +Maven identifies jar files by a set of strings: groupId, artifactId and version +(mostly). To let mvn-rpmbuild know what groupId:artifactId corresponds to which +pom or jar file, we use the `%add_maven_depmap` +macro. `%add_maven_depmap` reads the groupId and artifactId from the +pom file and creates a file in `%{_mavendepmapfragdir}` that maps +groupId:artifactId pairs to jar files under `%{_javadir}`. All +fragments in this directory are read by mvn-rpmbuild during startup, allowing +the locally installed jar files and poms to be used as a maven repository. + +Note that -- unless you use the `-f` option as shown below -- all +depmap fragments for a given package are written to the same file, +`%{_mavendepmapfragdir}/%{name}`. You should be sure to include this +file in the `%files` section of your RPM. + +For the macro to work properly, all jar files must be copied into +`%{_javadir}` (see [[#JAR_file_installation|JAR file installation]]), +and all pom files must be copied into `%{_mavenpomdir}` and given +file names of the following form, where `jarname` is the name of the +jar without the .jar suffix: + +[source,bash] +-------- +%{_mavenpomdir}/JPP[.subdirectory]-jarname.pom +-------- + +Note that the subdirectory is only necessary if the jar file is put into a subdirectory of `%{_javadir}`. For example: + +* For junit, the jar is `%{_javadir}/junit.jar`, so the pom would be + `%{_mavenpomdir}/JPP-junit.pom`. +* For plexus-ant-factory, the jar is `%{_javadir}/plexus/ant-factory.jar`, so + the pom would named `%{_mavenpomdir}/JPP.plexus-ant-factory.pom`. + +If a pom is installed with no corresponding jar file -- for example, for parent +poms -- the same convention should be followed: + +* The Apache commons parent pom is installed in + `%{_mavenpomdir}/JPP-commons-parent.pom`. + +In its simplest form (a pom without a jar file), `%add_maven_depmap` looks like this: + +.Parent pom +[source,bash] +-------- +%add_maven_depmap JPP-%{name}.pom +-------- + +This will read the pom file in question and provide a mapping between the +groupId and artifactId inside the pom file and the pom file placed into +`%{_mavenpomdir}`. + +For a pom that maps directly to a jar file, the following is the correct form: + +.Standard invocation +[source,bash] +-------- +%add_maven_depmap JPP-%{name}.pom %{name}.jar +-------- + +In addition to creating the pom mapping, this will also ensure that the correct +jar is associated with the groupId and artifactId from the pom. + +.Providing additional artifact mappings +[source,bash] +-------- +%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang" +-------- +This form also adds additional mappings for given pom/jar file. For example, if +the pom file indicates that it contains groupId commons-lang, artifactId +commons-lang, this form ensures that we also add a mapping between groupId +org.apache.commons and the installed jar/pom files. This is necessary in cases +where the groupId or artifactId may have changed, and other packages might +require different IDs than those reflected in the installed pom. + +.Multiple subpackages +[source,bash] +-------- +%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX" +-------- +This form stores dependency mapping inside `%{_mavendepmapfragdir}/%{name}-XXX` +instead of standard location. This is useful for packages with multiple +subpackages where each has its own jar files. + +.Multiple artifacts in a subdirectory +[source,bash] +-------- +%add_maven_depmap JPP.%{name}-sub.pom %{name}/sub.jar +-------- + +This form should be used when a package consists of multiple jar files that are +installed into a subdirectory of `%{_javadir}`. Note that in this case, the pom +file name includes the optional subdirectory field. + + + +== Build systems + +Lorem ipsum about build systems, differences, preferences etcetera. + + +Will probably include some information about <<Xdepmap,depmap>> files. + +=== Maven + +Loong section about maven + +.XMvn package relationships +image:images/xmvn.svg["XMvn related packages",width=600] + + +=== Ant + +Medium length-section about Ant + +=== Gradle + +No information for Gradle! + +:numbered!: + + +== History + +This section will be updated with history of Java packaging so that packagers +can get bigger context. We can mention JPP, add_to_maven_depmap madness, Maven +updates between major versions etcetera. + +[appendix] +== Example Appendix +AsciiDoc article appendices are just just article sections with +'specialsection' titles. + +=== Appendix Sub-section +Appendix sub-section at level 2. + + +[bibliography] +References +---------- + +[bibliography] +- [[[guidelines]]] https://fedoraproject.org/wiki/Packaging:Java +- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner. + 'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999. + ISBN 1-56592-580-7. + + +[glossary] +Glossary +-------- +Glossaries are optional. Glossaries entries are an example of a style +of AsciiDoc labeled lists. + +[glossary] +[[Xdepmap]]depmap:: + Depmap is a special file telling Maven relationships between + groupId,artifactId and jar file on the filesystem + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::backend-docbook[] +[index] +Example Index +------------- +//////////////////////////////////////////////////////////////// +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::backend-docbook[]