[struts-site] 03/09: Adds how to build

[lu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lukaszlenart pushed a commit to branch contributors-guide
in repository https://gitbox.apache.org/repos/asf/struts-site.git

commit 44312b5d5c9f925d8e19a85e3b4913717868dddb
Author: Lukasz Lenart <lu...@apache.org>
AuthorDate: Tue Jul 7 11:35:59 2020 +0200

    Adds how to build
---
 .../building-the-framework-from-source.md          |  70 +++++++
 source/contributors/building-with-maven.md         | 206 +++++++++++++++++++++
 2 files changed, 276 insertions(+)

diff --git a/source/contributors/building-the-framework-from-source.md b/source/contributors/building-the-framework-from-source.md
new file mode 100644
index 0000000..0f1fe95
--- /dev/null
+++ b/source/contributors/building-the-framework-from-source.md
@@ -0,0 +1,70 @@
+---
+layout: default
+title: Building the Framework from Source
+parent:
+    title: Contributors Guide
+    url: index.html
+---
+
+# Building the Framework from Source
+{:.no_toc}
+
+* Will be replaced with the ToC, excluding a header
+{:toc}
+
+## Why Build?
+
+Most developers will never need to build the framework from source. The distribution package contains everything 
+a developer needs to get started and become productive with the framework. For more on how to go to work with 
+the distributed binaries right away, see _Ready, Set, Go\!_ . However, there are situations when someone will want 
+to build the framework from scratch. You may want to try out new tweaks and patches, or you might want to try writing 
+your own tweak or patch.
+
+> If you just want to use the latest development build, perhaps because a patch you need has been applied, you can 
+> also [download a nightly build](http://ci.apache.org/projects/struts/nightlies/).
+
+## Getting the Sources
+
+The source code for the framework is available as a distribution you can download directly and from the source code repository.
+
+## Distribution
+
+The distributions of the framework contain all sources, as well as all needed libraries for building JARs and running. 
+Distributions can be downloaded from the [Apache Struts project](../../downloads)
+
+## Repository (Git)
+
+Use [Git](https://git-scm.com/) to checkout the source code.
+
+```
+> cd Projects\Apache\
+> git clone https://gitbox.apache.org/repos/asf/struts.git 
+```
+
+## Building with Maven
+
+The default build environment is Maven. You can either install Maven 3 or use Maven Wrapper delivered with the source code.
+Change to your framework home directory: 
+
+```
+cd Projects\Apache\struts
+```
+
+and run Maven
+
+```
+mvn clean install
+```
+
+or run using Maven Wrapper
+
+```
+./mvnw clean install
+```
+
+That will take care of the basic maven build. There is a bunch more that you can do. Checkout out [Building with Maven](building-with-maven) 
+for more information.
+
+## JDK/JRE Compatibility
+
+The framework requires JDK 1.8 to build.
diff --git a/source/contributors/building-with-maven.md b/source/contributors/building-with-maven.md
new file mode 100644
index 0000000..4c76bc4
--- /dev/null
+++ b/source/contributors/building-with-maven.md
@@ -0,0 +1,206 @@
+---
+layout: default
+title: Building with Maven
+parent:
+  title: Contributors Guide
+  url: index.html
+---
+
+# Building with Maven
+{:.no_toc}
+
+* Will be replaced with the ToC, excluding a header
+{:toc}
+
+[Maven 3.0.0 or later](http://maven.apache.org) is required to build Struts 2
+
+First, let's review some Maven basics. Maven uses the notion of a build _life-cycle_ to which plugins can attach. 
+Plugins are similar to Ant tasks. When a Maven build is invoked, we specify a point in the life-cycle up to which 
+the build _should_ proceed. The _compile_ phase 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
+
+```
+mvn
+```
+
+That's it! Maven will download any dependencies the build needs; run all unit tests; package up the JARs; then install th
+e 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
+```
+
+> Sometimes, licensing restrictions prevent Maven from 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 available to all your Maven builds, not just Struts.
+
+**Initial Build Successful**
+
+```
+[INFO] Reactor Summary:
+[INFO]
+[INFO] Struts 2 .......................................... SUCCESS [6.016s]
+[INFO] XWork: Core ....................................... SUCCESS [1:08.086s]
+[INFO] Struts 2 Core ..................................... SUCCESS [2:42.604s]
+[INFO] Struts Plugins .................................... SUCCESS [0.944s]
+[INFO] Struts 2 Spring Plugin ............................ SUCCESS [13.523s]
+[INFO] Struts 2 Convention Plugin ........................ SUCCESS [16.473s]
+[INFO] Struts 2 JUnit Plugin ............................. SUCCESS [13.325s]
+[INFO] Webapps ........................................... SUCCESS [1.027s]
+[INFO] Blank Webapp ...................................... SUCCESS [9.572s]
+[INFO] JBoss Blank Webapp ................................ SUCCESS [7.814s]
+[INFO] Mail Reader Webapp ................................ SUCCESS [7.028s]
+[INFO] Struts 2 Portlet Plugin ........................... SUCCESS [20.995s]
+[INFO] Struts 2 DWR Plugin ............................... SUCCESS [4.432s]
+[INFO] Struts 2 Tiles Plugin ............................. SUCCESS [4.451s]
+[INFO] Struts 2 Portlet Tiles Plugin ..................... SUCCESS [3.741s]
+[INFO] Portlet Webapp .................................... SUCCESS [28.480s]
+[INFO] Struts 2 Struts 1 Plugin .......................... SUCCESS [8.353s]
+[INFO] Struts 2 Dojo Plugin .............................. SUCCESS [30.181s]
+[INFO] Struts 2 JSF Plugin ............................... SUCCESS [6.000s]
+[INFO] Struts 2 Configuration Browser Plugin ............. SUCCESS [7.531s]
+[INFO] Struts 2 Sitemesh Plugin .......................... SUCCESS [6.159s]
+[INFO] Struts 2 JSON Plugin .............................. SUCCESS [16.944s]
+[INFO] Showcase Webapp ................................... SUCCESS [20.303s]
+[INFO] Struts 2 REST Plugin .............................. SUCCESS [10.015s]
+[INFO] Struts 2 Rest Showcase Example .................... SUCCESS [6.928s]
+[INFO] Struts 2 Codebehind Plugin ........................ SUCCESS [10.394s]
+[INFO] Struts 2 Java Templates Plugin .................... SUCCESS [9.633s]
+[INFO] Struts 2 Jasper Reports Plugin .................... SUCCESS [5.920s]
+[INFO] Struts 2 JFreeChart Plugin ........................ SUCCESS [18.296s]
+[INFO] Struts 2 Pell Multipart Plugin .................... SUCCESS [3.891s]
+[INFO] Struts 2 Plexus Plugin ............................ SUCCESS [4.715s]
+[INFO] Struts 2 Sitegraph Plugin ......................... SUCCESS [8.009s]
+[INFO] Struts 2 TestNG Plugin ............................ SUCCESS [6.012s]
+[INFO] Struts 2 OVal Plugin .............................. SUCCESS [9.629s]
+[INFO] Struts 2 OSGi Plugin .............................. SUCCESS [8.118s]
+[INFO] Struts 2 Embedded JSP Plugin ...................... SUCCESS [30.524s]
+[INFO] Struts 2 GXP Plugin ............................... SUCCESS [4.878s]
+[INFO] Struts 2 CDI Plugin ............................... SUCCESS [7.620s]
+[INFO] Struts 2 Tiles 3 Plugin ........................... SUCCESS [5.132s]
+[INFO] Struts OSGi Bundles ............................... SUCCESS [0.254s]
+[INFO] Struts 2 OSGi Admin Bundle ........................ SUCCESS [5.204s]
+[INFO] Struts 2 OSGi Demo Bundle ......................... SUCCESS [4.582s]
+[INFO] Struts 2 Maven Archetypes ......................... SUCCESS [0.198s]
+[INFO] Struts 2 Archetypes - Angular JS .................. SUCCESS [10.509s]
+[INFO] Struts 2 Archetypes - Blank ....................... SUCCESS [1.440s]
+[INFO] Struts 2 Archetypes - Blank Convention ............ SUCCESS [1.324s]
+[INFO] Struts 2 Archetypes - Database Portlet ............ SUCCESS [0.990s]
+[INFO] Struts 2 Archetypes - Plugin ...................... SUCCESS [0.923s]
+[INFO] Struts 2 Archetypes - Portlet ..................... SUCCESS [0.888s]
+[INFO] Struts 2 Archetypes - Starter ..................... SUCCESS [1.992s]
+[INFO] Struts 2 Assembly ................................. SUCCESS [1:37.556s]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 12:23.728s
+[INFO] Finished at: Wed Oct 30 17:26:27 CET 2013
+[INFO] Final Memory: 57M/945M
+[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 only execute 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.
+
+## Maven Tips
+
+A few helpful tips for using Maven are provided:
+
+### Skip exporting pages from Confluence
+
+The whole Struts2 documentation resists on Confluence and during normal build process is exported with SiteExporter tool 
+locally to html files. To perform that, you must have an account on Confluence. In most cases you don't need to export 
+the whole Confluence, so you can skip this, just type command:
+
+```
+mvn clean install -DskipWiki
+```
+
+### Skip creating assemblies
+
+During normal development cycle you don't need to create assembly packages which consist of all the libraries, 
+example apps and docs - you can skip them as well:
+
+```
+mvn clean install -DskipAssembly
+```
+
+### 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.
+
+```
+mvn -o
+```
+
+### OutOfMemoryError
+
+If you get an OutOfMemoryError while running the tests:
+
+```
+// Bash
+export MAVEN_OPTS=-Xmx512m
+
+// Windows
+set MAVEN_OPTS=-Xmx512m
+```
+
+### 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.
+
+```
+mvn -Dmaven.test.skip=true
+```
+
+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
+```
+
+This will force the Struts Maven build to pull down a fresh copy of XWork and hopefully resolve your problem.
+
+## First time building
+
+In some cases it has been seen that Maven will complain if a module doesn't exist, even though it is part of the current 
+build. Often, the missing module turns 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.