src/site/asciidoc/developers/building.adoc - plc4x - Git at Google

 //
 //  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.
 //

 == Building PLC4X

 PLC4X is built with `Apache Maven` and we have tried to make the build as simple as possible.

 However PLC4X aims at providing means to communicate with PLCs of multiple vendors using a shared API but also in a variety of different languages.

 We have partitioned the build to allow selecting the parts that are of interest.
 This is done by selecting so-called `Maven profiles`.
 More about these later down in this manual.

 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 - latest tested version: Java 12)
 * Git (Even if you are building the source distribution, the Kafka plugin seems to require a `git` executable being available on the systems `PATH`)
 * Apache Maven (3.1.0 or newer) *(Optional)* (See next chapter)

 === 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 commands `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.

 .Recording of a Maven Training for Apache Flex from 2016
 video::167857327[vimeo,width=640,height=420]

 === Building PLC4X with Maven

 In order to build only the parts you are interested in, we have partitioned the build into multiple parts.
 By enabling these, you add more modules to the build.

 By not enabling any profile, only the `protocols` and part of the `tools` will be built, which is pretty useless.

 The following profiles are available:

 - `with-java`: Builds all Java related modules, integrations and examples
 - `with-cpp`: Builds all C++ related modules, integrations and examples
 - `with-dotnet`: Builds all C# and .Net related modules, integrations and examples
 - `with-python`: Builds all Python related modules, integrations and examples

 WARNING: All profiles except the `with-java` typically require some preparation and setup on your development machine, please read the link:preparing.html[Preparing your Computer] guide for a detailed description on this.

 Beyond that there is an additional profile `with-proxies` which will enable additional modules in each of the activated languages.
 This `proxies` module, uses Apache Thrift to generate modules for forwarding requests to an `interop server` which runs somewhere else or on the same machine.

 WARNING: Currently when enabling the `with-python` module, you are required to also enable the `with-proxies` profile too as this is currently required there but will probably change in the near future.

 PLC4X is built by executing the following command (Example for building all modules):

     mvn -P with-java,with-cpp,with-dotnet,with-python,with-proxies,with-sandbox 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 -P with-java,with-cpp,with-dotnet,with-python,with-proxies,with-sandbox 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/developers/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.
	//
	// 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.
	//

	== Building PLC4X

	PLC4X is built with `Apache Maven` and we have tried to make the build as simple as possible.

	However PLC4X aims at providing means to communicate with PLCs of multiple vendors using a shared API but also in a variety of different languages.

	We have partitioned the build to allow selecting the parts that are of interest.
	This is done by selecting so-called `Maven profiles`.
	More about these later down in this manual.

	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 - latest tested version: Java 12)
	* Git (Even if you are building the source distribution, the Kafka plugin seems to require a `git` executable being available on the systems `PATH`)
	* Apache Maven (3.1.0 or newer) (Optional) (See next chapter)

	=== 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 commands `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.

	.Recording of a Maven Training for Apache Flex from 2016
	video::167857327[vimeo,width=640,height=420]

	=== Building PLC4X with Maven

	In order to build only the parts you are interested in, we have partitioned the build into multiple parts.
	By enabling these, you add more modules to the build.

	By not enabling any profile, only the `protocols` and part of the `tools` will be built, which is pretty useless.

	The following profiles are available:

	- `with-java`: Builds all Java related modules, integrations and examples
	- `with-cpp`: Builds all C++ related modules, integrations and examples
	- `with-dotnet`: Builds all C# and .Net related modules, integrations and examples
	- `with-python`: Builds all Python related modules, integrations and examples

	WARNING: All profiles except the `with-java` typically require some preparation and setup on your development machine, please read the link:preparing.html[Preparing your Computer] guide for a detailed description on this.

	Beyond that there is an additional profile `with-proxies` which will enable additional modules in each of the activated languages.
	This `proxies` module, uses Apache Thrift to generate modules for forwarding requests to an `interop server` which runs somewhere else or on the same machine.

	WARNING: Currently when enabling the `with-python` module, you are required to also enable the `with-proxies` profile too as this is currently required there but will probably change in the near future.

	PLC4X is built by executing the following command (Example for building all modules):

	mvn -P with-java,with-cpp,with-dotnet,with-python,with-proxies,with-sandbox 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 -P with-java,with-cpp,with-dotnet,with-python,with-proxies,with-sandbox 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/developers/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.