diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-build')
8 files changed, 460 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc b/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc new file mode 100644 index 000000000..f1a8a003f --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc @@ -0,0 +1,34 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Checkstyle with Maven + +The codestyle for all APEX java projects can be checked automatically. +The checks include empty or non-existing Javadocs. +Any checkstyle run should complete without any errors, some warnings are acceptable. + +To run checkstyle on an APEX Maven project use: + +[source%nowrap,sh] +---- +mvn checkstyle:check +---- + + +To run checkstyle on all modules use: + +[source%nowrap,sh] +---- +mvn checkstyle:checkstyle -DapexAll +---- + diff --git a/src/site-docs/adoc/fragments/howto-build/documentation.adoc b/src/site-docs/adoc/fragments/howto-build/documentation.adoc new file mode 100644 index 000000000..3a42cc78b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/documentation.adoc @@ -0,0 +1,41 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Build the APEX Documentation + +The APEX Maven build also includes stand-alone documentations, such as the HowTo documents, the Installation Guide, and the User Manual. +Use Maven to build the APEX Documentation. +The Maven options `-N` prevents Maven to go through all APEX modules, which is not necessary for the documentation. +The final documents will be in `target/generated-docs` (Windows: `target\generated-docs`). +The __HTML__ documents are in the `html/` folder, the __PDF__ documents are in the `pdf/` folder. +Once the documentation is build, copy the __HTML__ and __PDF__ documents to a folder of choice + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean generate-resources -N -DapexDocs +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean generate-resources -N -DapexDocs +---- +|==================== + + diff --git a/src/site-docs/adoc/fragments/howto-build/introduction.adoc b/src/site-docs/adoc/fragments/howto-build/introduction.adoc new file mode 100644 index 000000000..02ba21fbd --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/introduction.adoc @@ -0,0 +1,56 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Introduction to building APEX + +APEX is written 100% in Java and uses link:https://maven.apache.org/[Apache Maven] as the build system. +The requirements for building APEX are: + +- An installed Java development kit for Java version 8 or higher + ** To install a Java SDK please follow these guidelines link:https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html[Oracle Java 8 SDK]. +- Maven 3 + ** To get Maven 3 running please follow the guidelines for link:https://maven.apache.org/download.cgi[Download] and link:https://maven.apache.org/install.html[Install], and link:https://maven.apache.org/run.html[Run] Maven +- A clone of the APEX source repositories + +To get a clone of the APEX source repositories, please see the APEX Installation Guide or the APEX User manual. + +One all requirements are in place, APEX can be build. +There are several different artifacts one can create building APEX, most of them defined in their own __profile__. +APEX can also be build in a standard way with standard tests (`mvn clean install`) or without standard tests (`mvn clean install -DskipTests`). + +The examples in this document assume that the APEX source repositories are cloned to: + +- Unix, Cygwin: `/usr/local/src/apex` +- Windows: `C:\dev\apex` +- Cygwin: `/cygdrive/c/dev/apex` + +[IMPORTANT] +.A Build needs Space +==== +Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full distribution and 1-2 GB for the downloaded dependencies +==== + +[IMPORTANT] +.A Build requires Internet (for first build to download all dependencies and plugins) +==== +During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven repository. +The first standard build (and any first specific build) requires Internet access to download those dependencies. +==== + +[IMPORTANT] +.Building RPM distributions +==== +RPM images are only build if the `rpm` package is installed (Unix). +To install `rpm` run `sudo apt-get install rpm`, then build APEX. +==== + diff --git a/src/site-docs/adoc/fragments/howto-build/site.adoc b/src/site-docs/adoc/fragments/howto-build/site.adoc new file mode 100644 index 000000000..42cbda525 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/site.adoc @@ -0,0 +1,93 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Build APEX Site + +The APEX Maven build comes with full support to build a web site using Maven Site. +Use Maven to build the APEX Site. +Stage the APEX web site. +The target folder for the staged site is + +- Unix: `/usr/local/src/apex/target/gh-pages` +- Windows: `C:\dev\apex\target\gh-pages` +- Cygwin: `/cygdrive/c/dev/apex/target/gh-pages` + +Once the web site is staged, copy the full site to a folder of choice or into a web server. + + +[IMPORTANT] +.Building a Site takes Time +==== +Building and staging the APEX web site can take very long. +The stand-alone documentation will take about 2 minutes. +The sites for all modules and projects and the main APEX site can take between 10-30 minutes depending on your build machine +(~10 minutes without generating source and test-source reports, closer to 30 minutes with all reports). +==== + + +Start the build deleting the staging directory that might have been created by a previous site build. +Then go to the APEX packaging directory. + +[width="100%",options="header",cols="5a,5a,5a"] +|==================== +| Unix | Windows | Cygwin +| +[source%nowrap,sh] +---- +cd /usr/local/src/apex +rm -fr target/gh-pages +---- +| +[source%nowrap,bat] +---- +c: +cd \dev\apex +rmdir /s /q target\gh-pages +---- +| +[source%nowrap,sh] +---- +cd /cygdrive/c/dev/apex +rm -fr target/gh-pages +---- +|==================== + +the workflow for building a complete site then is as follows: + +[source%nowrap,sh] +---- +mvn clean -DapexAll #<1> +mvn install -DskipTests #<2> +mvn generate-resources -N -DapexDocs #<3> +mvn initialize site:attach-descriptor site site:stage -DapexSite #<4> +---- +. First clean all modules to remove any site artifacts, use the _apexXtext_ profile to make sure these modules are processed as well +. Next run a simple install without tests +. Now generate the APEX stand -alone documentation, they are in the local package only so we can use the _-N_ switch +. Last build the actual sites and stage (copy to the staging directory) with the profile _apexSite_ (do not forget the initialize goal, otherwise the staging directory will not be correctly set and sites are staged in every model in a directory called `docs`). + +If you want to build the site for a particular project for testing, the Maven command is simpler. +Since only the main project has APEX documentation (stand-alone), you can use Maven as follow. + +[source%nowrap,sh] +---- +mvn clean site -DapexSite +---- + +If you want to stage the tested site, then use + +[source%nowrap,sh] +---- +mvn clean initialize site:attach-descriptor site site:stage -DapexSite +---- + diff --git a/src/site-docs/adoc/fragments/howto-build/standard.adoc b/src/site-docs/adoc/fragments/howto-build/standard.adoc new file mode 100644 index 000000000..76ebfc2bf --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/standard.adoc @@ -0,0 +1,86 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Standard Build + +Use Maven to for a standard build without any tests. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DskipTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DskipTests +---- +|==================== + +The build takes 2-3 minutes on a standard development laptop. +It should run through without errors, but with a lot of messages from the build process. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests] +---- + + +The build will have created all artifacts required for an APEX installation. +The following example show how to change to the target directory and how it should look like. + +[width="100%",options="header",cols="a"] +|==================== +| Unix, Cygwin +| +[source%nowrap,sh,numbered] +---- +# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# ls -l +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix] +---- + +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| Windows +| +[source%nowrap,bat,numbered] +---- +>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>dir +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows] +---- + +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc b/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc new file mode 100644 index 000000000..4cd08cf0d --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc @@ -0,0 +1,43 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Build with all Components + +A standard APEX build will not build all components. +Some parts are for specific deployments, only. +Use Maven to for a standard build with __all__ components. + +[IMPORTANT] +.Might require specific software +==== +When building all components, some modules require specific software installed on the build machine. +==== + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DapexAll +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DapexAll +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc b/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc new file mode 100644 index 000000000..6fa654d00 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc @@ -0,0 +1,50 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Build with all Tests + +Use Maven to for a standard build with __all__ tests. + +[IMPORTANT] +.Some tests have specific timing Requirements +==== +Some of the tests have very specific timing requirements. +If run on a low-powered build machine, or if the build machine is on high load, those tests might fail and the whole build might fail as well. +If this happens, reduce the load on your build machine and restart the build. +==== + +[IMPORTANT] +.Might require specific software +==== +When running all tests, some modules require specific software installed on the build machine. +For instance, testing the full capabilities of context (with distribution and persistence) will require Hazelcast and Infinispan installed on the build machine. +==== + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DallTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DallTests +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-build/with-tests.adoc b/src/site-docs/adoc/fragments/howto-build/with-tests.adoc new file mode 100644 index 000000000..f8d300c45 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/with-tests.adoc @@ -0,0 +1,57 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Build with standard Tests + +Use Maven to for a standard build with standard tests. + +[IMPORTANT] +.Some tests have specific timing Requirements +==== +Some of the tests have very specific timing requirements. +If run on a low-powered build machine, or if the build machine is on high load, those tests might fail and the whole build might fail as well. +If this happens, reduce the load on your build machine and restart the build. +==== + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install +---- +|==================== + +The build takes about 5-6 minutes with tests on a standard development laptop. +It should run through without errors, but with a lot of messages from the build process. +If build with tests (i.e. without `-DskipTests`), there will be error messages and stack trace prints from some tests. +This is normal, as long as the build finishes successful. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, with tests] +---- + +The build will have created all artifacts required for an APEX installation. + |