Difference between revisions of "Multi-Module Maven with github pages"
Jump to navigation
Jump to search
| Line 179: | Line 179: | ||
} | } | ||
</source> | </source> | ||
| + | == Speed comparison == | ||
| + | On my computer the plugin takes 18 minutes for the simple com.bitplan.multimodule example | ||
| + | |||
| + | The script needs 25 seconds! | ||
= Experimenting with distributionManagement.url settings = | = Experimenting with distributionManagement.url settings = | ||
Revision as of 14:07, 24 August 2018
Motivation
The issues
led to the creation of the example project:
- https://github.com/BITPlan/com.bitplan.multimodule which uses
- https://github.com/BITPlan/com.bitplan.pom for the parent pom definition
in which the github maven site plugin is defined with the configuration
<!-- git hub site plugin https://github.com/github/maven-plugins -->
<plugin>
<groupId>com.github.github</groupId>
<artifactId>site-maven-plugin</artifactId>
<version>${site-maven-plugin.version}</version>
<configuration>
<message>Creating site for ${github.owner} ${github.project}
${project.version}</message>
<repositoryName>${github.project}</repositoryName> <!-- github repo name -->
<repositoryOwner>${github.owner}</repositoryOwner> <!-- github username -->
</configuration>
<executions>
<execution>
<goals>
<goal>site</goal>
</goals>
<phase>site</phase>
</execution>
</executions>
</plugin>
Following the suggestion of https://stackoverflow.com/a/19336536/1497139 led to adding
<distributionManagement>
<site>
<id>${project.artifactId}-site</id>
<url>${project.baseUri}</url>
</site>
</distributionManagement>
to the parent pom.xml
mvn clean site
... wait a long while ...
[INFO] Multi-Module ....................................... SUCCESS [04:22 min]
[INFO] Multi-Module 1 ..................................... SUCCESS [04:09 min]
[INFO] Multi-Module 2 ..................................... SUCCESS [04:09 min]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12:42 min
and you end up with Module 2 overriding the results of the Multi-Module and Module 1 results
Is it a bug or a feature?
Whats the work-around?
- Do not use the plugin!
- git clone or pull the gh-pages to a local folder
- mvn site:stage to a temporary staging directory
- rsync the results into the git local folder
- check in the local folder
- have a cup of coffee or drink a beer / be happy ✓
Do not use the plugin!
- It's slow (as in really slow ...)
- It's not reliable (as in 500 HTML Codes)
- It's not maintained well (as in 57 open issues as of 2018-08
- It's superflous (see below)
- Even the committer's don't use it any more (as in a personal mail I got today ..)
Steps to work around
git clone or pull the gh-pages to a local folder
git clone https://github.com/$owner/$project --branch gh-pages --single-branch
mvn site:stage to a temporary staging directory
mkdir -p /tmp/stage/4site
mvn -U clean install site site:stage -DstagingDirectory=/tmp/stage/4site
[INFO] --- maven-site-plugin:3.7.1:stage (default-cli) @ multimodule2 ---
[INFO] Using this base directory for staging: /tmp/stage/4site
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO] >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] Multi-Module ....................................... SUCCESS [ 5.423 s]
[INFO] Multi-Module 1 ..................................... SUCCESS [ 4.043 s]
[INFO] Multi-Module 2 ..................................... SUCCESS [ 3.393 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 13.665 s
Yes - thats right seconds not minutes!
rsync the results into the git local folder
rsync -avz /tmp/stage/com.bitplan.multimodule/* $ghpages/com.bitplan.multimodule
check in the local folder
in the $gphages/com.bitplan.multimodule folder:
git add *
git commit -m "checking new site in ..."
git push
have a cup of coffee or drink a beer / be happy ✓
gist of a script
The following bash createSite function does the core work. To call it set the globals ws variable to your workspace and supply the three arguments e.g.
createSite com.bitplan.multimodule $HOME/Documents/gh-pages "multimodule1 multimodule2"
see the comments of the function below for the description of the three arguments.
createSite bash function
#
# createSite
# ws: global variable pointing to workspace
# param 1: l_project - project name/directory
# param 2: l_ghpages - directory where gh-pages branch has been git cloned/pulled
# param 3: l_modules - non-empty for a multi-module project (e.g. containing the list of modules)
#
createSite() {
local l_project="$1"
local l_ghpages="$2"
local l_modules="$3"
color_msg $green "creating site for $l_project $l_modules"
cd $ws/$l_project
stage=/tmp/stage$$
sitelog=/tmp/sitelog$$.txt
rm -rf $stage
# the stagingDirectory needs to be subdirectory
mkdir -p $stage/$l_project
# run the staging of the site against this directory and log the results
mvn -U clean install site site:stage -DstagingDirectory=$stage/$l_project | tee $sitelog
# rsync the result into the github-pages folder
rsync -avz --del $stage/* $l_ghpages/$l_project/
# is this a multi module project?
if [ "$l_modules" != "" ]
then
cd $l_ghpages/$l_project/
if [ ! -f index.html ]
then
cat << EOF > index.html
<!DOCTYPE html>
<html>
<head>
<!-- HTML meta refresh URL redirection -->
<meta http-equiv="refresh"
content="0; url=./$l_project/$l_project/index.html">
</head>
<body>
<p>This is a multimodule mvn site click below to get to the index.html of
<a href="./$l_project/$l_project/index.html">$l_project</a></p>
</body>
</html>
EOF
fi
# add potentially new files
git add *
# commit results
git commit -m "checked in by checksite script"
# push results
git push
fi
if [ "$debug" = "false" ]
then
rm -rf $stage
rm $sitelog
fi
}
Speed comparison
On my computer the plugin takes 18 minutes for the simple com.bitplan.multimodule example
The script needs 25 seconds!
Experimenting with distributionManagement.url settings
For this we wrote a script to log the results of the mvn site command and analyze where the results go
#!/bin/bash
# WF 2018-08-24
# prepare to log the mvn site command
sitelog=/tmp/sitelog$$.txt
# create an empty staging area
stage=/tmp/stage
rm -rf $stage
mkdir -p $stage/4site
# run the staging of the site against this directory and log the results
mvn -U clean install site site:stage -DstagingDirectory=$stage/4site | tee $sitelog
# what url did we set for the site in distributionManagement?
cat ../com.bitplan.pom/pom.xml | xml2 | grep /project/distributionManagement/site/url
# and where did the results go?
egrep "(Pushing|to file)" $sitelog
${project.baseUri}
/project/distributionManagement/site/url=${project.baseUri}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
[INFO] >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO] >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO] >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module2/com.bitplan.multimodule/multimodule2
- the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html ✓
- inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html ✓
${project.artifactId}
/project/distributionManagement/site/url=${project.artifactId}
- failed: Base URI is not absolute: com.bitplan.pom -> [Help 1]
https://${github.owner}.github.io/${project.artifactId}
/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
[INFO] >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO] >>> to file:///tmp/stage/4site/../multimodule1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO] >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2
Same result as the working result above ..
- the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html ✓
- inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html ✓
Test with non -module pom based project
/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.fritzbox/target/site
[INFO] >>> to file:///tmp/stage/4site/../com.bitplan.fritzbox/com.bitplan.fritzbox
Example pom.xml files
- https://github.com/kohsuke/pom/blob/master/pom.xml (uses wagon-gitsite ...)
- https://github.com/PathwayCommons/cpath2/blob/master/pom.xml
- https://github.com/CoreMedia/joala/commit/5f12395b8b6d84a39c2c11534ec5a509dace4720
Stackoverflow questions
- https://stackoverflow.com/questions/10848715/multi-module-pom-creating-a-site-that-works
- https://stackoverflow.com/questions/21520904/multi-module-example-of-using-mvn-site-deploy-with-github-pages