Author: dfabulich Date: Fri Aug 15 16:07:41 2008 New Revision: 686414 URL: http://svn.apache.org/viewvc?rev=686414&view=rev Log: adding site, updating documentation
Added: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/examples.apt.vm maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/index.apt maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/site.xml Modified: maven/sandbox/trunk/plugins/maven-reactor-plugin/TODO.txt maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMojo.java maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMyChanges.java maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/ResumeMojo.java Modified: maven/sandbox/trunk/plugins/maven-reactor-plugin/TODO.txt URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/TODO.txt?rev=686414&r1=686413&r2=686414&view=diff ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/TODO.txt (original) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/TODO.txt Fri Aug 15 16:07:41 2008 @@ -1,6 +1,6 @@ release maven-invoker 2.0.10 so we can consume the new --reactor feature -deal with sibling aggregators (which use <module>../blah</module>) ... can we do that with -r? Should we generate a temporary POM instead? -create a site -basic unit test integration tests -graduate from sandbox \ No newline at end of file +deal with sibling aggregators (which use <module>../blah</module>) ... can we do that with -r? Should we generate a temporary POM instead? +basic unit test - would require injecting ProjectSorter (can somebody give me a hint?) +graduate from sandbox +make a reverse dependency tree \ No newline at end of file Modified: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMojo.java URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMojo.java?rev=686414&r1=686413&r2=686414&view=diff ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMojo.java (original) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMojo.java Fri Aug 15 16:07:41 2008 @@ -45,42 +45,47 @@ extends AbstractMojo { /** - * Location of the file. + * Location of the POM file; provided by Maven * @parameter expression="${basedir}" - * @required + * */ File baseDir; /** + * A list of every project in this reactor; provided by Maven * @parameter expression="${project.collectedProjects}" */ List collectedProjects; /** + * If you don't specify a groupId in your artifactList, we'll use this as the default groupId. * @parameter expression="${make.group}" default-value="${project.groupId}" - * @required + * */ String defaultGroup; /** * A list of artifacts to build, e.g. "com.mycompany:bar,com.mycompany:foo" or just "foo,bar", or just "foo" - * @parameter expression="${make.artifacts}" + * @parameter expression="${make.artifacts}" default-value="" + * @required */ String artifactList; /** * A list of relative paths to build, e.g. "foo,baz/bar" - * @parameter expression="${make.folders}" + * @parameter expression="${make.folders}" default-value="" + * @required */ String folderList; /** - * Goals to run on subproject + * Goals to run on subproject. * @parameter expression="${make.goals}" default-value="install" */ String goals; /** + * Provided by Maven * @component */ Invoker invoker; @@ -94,7 +99,7 @@ public void execute() throws MojoExecutionException, MojoFailureException { - if (artifactList == null && folderList == null) { + if ( artifactList == null && folderList == null ) { throw new MojoFailureException("You must specify either folders or projects with -Dmake.folders=foo,baz/bar or -Dmake.projects=com.mycompany:foo,com.mycompany:bar"); } String[] reactorIncludes; Modified: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMyChanges.java URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMyChanges.java?rev=686414&r1=686413&r2=686414&view=diff ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMyChanges.java (original) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/MakeMyChanges.java Fri Aug 15 16:07:41 2008 @@ -45,10 +45,11 @@ extends MakeDependentsMojo { /** - * @parameter expression="${make.scmUrl}" default-value="${project.scm.connection}" + * The SCM connection/provider info. Should be specified in your POM. + * @parameter expression="${make.scmConnection}" default-value="${project.scm.connection}" * @required */ - private String scmUrl; + private String scmConnection; /** * Ignore files in the "unknown" status (created but not added to source control) @@ -69,10 +70,14 @@ { throw new NonReactorException(); } + if ( scmConnection == null ) + { + throw new MojoFailureException("No SCM connection specified. You must specify an SCM connection by adding a <connection> element to your <scm> element in your POM"); + } StatusScmResult result = null; try { - ScmRepository repository = scmManager.makeScmRepository( scmUrl ); + ScmRepository repository = scmManager.makeScmRepository( scmConnection ); result = scmManager.status( repository, new ScmFileSet( baseDir ) ); } catch ( Exception e ) @@ -81,7 +86,7 @@ } List changedFiles = result.getChangedFiles(); - // TODO There's a cleverer/faster way to code this...? + List projectDirectories = getProjectDirectories(); Set changedDirectories = new HashSet(); for ( int i = 0; i < changedFiles.size(); i++ ) @@ -102,6 +107,7 @@ File changedFile = new File( changedScmFile.getPath() ); boolean found = false; + // TODO There's a cleverer/faster way to code this, right? This is O(n^2) for ( int j = 0; j < projectDirectories.size(); j++ ) { File projectDirectory = (File) projectDirectories.get( j ); Modified: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/ResumeMojo.java URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/ResumeMojo.java?rev=686414&r1=686413&r2=686414&view=diff ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/ResumeMojo.java (original) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/main/java/org/apache/maven/plugin/reactor/ResumeMojo.java Fri Aug 15 16:07:41 2008 @@ -47,25 +47,25 @@ /** * Location of the file. * @parameter expression="${basedir}" - * @required */ private File baseDir; /** * @parameter expression="${make.group}" default-value="${project.groupId}" - * @required */ private String continueFromGroup; /** * The artifact from which we'll resume, e.g. "com.mycompany:foo" or just "foo" * @parameter expression="${fromArtifact}" + * @required */ private String continueFromProject; /** * The project folder from which we'll resume * @parameter expression="${from}" + * @required */ private File continueFromFolder; Added: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/examples.apt.vm URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/examples.apt.vm?rev=686414&view=auto ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/examples.apt.vm (added) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/examples.apt.vm Fri Aug 15 16:07:41 2008 @@ -0,0 +1,222 @@ + ------ + Examples + ------ + Dan Fabulich + ------ + 2008-08-15 + ------ + +~~ 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. + +Examples + +* Example reactor project + + Consider an ordinary multi-module reactor build: + ++---+ +my-root-project +|-- pom.xml +|-- fooUI +| `-- pom.xml +|-- barBusinessLogic +| `-- pom.xml +`-- bazDataAccess + `-- pom.xml ++---+ + + Suppose project "fooUI" depends on project "barBusinessLogic", which depends on project "bazDataAccess". + ++---+ +fooUI --> barBusinessLogic --> bazDataAccess ++---+ + + Ordinarily, when you run <<<mvn install>>> from <<<my-root-project>>>, you'll first build bazDataAccess, then barBusinessLogic, then fooUI. + +* Resuming the build with reactor:resume + + Suppose you're working on your code and you attempt to build your code with <<<mvn install>>> from <<<my-root-project>>>, and suppose you get a test failure in barBusinessLogic. You make additional changes to barBusinessLogic without changing bazDataAccess; you know that bazDataAccess is fine, so there's no need to rebuild/test it. You can then use <<<reactor:resume>>>, like this: + ++---+ +mvn reactor:resume -Dfrom=barBusinessLogic ++---+ + + That will skip over bazDataAccess and pick up the build where you left off in barBusinessLogic. If barBusinessLogic succeeds, it will go on to build fooUI. + +* Making barBusinessLogic without building fooUI using reactor:make + + Suppose you're a developer working on barBusinessLogic; you don't want to work on fooUI right now, but just want to get a working build of barBusinessLogic. You can use <<<reactor:make>>>, like this: + ++---+ +mvn reactor:make -Dmake.folders=barBusinessLogic ++---+ + + <<<reactor:make>>> will examine barBusinessLogic and walk down its dependency tree, finding all of the projects that it needs to build. + In this case, it will automatically build bazDataAccess and then barBusinessLogic, without building fooUI. + +* Changing barBusinessLogic and verifying you didn't break anything using reactor:makeDependents + + Suppose you've made a change to barBusinessLogic; you want to make sure you didn't break any of the projects that depend on you. (In this case, you want to make sure that you didn't break fooUI, but in a more complex reactor that might not be so obvious.) You also want to avoid rebuilding/testing projects that you know you haven't changed. In this case, you want to avoid building bazDataAccess. You can use <<<reactor:makeDependents>>>, like this: + ++---+ +mvn reactor:makeDependents -Dmake.folders=barBusinessLogic ++---+ + + <<<reactor:makeDependents>>> will examine all of the projects in your reactor to find projects that depend on barBusinessLogic, and automatically build those and nothing else. In this case, it will automatically build barBusinessLogic and then fooUI. + +* Building anything that you personally have changed using reactor:makeMyChanges + + Suppose you've made a change to some source files in barBusinessLogic but you've forgotten what you've changed. You want to make sure you're safe to check-in, and that you haven't broken any projects that depend on you. You can use <<<reactor:makeMyChanges>>>, like this: + ++---+ +mvn reactor:makeMyChanges ++---+ + + <<<reactor:makeMyChanges>>> determines which files have changed using your SCM (Source Configuration Management) tool, e.g. Subversion, Perforce, Git, etc. To use it, you'll need to configure an SCM connection in your root project POM file: + ++---+ +<project> + ... + <scm> + <connection>scm:svn:http://svn.mycompany.com/trunk/blah</connection> + <url>http://svn.mycompany.com/trunk/blah</url> + </scm> + ... +</project> ++---+ + + The reactor plugin will use Maven's built-in SCM providers to attempt to figure out which files you've modified. (By default, it will ignore "unknown" files: files that have been created in a source directory but which haven't been explicitly added to source control.) + + Once the reactor plugin computes the list of changed files, it will figure out which of those files correspond to which projects in the reactor, and basically do a <<<reactor:makeDependents>>> on those projects that contain changed files. + + In this example, if you only modified files in barBusinessLogic, then running <<<reactor:makeMyChanges>>> is equivalent to running <<<reactor:makeDependents -Dmake.folders=barBusinessLogic>>> -- it builds barBusinessLogic and anything that depends on barBusinessLogic (in this case, it will build fooUI). + + <<If you find that reactor:makeMyChanges is doing somthing you don't expect, try running Maven in debug mode>> with <<<--debug>>> or <<<-X>>> like this: + ++---+ +mvn reactor:makeMyChanges -X ++---+ + + You'll see a log of all the changed files and a depiction of how we computed which projects to pass to <<<reactor:makeDependents>>>. + +* Doing a "dry run" with the reactor plugin + + All of the reactor plugin goals take in an argument <<<-Dmake.printOnly>>> that you can use to see what the goal would have done without actually doing it. For example: + ++---+ +> mvn reactor:make -Dmake.folders=barBusinesslogic -Dmake.printOnly +[INFO] Scanning for projects... +[...] +[INFO] [reactor:make] +[INFO] Executing: /Users/danfabulich/svn/redfin/buildtools/maven/bin/mvn -B -N -r -D maven.reactor.includes=bazDataAcecss/pom.xml,barBusinessLogic/pom.xml install +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESSFUL +[INFO] ------------------------------------------------------------------------ ++---+ + +* Running a different goal/lifecycle ("test", "package", "eclipse:eclipse", "clean", etc.) + + By default, all of the reactor plugin goals will run <<<mvn install>>> on the appropriate projects. That's a pretty reasonable default, but sometimes you want to run a different command on a bunch of projects. All of the reactor plugin goals will accept a <<<-Dmake.goals>>> argument that will let you run other goals instead. You can separate multiple goals with commas: + ++---+ +mvn reactor:make -Dmake.folders=barBusinessLogic -Dmake.goals=eclipse:eclipse +mvn reactor:makeDependents -Dmake.folders=barBusinessLogic -Dmake.goals=package,clean +mvn reactor:resume -Dmake.folders=barBusinessLogic -Dmake.goals=test ++---+ + +* Skipping tests and passing flags to the spawned Maven + + The reactor plugin launches a second copy of Maven to do its magic. This copy of Maven doesn't necessarily have all of the flags and options that you passed to your first copy of Maven, including the --debug flag, system properties, and -DskipTests. + + You can pass additional arguments to the spawned Maven by treating them as goals with <<<-Dmake.goals>>>, like this: + ++---+ +mvn reactor:resume -Dmake.folders=barBusinessLogic -Dmake.goals=install,-DskipTests ++---+ + + In other words, the "goals" are just extra command-line parameters passed to the spawned Maven; they don't necessarily have to be "goals." + + If you want to get really fancy, you may prefer to just dry run the reactor plugin in <<<-Dmake.printOnly>>> mode, described above. That will print out the command that the plugin would have used to build, but you can tweak that command line to your heart's content! + +* Nested directories + + Let's consider a more complex project: + ++---+ +my-root-project +|-- pom.xml +|-- fooUI +| `-- pom.xml +|-- barBusinessLogic +| `-- pom.xml +|-- quz +| |-- pom.xml +| |-- quzAdditionalLogic +| | `-- pom.xml +| `-- quzUI +| `-- pom.xml +`-- bazDataAccess + `-- pom.xml ++---+ + + Again suppose project "fooUI" depends on project "barBusinessLogic", which depends on project "bazDataAccess". + ++---+ +fooUI --> barBusinessLogic --> bazDataAccess ++---+ + + But furthermore, suppose "quzUI" depends on "quzAdditionalLogic", which depends on "barBusinessLogic." + ++---+ +quzUI --> quzAdditionalLogic --> barBusinessLogic --> bazDataAccess ++---+ + + If you try to run <<<mvn reactor:make -Dmake.folders=quzUI>>>, you'll get an error: + ++---+ +> mvn reactor:make -Dmake.folders=quzUI +[INFO] Folder doesn't exist: /home/person/svn/trunk/quzUI ++---+ + + Naturally, you'll have to specify the complete relative path to quzUI, like this: + ++---+ +> mvn reactor:make -Dmake.folders=quz/quzUI ++---+ + + That would build everything in the reactor except "fooUI". Note that in this project, if you ran <<<mvn reactor:makeDependents -Dmake.folders=barBusinessLogic>>> it would build everything in the reactor except bazDataAccess. + +* Identifying projects by artifact, instead of by folder name + + Sometimes projects can be nested pretty far down the tree; it can be easier in that case to just identify them by their artifactId instead of by their full relative path. Assuming that the artifactId for "quzUI" is just "quzUI", you can do this: + ++---+ +mvn reactor:make -Dmake.artifacts=com.mycompany:quzUI ++---+ + + or, if you want to resume: + ++---+ +mvn reactor:resume -DfromArtifact=com.mycompany:quzAdditionalLogic ++---+ + + If quzUI has the same groupId as the root POM, you can even omit the "com.mycompany:" groupId and just say: + ++---+ +mvn reactor:make -Dmake.artifacts=quzUI ++---+ Added: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/index.apt URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/index.apt?rev=686414&view=auto ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/index.apt (added) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/apt/index.apt Fri Aug 15 16:07:41 2008 @@ -0,0 +1,87 @@ + ------ + Introduction + ------ + Dan Fabulich + ------ + 2008-08-15 + ------ + +~~ 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. + +Maven 2 Reactor Plugin + + This plugin can build a subset of interdependent projects in a + reactor. It should be useful in large reactor builds that include + irrelevant stuff you're not working on. + +* Goals Overview + + The Reactor plugin has several goals: + + * {{{resume-mojo.html}reactor:resume}} resumes a reactor at a certain point (e.g. when it fails + in the middle) + + Example: <<<mvn reactor:resume -Dfrom=bar>>> + + * {{{make-mojo.html}reactor:make}} builds a project X and all of the reactor projects on which X depends + + Example: <<<mvn reactor:make -Dmake.folders=foo,bar>>> + + * {{{makeDependents-mojo.html}reactor:makeDependents}} builds a project X and all of the reactor projects that depend on X (the reverse of reactor:make) + + Example: <<<mvn reactor:makeDependents -Dmake.folders=foo,bar>>> + + * {{{makeMyChanges-mojo.html}reactor:makeMyChanges}} build all reactor projects that you personally + have changed (according to SCM) and all reactor projects that depend + on your changes + + Example: <<<mvn reactor:makeMyChanges>>> + +* make vs. makeDependents + + The goals <<<reactor:make>>> and <<<reactor:makeDependents>>> are very similar. They differ in the <direction> of dependency analysis. + + For example, suppose project "fooUI" depends on project "barBusinessLogic", which depends on project "bazDataAccess". + ++---+ +fooUI --> barBusinessLogic --> bazDataAccess ++---+ + + Ordinarily, when building, you'll first build bazDataAccess, then barBusinessLogic, then fooUI. + + * <<make>>: In order to "make" barBusinessLogic, you first have to build bazDataAccess. So if you run reactor:make on barBusinessLogic, it will build bazDataAccess, and then build barBusinessLogic; it won't build fooUI. (This should remind you of the traditional "make" tool.) + ++---+ +barBusinessLogic --> bazDataAccess ++---+ + + * <<makeDependents>>: Because fooUI depends on barBusinessLogic, fooUI is a "dependent" project of barBusinessLogic. Anything that depends on barBusinessLogic is one of barBusinessLogic's "dependents." Hence, reactor:makeDependents will build barBusinessLogic, and then build fooUI. + ++---+ +fooUI --> barBusinessLogic ++---+ + + [] + + <<In other words, reactor:make walks *down* the dependency tree, whereas reactor:makeDependents walks *up* the dependency tree.>> + +* Examples + + To provide you with better understanding on some usages of the Reactor + Plugin, you can take a look at the {{{examples.html}examples}} page. + Added: maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/site.xml URL: http://svn.apache.org/viewvc/maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/site.xml?rev=686414&view=auto ============================================================================== --- maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/site.xml (added) +++ maven/sandbox/trunk/plugins/maven-reactor-plugin/src/site/site.xml Fri Aug 15 16:07:41 2008 @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> + +<!-- + 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. +--> + +<project name="Maven Reactor Plugin"> + <body> + <menu name="Overview"> + <item name="Introduction" href="index.html"/> + <item name="Goals" href="plugin-info.html"/> + <item name="Examples" href="examples.html"/> + </menu> + </body> +</project>