[CONF] Apache Struts 2 Documentation: Building with Maven (page edited)

[confluence]

Page Edited : WW : Building with Maven Building with Maven has been edited by Rainer Hermanns (Nov 05, 2006). (View changes) Content: Maven 2.0.4 or later is required to build Struts 2 First, let's review some Maven basics. Maven uses the notion of a build lifecycleto which plugins can attach. (Plugins are similar to Ant tasks.) When a Maven build is invoked, we specify a point in the lifecycle up to which the build should proceed. The phase compile comes before test, and test comes before package, and package comes before install. Once we have Maven setup, we can invoke the Struts build, and specify which phase the build should use. Installing The install phase builds up the project ("package"), and installs any JARs it needs into your local repository (e.g. ~/.m2/repository). Once installed, the JARs can be used by any other Maven project you build.  The install phase is the default phase if none is specified. To run a basic install, change to the root of the source distribution, and enter Go! > mvn That's it! Maven will download all dependencies the build needs, run all unit tests, package up the JARs, and then install the new JARs locally. For your convenience, copies of the JARs can be found in the target directories of each module. For example, after the build, the main JAR can found at core/target/struts2-core-2.0-SNAPSHOT.jar. It's suppose to be automatic, but you might still have to press the button Sometimes, licensing restrictions prevent Maven for downloading all the JARs that a build might need. For example, JavaMail and Activation, can only be downloaded from Sun. When this happens, Maven will display a helpful message that explains how to install these JARs manually. After downloading the required JAR, follow the instructions to install it to the your local repository. Once installed, the JAR is availale to all your Maven builds, not just Struts. Initial Build Successful [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] ------------------------------------------------------------------------ [INFO] Struts 2 .............................................. SUCCESS [0.870s] [INFO] Struts 2 - Core ....................................... SUCCESS [1:17.272s] [INFO] Struts 2 API .......................................... SUCCESS [3.252s] [INFO] ------------------------------------------------------------------------ [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1 minute 22 seconds [INFO] Finished at: Wed Jul 19 10:46:01 PDT 2006 [INFO] Final Memory: 10M/42M [INFO] ------------------------------------------------------------------------ Other phases There are other phases that can be useful when working with Maven. The package phase will just JAR (or WAR) the modules. The test phase will run only the unit tests. The compile phase will only build the source code (but not the test sources). And the clean phase will remove all artifacts, typically the entire target directory. Build profiles The next step to building the framework with Maven is to understand build profiles. Profiles provide different configurations for a build. There are several profiles, including default, xwork, and _thirdparty". Profile Description default Builds site, api, and core apps Builds the example applications plugins Builds all plugins extras Includes the extras module that cannot be part of the default build due to licensing incompatibilties xwork Includes the xwork build Tbe default profile will work for most developers, but some developers will want to use additional profiles as they work on both XWork and other modules, such as the JasperReports integration. Specify a profile is as simple as: Profile, please > mvn -Pprofile ... Extras Profile If you want to build all the extras module not included with the default build, use the _extras*_profile. Extras Module > mvn -Pextras Build with Third Party Modules [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] ------------------------------------------------------------------------ [INFO] Struts 2 .............................................. SUCCESS [1.047s] [INFO] Struts 2 - Core ....................................... SUCCESS [33.615s] [INFO] Struts 2 API .......................................... SUCCESS [0.520s] [INFO] Struts Extras ......................................... SUCCESS [20.944s] [INFO] ------------------------------------------------------------------------ [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 57 seconds [INFO] Finished at: Wed Jul 19 10:51:05 PDT 2006 [INFO] Final Memory: 9M/40M [INFO] ------------------------------------------------------------------------ In the second run, the Extras module is built. If you decide to make use of this module, be sure to review the licenses of its dependencies, since they may be under a license incompatible with the Apache License. XWork profile Struts 2 is an extension of the XWork framework. While Struts2 adds a lot of value for web developers, much of the core functionality derives from XWork. The xwork plugins add the capability to build against a current XWork checkout, rather than a precompiled JAR. The plugin assumes that the latest XWork code is checked out and is located at ../xwork, relative to the struts2 folder. You can check out XWork using the Subversion command: Checking out XWork svn co https://svn.opensymphony.com/svn/xwork/trunk xwork Subversion If you don't have the command line version of Subversion installed, you can download it from the Subversion site, and add the bin folder to your command path. Working XWork > mvn -Pxwork package [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] ------------------------------------------------------------------------ [INFO] XWork ................................................. SUCCESS [39.527s] [INFO] Struts 2 .............................................. SUCCESS [0.216s] [INFO] Struts 2 - Core ....................................... SUCCESS [29.736s] [INFO] Struts 2 API .......................................... SUCCESS [0.318s] [INFO] ------------------------------------------------------------------------ [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1 minute 11 seconds [INFO] Finished at: Wed Jul 19 10:57:27 PDT 2006 [INFO] Final Memory: 12M/53M [INFO] ------------------------------------------------------------------------ Now, Maven will build XWork from source and use that as the XWork snapshot for the Struts build. Multiple profiles Maven can build against multiple profiles. If you are developing against both the XWork and Struts 2 frameworks at once, you can install both profiles with one call to Maven. Getting it All > mvn -Pextras,plugins,xwork Using both profiles is especially important when using Maven to build your IDE project files (recommended). Building IDE project files Maven has a great feature that will allow you to build up your IDEA or Eclipse project files based on the project build structure. Using the Maven project files helps keep developers in-sync and efficient. The IDEA project files are pre-configured to define in the Run/Debug menu many common tasks, such as "execute all tests", "launch the showcase sample app", and so fort. IDEA by JetBrains The Maven IDEA plugin creates IDEA project and modules files, based on the Maven build configuraton (pom.xml). First, be sure you have the latest IDEA plugin for Maven. Get the latest plugin! mvn -DconnectionUrl=scm:svn:http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-idea-plugin \ -Dgoals=install \ scm:bootstrap Most often, we use Maven to build projects, but it can also run plugins directly. To build an IDEA project file for Struts 2, including all the modules, run Generate the project files > mvn idea:idea -Papps,extras,thirdparty,xwork Maven will generate struts-parent.ipr, struts-parent.iws, and an iml file for each module listed Open up struts-parent.ipr in IDEA, and you should be good to go. If you ever need to rebuild your projects, running the idea:idea command again will update your files without overriding any information that doesn't conflict. If you do want to overwrite the project files, specify the overwrite parameter as true. Starting over > mvn idea:idea -Doverwrite=true -Papps,extras,thirdparty,plugins,xwork If you only need to rebuild some of the modules, adjust the list of "profiles". Clearing the cache If you find the xwork module causing you problems, such as displaying as "XWork" when it should be named "xwork", the problem is likely to be within IDEA. Try clearing out your IDEA system cache and then run it again Eclipse For Eclipse, try Generating Eclipse > mvn -Pthirdparty,plugins,xwork eclipse:eclipse Feedback Wanted Many Struts 2 developers use IDEA, and the Eclipse project files are not as well-tested or featureful as the IDEA versions. But as far as we know, they work! IMPORTANT: Running the Sample Applications from Eclipse or non-IDEA IDEs Currently the sample applications can be deployed using QuickStart. With the switch to Maven, the expected location for the JARs is no longer valid. Fortunately, QuickStart has a feature where it can read in one or more IDEA iml (module) file and use the JARs specified there. So far the Showcase application is configured to do this (see its quickstart.xml file). (i)Even if you're using Eclipse, it is recommended that you generate the IDEA project files so that you can run the Showcase webapp via QuickStart. QuickStart Settings for Showcase Main class: org.apache.struts2.Main VM params: none Program params: quickstart Working directory: apps/showcase Classpath: must include at least the core module (Which contains the Main class) These settings are already baked into the IDEA workspace file. Maven Tips A few helpful tips for using Maven are provided: Offline mode If you are disconnected from the Internet or simply wish to make your build faster, pass in the -o argument and Maven won't check for new modules to download. Offline Mode mvn -o -Pextras,plugins,xwork Skipping test execution Although this shouldn't ever happen, sometimes tests do fail and you need to build the framework anyway. If there's a problem, you can pass in the skip tests parameter. Skip Tests mvn -Dmaven.test.skip=true -Pextras,plugins,xwork Of course, if you find tests are failing, please submit a patch to fix them! Debugging build failures Struts 2 depends on the current snapshot artifact of XWork 2. Unfortunately, if XWork 2 is modified in a significant way, the Struts build doesn't check for and retrieve a new version of the XWork snapshot jar, resulting in compilation or unit test failures. The solution is to clear out any stale XWork 2 jars in your local Maven repository, usually by removing the directory ~/.m2/repository/opensymphony. This will force the Struts Maven build to pull down a fresh copy of XWork and hopefully resolve your problem. Creating a release Maven terms a release build an "assembly". An assembly aggregates the builds of all the modules installed locally on your machine into one or more release files. To create a release, you must first build and install locally every artifact. From the root struts2 directory, run: Building all modules mvn -Pextras,apps,plugins install Next, you need to run the assembly build to create the release files. From the struts2/assembly directory, run: Building the assembly mvn assembly:assembly If the assembly built correctly, you should see the release files in the target/assembly/out directory. Mirrors The default mirror for Maven builds ("ibiblio") can be slow and unreliable. Maven lets you specify alternative mirrors so that you don't have to depend on ibiblio for everything. You can add new mirrors through the Settings file (~/.m2/settings.xml). Mirror, Mirror <settings> <mirrors> <mirror> <id>dotsrc</id> <url>http://mirrors.dotsrc.org/maven2</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> </settings> Sometimes the alternative mirrors have problems too or aren't updated at the same frequency as the main mirror. If you have trouble building, try commenting out the aternative mirror. First time building In some cases it has been seen that Maven will complain a module doesn't exist, even though it is part of the current build. Often, the missing module complete turins up when executing {mvn package}}. A simple fix for this is to run mvn install instead. If you have to do this, it will probably only be a one-time thing.

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences