diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-build')
8 files changed, 0 insertions, 459 deletions
diff --git a/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc b/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc deleted file mode 100644 index f1a8a003f..000000000 --- a/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// -// ============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 deleted file mode 100644 index 3a42cc78b..000000000 --- a/src/site-docs/adoc/fragments/howto-build/documentation.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// -// ============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 deleted file mode 100644 index 546a769d7..000000000 --- a/src/site-docs/adoc/fragments/howto-build/introduction.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// -// ============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 requires ONAP Nexus -==== -APEX has a dependency to ONAP parent projects. -You might need to adjust your Maven M2 settings. -The most current settings can be found in the ONAP oparent repo: link:https://git.onap.org/oparent/plain/settings.xml[Settings]. -==== - -[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 deleted file mode 100644 index 6ec453c9e..000000000 --- a/src/site-docs/adoc/fragments/howto-build/site.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// -// ============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/ad-site` -- Windows: `C:\dev\apex\target\ad-site` -- Cygwin: `/cygdrive/c/dev/apex/target/ad-site` - -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/ad-site ----- -| -[source%nowrap,bat] ----- -c: -cd \dev\apex -rmdir /s /q target\ad-site ----- -| -[source%nowrap,sh] ----- -cd /cygdrive/c/dev/apex -rm -fr target/ad-site ----- -|==================== - -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 deleted file mode 100644 index 97013742b..000000000 --- a/src/site-docs/adoc/fragments/howto-build/standard.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// -// ============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 about 6 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 packages/apex-pdp-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 packages\apex-pdp-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 deleted file mode 100644 index 4cd08cf0d..000000000 --- a/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// -// ============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 deleted file mode 100644 index 6fa654d00..000000000 --- a/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// -// ============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 deleted file mode 100644 index e923ece60..000000000 --- a/src/site-docs/adoc/fragments/howto-build/with-tests.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// -// ============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 10 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. |