[incubator-plc4x] branch master updated: - Added some initial content to the how to build plc4x section of the website.

[cd...@apache.org]

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

cdutz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-plc4x.git


The following commit(s) were added to refs/heads/master by this push:
     new ddd71cb  - Added some initial content to the how to build plc4x section of the website.
ddd71cb is described below

commit ddd71cbaa56576f881341b6847522f93120b06dd
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Fri Dec 29 15:56:19 2017 +0100

    - Added some initial content to the how to build plc4x section of the website.
---
 src/site/asciidoc/development/building.adoc | 81 +++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/src/site/asciidoc/development/building.adoc b/src/site/asciidoc/development/building.adoc
index d1959e9..782e64e 100644
--- a/src/site/asciidoc/development/building.adoc
+++ b/src/site/asciidoc/development/building.adoc
@@ -17,5 +17,86 @@
 
 == Building PLC4X
 
+PLC4X is built with `Apache Maven` and we have tried to make the build as simple as possible.
 
+For your convenience we also have provided a `Maven-Wrapper`, that should allow building of PLC4X with only `Java 8` or greater as requirement.
 
+=== Requirements
+
+The only requirements to building PLC4X should be:
+
+* Java 8 JDK (or newer)
+* Apache Maven (3.1.0 or newer) *(Optional)*
+
+=== Using the Maven-Wrapper
+
+The so-called `Maven-Wrapper` is used by calling the Maven-Wrapper scripts `mvnw` (Mac & Linux) or `mvnw.cmd` (Windows) instead of the default Maven commads `mvn` and `mvn.cmd`.
+
+These helpers ensure Maven is available in at least the version defined in `.mvn/maven-wrapper.properties`.
+If no suitable version can be found, it is automatically downloaded and installed alongside the project (So it doesn't have to be downloaded every time and every project can have it's own Maven version)
+
+After the script has ensured a suitable Maven version is available, this is used and all arguments and parameters are transparently forwarded to this.
+So simply adding the additional `w` to each of the Maven commands, there should be no difference to using a pre-installed Maven version.
+
+=== Using Maven
+
+This document can't provide you with all the details needed to get started with `Maven` itself.
+But there is a lot of good documentation out there.
+
+Justin McLean and Christofer Dutz even recorded a not quite 2 hour Maven training Video some time ago for another Apache project.
+
+It should handle all the details needed to get a general understanding of Maven and how it works.
+
+video::167857327[vimeo]
+
+=== Building PLC4X with Maven
+
+PLC4X is built by executing the following command:
+
+    mvn package
+
+This not only builds the artifacts and creates the jar files, but also runs all unit- and integration-tests.
+
+If you want to skip the running of tests (even if this is not encouraged) you can skip them all together.
+
+    mvn package -DskipTests
+
+This will not skip the compilation of tests however.
+
+=== Building the PLC4X Website with Maven
+
+The PLC4X Website is also part of the same GIT repository that contains the code and it is built by Maven as well.
+
+In order to build the website the following command should be sufficient:
+
+    mvn site
+
+However this will generate the website for each module inside it's `target/site` directory.
+Opening this in a browser and navigating from pages of one module to another will not work as these links expect a different directory structure.
+In order to create a fully navigatable version of the Website, the following command should be sufficient:
+
+    mvn site site:stage
+
+This will generate an additional `target/staging` directory which contains the fully functional version.
+
+A lot of documentation on Maven suggests to use the `site:site` goal directly instead of calling the `site` phase, but in case of PLC4X there is more than just the site generation that has to be executed.
+
+This is just a quick-start version of the site generation, for a fully detailed documentation please read the http://plc4x.apache.org/development/website.html[Website] documentation page.
+
+=== Some special Maven profiles
+
+Maven supports so-called `profiles` for customizing the build in special cases.
+We have tried to keep the number of profiles as low as possible.
+So far there is only one profile.
+
+==== debug-pom profile
+
+Especially for Maven beginners, it might be difficult to understand why a module builds the way it does.
+Maven contains a lot of concepts to inherit and override settings.
+
+The `debug-pom` profile will generate the so-called `effective pom` in the modules `target` directory.
+
+This file contains 100% of the settings Maven uses to execute. All settings are inherited and overridden.
+All Properties are expanded to the value Maven uses.
+
+So whenever Maven doesn't behave the way you expect it to, just enable this profile and it should help you find out, what's going on.
\ No newline at end of file

-- 
To stop receiving notification emails like this one, please contact
['"commits@plc4x.apache.org" <co...@plc4x.apache.org>'].