| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| <title>PLC4X – </title> |
| <script src="../js/jquery.slim.min.js" type="text/javascript"></script> |
| <!--script src="../js/popper.min.js" type="javascript"></script--> |
| <script src="../js/bootstrap.bundle.min.js" type="text/javascript"></script> |
| <!-- The tooling for adding images and links to Apache events --> |
| <script src="https://www.apachecon.com/event-images/snippet.js" type="text/javascript"></script> |
| <!-- FontAwesome --> |
| <link rel="stylesheet" href="../css/all.min.css" type="text/css"/> |
| <!-- Bootstrap --> |
| <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css"/> |
| <!-- Some Maven Site defaults --> |
| <link rel="stylesheet" href="../css/maven-base.css" type="text/css"/> |
| <link rel="stylesheet" href="../css/maven-theme.css" type="text/css"/> |
| <!-- The PLC4X version of a bootstrap theme --> |
| <link rel="stylesheet" href="../css/themes/plc4x.css" type="text/css" id="pagestyle"/> |
| <!-- A custom style for printing content --> |
| <link rel="stylesheet" href="../css/print.css" type="text/css" media="print"/> |
| |
| <meta http-equiv="Content-Language" content="en"/> |
| |
| </head> |
| <body class="composite"> |
| <nav class="navbar navbar-light navbar-expand-md bg-faded justify-content-center border-bottom"> |
| <!--a href="/" class="navbar-brand d-flex w-50 mr-auto">Navbar 3</a--> |
| <a href="https://plc4x.apache.org/" id="bannerLeft"><img src="../images/apache_plc4x_logo_small.png" alt="Apache PLC4X"/></a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#collapsingNavbar3"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <div class="navbar-collapse collapse w-100" id="collapsingNavbar3"> |
| <ul class="navbar-nav w-100 justify-content-center"> |
| <li class="nav-item"> |
| <a class="nav-link" href="../index.html">Home</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="../users/index.html">Users</a> |
| </li> |
| <li class="nav-item active"> |
| <a class="nav-link" href="../developers/index.html">Developers</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="../apache/index.html">Apache</a> |
| </li> |
| </ul> |
| <ul class="nav navbar-nav ml-auto justify-content-end"> |
| <li class="nav-item row valign-middle"> |
| <a class="acevent" data-format="wide" data-mode="light" data-event="random" style="width:240px;height:60px;"></a> |
| </li> |
| </ul> |
| </div> |
| </nav> |
| <div class="container-fluid"> |
| <div class="row h-100"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <nav class="col-sm-push col-md-2 pt-3 sidebar"> |
| <div class="sidebar-sticky"> |
| <ul class="nav flex-column"> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/index.html" class="nav-link">Section Home</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/preparing/index.html" class="nav-link">Preparing your Computer</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/preparing/linux.html" class="nav-link">Linux</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/preparing/macos.html" class="nav-link">Mac OS</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/preparing/windows.html" class="nav-link">Windows</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <strong class="nav-link">Building</strong> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/contributing.html" class="nav-link">Contributing</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/tutorials/index.html" class="nav-link">Tutorials</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/tutorials/writing-driver.html" class="nav-link">Writing Drivers</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/tutorials/testing-serializers-and-parsers.html" class="nav-link">Testing Drivers</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/code-gen/index.html" class="nav-link">Code Generation</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/code-gen/protocol/mspec.html" class="nav-link">Protocol: MSpec Format</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/code-gen/language/freemarker.html" class="nav-link">Language: Apache Freemarker</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/code-gen/protocol/df1.html" class="nav-link">Example: DF1 MSpec</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/index.html" class="nav-link">Infrastructure</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/ci.html" class="nav-link">Continuous Integration</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/sonar.html" class="nav-link">Code Analysis</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/wiki.html" class="nav-link">Wiki</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/vm.html" class="nav-link">Build VM</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/website.html" class="nav-link">Website</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/vpn.html" class="nav-link">IoT VPN</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/release/index.html" class="nav-link">Releasing</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/release/release.html" class="nav-link">Releasing</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/release/validation.html" class="nav-link">Validating</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/release/build-tools.html" class="nav-link">Releasing Build-Tools</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/tools.html" class="nav-link">Tools</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/team.html" class="nav-link">Team</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/decisions.html" class="nav-link">Decision Making</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/maturity.html" class="nav-link">Maturity</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| </div> |
| </nav> |
| <main role="main" class="ml-sm-auto px-4 col-sm-pull col-md-9 col-lg-10 h-100"> |
| <div class="sect1"> |
| <h2 id="building_plc4x">Building PLC4X</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>PLC4X is built with <code>Apache Maven</code> and we have tried to make the build as simple as possible.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>We have partitioned the build to allow selecting the parts that are of interest. |
| This is done by selecting so-called <code>Maven profiles</code>. |
| More about these later down in this manual.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For your convenience we also have provided a <code>Maven-Wrapper</code>, that should allow building of PLC4X with only <code>Java 11</code> or greater as requirement.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="requirements">Requirements</h3> |
| <div class="paragraph"> |
| <p>The only requirements to building PLC4X should be:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Java 11 JDK (or newer)</p> |
| </li> |
| <li> |
| <p>Git (Even if you are building the source distribution, the Kafka plugin seems to require a <code>git</code> executable being available on the systems <code>PATH</code>)</p> |
| </li> |
| <li> |
| <p>Apache Maven (3.6.0 or newer) <strong>(Optional)</strong> (See next chapter)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="using_the_maven_wrapper">Using the Maven-Wrapper</h3> |
| <div class="paragraph"> |
| <p>The so-called <code>Maven-Wrapper</code> is used by calling the Maven-Wrapper scripts <code>mvnw</code> (Mac & Linux) or <code>mvnw.cmd</code> (Windows) instead of the default Maven commands <code>mvn</code> and <code>mvn.cmd</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These helpers ensure Maven is available in at least the version defined in <code>.mvn/maven-wrapper.properties</code>. |
| 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)</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 <code>w</code> to each of the Maven commands, there should be no difference to using a pre-installed Maven version.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="using_maven">Using Maven</h3> |
| <div class="paragraph"> |
| <p>This document can’t provide you with all the details needed to get started with <code>Maven</code> itself. |
| But there is a lot of good documentation out there.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Justin McLean and Christofer Dutz even recorded a not quite 2 hour Maven training Video some time ago for another Apache project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It should handle all the details needed to get a general understanding of Maven and how it works.</p> |
| </div> |
| <div class="videoblock"> |
| <div class="title">Recording of a Maven Training for Apache Flex from 2016</div> |
| <div class="content"> |
| <iframe width="640" height="420" src="https://player.vimeo.com/video/167857327" frameborder="0" allowfullscreen="allowfullscreen"></iframe> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="building_plc4x_with_maven">Building PLC4X with Maven</h3> |
| <div class="paragraph"> |
| <p>In general all modules which are not considered production-ready are located in the <code>sandbox</code> section of the project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>They are not built per default and are enabled by enabling the <code>with-sandbox</code> Maven profile.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As especially building the C++, and C# drivers requires building of some third party artifacts and increases build-time dramatically and requires setting up some additional third party tools, we have excluded these parts form the default Maven build.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following profiles are available (<strong>They have to be enabled additionally to the <code>with-sandbox</code> profile</strong>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>with-sandbox</code>: Builds the modules which are not yet considered stable enough to become part of the main distribution</p> |
| </li> |
| <li> |
| <p><code>with-cpp</code>: Builds all C++ related modules, integrations and examples</p> |
| </li> |
| <li> |
| <p><code>with-dotnet</code>: Builds all C# and .Net related modules, integrations and examples</p> |
| </li> |
| <li> |
| <p><code>with-python</code>: Builds all Python related modules, integrations and examples</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| As these profiles typically require some preparation and setup on your development machine, please read the <a href="preparing/index.html">Preparing your Computer</a> guide for a detailed description on this. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Beyond that there is an additional profile <code>with-proxies</code> which will enable additional modules in each of the activated languages. |
| This <code>proxies</code> module, uses <code>Apache Thrift</code> to generate modules for forwarding requests to an <code>interop server</code> which runs somewhere else or on the same machine.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| Currently when enabling the <code>with-python</code> module, you are required to also enable the <code>with-proxies</code> profile too as this is currently required there but will probably change in the near future. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>There are 3 more profiles that allow you to activate additional modules or functionality:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>with-docker</code> : Some modules also provide the means to build <code>Docker</code> images. By enabling this profile these images are automatically built too</p> |
| </li> |
| <li> |
| <p><code>with-boost</code> : Builds a <code>C</code>/<code>C` Library used by both the `Apache Thrift` build as well as the `C</code> drivers. Unfortunately this is an extremely intense build so we have setup the PLC4X build to only require this profile to be activated once. If the resulting artifacts are installed in your <code>Maven-Local-Repo</code>, these will be re-used.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The minimum Apache PLC4X build will build only the <code>Java</code> modules without any experimental modules:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn install</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to skip the running of tests (even if this is not encouraged) you can skip them all together.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn install -DskipTests</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>All Apache PLC4X modules are built by executing the following command:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn -P with-boost,with-cpp,with-docker,with-dotnet,with-sandbox,with-logstash,with-proxies,with-python,with-sandbox install</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This not only builds the artifacts and creates the jar files, but also runs all unit- and integration-tests.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to skip the running of tests (even if this is not encouraged) you can skip them all together.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn -P with-boost,with-cpp,with-docker,with-dotnet,with-sandbox,with-logstash,with-proxies,with-python,with-sandbox install -DskipTests</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will not skip the compilation of tests however.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="building_the_plc4x_website_with_maven">Building the PLC4X Website with Maven</h3> |
| <div class="paragraph"> |
| <p>The PLC4X Website is also part of the same GIT repository that contains the code and it is built by Maven as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to build the website the following command should be sufficient:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn site</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This is just a quick-start version of the site generation, for a fully detailed documentation please read the <a href="https://plc4x.apache.org/developers/infrastructure/website.html">Website</a> documentation page.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="some_special_maven_profiles">Some special Maven profiles</h3> |
| <div class="paragraph"> |
| <p>Maven supports so-called <code>profiles</code> 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.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="apache_release_profile"><code>apache-release</code> profile</h4> |
| <div class="paragraph"> |
| <p>This profile is automatically enabled on a release-build and it automatically creates some additional artifacts:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>JavaDoc artifact</p> |
| </li> |
| <li> |
| <p>Sources artifact</p> |
| </li> |
| <li> |
| <p>Source distribution assembly</p> |
| </li> |
| <li> |
| <p>SHA512 checksum files for every artifact</p> |
| </li> |
| <li> |
| <p>PGP signature files for every artifact</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Generally it is not required to enable ths profile unless you are interested in these Artifacts.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="debug_pom_profile"><code>debug-pom</code> profile</h4> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>debug-pom</code> profile will generate the so-called <code>effective pom</code> in the modules <code>target</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="development_profile"><code>development</code> profile</h4> |
| <div class="paragraph"> |
| <p>This profile enables some extra strict enforcer rules. It is encouraged to activate this profile during development.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <code>CI Build</code> this profile is enabled.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="skip_prerequisite_check_profile"><code>skip-prerequisite-check</code> profile</h4> |
| <div class="paragraph"> |
| <p>Some times, actually only on the build-server we have encountered random failures of the <code>prerequisite check</code> build step.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to still be able to build in this case, activating this profile simply disables these checks.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="use_the_compiled_library_with_gradle">Use the compiled library with Gradle</h3> |
| <div class="paragraph"> |
| <p>Compiling the library as explained here add the new version in the local Maven repository (i.e. usually under <code>~/.m2/repository</code> on linux like systems), if you would like to use Gradle as Build Tool for your project you have just to use a local repository in your Gradle <code>build.gradle</code> file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here there’s an example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code data-lang="groovy">repositories { |
| mavenCentral() |
| mavenLocal() |
| } |
| |
| dependencies { |
| implementation group: 'org.apache.plc4x', name: 'plc4j-api', version: '0.8.0-SNAPSHOT' |
| implementation group: 'org.apache.plc4x', name: 'plc4j-driver-s7', version: '0.8.0-SNAPSHOT' |
| implementation group: 'org.apache.plc4x', name: 'plc4j-connection-pool', version: '0.8.0-SNAPSHOT' |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </main> |
| <footer class="pt-4 my-md-5 pt-md-5 w-100 border-top"> |
| <div class="row justify-content-md-center" style="font-size: 13px"> |
| <div class="col col-6 text-center"> |
| Copyright © 2017–2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.<br/> |
| Apache PLC4X, PLC4X, Apache, the Apache feather logo, and the Apache PLC4X project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries. All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| <br/><div style="text-align:center;">Home screen image taken from <a |
| href="https://flic.kr/p/chEftd">Flickr</a>, "Tesla Robot Dance" by Steve Jurvetson, licensed |
| under <a href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0 Generic</a>, image cropped |
| and blur effect added.</div> |
| </div> |
| </div> |
| </footer> |
| </div> |
| </div> |
| |
| <!-- Bootstrap core JavaScript |
| ================================================== --> |
| <!-- Placed at the end of the document so the pages load faster --> |
| <script src="../js/jquery.slim.min.js"></script> |
| <script src="../js/popper.min.js"></script> |
| <script src="../js/bootstrap.min.js"></script> |
| <script type="text/javascript"> |
| $('.carousel .carousel-item').each(function(){ |
| var next = $(this).next(); |
| if (!next.length) { |
| next = $(this).siblings(':first'); |
| } |
| next.children(':first-child').clone().appendTo($(this)); |
| |
| for (let i = 0; i < 3; i++) { |
| next=next.next(); |
| if (!next.length) { |
| next = $(this).siblings(':first'); |
| } |
| next.children(':first-child').clone().appendTo($(this)); |
| } |
| }); |
| </script> |
| </body> |
| </html> |
