You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2022/07/21 08:37:03 UTC
[plc4x] branch develop updated: chore(docs): Made sure the README is in good shape. Removed all references to no longer existing profiles.
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
The following commit(s) were added to refs/heads/develop by this push:
new ed39a0453 chore(docs): Made sure the README is in good shape. Removed all references to no longer existing profiles.
ed39a0453 is described below
commit ed39a0453d7fa0afed562a91f400400b95e6988a
Author: christoferdutz <ch...@c-ware.de>
AuthorDate: Thu Jul 21 09:54:29 2022 +0200
chore(docs): Made sure the README is in good shape. Removed all references to no longer existing profiles.
---
Jenkinsfile | 4 -
README.md | 151 ++++++----------------
build-reproducible.sh | 2 +-
src/main/script/prerequisiteCheck.groovy | 9 --
src/site/asciidoc/developers/building.adoc | 13 +-
src/site/asciidoc/developers/preparing/index.adoc | 23 +---
6 files changed, 51 insertions(+), 151 deletions(-)
diff --git a/Jenkinsfile b/Jenkinsfile
index b30e04e7e..1a8487d9e 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -92,8 +92,6 @@ pipeline {
}
steps {
echo 'Building'
- //sh './mvnw -B -P${JENKINS_PROFILE},skip-prerequisite-check,with-sandbox,with-c,with-cpp,with-boost,with-dotnet,with-python,with-proxies ${MVN_TEST_FAIL_IGNORE} ${MVN_LOCAL_REPO_OPT} clean install'
- //sh './mvnw -B -P${JENKINS_PROFILE},skip-prerequisite-check,with-sandbox,with-go ${MVN_TEST_FAIL_IGNORE} ${MVN_LOCAL_REPO_OPT} clean install'
sh './mvnw -B -P${JENKINS_PROFILE},skip-prerequisite-check,with-sandbox,with-c,with-go ${MVN_TEST_FAIL_IGNORE} ${MVN_LOCAL_REPO_OPT} clean install'
}
post {
@@ -117,8 +115,6 @@ pipeline {
// We'll deploy to a relative directory so we can save
// that and deploy in a later step on a different node
- //sh './mvnw -U -P${JENKINS_PROFILE},skip-prerequisite-check,development,with-sandbox,with-c,with-cpp,with-boost,with-dotnet,with-python,with-proxies ${MVN_TEST_FAIL_IGNORE} ${JQASSISTANT_NEO4J_VERSION} -DaltDeploymentRepository=snapshot-repo::default::file:./local-snapshots-dir clean deploy'
- //sh './mvnw -U -P${JENKINS_PROFILE},skip-prerequisite-check,development,with-sandbox,with-go ${MVN_TEST_FAIL_IGNORE} ${JQASSISTANT_NEO4J_VERSION} -DaltDeploymentRepository=snapshot-repo::default::file:./local-snapshots-dir clean deploy'
sh './mvnw -U -P${JENKINS_PROFILE},skip-prerequisite-check,with-sandbox,with-c,with-go ${MVN_TEST_FAIL_IGNORE} ${JQASSISTANT_NEO4J_VERSION} -DaltDeploymentRepository=snapshot-repo::default::file:./local-snapshots-dir clean deploy'
// Stash the build results so we can deploy them on another node
diff --git a/README.md b/README.md
index ec549340f..39d5fe37b 100644
--- a/README.md
+++ b/README.md
@@ -61,11 +61,22 @@ PLC4X also integrates with other Apache projects, such as:
* [Apache Calcite](https://calcite.apache.org/)
* [Apache Camel](https://camel.apache.org/)
-* [Apache Edgent](https://edgent.apache.org/)
* [Apache Kafka-Connect](https://kafka.apache.org)
* [Apache Karaf](https://karaf.apache.org/)
* [Apache NiFi](https://nifi.apache.org/)
+And brings stand-alone (Java) utils like:
+
+* OPC-UA Server: Enables you to communicate with legacy devices using PLC4X with OPC-UA.
+* PLC4X Server: Enables you to communicate with a central PLC4X Server which then communicates with devices via PLC4X.
+
+It also provides (Java) tools for usage inside an application:
+
+* Connection Cache: New implementation of our framework for re-using and sharing PLC-connections
+* Connection Pool: Old implementation of our framework for re-using and sharing PLC-connections
+* OPM: Object-Plc-Mapping: Allows binding PLC fields to properties in java POJOs similar to JPA
+* Scraper: Utility to do scheduled and repeated data collection.
+
## Getting started
Depending on the programming language, the usage will differ, therefore please go to the
@@ -86,113 +97,36 @@ See the PLC4J user guide on the website to start using PLC4X in your Java applic
Currently, the project is configured to require the following software:
1. Java 11 JDK: For running Maven in general as well as compiling the Java and Scala modules `JAVA_HOME` configured to point to that.
-2. libpcap/Npcap for raw socket tests in Java or use of `passive-mode` drivers
-3. (Optional) [Graphviz](https://www.graphviz.org/) : For generating the graphs in the documentation
-4. Git (even when working on the source distribution)
-
-With this setup you will be able to build the Java part of PLC4X.
-
-The build however does automatically run a prerequisite check and fail the build with an explanation, if not all requirements are meet.
-
-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 install python-setuptools gcc g++ make libpcap-dev
-```
-
-If you're building a source-distribution and haven't installed git yet, be sure to do so:
-
-```
- sudo apt 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` is 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`:
+2. Git (even when working on the source distribution)
+3. (Optional, for running all tests) libpcap/Npcap for raw socket tests in Java or use of `passive-mode` drivers
+4. (Optional, for building the website) [Graphviz](https://www.graphviz.org/) : For generating the graphs in the documentation
-```
- brew install python@2
-```
-
-Be sure to re-open the command window or the changes will not apply.
+WARNING: The code generation uses a utility which requires some additional VM settings. When running a build from the root, the settings in the `.mvn/jvm.config` are automatically applied. When building only a sub-module, it is important to set the vm args: `--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools [...]
-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.
+A more detailed description is available on our website:
-LibPCAP is also installed via Homebrew:
-
-```
- brew install libpcap
-```
+https://plc4x.apache.org/developers/preparing/index.html
-#### Windows
+#### For building `PLC4C` we also need:
-Some tools need to be installed before being able to build on Windows:
+All requirements are retrieved by the build itself
-* 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)
-* Npcap
-* OpenSSL
+#### For building `PLC4Go` we also need:
-We have tested `WinBuilds` with the bundle of: http://win-builds.org/doku.php/download_and_installation_from_windows
-Run the installer as "Administrator" or you won't be able to install it to every location.
-Please install it to a location, for which the path doesn't contain any whitespaces.
-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.
-If the installer fails to do something complaining about having to use a different mirror, enter "http://win-builds.org/1.5.0" as mirror address.
+All requirements are retrieved by the build itself
-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 manually unpacking
-the archive.
+#### For building `PLC4Py` we also need:
-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/)
+1. Python 3.7 or higher
+2. Python pyenv
-Please download the `Flex` compiler from here: http://gnuwin32.sourceforge.net/packages/flex.htm (Ideally download the binary zip distribution)
+#### For building `PLC4Net` we also need:
-You can get `Python` from here: https://www.python.org/downloads/release/python-2716/
+1. DotNet SDK 6.0
-For `.Net`, you need the `Developer Pack` in order to build .Net applications. So be sure to get a reasonably fresh installation from https://dotnet.microsoft.com
-
-If you're building a source-distribution and haven't installed git yet, be sure to do so.
-
-The Windows version of the PCAP library can be found here: https://npcap.com/ .
-Additional tasks to enable Java to find the pcap executables may need to be done.
-Follow the instructions here https://github.com/kaitoy/pcap4j#about-native-library-loading
-
-Last not least we need to install OpenSSL, which is available from here: https://indy.fulgan.com/SSL/
-The letter at the end of the version is sort of a "sub-minor" version, so I usually just take the version with the highest letter.
+With this setup you will be able to build the Java part of PLC4X.
-Make sure the `bin` directories of containing the executables `mingw32-make.exe`, `bison.exe` and `flex.exe` are all on your systems `PATH` as well as the directory containing the `openssl.exe`.
+The when doing a full build, we automatically run a prerequisite check and fail the build with an explanation, if not all requirements are meet.
### Building with Docker
@@ -220,7 +154,7 @@ NOTE: If you are working on a `Windows` system, please use `mvnw.cmd` instead of
Build PLC4X Java jars and install them in your local maven repository
```
-./mvnw install # add -DskipTests to omit running the tests
+./mvnw install
```
You can now construct Java applications that use PLC4X. The PLC4X examples
@@ -230,27 +164,15 @@ directory.
The `Go` drivers can be built by enabling the `with-go` profile:
```
-./mvnw -P with-go install # add -DskipTests to omit running the tests
-```
-
-NOTE: The C++ build is considered experimental and currently not working properly.
-
-The `C++` drivers are still under development and still not really usable.
-Therefore, they are located in the so-called `sandbox`. Also does it rely on a
-library called, `boost`, which needs to also be built.
-
-If you want to build them, this has to be enabled by activating the `with-boost`, `with-sandbox` and `with-cpp` maven profiles:
-
-```
-./mvnw -P with-boost,with-sandbox,with-cpp install # add -DskipTests to omit running the tests
+./mvnw -P with-go install
```
The `C# / .Net` implementation is currently in a `work in progress` state.
In order to be able to build the `C# / .Net` module, you currently need to activate the:
-`with-sandbox` and `with-dotnet` profiles.
+`with-dotnet` profiles.
```
-./mvnw -P with-sandbox,with-dotnet install # add -DskipTests to omit running the tests
+./mvnw -P with-dotnet install
```
The Python implementation is currently in a somewhat unclean state and still needs refactoring.
@@ -258,7 +180,7 @@ In order to be able to build the Python module, you currently need to activate t
`with-sandbox` and `with-python` profiles.
```
-./mvnw -P with-sandbox,with-python install # add -DskipTests to omit running the tests
+./mvnw -P with-sandbox,with-python install
```
In order to build everything the following command should work:
@@ -290,17 +212,18 @@ There are multiple forms in which you can become involved with the PLC4X project
These are, but are not limited to:
+* Providing information and insights
+* Testing PLC4X and providing feedback
* Submitting Pull Requests
* Filing Bug-Reports
* Active communication on our mailing lists
* Promoting the project (articles, blog posts, talks at conferences)
* Documentation
-We are a very friendly bunch and don’t be afraid to step forward.
+We are a very friendly bunch so don’t be afraid to step forward.
If you'd like to contribute to PLC4X, have a look at our
[contribution guide](https://plc4x.apache.org/developers/contributing.html)!
-
## Licensing
Apache PLC4X is released under the Apache License Version 2.0.
diff --git a/build-reproducible.sh b/build-reproducible.sh
index e72fe5ff5..22f460738 100644
--- a/build-reproducible.sh
+++ b/build-reproducible.sh
@@ -21,7 +21,7 @@
# Run a standard build
function build() {
echo "Building ..."
- mvn -U -P apache-release,with-boost,with-dotnet,with-cpp,with-python,with-proxies,with-sandbox -DaltDeploymentRepository=snapshot-repo::default::file:./local-snapshots-dir clean deploy
+ mvn -U -P apache-release,with-c,with-dotnet,with-go,with-python,with-sandbox -DaltDeploymentRepository=snapshot-repo::default::file:./local-snapshots-dir clean deploy
echo "Done"
}
diff --git a/src/main/script/prerequisiteCheck.groovy b/src/main/script/prerequisiteCheck.groovy
index 39d812c89..63e728e74 100644
--- a/src/main/script/prerequisiteCheck.groovy
+++ b/src/main/script/prerequisiteCheck.groovy
@@ -317,7 +317,6 @@ println "Detected Arch: " + arch
/////////////////////////////////////////////////////
def cEnabled = false
-def dockerEnabled = false
def dotnetEnabled = false
def goEnabled = false
// Java is always enabled ...
@@ -329,10 +328,6 @@ def activeProfiles = session.request.activeProfiles
for (def activeProfile : activeProfiles) {
if (activeProfile == "with-c") {
cEnabled = true
- } else if (activeProfile == "with-cpp") {
- cppEnabled = true
- } else if (activeProfile == "with-docker") {
- dockerEnabled = true
} else if (activeProfile == "with-dotnet") {
dotnetEnabled = true
} else if (activeProfile == "with-go") {
@@ -390,10 +385,6 @@ if (pythonEnabled) {
checkPythonVenv()
}
-if (dockerEnabled) {
- checkDocker()
-}
-
if (cEnabled) {
// CMake requires at least maven 3.6.0
checkMavenVersion("3.6.0", null)
diff --git a/src/site/asciidoc/developers/building.adoc b/src/site/asciidoc/developers/building.adoc
index fddf2ac3e..d437704b7 100644
--- a/src/site/asciidoc/developers/building.adoc
+++ b/src/site/asciidoc/developers/building.adoc
@@ -67,10 +67,11 @@ As especially building the C++, and C# drivers requires building of some third p
The following profiles are available (*They have to be enabled additionally to the `with-sandbox` profile*):
-- `with-sandbox`: Builds the modules which are not yet considered stable enough to become part of the main distribution
-- `with-cpp`: Builds all C++ related modules, integrations and examples
+- `with-c`: 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
+- `with-go`: Builds all Go related modules, integrations and examples
+- `with-python`: Builds all Python related modules, integrations and examples (Also requires `with-sandbox`)
+- `with-sandbox`: Builds the modules which are not yet considered stable enough to become part of the main distribution
WARNING: As these profiles typically require some preparation and setup on your development machine, please read the link:preparing/index.html[Preparing your Computer] guide for a detailed description on this.
@@ -94,15 +95,15 @@ If you want to skip the running of tests (even if this is not encouraged) you ca
All Apache PLC4X modules are built by executing the following command:
- mvn -P with-boost,with-cpp,with-docker,with-dotnet,with-sandbox,with-logstash,with-proxies,with-python,with-sandbox install
+ mvn -P with-c,with-dotnet,with-go,with-python,with-sandbox install
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-boost,with-cpp,with-docker,with-dotnet,with-sandbox,with-logstash,with-proxies,with-python,with-sandbox install -DskipTests
+ mvn -P with-c,with-dotnet,with-go,with-python,with-sandbox install -DskipTests
-This will not skip the compilation of tests however.
+This will not skip the compilation of tests, however.
=== Building the PLC4X Website with Maven
diff --git a/src/site/asciidoc/developers/preparing/index.adoc b/src/site/asciidoc/developers/preparing/index.adoc
index 1e1205794..bd5c4b624 100644
--- a/src/site/asciidoc/developers/preparing/index.adoc
+++ b/src/site/asciidoc/developers/preparing/index.adoc
@@ -26,19 +26,15 @@ The `Java` modules hereby probably have the least demanding requirements.
In order to build most Java parts of `PLC4X` you are required to have at least `Java 9` installed on your machine.
Some integration modules and some other languages however may add some additional constraints to this.
-As soon as you're building with the `with-c`, `with-cpp` or `with-proxies` you need to use at least `Java 11` as the `cmake-maven-plugin` requires at least this version.
-
-TIP: Currently, Java 11 is the sweet-spot for being able to build all parts of PLC4X.
-
-TIP: We have tested the build with Java 11 up to Java 16 (Latest version at the time of writing this document).
+TIP: We have tested the build with Java 11 up to Java 18 (Latest version at the time of writing this document).
If a new version comes out, please give us a little time to verify and handle any related issues.
We'll probably fix them as soon as possible.
However, in the past with Oracle's new release strategy, there have been a few bumps on the road.
-Also will PLC4X build with any Maven version starting with `Maven 3.3.0` however the `with-c`, `with-cpp` and `with-proxies` profiles require at least `Maven 3.6` as the `cmake-maven-plugin` requires this.
+Also will PLC4X build with any Maven version starting with `Maven 3.3.0` however the `with-c` profile requires at least `Maven 3.6` as the `cmake-maven-plugin` requires this.
-TIP: Currently Maven 3.6 and above is required for being able to build all parts of PLC4X.
+TIP: Currently, Maven 3.6 and above is required for being able to build all parts of PLC4X.
[width=100%]
|===
@@ -46,19 +42,12 @@ TIP: Currently Maven 3.6 and above is required for being able to build all parts
| | Builds Java API, drivers, integrations, examples a|
* Git
* LibPCAP
-| `with-cpp` | Builds C++ API, drivers, integrations, examples a|
-* gcc
-* g++
+| `with-c` | Builds C API, drivers, integrations, examples a|
| `with-dotnet` | Builds C# and .Net API, drivers, integrations, examples a|
* dotnet
| `with-python` | Builds Python API, drivers, integrations, examples a|
-* python (2.7)
-| `with-proxies` | Adds proxy modules to each enabled language a|
-* bison
-* flex
-* python
-| `with-docker` | Adds building of Docker images a|
-* docker
+* python (min 3.7)
+* pyenv
|===
The following pages will describe how to provide these requirements for your operating system.