From b44d7ddb05172a092a71a029a862b9777d3eb09e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ralf=20D=2E=20M=C3=BCller?= Date: Fri, 15 Dec 2023 14:57:51 +0000 Subject: [PATCH] added docToolchain and arc42 plain template --- .gitignore | 2 + docToolchainConfig.groovy | 549 +++++++++++++++ documentation/arc42/.asciidoctorconfig.adoc | 2 + documentation/arc42/arc42.adoc | 93 +++ .../arc42/chapters/.asciidoctorconfig.adoc | 2 + .../chapters/01_introduction_and_goals.adoc | 35 + .../chapters/02_architecture_constraints.adoc | 17 + .../chapters/03_system_scope_and_context.adoc | 36 + .../arc42/chapters/04_solution_strategy.adoc | 17 + .../chapters/05_building_block_view.adoc | 121 ++++ .../arc42/chapters/06_runtime_view.adoc | 30 + .../arc42/chapters/07_deployment_view.adoc | 54 ++ documentation/arc42/chapters/08_concepts.adoc | 34 + .../chapters/09_architecture_decisions.adoc | 17 + .../chapters/10_quality_requirements.adoc | 25 + .../arc42/chapters/11_technical_risks.adoc | 17 + documentation/arc42/chapters/12_glossary.adoc | 27 + documentation/arc42/chapters/about-arc42.adoc | 15 + documentation/arc42/chapters/config.adoc | 9 + documentation/images/arc42-logo.png | Bin 0 -> 8151 bytes dtcw | 640 ++++++++++++++++++ 21 files changed, 1742 insertions(+) create mode 100644 docToolchainConfig.groovy create mode 100644 documentation/arc42/.asciidoctorconfig.adoc create mode 100644 documentation/arc42/arc42.adoc create mode 100644 documentation/arc42/chapters/.asciidoctorconfig.adoc create mode 100644 documentation/arc42/chapters/01_introduction_and_goals.adoc create mode 100644 documentation/arc42/chapters/02_architecture_constraints.adoc create mode 100644 documentation/arc42/chapters/03_system_scope_and_context.adoc create mode 100644 documentation/arc42/chapters/04_solution_strategy.adoc create mode 100644 documentation/arc42/chapters/05_building_block_view.adoc create mode 100644 documentation/arc42/chapters/06_runtime_view.adoc create mode 100644 documentation/arc42/chapters/07_deployment_view.adoc create mode 100644 documentation/arc42/chapters/08_concepts.adoc create mode 100644 documentation/arc42/chapters/09_architecture_decisions.adoc create mode 100644 documentation/arc42/chapters/10_quality_requirements.adoc create mode 100644 documentation/arc42/chapters/11_technical_risks.adoc create mode 100644 documentation/arc42/chapters/12_glossary.adoc create mode 100644 documentation/arc42/chapters/about-arc42.adoc create mode 100644 documentation/arc42/chapters/config.adoc create mode 100644 documentation/images/arc42-logo.png create mode 100755 dtcw diff --git a/.gitignore b/.gitignore index 4b7dcb2..42a4b63 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ node_modules Gemfile.lock *.bkp *.dtmp +.gradle +build diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy new file mode 100644 index 0000000..6b5647e --- /dev/null +++ b/docToolchainConfig.groovy @@ -0,0 +1,549 @@ +outputPath = 'build' + +// If you want to use the Antora integration, set this to true. +// This requires your project to be setup as Antora module. +// You can use `downloadTemplate` task to bootstrap your project. +//useAntoraIntegration = false + +// Path where the docToolchain will search for the input files. +// This path is appended to the docDir property specified in gradle.properties +// or in the command line, and therefore must be relative to it. + +inputPath = 'documentation'; + +// the pdfThemeDir config in this file is outdated. +// please check http://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/030_generateHTML.html#_pdf_style for further details +// pdfThemeDir = './src/docs/pdfTheme' + +inputFiles = [ + //[file: 'doctoolchain_demo.adoc', formats: ['html','pdf']], + //[file: 'arc42-template.adoc', formats: ['html','pdf']], + [file: 'arc42/arc42.adoc', formats: ['html','pdf']], + /** inputFiles **/ +] + +//folders in which asciidoc will find images. +//these will be copied as resources to ./images +//folders are relative to inputPath +// Hint: If you define an imagepath in your documents like +// :imagesdir: ./whatsoever +// define it conditional like +// ifndef::imagesdir[:imagesdir: ./whatsoever] +// as doctoolchain defines :imagesdir: during generation +imageDirs = [ + 'images/.', + 'images/.', + /** imageDirs **/ +] + +// whether the build should fail when detecting broken image references +// if this config is set to true all images will be embedded +failOnMissingImages = true + +// these are directories (dirs) and files which Gradle monitors for a change +// in order to decide if the docs have to be re-build +taskInputsDirs = [ + "${inputPath}", +// "${inputPath}/src", +// "${inputPath}/images", + ] + +taskInputsFiles = [] + +//***************************************************************************************** + +// Configuration for customTasks +// create a new Task with ./dtcw createTask +customTasks = [ + /** customTasks **/ +] + + +//***************************************************************************************** + +//Configuration for microsite: generateSite + previewSite + +microsite = [:] + +// these properties will be set as jBake properties +// microsite.foo will be site.foo in jBake and can be used as config.site_foo in a template +// see https://jbake.org/docs/2.6.4/#configuration for how to configure jBake +// other properties listed here might be used in the jBake templates and thus are not +// documented in the jBake docs but hopefully in the template docs. +microsite.with { + /** start:microsite **/ + + // is your microsite deployed with a context path? + contextPath = '/' + // configure a port on which your preview server will run + previewPort = 8042 + // the folder of a site definition (theme) relative to the docDir+inputPath + //siteFolder = '../site' + + /** end:microsite **/ + + //project theme + //site folder relative to the docs folder + //see 'copyTheme' for more details + siteFolder = '../site' + + // the title of the microsite, displayed in the upper left corner + title = '##site-title##' + // the next items configure some links in the footer + // + // contact eMail + // example: mailto:bert@example.com + footerMail = '##footer-email##' + // + // twitter account url + footerTwitter = '##twitter-url##' + // + // Stackoverflow QA + footerSO = '##Stackoverflow-url##' + // + // Github Repository + footerGithub = '##Github-url##' + // + // Slack Channel + footerSlack = '##Slack-url##' + // + // Footer Text + // example: built with docToolchain and jBake
theme: docsy + footerText = 'built with docToolchain and jBake
theme: docsy' + // + // site title if no other title is given + title = 'docToolchain' + // + // the url to create an issue in github + // Example: https://github.com/docToolchain/docToolchain/issues/new + issueUrl = '##issue-url##' + // + // the base url for code files in github + // Example: https://github.com/doctoolchain/doctoolchain/edit/master/src/docs + branch = System.getenv("DTC_PROJECT_BRANCH")?:'-' + gitRepoUrl = '##git-repo-url##' + + // + // the location of the landing page + landingPage = 'landingpage.gsp' + // the menu of the microsite. A map of [code:'title'] entries to specify the order and title of the entries. + // the codes are autogenerated from the folder names or :jbake-menu: attribute entries from the .adoc file headers + // set a title to '-' in order to remove this menu entry. + menu = [adr: 'Tech Decisions (ADRs)'] + +//tag::additionalConverters[] +/** + +if you need support for additional markup converters, you can configure them here +you have three different types of script you can define: + +- groovy: just groovy code as string +- groovyFile: path to a groovy script +- bash: a bash command. It will receive the name of the file to be converted as first argument + +`groovy` and `groovyFile` will have access to the file and config object + +`dtcw:rstToHtml.py` is an internal script to convert restructuredText. +Needs `python3` and `docutils` installed. + +**/ + additionalConverters = [ + //'.one': [command: 'println "test"+file.canonicalPath', type: 'groovy'], + //'.two': [command: 'scripts/convert-md.groovy', type: 'groovyFile'], + //'.rst': [command: 'dtcw:rstToHtml.py', type: 'bash'], + ] +//end::additionalConverters[] + + // if you prefer another convention regarding the automatic generation + // of jBake headers, you can configure a script to modify them here + // the script has access to + // - file: the current object + // - sourceFolder: the copy of the docs-source on which the build operates + // default `/microsite/tmp/site/doc` + // - config: the config object (this file, but parsed) + // - headers: already parsed headers to be modified + /** + customConvention = """ + System.out.println file.canonicalPath + headers.title += " - from CustomConvention" + """.stripIndent() + **/ + + // if you need to register custom Asciidoctor extensions, this is the right place + // configure the name and path to your extension, relative to the root of your project + // (relative to dtcw). For example: 'src/ruby/asciidoctor-lists.rb'. + // this is the same as the `requires`-list of the asciidoctor gradle plugin + + // rubyExtensions = [] +} + +//***************************************************************************************** + +//Configuration for exportChangelog + +exportChangelog = [:] + +changelog.with { + + // Directory of which the exportChangelog task will export the changelog. + // It should be relative to the docDir directory provided in the + // gradle.properties file. + dir = 'src/docs' + + // Command used to fetch the list of changes. + // It should be a single command taking a directory as a parameter. + // You cannot use multiple commands with pipe between. + // This command will be executed in the directory specified by changelogDir + // it the environment inherited from the parent process. + // This command should produce asciidoc text directly. The exportChangelog + // task does not do any post-processing + // of the output of that command. + // + // See also https://git-scm.com/docs/pretty-formats + cmd = 'git log --pretty=format:%x7c%x20%ad%x20%n%x7c%x20%an%x20%n%x7c%x20%s%x20%n --date=short' + +} + +//***************************************************************************************** + +//tag::confluenceConfig[] +//Configuration for publishToConfluence + +confluence = [:] + +/** +//tag::input-config[] + +*input* + +is an array of files to upload to Confluence with the ability +to configure a different parent page for each file. + +=== Attributes + +- `file`: absolute or relative path to the asciidoc generated html file to be exported +- `url`: absolute URL to an asciidoc generated html file to be exported +- `ancestorName` (optional): the name of the parent page in Confluence as string; + this attribute has priority over ancestorId, but if page with given name doesn't exist, + ancestorId will be used as a fallback +- `ancestorId` (optional): the id of the parent page in Confluence as string; leave this empty + if a new parent shall be created in the space + +The following four keys can also be used in the global section below + +- `spaceKey` (optional): page specific variable for the key of the confluence space to write to +- `subpagesForSections` (optional): The number of nested sub-pages to create. Default is '1'. + '0' means creating all on one page. + The following migration for removed configuration can be used. +** `allInOnePage = true` is the same as `subpagesForSections = 0` +** `allInOnePage = false && createSubpages = false` is the same as `subpagesForSections = 1` +** `allInOnePage = false && createSubpages = true` is the same as `subpagesForSections = 2` +- `pagePrefix` (optional): page specific variable, the pagePrefix will be a prefix for the page title and it's sub-pages + use this if you only have access to one confluence space but need to store several + pages with the same title - a different pagePrefix will make them unique +- `pageSuffix` (optional): same usage as prefix but appended to the title and it's subpages + +only 'file' or 'url' is allowed. If both are given, 'url' is ignored + +//end::input-config[] +**/ + +confluence.with { + input = [ + [ file: "build/html5/arc42-template-de.html" ], + ] + + // endpoint of the confluenceAPI (REST) to be used + // if you use Confluence Cloud, you can set this value to + // https://[yourServer] + // a working example is https://arc42-template.atlassian.net + // if you use Confluence Server, you may need to set a context: + // https://[yourServer]/[context] + // a working example is https://arc42-template.atlassian.net/wiki + api = 'https://[yourServer]/[context]' + + // if true API V1 only will be used. Default is true. + // useV1Api = true + + // if true, the new editor v2 will be used. Default is false. + // enforceNewEditor = false + + // Additionally, spaceKey, subpagesForSections, pagePrefix and pageSuffix can be globally defined here. The assignment in the input array has precedence + + // the key of the confluence space to write to + spaceKey = 'asciidoc' + + // if true, all pages will be created using the new editor v2 + // enforceNewEditor = false + + // variable to determine how many layers of sub pages should be created + subpagesForSections = 1 + + // the pagePrefix will be a prefix for each page title + // use this if you only have access to one confluence space but need to store several + // pages with the same title - a different pagePrefix will make them unique + pagePrefix = '' + + pageSuffix = '' + + // the comment used for the page version + pageVersionComment = '' + + /* + WARNING: It is strongly recommended to store credentials securely instead of commiting plain text values to your git repository!!! + + Tool expects credentials that belong to an account which has the right permissions to to create and edit confluence pages in the given space. + Credentials can be used in a form of: + - passed parameters when calling script (-PconfluenceUser=myUsername -PconfluencePass=myPassword) which can be fetched as a secrets on CI/CD or + - gradle variables set through gradle properties (uses the 'confluenceUser' and 'confluencePass' keys) + Often, same credentials are used for Jira & Confluence, in which case it is recommended to pass CLI parameters for both entities as + -Pusername=myUser -Ppassword=myPassword + */ + + //optional API-token to be added in case the credentials are needed for user and password exchange. + //apikey = "[API-token]" + + // HTML Content that will be included with every page published + // directly after the TOC. If left empty no additional content will be + // added + // extraPageContent = 'This is a generated page, do not edit! + extraPageContent = '' + + // enable or disable attachment uploads for local file references + enableAttachments = false + + // variable to limit number of pages retreived per REST-API call + pageLimit = 100 + + // default attachmentPrefix = attachment - All files to attach will require to be linked inside the document. + // attachmentPrefix = "attachment" + + + // Optional proxy configuration, only used to access Confluence + // schema supports http and https + // proxy = [host: 'my.proxy.com', port: 1234, schema: 'http'] + + // Optional: specify which Confluence OpenAPI Macro should be used to render OpenAPI definitions + // possible values: ["confluence-open-api", "open-api", true]. true is the same as "confluence-open-api" for backward compatibility + // useOpenapiMacro = "confluence-open-api" + + // for exportConfluence-Task + export = [ + srcDir: 'sample_data', + destDir: 'src/docs' + ] + +} +//end::confluenceConfig[] + +//***************************************************************************************** +//tag::exportEAConfig[] +//Configuration for the export script 'exportEA.vbs'. +// The following parameters can be used to change the default behaviour of 'exportEA'. +// All parameter are optionally. +// Parameter 'connection' allows to select a certain database connection by using the ConnectionString as used for +// directly connecting to the project database instead of looking for EAP/EAPX files inside and below the 'src' folder. +// Parameter 'packageFilter' is an array of package GUID's to be used for export. All images inside and in all packages below the package represented by its GUID are exported. +// A packageGUID, that is not found in the currently opened project, is silently skipped. +// PackageGUID of multiple project files can be mixed in case multiple projects have to be opened. + +exportEA.with { +// OPTIONAL: Set the connection to a certain project or comment it out to use all project files inside the src folder or its child folder. +// connection = "DBType=1;Connect=Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=[THE_DB_NAME_OF_THE_PROJECT];Data Source=[server_hosting_database.com];LazyLoad=1;" +// OPTIONAL: Add one or multiple packageGUIDs to be used for export. All packages are analysed, if no packageFilter is set. +// packageFilter = [ +// "{A237ECDE-5419-4d47-AECC-B836999E7AE0}", +// "{B73FA2FB-267D-4bcd-3D37-5014AD8806D6}" +// ] +// OPTIONAL: relative path to base 'docDir' to which the diagrams and notes are to be exported +// exportPath = "src/docs/" +// OPTIONAL: relative path to base 'docDir', in which Enterprise Architect project files are searched +// searchPath = "src/docs/" + +} +//end::exportEAConfig[] + +//tag::htmlSanityCheckConfig[] +htmlSanityCheck.with { + //sourceDir = "build/html5/site" + //checkingResultsDir = +} +//end::htmlSanityCheckConfig[] + +//tag::jiraConfig[] +// Configuration for Jira related tasks +jira = [:] + +jira.with { + + // endpoint of the JiraAPI (REST) to be used + api = 'https://your-jira-instance' + + /* + WARNING: It is strongly recommended to store credentials securely instead of commiting plain text values to your git repository!!! + + Tool expects credentials that belong to an account which has the right permissions to read the JIRA issues for a given project. + Credentials can be used in a form of: + - passed parameters when calling script (-PjiraUser=myUsername -PjiraPass=myPassword) which can be fetched as a secrets on CI/CD or + - gradle variables set through gradle properties (uses the 'jiraUser' and 'jiraPass' keys) + Often, Jira & Confluence credentials are the same, in which case it is recommended to pass CLI parameters for both entities as + -Pusername=myUser -Ppassword=myPassword + */ + + // the key of the Jira project + project = 'PROJECTKEY' + + // the format of the received date time values to parse + dateTimeFormatParse = "yyyy-MM-dd'T'H:m:s.SSSz" // i.e. 2020-07-24'T'9:12:40.999 CEST + + // the format in which the date time should be saved to output + dateTimeFormatOutput = "dd.MM.yyyy HH:mm:ss z" // i.e. 24.07.2020 09:02:40 CEST + + // the label to restrict search to + label = + + // Legacy settings for Jira query. This setting is deprecated & support for it will soon be completely removed. Please use JiraRequests settings + //jql = "project='%jiraProject%' AND labels='%jiraLabel%' ORDER BY priority DESC, duedate ASC" + + // Base filename in which Jira query results should be stored + resultsFilename = 'JiraTicketsContent' + + saveAsciidoc = true // if true, asciidoc file will be created with *.adoc extension + saveExcel = true // if true, Excel file will be created with *.xlsx extension + + // Output folder for this task inside main outputPath + resultsFolder = 'JiraRequests' + + /* + List of requests to Jira API: + These are basically JQL expressions bundled with a filename in which results will be saved. + User can configure custom fields IDs and name those for column header, + i.e. customfield_10026:'Story Points' for Jira instance that has custom field with that name and will be saved in a coloumn named "Story Points" + */ + requests = [ + new JiraRequest( + filename:"File1_Done_issues", + jql:"project='%jiraProject%' AND status='Done' ORDER BY duedate ASC", + customfields: [customfield_10026:'Story Points'] + ), + new JiraRequest( + filename:'CurrentSprint', + jql:"project='%jiraProject%' AND Sprint in openSprints() ORDER BY priority DESC, duedate ASC", + customfields: [customfield_10026:'Story Points'] + ), + ] +} + +@groovy.transform.Immutable +class JiraRequest { + String filename //filename (without extension) of the file in which JQL results will be saved. Extension will be determined automatically for Asciidoc or Excel file + String jql // Jira Query Language syntax + Map customfields // map of customFieldId:displayName values for Jira fields which don't have default names, i.e. customfield_10026:StoryPoints +} +//end::jiraConfig[] + +//tag::openApiConfig[] +// Configuration for OpenAPI related task +openApi = [:] + +// 'specFile' is the name of OpenAPI specification yaml file. Tool expects this file inside working dir (as a filename or relative path with filename) +// 'infoUrl' and 'infoEmail' are specification metadata about further info related to the API. By default this values would be filled by openapi-generator plugin placeholders +// + +openApi.with { + specFile = 'src/docs/petstore-v2.0.yaml' // i.e. 'petstore.yaml', 'src/doc/petstore.yaml' + infoUrl = 'https://my-api.company.com' + infoEmail = 'info@company.com' +} +//end::openApiConfig[] + +//tag::sprintChangelogConfig[] +// Sprint changelog configuration generate changelog lists based on tickets in sprints of an Jira instance. +// This feature requires at least Jira API & credentials to be properly set in Jira section of this configuration +sprintChangelog = [:] +sprintChangelog.with { + sprintState = 'closed' // it is possible to define multiple states, i.e. 'closed, active, future' + ticketStatus = "Done, Closed" // it is possible to define multiple ticket statuses, i.e. "Done, Closed, 'in Progress'" + + showAssignee = false + showTicketStatus = false + showTicketType = true + sprintBoardId = 12345 // Jira instance probably have multiple boards; here it can be defined which board should be used + + // Output folder for this task inside main outputPath + resultsFolder = 'Sprints' + + // if sprintName is not defined or sprint with that name isn't found, release notes will be created on for all sprints that match sprint state configuration + sprintName = 'PRJ Sprint 1' // if sprint with a given sprintName is found, release notes will be created just for that sprint + allSprintsFilename = 'Sprints_Changelogs' // Extension will be automatically added. +} +//end::sprintChangelogConfig[] + +//tag::collectIncludesConfig[] +collectIncludes = [:] + +collectIncludes.with { + + fileFilter = "adoc" // define which files are considered. default: "ad|adoc|asciidoc" + + minPrefixLength = "3" // define what minimum length the prefix. default: "3" + + maxPrefixLength = "3" // define what maximum length the prefix. default: "" + + separatorChar = "_" // define the allowed separators after prefix. default: "-_" + + cleanOutputFolder = true // should the output folder be emptied before generation? default: false + + excludeDirectories = [] // define additional directories that should not be traversed. + +} +//end::collectIncludesConfig[] + +//tag::structurizrConfig[] +// Configuration for Structurizr related tasks +structurizr = [:] + +structurizr.with { + + // Configure where `exportStructurizr` looks for the Structurizr model. + workspace = { + // The directory in which the Structurizr workspace file is located. + // path = 'src/docs/structurizr' + + // By default `exportStructurizr` looks for a file '${structurizr.workspace.path}/workspace.dsl'. + // You can customize this behavior with 'filename'. Note that the workspace filename is provided without '.dsl' extension. + // filename = 'workspace' + } + + export = { + // Directory for the exported diagrams. + // + // WARNING: Do not put manually created/changed files into this directory. + // If a valid Structurizr workspace file is found the directory is deleted before the diagram files are generated. + // outputPath = 'src/docs/structurizr/diagrams' + + // Format of the exported diagrams. Defaults to 'plantuml' if the parameter is not provided. + // + // Following formats are supported: + // - 'plantuml': the same as 'plantuml/structurizr' + // - 'plantuml/structurizr': exports views to PlantUML + // - 'plantuml/c4plantuml': exports views to PlantUML with https://github.com/plantuml-stdlib/C4-PlantUML + // format = 'plantuml' + } +} +//end::structurizrConfig[] + +//tag::openAIConfig[] +// Configuration for openAI related tasks +openAI = [:] + +openAI.with { + // This task requires a person access token for openAI. + // Ensure to pass this token as parameters when calling the task + // using -PopenAI.token=xx-xxxxxxxxxxxxxx + + //model = "text-davinci-003" + //maxToken = '500' + //temperature = '0.3' +} +//end::openAIConfig[] diff --git a/documentation/arc42/.asciidoctorconfig.adoc b/documentation/arc42/.asciidoctorconfig.adoc new file mode 100644 index 0000000..e0bfb91 --- /dev/null +++ b/documentation/arc42/.asciidoctorconfig.adoc @@ -0,0 +1,2 @@ +:imagesdir: ../images + diff --git a/documentation/arc42/arc42.adoc b/documentation/arc42/arc42.adoc new file mode 100644 index 0000000..d40f567 --- /dev/null +++ b/documentation/arc42/arc42.adoc @@ -0,0 +1,93 @@ +:imagesdir: ../images +:jbake-menu: - +// header file for arc42-template, +// including all help texts +// +// ==================================== + +// configure EN settings for asciidoc +include::chapters/config.adoc[] + += image:arc42-logo.png[arc42] Template +:revnumber: 8.2 EN +:revdate: January 2023 +:revremark: (based upon AsciiDoc version) +// toc-title definition MUST follow document title without blank line! +:toc-title: Table of Contents + +//additional style for arc42 help callouts +ifdef::backend-html5[] +++++ + +++++ +endif::backend-html5[] + + +include::chapters/about-arc42.adoc[] + +// horizontal line +*** + + + + +// numbering from here on +:numbered: + +<<<< +// 1. Introduction and Goals +include::chapters/01_introduction_and_goals.adoc[] + +<<<< +// 2. Architecture Constraints +include::chapters/02_architecture_constraints.adoc[] + +<<<< +// 3. System Scope and Context +include::chapters/03_system_scope_and_context.adoc[] + +<<<< +// 4. Solution Strategy +include::chapters/04_solution_strategy.adoc[] + +<<<< +// 5. Building Block View +include::chapters/05_building_block_view.adoc[] + +<<<< +// 6. Runtime View +include::chapters/06_runtime_view.adoc[] + +<<<< +// 7. Deployment View +include::chapters/07_deployment_view.adoc[] + +<<<< +// 8. Concepts +include::chapters/08_concepts.adoc[] + +<<<< +// 9. Architecture Decisions +include::chapters/09_architecture_decisions.adoc[] + +<<<< +// 10. Quality Requirements +include::chapters/10_quality_requirements.adoc[] + +<<<< +// 11. Technical Risks +include::chapters/11_technical_risks.adoc[] + +<<<< +// 12. Glossary +include::chapters/12_glossary.adoc[] + + diff --git a/documentation/arc42/chapters/.asciidoctorconfig.adoc b/documentation/arc42/chapters/.asciidoctorconfig.adoc new file mode 100644 index 0000000..f513441 --- /dev/null +++ b/documentation/arc42/chapters/.asciidoctorconfig.adoc @@ -0,0 +1,2 @@ +:imagesdir: ../../images + diff --git a/documentation/arc42/chapters/01_introduction_and_goals.adoc b/documentation/arc42/chapters/01_introduction_and_goals.adoc new file mode 100644 index 0000000..0ed840f --- /dev/null +++ b/documentation/arc42/chapters/01_introduction_and_goals.adoc @@ -0,0 +1,35 @@ +:jbake-title: Introduction and Goals +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 1 +:filename: /chapters/01_introduction_and_goals.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-introduction-and-goals]] +== Introduction and Goals + + + +=== Requirements Overview + + + +=== Quality Goals + + + +=== Stakeholders + + + +[options="header",cols="1,2,2"] +|=== +|Role/Name|Contact|Expectations +| __ | __ | __ +| __ | __ | __ +|=== diff --git a/documentation/arc42/chapters/02_architecture_constraints.adoc b/documentation/arc42/chapters/02_architecture_constraints.adoc new file mode 100644 index 0000000..e29c547 --- /dev/null +++ b/documentation/arc42/chapters/02_architecture_constraints.adoc @@ -0,0 +1,17 @@ +:jbake-title: Architecture Constraints +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 2 +:filename: /chapters/02_architecture_constraints.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-architecture-constraints]] +== Architecture Constraints + + + diff --git a/documentation/arc42/chapters/03_system_scope_and_context.adoc b/documentation/arc42/chapters/03_system_scope_and_context.adoc new file mode 100644 index 0000000..d4922c8 --- /dev/null +++ b/documentation/arc42/chapters/03_system_scope_and_context.adoc @@ -0,0 +1,36 @@ +:jbake-title: System Scope and Context +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 3 +:filename: /chapters/03_system_scope_and_context.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-system-scope-and-context]] +== System Scope and Context + + + + + +=== Business Context + + + +**** + +**** + +=== Technical Context + + + +**** + +**** + +**** diff --git a/documentation/arc42/chapters/04_solution_strategy.adoc b/documentation/arc42/chapters/04_solution_strategy.adoc new file mode 100644 index 0000000..dfd51ec --- /dev/null +++ b/documentation/arc42/chapters/04_solution_strategy.adoc @@ -0,0 +1,17 @@ +:jbake-title: Solution Strategy +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 4 +:filename: /chapters/04_solution_strategy.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-solution-strategy]] +== Solution Strategy + + + diff --git a/documentation/arc42/chapters/05_building_block_view.adoc b/documentation/arc42/chapters/05_building_block_view.adoc new file mode 100644 index 0000000..41502c4 --- /dev/null +++ b/documentation/arc42/chapters/05_building_block_view.adoc @@ -0,0 +1,121 @@ +:jbake-title: Building Block View +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 5 +:filename: /chapters/05_building_block_view.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-building-block-view]] + + +== Building Block View + + + +=== Whitebox Overall System + + + +_****_ + +Motivation:: + +__ + + +Contained Building Blocks:: +__ + +Important Interfaces:: +__ + + + + +==== + + + +__ + +__ + +_<(Optional) Quality/Performance Characteristics>_ + +_<(Optional) Directory/File Location>_ + +_<(Optional) Fulfilled Requirements>_ + +_<(optional) Open Issues/Problems/Risks>_ + + + + +==== + +__ + +==== + +__ + + +==== + +... + +==== + + + +=== Level 2 + + + +==== White Box __ + + + +__ + +==== White Box __ + + +__ + +... + +==== White Box __ + + +__ + + + +=== Level 3 + + + + +==== White Box <_building block x.1_> + + + + +__ + + +==== White Box <_building block x.2_> + +__ + + + +==== White Box <_building block y.1_> + +__ diff --git a/documentation/arc42/chapters/06_runtime_view.adoc b/documentation/arc42/chapters/06_runtime_view.adoc new file mode 100644 index 0000000..c5246dd --- /dev/null +++ b/documentation/arc42/chapters/06_runtime_view.adoc @@ -0,0 +1,30 @@ +:jbake-title: Runtime View +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 6 +:filename: /chapters/06_runtime_view.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-runtime-view]] +== Runtime View + + + + +=== + + +* __ +* __ + +=== + +=== ... + +=== diff --git a/documentation/arc42/chapters/07_deployment_view.adoc b/documentation/arc42/chapters/07_deployment_view.adoc new file mode 100644 index 0000000..d81d155 --- /dev/null +++ b/documentation/arc42/chapters/07_deployment_view.adoc @@ -0,0 +1,54 @@ +:jbake-title: Deployment View +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 7 +:filename: /chapters/07_deployment_view.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-deployment-view]] + + +== Deployment View + + + +=== Infrastructure Level 1 + + + +_****_ + +Motivation:: + +__ + +Quality and/or Performance Features:: + +__ + +Mapping of Building Blocks to Infrastructure:: +__ + + +=== Infrastructure Level 2 + + + +==== __ + +__ + +==== __ + +__ + +... + +==== __ + +__ diff --git a/documentation/arc42/chapters/08_concepts.adoc b/documentation/arc42/chapters/08_concepts.adoc new file mode 100644 index 0000000..681d04c --- /dev/null +++ b/documentation/arc42/chapters/08_concepts.adoc @@ -0,0 +1,34 @@ +:jbake-title: Cross-cutting Concepts +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 8 +:filename: /chapters/08_concepts.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-concepts]] +== Cross-cutting Concepts + + + + + +=== __ + +__ + + + +=== __ + +__ + +... + +=== __ + +__ diff --git a/documentation/arc42/chapters/09_architecture_decisions.adoc b/documentation/arc42/chapters/09_architecture_decisions.adoc new file mode 100644 index 0000000..96d18d2 --- /dev/null +++ b/documentation/arc42/chapters/09_architecture_decisions.adoc @@ -0,0 +1,17 @@ +:jbake-title: Architecture Decisions +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 9 +:filename: /chapters/09_architecture_decisions.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-design-decisions]] +== Architecture Decisions + + + diff --git a/documentation/arc42/chapters/10_quality_requirements.adoc b/documentation/arc42/chapters/10_quality_requirements.adoc new file mode 100644 index 0000000..076f177 --- /dev/null +++ b/documentation/arc42/chapters/10_quality_requirements.adoc @@ -0,0 +1,25 @@ +:jbake-title: Quality Requirements +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 10 +:filename: /chapters/10_quality_requirements.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-quality-scenarios]] +== Quality Requirements + + + + +=== Quality Tree + + + +=== Quality Scenarios + + diff --git a/documentation/arc42/chapters/11_technical_risks.adoc b/documentation/arc42/chapters/11_technical_risks.adoc new file mode 100644 index 0000000..7de0e1b --- /dev/null +++ b/documentation/arc42/chapters/11_technical_risks.adoc @@ -0,0 +1,17 @@ +:jbake-title: Risks and Technical Debts +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 11 +:filename: /chapters/11_technical_risks.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-technical-risks]] +== Risks and Technical Debts + + + diff --git a/documentation/arc42/chapters/12_glossary.adoc b/documentation/arc42/chapters/12_glossary.adoc new file mode 100644 index 0000000..031b6d9 --- /dev/null +++ b/documentation/arc42/chapters/12_glossary.adoc @@ -0,0 +1,27 @@ +:jbake-title: Glossary +:jbake-type: page_toc +:jbake-status: published +:jbake-menu: arc42 +:jbake-order: 12 +:filename: /chapters/12_glossary.adoc +ifndef::imagesdir[:imagesdir: ../../images] + +:toc: + + + +[[section-glossary]] +== Glossary + + + +[cols="e,2e" options="header"] +|=== +|Term |Definition + +| +| + +| +| +|=== diff --git a/documentation/arc42/chapters/about-arc42.adoc b/documentation/arc42/chapters/about-arc42.adoc new file mode 100644 index 0000000..a9d3ae4 --- /dev/null +++ b/documentation/arc42/chapters/about-arc42.adoc @@ -0,0 +1,15 @@ +:homepage: https://arc42.org + +:keywords: software-architecture, documentation, template, arc42 + +:numbered!: +**About arc42** + +[role="lead"] +arc42, the template for documentation of software and system architecture. + +Template Version {revnumber}. {revremark}, {revdate} + +Created, maintained and (C) by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. +See https://arc42.org. + diff --git a/documentation/arc42/chapters/config.adoc b/documentation/arc42/chapters/config.adoc new file mode 100644 index 0000000..e664e4f --- /dev/null +++ b/documentation/arc42/chapters/config.adoc @@ -0,0 +1,9 @@ +// asciidoc settings for EN (English) +// ================================== +:toc-title: table of contents + +// enable table-of-contents +:toc: + +// where are images located? +:imagesdir: ../images diff --git a/documentation/images/arc42-logo.png b/documentation/images/arc42-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..88c76d06319442a14d956d2513c04a919aca0ac3 GIT binary patch literal 8151 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 literal 0 HcmV?d00001 diff --git a/dtcw b/dtcw new file mode 100755 index 0000000..bad7033 --- /dev/null +++ b/dtcw @@ -0,0 +1,640 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Copyright 2022 - 2023, Ralf D. Müller and the docToolchain contributors + +set -e +set -u +set -o pipefail + +# The main purpose of the wrapper script is to make 'docToolchain' easy to use. +# - it helps to install 'docToolchain' if not installed +# - you may manage different 'docToolchain' environments + +# See https://github.com/docToolchain/docToolchain/releases for available versions. +# Set DTC_VERSION to "latest" to get the latest, yet unreleased version. +: "${DTC_VERSION:=3.1.2}" + +# The 'generateSite' and 'copyThemes' tasks support DTC_SITETHEME, an URL of a theme. +# export DTC_SITETHEME=https://....zip + +# The 'downloadTemplate' tasks uses DTC_TEMPLATE1, DTC_TEMPLATE2, ... +# with which you can specify the location of additional templates +# export DTC_TEMPLATE1=https://....zip +# export DTC_TEMPLATE2=https://....zip + +# docToolchain configurtion file may be overruled by the user +: "${DTC_CONFIG_FILE:=docToolchainConfig.groovy}" + +# Contains the current project git branch, "-" if not available +: "${DTC_PROJECT_BRANCH:=$(git branch --show-current 2> /dev/null || echo -)}" +export DTC_PROJECT_BRANCH + +# DTC_HEADLESS is true if no STDIN is open (i.e. we have an non-interactive shell). +: "${DTC_HEADLESS:=$([ -t 0 ] && echo false || echo true)}" +export DTC_HEADLESS + +# Options passed to docToolchain +DTC_OPTS="${DTC_OPTS:-} -PmainConfigFile=${DTC_CONFIG_FILE} --warning-mode=none --no-daemon -Dfile.encoding=UTF-8 " + +# Here you find the project +GITHUB_PROJECT_URL=https://github.com/docToolchain/docToolchain +GITHUB_PROJECT_URL_SSH=git@github.com:docToolchain/docToolchain + +# Bump this version up if something is changed in the wrapper script +DTCW_VERSION=0.50 +# Template replaced by the GitHub value upon releasing dtcw +DTCW_GIT_HASH=##DTCW_GIT_HASH## + +# Exit codes +ERR_DTCW=1 +ERR_ARG=2 +ERR_CODING=3 + +main() { + # For debugging purpose at the top of the script + arch=$(uname -m) + os=$(uname -s) + bash=bash + + print_version_info + + assert_argument_exists "$@" + + [ "${1}" = "--version" ] && exit 0 + + available_environments=$(get_available_environments) + echo "Available docToolchain environments:${available_environments}" + + dtc_installations=$(get_dtc_installations "${available_environments}" "${DTC_VERSION}") + echo "Environments with docToolchain [${DTC_VERSION}]:${dtc_installations}" + + if is_supported_environment "${1}" && assert_environment_available "${1}" "${DTC_VERSION}"; then + # User enforced environment + environment=${1} + shift 1 + assert_argument_exists "$@" + else + environment=$(get_environment "$@") + fi + echo "Using environment: ${environment}" + + if [ "${1}" = "install" ]; then + install_component_and_exit "${environment}" "${2-}" + elif [ "${1}" = "getJava" ]; then + # TODO: remove getJava in the next major release + echo "Warning: 'getJava' is deprecated and and will be removed. Use './dtcw install java' instead." + install_component_and_exit "${environment}" "java" + fi + + # No install command, so forward call to docToolchain but first we check if + # everything is there. + if [[ ${environment} != docker ]]; then + assert_doctoolchain_installed "${environment}" "${DTC_VERSION}" + assert_java_version_supported + + # TODO: what if 'doctoolchain' found by $PATH does not match the one from the local environment? + # The version provided by $DTC_VERSION could be a different one. + fi + + command=$(build_command "${environment}" "${DTC_VERSION}" "$@") + + [[ "${DTC_HEADLESS}" = true ]] && echo "Using headless mode since there is no (terminal) interaction possible" + + show_os_related_info + + emu="" + if [ "${os}" = "Darwin" ] && [ "${arch}" = "arm64" ]; then + echo "Apple silicon detected, using x86_64 mode and os native bash" + emu="arch -x86_64" + bash="/bin/bash" + fi + + # echo "Command to invoke: ${command}" + exec ${emu} ${bash} -c "${command}" +} + +assert_argument_exists() { + if [[ $# -lt 1 ]]; then + error "argument missing" + usage + exit ${ERR_ARG} + fi +} + +error() { + printf "\nError: %s\n\n" "${1}" >&2 +} + +usage() { + cat < /dev/null || echo "unknown") + echo "docToolchain ${DTC_VERSION} - ${dtc_git_hash}" + else + echo "docToolchain ${DTC_VERSION}" + fi + echo "OS/arch: ${os}/${arch}" +} + +get_available_environments() { + # The local environment is alway available - even if docToolchain is not installed + local envs=" local" + + # 'sdk' is provided a bash founction - thus command doesn't work + if [ -n "${SDKMAN_DIR:-}" ] && [ -s "${SDKMAN_DIR}/bin/sdkman-init.sh" ]; then + envs+=" sdk" + fi + + if has docker; then + envs+=" docker" + fi + echo "${envs}" +} + +has() { + command -v "$1" 1>/dev/null 2>&1 +} + +get_dtc_installations() { + local envs=${1} + local version=${2} + local installations="" + + if [ -x "${DTC_HOME}/bin/doctoolchain" ]; then + installations+=" local" + fi + + if [[ "${envs}" =~ sdk ]] && sdk_home_doctoolchain "${version}" &> /dev/null ; then + installations+=" sdk" + fi + + if [[ "${envs}" =~ docker ]]; then + # Having docker installed means docToolchain is available + installations+=" docker" + fi + [ -z "${installations}" ] && installations=" none" + + echo "${installations}" +} + +sdk_home_doctoolchain() { + local version=${1} + local sdk_doctoolchain="${SDKMAN_DIR}/candidates/doctoolchain/${version}" + + # Don't use `sdk home doctoolchain ${version}` - see https://github.com/sdkman/sdkman-cli/issues/1196 + if [[ -x "${sdk_doctoolchain}/bin/doctoolchain" ]]; then + printf "%s" "${sdk_doctoolchain}" + return 0 + fi + printf "doctoolchain %s is not installed on your system" "${version}" 1>&2 + return 1 +} + +is_supported_environment() { + local supported_environments=("local" "sdk" "docker") + [[ "${supported_environments[*]}" =~ ${1} ]] +} + +assert_environment_available() { + local env=${1} + local version=${2} + # If environment not available, exit with error + if ! is_environment_available "${env}" ; then + error "argument error - environment '${env}' not available" + if [[ "${env}" == "sdk" ]]; then + printf "%s\n" \ + "Install SDKMAN! (https://sdkman.io) with" \ + "" \ + " $ curl -s \"https://get.sdkman.io\" | bash" \ + "" \ + "Then open a new shell and install 'docToolchain' with" \ + " $ sdk install doctoolchain ${version}" + else + echo "Install 'docker' on your host to execute docToolchain in a container." + fi + echo + exit ${ERR_ARG} + fi + if is_doctoolchain_development_version "${version}" && [ "${env}" != local ] ; then + error "argument error - invalid environment '${env}'." + echo "Development version '${version}' can only be used in a local environment." + echo + exit ${ERR_ARG} + fi +} + +is_environment_available() { + [[ "${available_environments}" =~ ${1} ]] +} + +is_doctoolchain_development_version() { + local version=${1} + # Is 'latest' a good name? It maybe interpreted as latest stable release. + # Alternatives: 'testing', 'dev' (used for development) + [ "${version}" == "latest" ] || [ "${version}" == "latestdev" ] +} + +# No environment provided - try to pick the right one +get_environment() { + # 'install' works only with 'local' environment + if [[ "${1}" == install ]] || [[ "${dtc_installations}" =~ none ]]; then + echo local + return + fi + + # Pick the first one which has an installed docToolchain. + # Note: the preference is defined by the order we searched for available environments. + for e in ${available_environments}; do + if is_doctoolchain_installed "${e}"; then + echo "${e}" + return + fi + done +} + +is_doctoolchain_installed() { + [[ "${dtc_installations}" =~ ${1} ]] +} + +install_component_and_exit() { + local env=${1} + local component=${2} + if [ -z "${component}" ] ; then + error_install_component_and_die "component missing" + fi + exit_code=1 + case ${env} in + local) + case ${component} in + doctoolchain) + local_install_doctoolchain "${DTC_VERSION}" + assert_java_version_supported + ;; + java) + local_install_java + ;; + *) + error_install_component_and_die "unknown component '${component}'" + ;; + esac + if ! is_doctoolchain_installed "${environment}"; then + how_to_install_doctoolchain "${DTC_VERSION}" + else + printf "%s\n" \ + "" \ + "Use './dtcw tasks --group doctoolchain' to see docToolchain related tasks." \ + "" + fi + exit_code=0 + ;; + sdk) + error "argument error - '${env} install' not supported." + printf "%s\n" \ + "To install docToolchain with SDKMAN! execute" \ + "" \ + " $ sdk install doctoolchain ${DTC_VERSION}" \ + "" + exit_code=${ERR_ARG} + ;; + docker) + error "argument error - '${env} install' not supported." + echo "Executing a task in the 'docker' environment will pull the docToolchain container image." + echo + exit_code=${ERR_ARG} + ;; + *) + echo "Coding error - not reachable" + exit ${ERR_CODING} + ;; + esac + exit ${exit_code} +} + +error_install_component_and_die() { + error "${1} - available components are 'doctoolchain', or 'java'" + printf "%s\n" \ + "Use './dtcw local install doctoolchain' to install docToolchain ${DTC_VERSION}." \ + "Use './dtcw local install java' to install a Java version supported by docToolchain." \ + "" + exit ${ERR_ARG} +} + +local_install_doctoolchain() { + local version=${1} + if is_doctoolchain_development_version "${version}"; then + # User decided to pick a floating version - which means a git clone into the local environment. + assert_git_installed "Please install 'git' for working with a 'doctToolchain' development version" + + if [ -d "${DTC_HOME}/.git" ]; then + git -C "${DTC_HOME}" pull + echo "Updated docToolchain in local environment to latest version" + else + local project_url + if [ "${version}" == "latest" ]; then + project_url="${GITHUB_PROJECT_URL}" + else + project_url="${GITHUB_PROJECT_URL_SSH}" + fi + git clone "${project_url}.git" "${DTC_HOME}" + echo "Cloned docToolchain in local environment to latest version" + fi + else + if [ -x "${DTC_HOME}/bin/doctoolchain" ]; then + echo "Skipped installation of docToolchain: already installed in '${DTC_HOME}'" + return + fi + if ! has unzip; then + error "no unzip program installed, exiting…" + echo "Install 'unzip' and try to install docToolchain again." + return ${ERR_DTCW} + fi + mkdir -p "${DTC_ROOT}" + local distribution_url=${GITHUB_PROJECT_URL}/releases/download/v${version}/docToolchain-${version}.zip + download_file "${distribution_url}" "${DTC_ROOT}/source.zip" + unzip -q "${DTC_ROOT}/source.zip" -d "${DTC_ROOT}" + rm -f "${DTC_ROOT}/source.zip" + echo "Installed docToolchain successfully in '${DTC_HOME}'." + fi + + # Add it to the existing installations so the output to guide the user can adjust accordingly. + dtc_installations+=" local" +} + +assert_git_installed() { + has git && return + + error "git - command not found" + echo "${1}" + echo + exit ${ERR_DTCW} +} + +download_file() { + local url=${1} + local file=${2} + + if has curl; then + cmd="curl --fail --location --output $file $url" + elif has wget; then + # '--show-progress' is not supported in all wget versions (busybox) + cmd="wget --quiet --show-progress --output-document=$file $url" + elif has fetch; then + cmd="fetch --quiet --output=$file $url" + else + error "no HTTP download program (curl, wget, fetch) found, exiting…" + echo "Install either 'curl', 'wget', or 'fetch' and try to install docToolchain again." + return ${ERR_DTCW} + fi + + $cmd && return 0 || rc=$? + + error "Command failed (exit code $rc): ${cmd}" + return "${rc}" +} + +assert_java_version_supported() { + # Defines the order in which Java is searched. + if [ -d "${DTC_JAVA_HOME}" ]; then + echo "Caution: Your JAVA_HOME setting is overriden by DTCs own JDK install (for this execution)" + if [ -d "${DTC_JAVA_HOME}/Contents" ]; then + # JDK for MacOS have a different structure + JAVA_HOME="${DTC_JAVA_HOME}/Contents/Home" + else + JAVA_HOME="${DTC_JAVA_HOME}" + fi + export JAVA_HOME + DTC_OPTS="${DTC_OPTS} '-Dorg.gradle.java.home=${JAVA_HOME}'" + JAVA_CMD="${JAVA_HOME}/bin/java" + elif [ -n "${JAVA_HOME-}" ]; then + JAVA_CMD="${JAVA_HOME}/bin/java" + else + # Don't provide JAVA_HOME if java is used by PATH. + JAVA_CMD=$(command -v java 2>/dev/null) || true + fi + if [ -z "${JAVA_CMD-}" ] || ! java_version=$("${JAVA_CMD}" -version 2>&1) ; then + error "unable to locate a Java Runtime" + java_help_and_die + fi + + # We got a Java version + java_version=$(echo "$java_version" | awk -F '"' '/version/ {print $0}' | head -1 | cut -d'"' -f2) + major_version=$(echo "$java_version" | sed '/^1\./s///' | cut -d'.' -f1) + + if [ "${major_version}" -ge 11 ] && [ "${major_version}" -le 17 ]; then + echo "Using Java ${java_version} [${JAVA_CMD}]" + return + fi + + error "unsupported Java version ${major_version} [${JAVA_CMD}]" + java_help_and_die +} + +java_help_and_die() { + printf "%s\n" \ + "docToolchain supports Java versions 11, 14, or 17 (preferred). In case one of those" \ + "Java versions is installed make sure 'java' is found with your PATH environment" \ + "variable. As alternative you may provide the location of your Java installation" \ + "with JAVA_HOME." \ + "" \ + "Apart from installing Java with the package manager provided by your operating" \ + "system, dtcw facilitates the Java installation into a local environment:" \ + "" \ + " # Install Java in '${DTC_JAVA_HOME}'" \ + " $ ./dtcw local install java" \ + "" \ + "Alternatively you can use SDKMAN! (https://sdkman.io) to manage your Java installations" \ + "" + if ! is_environment_available sdk; then + how_to_install_sdkman "Java 17" + fi + # TODO: This will break when we change Java version + printf "%s\n" \ + " $ sdk install java 17.0.7-tem" \ + "" \ + "If you prefer not to install Java on your host, you can run docToolchain in a" \ + "docker container. For this case dtcw provides the 'docker' execution environment." \ + "" \ + "Example: ./dtcw docker generateSite"\ + "" + exit ${ERR_DTCW} +} + +how_to_install_sdkman() { + printf "%s\n" \ + " # First install SDKMAN!" \ + " $ curl -s \"https://get.sdkman.io\" | bash" \ + " # Then open a new shell and install ${1} with" +} + +local_install_java() { + version=17 + implementation=hotspot + heapsize=normal + imagetype=jdk + releasetype=ga + + case "${arch}" in + x86_64) arch=x64 ;; + arm64) arch=aarch64 ;; + esac + if [[ ${os} == MINGW* ]]; then + error "MINGW64 is not supported" + echo "Please use powershell or WSL" + exit 1 + fi + case "${os}" in + Linux) os=linux ;; + Darwin) os=mac ;; + Cygwin) os=linux ;; + esac + mkdir -p "${DTC_JAVA_HOME}" + echo "Downloading JDK Temurin ${version} [${os}/${arch}] from Adoptium to ${DTC_JAVA_HOME}/jdk.tar.gz" + local adoptium_java_url="https://api.adoptium.net/v3/binary/latest/${version}/${releasetype}/${os}/${arch}/${imagetype}/${implementation}/${heapsize}/eclipse?project=jdk" + download_file "${adoptium_java_url}" "${DTC_JAVA_HOME}/jdk.tar.gz" + echo "Extracting JDK from archive file." + # TODO: should we not delete a previsouly installed on? + # Otherwise we may get a mix of different Java versions. + tar -zxf "${DTC_JAVA_HOME}/jdk.tar.gz" --strip 1 -C "${DTC_JAVA_HOME}/." + rm -f "${DTC_JAVA_HOME}/jdk/jdk.tar.gz" + + echo "Successfully installed Java in '${DTC_JAVA_HOME}'." + echo +} + +assert_doctoolchain_installed() { + local env=${1} + local version=${2} + if ! is_doctoolchain_installed "${env}"; then + # We reach this point if the user executes a command in an + # environment where docToolchain is not installed. + # Note that 'docker' always has a command (no instalation required) + error "doctoolchain - command not found [environment '${env}']" + how_to_install_doctoolchain "${version}" + exit ${ERR_DTCW} + fi +} + +how_to_install_doctoolchain() { + local version=${1} + printf "%s\n" \ + "It seems docToolchain ${version} is not installed. dtcw supports the" \ + "following docToolchain environments:" \ + "" \ + "1. 'local': to install docToolchain in [${DTC_ROOT}] use" \ + "" \ + " $ ./dtcw local install doctoolchain" \ + "" \ + "2. 'sdk': to install docToolchain with SDKMAN! (https://sdkman.io)" \ + "" + if ! is_environment_available sdk; then + how_to_install_sdkman docToolchain + fi + printf "%s\n" \ + " \$ sdk install doctoolchain ${version}" \ + "" \ + "Note that running docToolchain in 'local' or 'sdk' environment needs a" \ + "Java runtime (major version 11, 14, or 17) installed on your host." \ + "" \ + "3. 'docker': pull the docToolchain image and execute docToolchain in a container environment." \ + "" \ + " \$ ./dtcw docker tasks --group doctoolchain" \ + "" +} + +build_command() { + local env=${1} + local version=${2} + shift 2 + local cmd + if [ "${env}" = docker ]; then + # TODO: DTC_PROJECT_BRANCH is not passed into the docker environment + # See https://github.com/docToolchain/docToolchain/issues/1087 + + local container_name=doctoolchain-${version} + container_name+="-$(date '+%Y%m%d_%H%M%S')" + pwd=$(has cygpath && cygpath -w "${PWD}" || echo "${PWD}") + docker_args="run --rm -i --platform linux/amd64 -u $(id -u):$(id -g) --name ${container_name} \ + -e DTC_HEADLESS=true -e DTC_SITETHEME -e DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH} -p 8042:8042 \ + --entrypoint /bin/bash -v '${pwd}:/project' doctoolchain/doctoolchain:v${version}" + + cmd="docker ${docker_args} -c \"doctoolchain . ${*} ${DTC_OPTS} && exit\"" + else + # TODO: What is this good for? Has probably to do with Docker image creation. + if [[ "${DTC_HEADLESS}" = false ]]; then + # important for the docker file to find dependencies + DTC_OPTS="${DTC_OPTS} '-Dgradle.user.home=${DTC_ROOT}/.gradle'" + fi + if [ "${env}" = local ]; then + cmd="${DTC_HOME}/bin/doctoolchain . ${*} ${DTC_OPTS}" + else + cmd="$(sdk_home_doctoolchain "${version}")/bin/doctoolchain . ${*} ${DTC_OPTS}" + fi + fi + echo "${cmd}" +} + +show_os_related_info() { + + # check if we are running on WSL + if grep -qsi 'microsoft' /proc/version &> /dev/null ; then + # TODO: bug - This URL leads to now-where! + printf "%s\n" \ + "" \ + "Bash is running on WSL which might cause problems with plantUML." \ + "See https://doctoolchain.org/docToolchain/v2.0.x/010_manual/50_Frequently_asked_Questions.html#wsl for more details." \ + "" + fi +} + +# Location where local installations are placed. +DTC_ROOT="${HOME}/.doctoolchain" + +# More than one docToolchain version may be installed locally. +# This is the directory for the specific version. +DTC_HOME="${DTC_ROOT}/docToolchain-${DTC_VERSION}" + +# Directory for local Java installation +DTC_JAVA_HOME="${DTC_ROOT}/jdk" + +main "$@"