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
commit b4e964cc895d2495c5e7c1d7b8360a2d0ffc3d9c
Author: Christofer Dutz <christofer.d...@c-ware.de>
AuthorDate: Wed Feb 12 22:08:57 2020 +0100
- Working on some more documentation
---
src/site/asciidoc/developers/building.adoc | 59 ++++++++++++++++++++++--------
src/site/asciidoc/developers/index.adoc | 39 +++++++++++++++++++-
2 files changed, 82 insertions(+), 16 deletions(-)
diff --git a/src/site/asciidoc/developers/building.adoc
b/src/site/asciidoc/developers/building.adoc
index 28f4143..685911e 100644
--- a/src/site/asciidoc/developers/building.adoc
+++ b/src/site/asciidoc/developers/building.adoc
@@ -67,6 +67,7 @@ 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-dotnet`: Builds all C# and .Net related modules, integrations and
examples
- `with-python`: Builds all Python related modules, integrations and examples
@@ -78,15 +79,29 @@ This `proxies` module, uses `Apache Thrift` to generate
modules for forwarding r
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):
+There are 3 more profiles that allow you to activate additional modules or
functionality:
- mvn -P with-sandbox,with-cpp,with-dotnet,with-python,with-proxies install
+- `with-docker` : Some modules also provide the means to build `Docker`
images. By enabling this profile these images are automatically built too
+- `with-logstash` : Builds the `Elastic Logstash` integration. Unfortunately
Elasic has never released the core libraries publicly so we need to then also
build `Logstash` locally. As soon as these core libraries are officially
released in `Maven-Central`, this profile will be removed again.
+- `with-boost` : Builds a `C`/`C++` Library used by both the `Apache Thrift`
build as well as the `C++` 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
`Maven-Local-Repo`, these will be re-used.
+
+The minimum Apache PLC4X build will build only the `Java` modules without any
experimental modules:
+
+ mvn install
+
+If you want to skip the running of tests (even if this is not encouraged) you
can skip them all together.
+
+ mvn install -DskipTests
+
+All Apache PLC4X modules are built by executing the following command:
+
+ mvn -P
with-boost,with-cpp,with-docker,with-dotnet,with-logstash,with-sandbox,with-logstash,with-proxies,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-sandbox,with-cpp,with-dotnet,with-python,with-proxies install
-DskipTests
+ mvn -P
with-boost,with-cpp,with-docker,with-dotnet,with-logstash,with-sandbox,with-logstash,with-proxies,with-python,with-sandbox
install -DskipTests
This will not skip the compilation of tests however.
@@ -98,16 +113,6 @@ 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
@@ -116,7 +121,19 @@ 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
+==== `apache-release` profile
+
+This profile is automatically enabled on a release-build and it automatically
creates some additional artifacts:
+
+- JavaDoc artifact
+- Sources artifact
+- Source distribution assembly
+- SHA512 checksum files for every artifact
+- PGP signature files for every artifact
+
+Generally it is not required to enable ths profile unless you are interested
in these Artifacts.
+
+==== `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.
@@ -126,4 +143,16 @@ The `debug-pom` profile will generate the so-called
`effective pom` in the modul
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
+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.
+
+==== `development` profile
+
+This profile enables some extra strict enforcer rules. It is encouraged to
activate this profile during development.
+
+In the `CI Build` this profile is enabled.
+
+==== `skip-prerequisite-check` profile
+
+Some times, actually only on the build-server we have encountered random
failures of the `prerequisite check` build step.
+
+In order to still be able to build in this case, activating this profile
simply disables these checks.
\ No newline at end of file
diff --git a/src/site/asciidoc/developers/index.adoc
b/src/site/asciidoc/developers/index.adoc
index a53b86c..5cd3b52 100644
--- a/src/site/asciidoc/developers/index.adoc
+++ b/src/site/asciidoc/developers/index.adoc
@@ -17,4 +17,41 @@
:imagesdir: ../images/
:icons: font
-== Developers
+== Developer Section
+
+This part of the Apache PLC4X dedicated to provide information to people
wanting to build PLC4X and hopefully also start contributing to this awesome
project.
+
+=== Getting Help
+
+The primary source for getting help definitely is our project mailing list
d...@plc4x.apache.org.
+
+You can search previous content in our
link:++https://lists.apache.org/list.html?d...@plc4x.apache.org++[Mail Archive]
+
+In order to post to the list you first need to subscribe. This can be done by
sending an empty Email to dev-subscr...@plc4x.apache.org.
+
+=== Getting Started
+
+We have tried to make the PLC4X build experience as smooth as possible and
have tried to reduce the number of required third party tools to an absolute
minimum.
+
+The full PLC4X build however builds not only `Java` libraries, but also `C++`,
`Python` and `C#` libraries as well as builds `Docker` images on `Limux`, `Mac`
and `Windows`.
+
+As a start, you will basically need a `Java VM` of at least `Java 1.8`.
+
+Using the `Maven-Wrapper` you don't even need a `Maven` installation. The
build will automatically fetch the right version for you.
+
+As part of the build we have an initial build step that will do a
`prerequisite check`. Depending on the activated modules, it will check if all
preconditions are met and tell you what's missing.
+
+For details please have a look at the link:preparing.html[Preparing your
Computer] page.
+
+=== Building PLC4X
+
+We have a dedicated page on link:bulding.html[Building PLC4X].
+
+Please read this page on information about how to build Apache PLC4X.
+
+
+
+
+
+
+
