Execution details for MacOS on arm64 & Installation requirements for metric-gardener

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
 
 ## [unreleased] (Added 🚀 | Changed | Removed 🗑 | Fixed 🐞 | Chore 👨‍💻 👩‍💻)
 
+### Chore 👨‍💻 👩‍💻
+
+-   Add documentation for the installation requirements for metric-gardener [#3395](https://github.com/MaibornWolff/codecharta/pull/3395)
+-   Add hints to README (visualization and package) about MacOS arm64 standalone execution [#3395](https://github.com/MaibornWolff/codecharta/pull/3395)
+
 ## [1.120.0] - 2023-11-02
 
 ### Added 🚀

analysis/README.md

@@ -66,7 +66,7 @@ You can start with **Codecharta Analysis** on multiple ways:
 
 ## Installation via npm
 
-This installs all binaries to run the analysis. Java 11 is recommended, while Java 8 is still supported.
+This installs all binaries to run the analysis. Java 11 is recommended, while Java 8 might work.
 
 `npm install -g codecharta-analysis`
 
@@ -99,6 +99,13 @@ To containerize the analysis, please follow the below listed steps.
 
 # Build it yourself
 
+There are some additional requirements if you want to build it yourself:
+
+-   NodeJS
+-   Metric-Gardener:
+-   -   Python
+-   -   C/C++ compiler toolchain (e.g. Visual Studio Build Tools 2022 with "Desktop development with C++")
+
 ## Build
 
 Via gradle:

analysis/import/MetricGardenerImporter/README.md

@@ -9,8 +9,25 @@ For more information on MetricGardener, like the supported languages, and comman
 [README](https://github.com/MaibornWolff/metric-gardener#readme). You can also refer to the documentation in
 our [GitHub Pages](https://maibornwolff.github.io/codecharta/docs/metricgardener-importer)
 
-> Please note: MetricGardener is currently only compatible with NodeJS up to version 16.x. If you use NodeJS 18.x, you
-> need to install version 16.x to use MetricGardener.
+## Additional Requirements
+
+> Also refer to the [Metric-Gardener GitHub](https://github.com/MaibornWolff/metric-gardener) page, as the requirements can change
+
+If you want to execute the `metric-gardener`, either with your own installation or indirectly through the `ccsh`, you need to install the additional requirements listed below:
+
+### Windows
+
+-   Python
+-   C/C++ compiler toolchain (e.g. Visual Studio Build Tools 2022 with "Desktop development with C++")
+
+> You might need to install additional packages to python depending on its version. Please refer to the node-gyp GitHub page for help.
+
+### Unix
+
+-   Python
+-   C/C++ compiler toolchain
+
+> Those tools could be an included in your distribution of linux (or your version of MacOS).
 
 ## Supported Metrics
 
@@ -37,17 +54,19 @@ our [GitHub Pages](https://maibornwolff.github.io/codecharta/docs/metricgardener
 
 ## Examples
 
-### Create a CodeCharta json file from local source code (metric-gardener is executed internally on the fly):
+### Create a CodeCharta json file from local source code (metric-gardener is located/installed and executed internally on the fly):
 
 ```
 ccsh metricgardenerimport /path/to/source/code -o outfile.cc.json
 ```
 
 ### Create a CodeCharta json file by importing a given metric-gardener json file (run MetricGardener yourself):
 
-For this MetricGardener needs to be installed on your system. Install it with `npm i -g metric-gardener`
+In this case you need to use the metric-gardener beforehand (you can install it via `npm i -g metric-gardener`)
 
 ```
+# Parsing your source code with metric-gardener directly
 npx metric-gardener parse /path/to/source/code -o mg_results.json
+# Parsing the metric-gardener results with the cchs to produce a .cc.json
 ccsh metricgardenerimport mg_results.json --is-json-file -o outfile.cc.json
 ```

gh-pages/_docs/01-03-installation.md

@@ -113,3 +113,16 @@ cd codecharta-analysis/bin
 cd codecharta-visualization
 # Start visualization with the provided executable
 ```
+
+### MacOS
+
+> If you get an error on MacOS because of a missing license, try this [apple support article](https://support.apple.com/en-gb/guide/mac-help/mh40616/12.0/mac/12.0) <br>
+> You may be required to give the application executable rights
+
+> If you are using an M1 or similar (arm64) architectures you might need to do additional steps, because the OS might flag the executable as damaged, if it is downloaded and from an unverified developer:
+
+-   Remove the 'downloaded' attributes from the OS:
+
+```bash
+xattr -cr codecharta-visualization.app/
+```

gh-pages/_docs/04-13-metricgardener.md

@@ -11,8 +11,25 @@ file.
 For more information on MetricGardener, like the supported languages, and command line options, refer to its
 [README](https://github.com/MaibornWolff/metric-gardener#readme).
 
-> Please note: MetricGardener is currently only compatible with NodeJS up to version 16.x. If you use NodeJS 18.x, you
-> need to install version 16.x to use MetricGardener.
+## Additional Requirements
+
+> Also refer to the [Metric-Gardener GitHub](https://github.com/MaibornWolff/metric-gardener) page, as the requirements can change
+
+If you want to execute the `metric-gardener`, either with your own installation or indirectly through the `ccsh`, you need to install the additional requirements listed below:
+
+### Windows
+
+-   Python
+-   C/C++ compiler toolchain (e.g. Visual Studio Build Tools 2022 with "Desktop development with C++")
+
+> You might need to install additional packages to python depending on its version. Please refer to the node-gyp GitHub page for help.
+
+### Unix
+
+-   Python
+-   C/C++ compiler toolchain
+
+> Those tools could be an included in your distribution of linux (or your version of MacOS).
 
 ## Supported Metrics
 

gh-pages/_docs/07-01-new-to-code.md

@@ -55,7 +55,7 @@ There are a few issues regularly occurring when trying to start contributing. Th
 
 ### Analysis
 
-1. First build fails on new setup: One of our parsers depends on MetricGardener which is a multi-language parser to calculate metrics for a variety of languages. Therefore, make sure to install MetricGardener before trying to build the project. Also make sure that `metric-gardener` is available in your CLI. You can find more information on the documentation page about the [MetricGardenerImporter]({{site.baseurl}}{% link _docs/04-13-metricgardener.md %}).
+1. First build fails on new setup: One of our parsers depends on MetricGardener which is a multi-language parser to calculate metrics for a variety of languages. Therefore, make sure to install MetricGardener before trying to build the project. Also make sure that `metric-gardener` is available in your CLI, else npm will try to install it on the fly. You can find more information on the documentation page about the [MetricGardenerImporter]({{site.baseurl}}{% link _docs/04-13-metricgardener.md %}).
 
 # Further documentation
 

visualization/README.md

@@ -43,9 +43,16 @@ $ codecharta-visualization
 -   Download the correct standalone version for your OS from the [latest release page](https://github.com/MaibornWolff/codecharta/releases) under 'Assets'
 -   Extract & run the application
 
+### MacOS
+
 > If you get an error on MacOS because of a missing license, try this [apple support article](https://support.apple.com/en-gb/guide/mac-help/mh40616/12.0/mac/12.0) <br>
 > You may be required to give the application executable rights
 
+> If you are using an M1 or similar (arm64) architectures you might need to do additional steps, because the OS might flag the executable as damaged, if it is downloaded and from an unverified developer:
+
+-   Remove the 'downloaded' attributes from the OS:
+    `$ xattr -cr codecharta-visualization.app/`
+
 ## Build it yourself
 
 > To clone and run this application, you'll need [Git](https://git-scm.com) and [Node.js](https://nodejs.org/en/download/) (version >=16) installed

visualization/script/appBuild.js

@@ -4,7 +4,7 @@ const packager = require("electron-packager")
 const path = require("node:path")
 
 const { paths } = require("./appConfig.json")
-const { cleanDirectory } = require("./appUtils.js")
+const { cleanDirectory, createDarwinArmREADME } = require("./appUtils.js")
 
 async function bundleElectronApp(options) {
 	return packager({
@@ -18,9 +18,9 @@ async function bundleElectronApp(options) {
 async function buildElectronApps(version, distributions, downloadPath) {
 	const bundlePromises = []
 
-	for (aPlatform in distributions) {
+	for (let aPlatform in distributions) {
 		let allArchitectures = distributions[aPlatform]
-		allArchitectures.forEach(async anArchitecture => {
+		for (const anArchitecture of allArchitectures) {
 			bundlePromises.push(
 				bundleElectronApp({
 					platform: aPlatform,
@@ -31,7 +31,7 @@ async function buildElectronApps(version, distributions, downloadPath) {
 					out: paths.applicationPath
 				})
 			)
-		})
+		}
 	}
 
 	return Promise.all(bundlePromises)
@@ -46,6 +46,8 @@ async function build(version, distributions, downloadPath) {
 module.exports = {
 	prepareApplications: async function (version, distributions, downloadPath) {
 		await build(version, distributions, downloadPath)
-		return
+		if (Object.hasOwn(distributions, "darwin")) {
+			createDarwinArmREADME(path.join(paths.applicationPath, "codecharta-visualization-darwin-arm64/", "README.md"))
+		}
 	}
 }

visualization/script/appUtils.js

@@ -2,9 +2,23 @@
 
 const fs = require("fs")
 
+const readmeInfo = `
+If you can't execute the codecharta-visualization app, you might need to remove the 'downloaded' attributes from the OS:
+
+$ xattr -cr codecharta-visualization.app/
+
+> The OS might flag the executable as damaged, if it is downloaded and from an unverified developer
+
+`
+
 function cleanDirectory(dir) {
 	fs.rmSync(dir, { recursive: true, force: true })
 	fs.mkdirSync(dir, { recursive: true })
 }
 
+function createDarwinArmREADME(filePath) {
+	fs.writeFileSync(filePath, readmeInfo, { encoding: "utf-8" })
+}
+
 module.exports.cleanDirectory = cleanDirectory
+module.exports.createDarwinArmREADME = createDarwinArmREADME