| Apache PLC4X |
| ============ |
| |
| Apache PLC4X is an effort to create a set of libraries for communicating with industrial grade programmable logic controllers (PLCs) in a uniform way. |
| We are planning on shipping libraries for usage in: |
| |
| 1) Java |
| 2) Scala |
| 3) C/C++ |
| 4) C# (.Net) |
| 5) Python |
| |
| As well as provide direct integration into other Apache projects, such as: |
| |
| 1) Apache Calcite |
| 2) Apache Camel |
| 3) Apache Edgent |
| 4) Apache Kafka-Connect |
| 5) Apache Karaf |
| 6) Apache NiFi |
| |
| Environment |
| ----------- |
| |
| Currently the project is configured to require the following software: |
| |
| 1) Java 8 JDK: For running Maven in general as well as compiling the Java and Scala modules `JAVA_HOME configured to point to that. |
| 2) libpcap/WinPcap for raw socket tests in Java |
| 3) (Optional) Graphwiz: For generating the graphs in the documentation (http://www.graphviz.org/) |
| 4) Git (even when working on the source distribution) |
| |
| With this setup you will be able to build the Java part of PLC4X excluding the "proxy" drivers and servers. |
| For a full build of PLC4X with all options the following has to be provided: |
| |
| Linux |
| ----- |
| |
| On a clean Ubuntu 18.04 the following software needs to be installed: |
| |
| sudo apt |
| |
| If you're building a source-distribution and haven't installed git yet, be sure to do so: |
| |
| sudo get install git |
| |
| In order to build the .Net version, please install the .Net package according to this guide: |
| |
| https://dev.to/carlos487/installing-dotnet-core-in-ubuntu-1804-7lp |
| |
| Mac |
| --- |
| |
| Make sure `Homebrew` ist installed in order to update `Bison` to a newer version (the version 2.3 installed per default is too old) |
| |
| /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
| |
| Then update `Bison`: |
| |
| brew install bison |
| brew link bison --force |
| echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.bash_profile |
| |
| Install `Python 2.7`: |
| |
| brew install python@2 |
| |
| Be sure to re-open the command window or the changes will not apply. |
| |
| If you're going to build the `with-dotnet` profile you also need to install DotNet. |
| Please download it from: https://dotnet.microsoft.com/download and run the installer. |
| |
| Windows |
| ------- |
| |
| Some tools need to be installed before being able to build on Windows: |
| |
| - WinBuilds (for `with-cpp`, `with-proxies` profiles) |
| - Bison (for `with-cpp` profiles) |
| - Flex (for `with-cpp` profiles) |
| - Python 2.7 (for `with-python`, `with-proxies` profiles) |
| - Dotnet (for `with-dotnet` profiles) |
| |
| He have tested WinBuilds with the bundle of: http://win-builds.org/doku.php/download_and_installation_from_windows |
| When running the installer, make sure to select the options: |
| - Native Windows |
| - x86_64 |
| Not quite sure which elements are really needed, better just install all of them. |
| |
| WARNING: If you don't use the installer version of the distribution. The build will probably fail and it will be pretty |
| impossible to see the problem. When manually executing the command, a popup will appear complaining about not being able |
| to find some DLL. So if you are having these problems, please try using the installer instead of the manually unpackable |
| archive. |
| |
| For Bison, please download the Setup installer version from here: http://gnuwin32.sourceforge.net/packages/bison.htm (When using the zip version the bison.exe couldn't find some DLL files) |
| It seems the official 2.4.1 version has issues when installed in a directory which's path contains spaces. Please make sure you replace the exe with a patched version form here: http://marin.jb.free.fr/bison/bison-2.4.1-modified.zip |
| (More infos on this issue here: https://sourceforge.net/p/gnuwin32/bugs/473/) |
| |
| Please download the Flex compiler from here: http://gnuwin32.sourceforge.net/packages/flex.htm (Ideally download the binary zip distribution) |
| |
| You can get Python from here: https://www.python.org/downloads/release/python-2716/ |
| |
| Make sure the `bin` directories of containing the executables `mingw32-make.exe`, `bison.exe` and `flex.exe` are all on your systems `PATH`. |
| |
| If you're building a source-distribution and haven't installed git yet, be sure to do so. |
| |
| |
| Getting Started |
| --------------- |
| |
| You must have Java 8 installed on your system and connectivity to Maven Central |
| (for downloading external third party dependencies). Maven will be automatically |
| downloaded and installed by the maven wrapper `mvnw`. |
| |
| Build PLC4X Java jars and install them in your local maven repository |
| |
| $ ./mvnw install -P with-java # add -DskipTests to omit running the tests |
| |
| You can now construct Java applications that use PLC4X. The PLC4X samples |
| are a good place to start and are available inside the `examples` |
| directory. |
| |
| If you want to also build the C++ libraries, this has to be enabled by activating |
| |
| the `with-cpp` profile |
| |
| $ ./mvnw -P with-cpp install # add -DskipTests to omit running the tests |
| |
| Same applies for the C# .Net implementation with `with-dotnet` profiles. |
| |
| The Python implementation is currently in a somewhat unclean state and still needs refactoring. |
| In order to be able to build the Python module, you currently need to activate both the: |
| `with-python` and `with-proxies` profiles. |
| |
| However both of these are in a pretty experimental state. |
| |
| In order to build everything the following command should work: |
| |
| & ./mvnw -P with-java,with-cpp,with-dotnet,with-python,with-proxies,with-sandbox install |
| |
| Installing libpcap/WinPcap |
| -------------------------- |
| |
| Some parts of PLC4X, especially the raw socket support, require installed versions |
| of libpcap/WinPcap. |
| |
| You can download the Mac/Linux version from: http://www.tcpdump.org/ |
| The windows version can be found here: https://sourceforge.net/projects/winpcap413-176/ |
| (In order to read PCAPNG files we require a libpcap version 1.1.0 or greater. The default |
| Windows version is 1.0. At this location is a patched version based on libpcap 1.7.4) |
| |
| Same applies for Python with the `with-python` and the C# .Net imeplemtation with `with-dotnet` profiles. |
| However both of these are in a pretty experimental state. |
| |
| |
| Building the C++ libraries |
| -------------------------- |
| |
| When building the C++ libraries we require an installed `gcc` compiler. |
| On Mac and Linux this is usually the case. |
| On a minimal Ubuntu Linux system the following modules needed to be installed |
| manually: |
| |
| - gcc |
| - g++ |
| - make |
| |
| On Windows the required compiler is generally not available per default. |
| The build is optimized for using a gcc-port called MinGW, available from |
| http://win-builds.org/doku.php/download_and_installation_from_windows |
| Make sure the `bin` directory containing the executable `mingw32-make.exe` |
| is on your systems `PATH`. |
| |
| |
| Licensing |
| --------- |
| |
| Apache PLC4X is released under the Apache License Version 2.0. |