Commit 415cc882 authored by Yuri Blankenstein's avatar Yuri Blankenstein
Browse files

#18 Created a website including documentation and download links

parent 1b4418ac
Pipeline #4324 failed with stage
in 0 seconds
......@@ -62,8 +62,8 @@ pipeline {
GIT_DATE_EPOCH=$(git log -1 --format=%cd --date=raw | cut -d ' ' -f 1)
GIT_DATE=$(date -d @$GIT_DATE_EPOCH -u +%Y%m%d-%H%M%S)
# Configure 'jenkins' profile for build.
BUILD_ARGS="-Pjenkins"
# Configure update snapshots and fail-at-end for build.
BUILD_ARGS="-U -fae"
# Configure 'sign' profile for build.
# Sign 'develop' branch, to allow release signing for 'nightly' deployment.
......@@ -72,17 +72,22 @@ pipeline {
BUILD_ARGS="$BUILD_ARGS -Psign"
fi
# Override the 'trace4cps.version.enduser' property for releases. Remains 'dev' otherwise.
# Override the 'trace4cps.version.enduser' property for releases,
# 'nightly' for the develop branch or 'dev' otherwise.
if [[ "$TAG_NAME" =~ ^v[0-9]+\\.[0-9]+.*$ ]]; then
BUILD_ARGS="$BUILD_ARGS -Dtrace4cps.version.enduser=$TAG_NAME"
elif [[ "$GIT_BRANCH" == "develop" ]]; then
BUILD_ARGS="$BUILD_ARGS -Dtrace4cps.version.enduser=nightly"
fi
# Override the 'trace4cps.version.qualifier' property for Jenkins builds.
# It starts with 'v' and the Git date, followed by a qualifier postfix.
# For releases, the qualifier postfix is the postfix of the version tag (if any).
# For non-releases, the qualifier postfix is 'dev'.
# For non-releases, the qualifier postfix is 'nightly'.
if [[ "$TAG_NAME" =~ ^v[0-9]+\\.[0-9]+.*$ ]]; then
QUALIFIER_POSTFIX=$(echo "$TAG_NAME" | sed -e 's/^[^-]*//g')
elif [[ "$GIT_BRANCH" == "develop" ]]; then
QUALIFIER_POSTFIX=-nightly
else
QUALIFIER_POSTFIX=-dev
fi
......@@ -96,13 +101,16 @@ pipeline {
post {
success {
// Website.
archiveArtifacts 'releng/org.eclipse.trace4cps.website/target/*-website.zip'
// Update site.
archiveArtifacts 'releng/org.eclipse.trace4cps.repository/target/*-updatesite.zip'
}
}
}
stage('Deploy') {
stage('Deploy Downloads') {
when {
anyOf {
branch 'develop'
......@@ -112,7 +120,6 @@ pipeline {
environment {
DOWNLOADS_PATH = "/home/data/httpd/download.eclipse.org/trace4cps"
DOWNLOADS_URL = "genie.trace4cps@projects-storage.eclipse.org:${DOWNLOADS_PATH}"
WEBSITE_GIT_URL = "ssh://genie.trace4cps@git.eclipse.org:29418/www.eclipse.org/trace4cps.git"
RELEASE_VERSION = getReleaseVersionFromTag(env.TAG_NAME)
}
steps {
......@@ -128,6 +135,9 @@ pipeline {
// Create directory for this release.
sh 'ssh genie.trace4cps@projects-storage.eclipse.org mkdir -p ${DOWNLOADS_PATH}/${RELEASE_VERSION}/'
// Website.
sh 'scp -r releng/org.eclipse.trace4cps.website/target/*-website.zip ${DOWNLOADS_URL}/${RELEASE_VERSION}/'
// Update site (archive).
sh 'scp -r releng/org.eclipse.trace4cps.repository/target/*-updatesite.zip ${DOWNLOADS_URL}/${RELEASE_VERSION}/'
......@@ -137,6 +147,44 @@ pipeline {
}
}
}
stage('Deploy Website') {
/*
when {
anyOf {
branch 'develop'
tag pattern: "v\\d+\\.\\d+.*", comparator: "REGEXP"
}
}
*/
environment {
WEBSITE_GIT_URL = "ssh://genie.trace4cps@git.eclipse.org:29418/www.eclipse.org/trace4cps.git"
RELEASE_VERSION = getReleaseVersionFromTag(env.TAG_NAME)
}
steps {
// Deploy website.
sshagent(['git.eclipse.org-bot-ssh']) {
sh '''
mkdir -p deploy/www
git clone ${WEBSITE_GIT_URL} deploy/www
rm -rf deploy/www/${RELEASE_VERSION}
mkdir -p deploy/www/${RELEASE_VERSION}
unzip -q releng/org.eclipse.trace4cps.website/target/*-website.zip -d deploy/www/${RELEASE_VERSION}/
'''
dir('deploy/www') {
sh '''
git config user.email "trace4cps-bot@eclipse.org"
git config user.name "genie.trace4cps"
git config push.default simple # Required to silence Git push warning.
git add -A
git commit -q -m "Website release ${RELEASE_VERSION}." -m "Generated from commit ${GIT_COMMIT}"
git push
'''
}
}
}
}
}
post {
......
......@@ -29,6 +29,9 @@
<!-- 'v20210609-141908-RC1' for release candidates, and 'v20210609-141908' for final releases. -->
<trace4cps.version.qualifier>dev</trace4cps.version.qualifier>
<!-- The prefix to use for released binaries -->
<trace4cps.binary.prefix>eclipse-trace4cps-incubation</trace4cps.binary.prefix>
<!-- Building Java8 compliant code -->
<java.source>1.8</java.source>
<maven.compiler.source>${java.source}</maven.compiler.source>
......@@ -51,6 +54,14 @@
<!-- Eclipse Dash license tool. -->
<eclipse.dash.license.tool.version>0.0.1-SNAPSHOT</eclipse.dash.license.tool.version>
<!-- Documentation plug-in versions. -->
<asciidoctor.maven.plugin.version>2.1.0</asciidoctor.maven.plugin.version>
<asciidoctorj.version>2.4.3</asciidoctorj.version>
<asciidoctorj.diagram.version>2.1.0</asciidoctorj.diagram.version>
<asciidoctorj.pdf.version>1.5.4</asciidoctorj.pdf.version>
<jruby.version>9.2.15.0</jruby.version>
<geneclipsetoc.maven.plugin.version>1.0.3</geneclipsetoc.maven.plugin.version>
<!-- Checkstyle version. Should match version used by Eclipse Checkstyle Plugin. -->
<maven.checkstyle.version>3.1.2</maven.checkstyle.version>
<checkstyle.version>8.41</checkstyle.version>
......@@ -314,6 +325,49 @@
<version>${tycho.version}</version>
</plugin>
<!-- AsciiDoctor documentation generation configuration. -->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.maven.plugin.version}</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-diagram</artifactId>
<version>${asciidoctorj.diagram.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${asciidoctorj.pdf.version}</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>${jruby.version}</version>
</dependency>
</dependencies>
<configuration>
<requires>
<require>asciidoctor-diagram</require>
</requires>
<!-- Attributes common to all documents. -->
<attributes>
<baseDir>${project.basedir}</baseDir>
<attribute-missing>error</attribute-missing>
<attribute-undefined>error</attribute-undefined>
<revnumber>${trace4cps.version.enduser}</revnumber>
<last-update-label>false</last-update-label>
<asciimath />
</attributes>
</configuration>
</plugin>
<!--
Eclipse Dash, license check, configuration.
Plugin executed manually, not during Maven build.
......
......@@ -37,7 +37,7 @@
<repositoryName>Eclipse TRACE4CPS Update Site (Incubation)</repositoryName>
<!-- Custom archive file name (excluding file extension). -->
<finalName>eclipse-trace4cps-incubation-${trace4cps.version.enduser}-updatesite</finalName>
<finalName>${trace4cps.binary.prefix}-${trace4cps.version.enduser}-updatesite</finalName>
</configuration>
</plugin>
</plugins>
......
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>org.eclipse.trace4cps.website</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.m2e.core.maven2Builder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.m2e.core.maven2Nature</nature>
</natures>
</projectDescription>
eclipse.preferences.version=1
encoding/<project>=UTF-8
////
// Copyright (c) 2021 Contributors to the Eclipse Foundation
//
// This program and the accompanying materials are made
// available under the terms of the Eclipse Public License 2.0
// which is available at https://www.eclipse.org/legal/epl-2.0/
//
// SPDX-License-Identifier: EPL-2.0
////
ifndef::imgsdir[:imgsdir: ../images]
ifndef::trace4cps-version-enduser[:trace4cps-version-enduser: dev]
ifndef::trace4cps-binary-prefix[:trace4cps-binary-prefix: eclipse-trace4cps-incubation]
:idprefix:
:idseparator: -
:listing-caption: Listing
:source-highlighter: coderay
// enable kbd: / menu: / btn: UI macros
:experimental: true
// Enable Science, Technology, Engineering and Math (STEM) expressions in the browser
:stem:
// If we use this attribute in a heading, we need to encapsulate the whole heading text in pass:normal[...] macro due to bug
// https://github.com/asciidoctor/asciidoctor/issues/1173 (Replacements in an attribute value not substituted in headings (section titles))
:trace: Eclipse TRACE4CPS
<!--
Copyright (c) 2021 Contributors to the Eclipse Foundation
This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
-->
<style>
.menu, .submenu, .menuitem, .menuref {
background-color: Menu;
}
.button {
border: 1px solid ButtonFace;
/*
Styling too similar to a real button is considered bad practice, see https://github.com/asciidoctor/asciidoctor/issues/1881#issuecomment-250702085
border: 2px outset ButtonFace;
background-color: ButtonFace;
*/
padding-left: 0.5ex;
padding-right: 0.5ex;
font-weight: normal;
font-family: "Segoe UI","Open Sans","DejaVu Sans",sans-serif;
white-space: nowrap;
}
.button:before {
content: none !important;
}
.button:after {
content: none !important;
}
</style>
\ No newline at end of file
////
// Copyright (c) 2021 Contributors to the Eclipse Foundation
//
// This program and the accompanying materials are made
// available under the terms of the Eclipse Public License 2.0
// which is available at https://www.eclipse.org/legal/epl-2.0/
//
// SPDX-License-Identifier: EPL-2.0
////
include::_initCommon.adoc[]
// Enable custom style in _main-docinfo.html
:docinfo:
:!table-caption:
:xrefstyle: short
:eclipse-downloads-file: https://www.eclipse.org/downloads/download.php?file=
:trace4cps-cli-version-enduser: {eclipse-downloads-file}/trace4cps/{trace4cps-version-enduser}/{trace4cps-binary-prefix}-{trace4cps-version-enduser}
= {trace}
*{trace}* is a *customizable, domain-independent and source-independent Gantt chart viewer* with mathematically-founded analysis support.
{trace} supports the visualization of activities on resources as a function of time (Gantt charts), as well as the visualization of continuous signals.
{trace} also supports several analysis techniques to identify bottlenecks, check formally-specified (performance) properties, and analyze resource usage.
A key feature of {trace} is the ability to configure the identification, selection and visualization of such information to match any specific application domain.
== Visualization and analysis of concurrent system activities
{trace} helps us to understand complicated behavior over time for all kinds of systems through its domain-independent capabilities for visualizing and analyzing concurrent activities that are encoded in execution traces.
{trace} supports claims on resources, events, dependencies, and continuous signals.
<<fig-trace>> shows a typical {trace} Gantt chart of an application that iteratively executes activities A-G.
The claims model executions of these system activities and are shown as colored rectangles with a start and end time.
Data flow between the activities is modeled by dependencies between claims, shown as arrows between the claims.
Events, such as the start and end of an iteration of the application, are shown at the bottom as vertical arrows.
The signal, above the events and below the claims, shows the throughput of the modeled system.
[[fig-trace]]
.Example visualization of system activity over time (x-axis).
image::{imgsdir}/trace.png[width=1366]
== Understanding system behavior over time
There are many reasons why a system’s behavior over time is difficult to understand or, worse, confusing – even when the system is performing as designed.
An example is a situation in which many concurrent activities share resources.
Unforeseen interactions may arise due to the specific timing of the activities.
Moreover, if the timing of the activities changes (e.g. due to an upgrade to the computational platform), the interactions may also change, which could result in significantly different behavior.
Insight into the hows and whys of a system’s behavior over time is of paramount importance for making effective (design) choices and trade-offs in all phases of the system lifecycle, from the design of a new system to the maintenance of an old legacy system.
{trace} can help with this.
== Execution traces to capture behavior over time
{trace} works with execution traces.
These capture (a single) system behavior over time.
An execution trace contains time-stamped data for claims, events and signals.
{trace} extends this with concepts from the Y-chart paradigm and a number of user-defined attributes (e.g. the name of the activity) in order to be tailored to a specific problem domain.
This execution trace concept is generic, which makes {trace} widely applicable:
All levels of abstraction::
The trace format can capture all levels of abstraction, from low-level embedded activities to system-level activities.
Domain-independent::
The trace format is domain-independent but nevertheless has the means to be tailored to a specific domain via the user-defined attributes.
Source-independent::
{trace} input can be created from any source, e.g. from the log files of legacy systems or from a discrete-event simulation model.
[[fig-ychart]]
.The Y-chart method
image::{imgsdir}/ychart.png[width=1024]
The Y-chart paradigm decomposes a system into an application, a platform, and the mapping between them, fostering reuse when one of these parts changes.
Furthermore, it defines a feedback cycle to allow systematic design-space exploration (<<fig-ychart>>).
The Y-chart concepts of application, mapping and platform are realized in {trace} through the decomposition of an activity (e.g. an image-processing computation) into one or more claims on resources for a certain amount of time (e.g. two cores of the CPU and 20 MB of RAM for 50 ms).
These are the main elements of the execution traces that capture system behavior (star-1 in <<fig-ychart>>).
To provide feedback on the system under analysis (star-2 in <<fig-ychart>>), {trace} provides extensive visualization and analysis of execution traces.
== Visualization and analysis of execution traces
{trace} provides insights into the system dynamics of all kinds of systems through the visualization and analysis of execution traces (<<fig-workflow>>).
{trace}' Gantt chart view offers coloring, grouping and filtering options.
This visualization alone is already very powerful and can bring quick insights into the system dynamics.
{trace} also provides several analysis methods, which sets it apart from other Gantt-chart visualization tools.
Critical-path analysis::
Can be used to detect activities and resources that are bottlenecks for performance.
Distance analysis::
Can be used to compare execution traces with respect to structure, e.g. to check a model trace against an implementation trace.
Runtime verification::
Provides a means to formally specify and verify the properties of execution traces using temporal logic.
It is useful for expressing and checking performance properties, e.g., “the processing latency is at most 50 ms.”
Latency, throughput and work-in-progress analysis::
Provides built-in methods to derive these properties from an execution trace.
Behavioral analysis::
Can be used to visualize repetitive patterns that often are present in systems such as image-processing pipelines and manufacturing machines.
Resource-usage analysis::
Can quickly give insights into the details of the resource usage.
{trace} and the underlying concepts are relatively easy to learn, the trace input is easy to use, and the application of {trace} has great potential benefits.
[[fig-workflow]]
.A specialization of Figure 2 for {trace}
image::{imgsdir}/workflow.png[width=1024]
[[installation]]
== Installation of {trace}
The {trace} P2 update site contains all plugins and features, for easy integration into OSGi-based applications.
{trace} {trace4cps-version-enduser} is available as an Eclipse P2 update site:
`\https://download.eclipse.org/trace4cps/{trace4cps-version-enduser}/update-site/`
[CAUTION]
====
Can't wait for the next release?
A link:/trace4cps/nightly/index.html#installation[nightly build] of this page is also available, it is built from the https://gitlab.eclipse.org/eclipse/trace4cps/trace4cps/-/tree/develop[develop branch].
Please note that APIs, syntaxes and/or functionality might not be stable for nightly builds.
====
Below are instructions to install {trace} from scratch.
The first step is to install the Eclipse IDE:
* Install a 64-bit Java 1.8.
* Download an Eclipse IDE version 2020-06, e.g., https://www.eclipse.org/downloads/packages/release/2020-06/r/eclipse-ide-java-developers
* Unzip the IDE, e.g., to the directory `trace`.
* Start the Eclipse IDE via `trace/eclipse/eclipse.exe`.
* Select a workspace directory: Use the browse button and create a directory, e.g., “trace/workspace”.
* Close the Welcome tab.
The second step is to install the {trace} feature:
* Select menu:Help[Install New Software...]
* Click btn:[Add] and put a name (e.g., “{trace} update site”) and location: +
`\https://download.eclipse.org/trace4cps/{trace4cps-version-enduser}/update-site/`
* Click btn:[OK] and check that the window now shows the {trace} category.
* Expand the {trace} category, and select the {trace} feature and click btn:[Next].
* Complete the remaining steps of the installation process (including acceptance of the license agreement and a restart of the Eclipse IDE).
[[installation-examples]]
=== Installation of the examples
* Download the link:html/content/ODSE-traces.zip[trace examples zip file] from this site or from the Eclipse help pages following the sub-steps below.
** Open the Help menu via menu:Help[Help Contents].
** Navigate to the {trace} user manual, and select the “Running example” section.
** At the bottom of the page is a link to download a zip file with examples.
* Unzip the trace examples file in the “{trace}” directory (ensure that a directory is created with a number of `*.etf` files).
* Start the new project wizard from the menu menu:File[New, Project...]
* Select “General -> Project” in the tree and click “Next”.
* Choose a project name, e.g., “trace examples”, uncheck the “use default location” option, and use the btn:[Browse...] button to select the directory with the unzipped example content.
* Finally, click btn:[Finish].
Verify that the “Package Explorer” view now shows the contents of the zip file.
Double-click `reference.etf` and check whether a Gantt-chart view is shown.
If this is the case, then installation has been successful.
== Learn more
If you want to learn more, then read the link:html/content/manual.html[{trace} user manual].
It describes the input format of {trace} and contains an explanation of the visualization and analysis features.
Furthermore, it contains a <<installation-examples, zip file with example traces>>.
TIP: Once the {trace} feature is <<installation, installed>>, the Eclipse Help menu also contains this user manual.
.Publications
* M. Hendriks, T. Basten,
_“Performance engineering with {trace}”_,
Bits & Chips 5, 14 September 2018.
https://bits-chips.nl/artikel/performance-engineering-with-trace/
* M. Hendriks, F.W. Vaandrager.
_“Reconstructing Critical Paths from Execution Traces”_,
CSE '12 Proceedings of the 2012 IEEE 15th International Conference on Computational Science and Engineering.
IEEE Computer Society Washington, 2012.
doi:10.1109/ICCSE.2012.78
* M. Hendriks, M. Geilen, A.R.B. Behrouzian, T. Basten, H. Alizadeh, and D. Goswami.
_“Checking metric temporal logic with {trace}”_,
in 16th International Conference on Application of Concurrency to System Design (ACSD 2016), Torun, Poland, 2016.
doi: 10.1109/ACSD.2016.13
* M. Hendriks, J. Verriet, T. Basten, B. Theelen, M. Brassé, and L. Somers,
_“Analyzing execution traces: critical-path analysis and distance analysis”_,
International Journal on Software Tools for Technology Transfer, 2016.
doi:10.1007/s10009-016-0436-z
<!--
Copyright (c) 2021 Contributors to the Eclipse Foundation
This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
-->
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
<id>website</id>
<formats>
<format>zip</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<fileSets>
<fileSet>
<directory>${project.build.directory}/website</directory>
<outputDirectory />
</fileSet>
<fileSet>
<directory>${basedir}/images</directory>
</fileSet>
</fileSets>
<dependencySets>
<dependencySet>
<includes>
<include>org.eclipse.trace4cps:org.eclipse.trace4cps.ui</include>
</includes>
<unpack>true</unpack>
<unpackOptions>
<includes>
<include>html/**</include>
</includes>
</unpackOptions>
</dependencySet>
</dependencySets>
</assembly>
\ No newline at end of file
<!--
Copyright (c) 2021 Contributors to the Eclipse Foundation
This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.trace4cps</groupId>
<artifactId>org.eclipse.trace4cps.root</artifactId>
<version>0.1.0-SNAPSHOT</version>
<relativePath>../../</relativePath>
</parent>
<artifactId>org.eclipse.trace4cps.website</artifactId>
<packaging>pom</packaging>
<name>TRACE4CPS Website</name>
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>org.eclipse.trace4cps.ui</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<!-- Attributes common to all output formats -->
<executions>
<!-- Rendering the website -->
<execution>
<id>generate-website</id>
<phase>process-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>adoc</sourceDirectory>
<outputDirectory>${project.build.directory}/website</outputDirectory>
<backend>html5</backend>
<attributes>
<imagesdir />
<imgsdir>images</imgsdir>
<doctype>book</doctype>
<icons>font</icons>
<sectanchors>true</sectanchors>
<toc>left</toc>
<toclevels>3</toclevels>
<trace4cps-binary-prefix>${trace4cps.binary.prefix}</trace4cps-binary-prefix>
<trace4cps-version-enduser>${trace4cps.version.enduser}</trace4cps-version-enduser>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<executions>
<execution>
<id>assemble-website</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<finalName>${trace4cps.binary.prefix}-${trace4cps.version.enduser}</finalName>
<descriptors>
<descriptor>${basedir}/assembly.xml</descriptor>
</descriptors>
</configuration>
</execution>
</executions>
</plugin>