Repository files navigation

Template for system and software architecture done with OpenFastTrace.

The architecture documents structure is based the thearc42 architecture template by Dr. Gernot Starke, Dr. Peter Hruschka.

Thearc42 template is offered under theCC-BY-SA. Please keep attributions in all derived works.

This build automatically includes license headers in the Markdown files for that reasons. See"Automatic License Headers" for details.

• Change log

If you only want to render the document to you need to installPandoc. UML diagrams are rendered withPlantUML.

apt install plantuml pandoc

Since Pandoc renders PDFs with the Help ofpdflatex you also need to install a appropriate TeX distribution. On Linux theTeX Live packages are typically part of the standard repositories. Since PlantUML generates SVGs as vector format, we also need a converter from SVN to PDF.

apt install plantuml pandoc texlive-latex-base texlive-fonts-recommended librsvg2-bin

yum install plantuml pandoc texlive-schema-full librsvg2-tools

The directory structure below shows the most important parts of the project layout and what they mean.

project root  |-- launch                     Eclipse launch configurations  |  |-- src  |    |-- assembly              Configuration for creating archives (TAR, ZIP)  |    |  |    |-- doc                   Markdown sources of the specification  |    |    |-- css              CSS for the HTML output  |    |   ...  |    |  |    |-- license               License and license headers  |    |  |    |-- main  |    |    '-- lua              Lua filters for Pandoc  |    |  |    '-- uml                   PlantUML sources for the UML model  |         |-- actors           |         |-- classes  |         |-- diagrams         Sources for the UML diagrams  |         |     |-- activity  |         |     |-- class  |         |    ...  |        ...  |  |-- target  |    |-- <spec-name>.html      Generated HTML output of the specification  |    '-- <spec-name>.pdf       Generated PDF ...  '-- pom.xml                    Maven project configuration

⚠ Be careful not to accidentally edit files in the target directory. It happens to us now and then and is each time a source of annoyance since the changes are gone with the next build run.

For authoring any text editor will work.

We recommend usingEclipse, the built-in WikiText editor forMarkdown and theEclipse PlantUML plug-in.

Read theOpenFastTrace User Guide to learn how to create specifications in the OFT Markdown format.

The template contains a lot of comments in the form of Markdown quotes starting with "OFT:". You can strip them with your editors multi-file search and replace function (e.g. CRTL+H in Eclipse).

Or you can use command line tools likesed. Run the script below on the root directory of the architecture template.

find src/doc -name'*.md' -exec sed -i -e'/^>\s*OFT:.*/d' {}\;

You can find the configuration for the build in theMavenpom.xml file of this project.

To configure the build variables like document name and version number change the properties:

<projectxmlns="http://maven.apache.org/POM/4.0.0"  <!-- ... -->  <properties><!-- ...-->    <spec.version>${project.version}</spec.version>    <spec.date>${maven.build.timestamp}</spec.date>    <spec.title>AutoYummiBox ${spec.version} - Software Architectural Design</spec.title>    <spec.authors>S. Bär, M. Thielcke</spec.authors>    <spec.filename>SwAD-AutoYummiBox</spec.filename>    <spec.files>architecture.md introduction.md context.md      ...      glossary.md bibliography.md</spec.files>  </properties><!-- ...--></project>

Thespec.files property must contain all files you want to render into the specification in the order in which that must be concatenated.

The document version (spec.version) defaults to the version of the Maven artifact. This has the advantage that the version only needs to be maintained in a single place.

The document date (spec.date) defaults to the date of the build which is usually what you want if you build, release and deploy a document withContinuous Integration.

While you will have to adapt the document's title (spec.title), we recommend that you let the build inject the version number as in the original example.

⚠ If you introduce new files, don't forget to list them there!

The Maven build automatically checks whether all markdown files have a license header in in life cylce phase "validate". The build fails if one or more headers are missing.

Run the following Maven command to create or update the file headers:

mvn license:update-project-license license:update-file-header

The original files are in Markdown format. The general idea of the links between those files is that you can navigate without conversion to other formats already. This way you can read your specifications directly in your favorite repository viewer.

On the other hand you of course want the links to work properly when converting to HTML or PDF too. Pandoc allows us to use filters during conversion that achieve this. Either as filters in a pipe on the console or via the built-in Lua interpreter.

Check the followingLua file to see how the original links between the source Markdown files are converted to the target format.

src/main/lua/link_converter.lua

The filter is applied via the--lua-filters command line switch.

If you only want to render the document and UML source into HTML and images run:

mvn compile

To create archives from the rendered documents run:

mvn package

It is a good idea to check the links in your document from time to time.

Install thelinkchecker package:

apt install linkchecker

Check the links in the generated HTML docuements:

linkchecker --check-extern target/*.html

If you remove the command line switch--check-extern only local links are checked.

This project contains a CI setup for Jenkins. The build usesDocker to provide a stable environment for its execution. So Jenkins needs to be able to execute Docker commands.The build process itself is defined withinJenkinsfile and consists of these stages:

• checkout : Get the source from repo
• build docker : Create the Docker image to be used during build execution (only once if it doesn't exist locally)
• render html : render a HTML file from sources
• render pdf : render a PDF file from source

The rendering of HTML, PDF,... is controlled with Maven profiles (render-html,render-pdf). To enable other/ additional formats new profiles can be defined withinpom.xml.

If there is no Docker installation available the required tools/ dependencies described above need to be provided on Jenkins or at least one of its agents.

• docker/Dockerfile can be used as template for the setup of the required tools.
• the Jenkins agents should be labeled accordingly (i.e. pandoc)
• Jenkinsfile : label needs to match agent-labels (i.e. pandoc)
• Jenkinsfile : the "build docker" stage has to be removed
• Jenkinsfile : the "run docker"-part has to be removed from sh-executions