Skip to content

Commit ce7a3ab

Browse files
JohTJohT
committed
Improve getting started command line experience
1 parent 886ad51 commit ce7a3ab

File tree

4 files changed

+224
-17
lines changed

4 files changed

+224
-17
lines changed

‎GETTING_STARTED.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ This document describes the steps to get started as quickly as possible.
66

77
## 🛠 Prerequisites
88

9-
Please read through the [Prerequisites](./README.md#hammer_and_wrench-prerequisites) in the [README](./README.md) file for what is required to run the scripts.
9+
Please read through the [Prerequisites](./README.md#hammer_and_wrench-prerequisites) in the [README](./README.md) file for what is required to run the scripts or simply run the [checkCompatibility.sh](./scripts/checkCompatibility.sh) script to verify that your environment is set up correctly.
1010

1111
## The easiest way to get started
1212

@@ -40,8 +40,6 @@ Use these optional command line options as needed:
4040

4141
### 1. Setup
4242

43-
- Have a look at the [prerequisites](./README.md#hammer_and_wrench-prerequisites).
44-
4543
- Choose an initial password for Neo4j if not already done.
4644

4745
```shell
@@ -96,12 +94,18 @@ Use these optional command line options as needed:
9694
./../../scripts/analysis/analyze.sh --report Python
9795
```
9896
99-
- Graph visualizations when Node.js and npm are installed:
97+
- Graph visualizations with GraphViz installed or npx to run it indirectly:
10098
10199
```shell
102100
./../../scripts/analysis/analyze.sh --report Visualization
103101
```
104102
103+
- Markdown reports:
104+
105+
```shell
106+
./../../scripts/analysis/analyze.sh --report Markdown
107+
```
108+
105109
- All reports with Python, Conda (or venv), Node.js and npm installed:
106110
107111
```shell

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,8 @@ Here are some fully automated graph visualizations utilizing [GraphViz](https://
8585

8686
## :hammer_and_wrench: Prerequisites
8787

88+
Run [scripts/checkCompatibility.sh](./scripts/checkCompatibility.sh) to check if all required dependencies are installed and available in your environment.
89+
8890
- Java 21 is [required since Neo4j 2025.01](https://neo4j.com/docs/operations-manual/current/installation/requirements/#deployment-requirements-java). See also [Changes from Neo4j 5 to 2025.x](https://neo4j.com/docs/upgrade-migration-guide/current/version-2025/upgrade).
8991
- Java 17 is [required for Neo4j 5](https://neo4j.com/docs/operations-manual/current/installation/requirements/#deployment-requirements-java).
9092
- On Windows it is recommended to use the git bash provided by [git for windows](https://github.com/git-guides/install-git#install-git-on-windows).

‎init.sh‎

Lines changed: 44 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,31 +4,51 @@
44

55
# Note: This script needs to be executed in the root of this directory (= same directory as this file)
66

7+
# Requires analyze.sh, startNeo4j.sh, stopNeo4j.sh, checkCompatibility.sh
8+
79
# Fail on any error ("-e" = exit on first error, "-o pipefail" exist on errors within piped commands)
810
set -o errexit -o pipefail
911

12+
# Overrideable Defaults
1013
ARTIFACTS_DIRECTORY=${ARTIFACTS_DIRECTORY:-"artifacts"}
1114
SOURCE_DIRECTORY=${SOURCE_DIRECTORY:-"source"}
1215

13-
# Read the first (and only) parameter containing the name of the analysis.
16+
## Get this "scripts" directory if not already set
17+
# Even if $BASH_SOURCE is made for Bourne-like shells it is also supported by others and therefore here the preferred solution.
18+
# CDPATH reduces the scope of the cd command to potentially prevent unintended directory changes.
19+
# This way non-standard tools like readlink aren't needed.
20+
SCRIPTS_DIR=${SCRIPTS_DIR:-$( CDPATH=. cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P )} # Repository directory containing the shell scripts
21+
22+
# Local constants
23+
SCRIPT_NAME=$(basename "${0}")
24+
ERROR_COLOR='\033[0;31m'
25+
NO_COLOR='\033[0m'
26+
27+
fail() {
28+
echo -e "${ERROR_COLOR}${SCRIPT_NAME}: ${1}${NO_COLOR}" >&2
29+
if [ -n "${2}" ]; then
30+
echo -e "${ERROR_COLOR}${SCRIPT_NAME}: ${2}${NO_COLOR}" >&2
31+
fi
32+
exit 1
33+
}
34+
35+
# Validate the first (and only) parameter containing the name of the analysis.
1436
analysisName="${1}"
1537
if [ -z "${analysisName}" ]; then
16-
echo "init: Error: Missing parameter <analysisName>." >&2
17-
echo "init: Usage example: ${0} <analysisName>" >&2
18-
exit 1
38+
fail "Please specify the name of the project you want to analyze." "Example: ${0} my-project"
39+
fi
40+
if [ -d "./temp/${analysisName}" ]; then
41+
fail "Analysis project '${analysisName}' already exists in './temp/${analysisName}' directory." "Choose another name or delete it using 'rm -rf ./temp/${analysisName}' first and re-run the script."
1942
fi
2043

21-
nameOfThisScript=$(basename "${0}")
22-
if [ ! -f "./${nameOfThisScript}" ]; then
23-
echo "init: Error: Please execute the script in the root directory of the code-graph-analysis-pipeline repository." >&2
24-
echo "init: Change to the directory of this ${nameOfThisScript} script and execute it from there." >&2
25-
exit 1
44+
# Validate the execution directory
45+
if [ ! -f "./${SCRIPT_NAME}" ]; then
46+
fail "Please re-execute the script in the root directory of the repository." "Use 'cd <path-to-repo>' and re-run the script."
2647
fi
2748

28-
# Check if initial password environment variable is set
49+
# Assure that the environment variable containing the Neo4j password is set
2950
if [ -z "${NEO4J_INITIAL_PASSWORD}" ]; then
30-
echo "init: Error: Environment variable NEO4J_INITIAL_PASSWORD is recommended to be set first. Use 'export NEO4J_INITIAL_PASSWORD=<your-own-password>'."
31-
exit 1
51+
fail "Please set NEO4J_INITIAL_PASSWORD before running this script to avoid Neo4j startup issues later." "Use 'export NEO4J_INITIAL_PASSWORD=<your-own-password>' and re-run the script."
3252
fi
3353

3454
createForwardingScript() {
@@ -60,4 +80,15 @@ createForwardingScript "./../../scripts/analysis/analyze.sh"
6080
createForwardingScript "./../../scripts/startNeo4j.sh"
6181
createForwardingScript "./../../scripts/stopNeo4j.sh"
6282

63-
echo "init: Successfully initialized analysis project ${analysisName}" >&2
83+
source "${SCRIPTS_DIR}/scripts/checkCompatibility.sh"
84+
85+
echo ""
86+
echo "${SCRIPT_NAME}: Successfully initialized analysis project ${analysisName}"
87+
echo ""
88+
echo "${SCRIPT_NAME}: Next steps:"
89+
echo "${SCRIPT_NAME}: 1) Place your artifacts (e.g., Java jar/ear files) into this directory:"
90+
echo "${SCRIPT_NAME}: $(pwd)/${ARTIFACTS_DIRECTORY}"
91+
echo "${SCRIPT_NAME}: 2) (Optional) Place your source code projects/repositories into this directory:"
92+
echo "${SCRIPT_NAME}: $(pwd)/${SOURCE_DIRECTORY}"
93+
echo "${SCRIPT_NAME}: 3) Run './analyze.sh' inside 'temp/${analysisName}' to start the analysis."
94+
echo ""

‎scripts/checkCompatibility.sh‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
#!/usr/bin/env bash
2+
3+
# Check environment dependencies and tool availability.
4+
5+
# Fail on any error ("-e" = exit on first error, "-o pipefail" exist on errors within piped commands)
6+
set -o errexit -o pipefail
7+
8+
# Overrideable Defaults
9+
10+
## Get this "scripts" directory if not already set
11+
# Even if $BASH_SOURCE is made for Bourne-like shells it is also supported by others and therefore here the preferred solution.
12+
# CDPATH reduces the scope of the cd command to potentially prevent unintended directory changes.
13+
# This way non-standard tools like readlink aren't needed.
14+
SCRIPTS_DIR=${SCRIPTS_DIR:-$( CDPATH=. cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P )} # Repository directory containing the shell scripts
15+
echo "startNeo4j: SCRIPTS_DIR=$SCRIPTS_DIR"
16+
17+
checkCommand() {
18+
local cmd="$1"
19+
local description="$2"
20+
local missing_icon="$3"
21+
local present_icon="${4:-✅}"
22+
23+
if command -v "${cmd}" &> /dev/null; then
24+
echo " ${present_icon} ${cmd} - ${description}"
25+
else
26+
echo " ${missing_icon} ${cmd} - ${description}"
27+
fi
28+
}
29+
30+
checkRequiredCommand() {
31+
checkCommand "$1" "$2" "❌" ""
32+
}
33+
34+
checkOptionalCommand() {
35+
checkCommand "$1" "$2" "⚠️ " "✅"
36+
}
37+
38+
checkRequiredJavaVersion() {
39+
required_java_version="$1"
40+
41+
if [ -z "${required_java_version}" ]; then
42+
echo "Usage: check_java_version <major-version>" 1>&2
43+
return 2
44+
fi
45+
46+
if ! command -v "java" &> /dev/null; then
47+
echo " ❌ java - Java Development Kit (https://adoptium.net/) for running Java applications is not installed."
48+
return 0
49+
fi
50+
# Capture the first line of `java -version` (macOS & Linux both print to stderr)
51+
java_version_output=$(java -version 2>&1 | head -n 1)
52+
53+
# Extract the version inside the first quotes
54+
# Examples:
55+
# openjdk version "17.0.2"
56+
# java version "1.8.0_312"
57+
# Use shell parameter expansion instead of external sed for portability and performance
58+
full_java_version="${java_version_output#*\"}"
59+
java_version="${full_java_version%%\"*}"
60+
61+
# Extract major version number supporting both Java 8 and older (1.x) and Java 9+ formats
62+
case "${java_version}" in
63+
1.*)
64+
# Java 8 and older -> "1.8.0_xxx" → major = 8
65+
java_version="${java_version#1.}"
66+
java_version="${java_version%%.*}"
67+
;;
68+
*)
69+
# Java 9+ -> "17.0.2" → major = 17
70+
java_version="${java_version%%.*}"
71+
;;
72+
esac
73+
74+
# Compare numeric versions
75+
if [ "${java_version}" -ge "${required_java_version}" ]; then
76+
echo " ✅ java - Java version ${java_version} meets required version ${required_java_version}"
77+
else
78+
echo " ❌ java - Java version ${required_java_version} or higher is required, but found version ${java_version}"
79+
fi
80+
}
81+
82+
oneOf() {
83+
for option in "$@"; do
84+
if command -v "$option" &> /dev/null; then
85+
echo "✅"
86+
return 0
87+
fi
88+
done
89+
echo "❌"
90+
}
91+
92+
allOf() {
93+
for option in "$@"; do
94+
if ! command -v "$option" &> /dev/null; then
95+
echo "❌"
96+
return 0
97+
fi
98+
done
99+
echo "✅"
100+
}
101+
102+
isFailed() {
103+
if [ "$1" = "❌" ]; then
104+
return 0
105+
else
106+
return 1
107+
fi
108+
}
109+
110+
echo ""
111+
echo "Checking environment dependencies and tool availability..."
112+
echo ""
113+
echo "--------------------------------"
114+
115+
# Check required main dependencies
116+
icon=$(allOf "bash" "awk" "wc" "sed" "grep" "curl" "jq" "git" "java")
117+
echo "${icon} Minimum required dependencies:"
118+
checkRequiredCommand "bash" "Bourne Again SHell (https://www.gnu.org/software/bash/) for running the shell scripts"
119+
checkRequiredCommand "awk" "Text processing tool (https://www.gnu.org/software/gawk/) for processing text files"
120+
checkRequiredCommand "wc" "Word, line, character, byte count tool (https://www.gnu.org/software/coreutils/wc/) for counting lines in files"
121+
checkRequiredCommand "sed" "Stream editor (https://www.gnu.org/software/sed/) for parsing and transforming text"
122+
checkRequiredCommand "grep" "Text search tool (https://www.gnu.org/software/grep/) for text searching with regular expressions"
123+
checkRequiredCommand "curl" "Command line tool for transferring data with URLs (https://curl.se/) for HTTP requests to Neo4j"
124+
checkRequiredCommand "jq" "Command-line JSON processor (https://stedolan.github.io/jq/) for parsing JSON results from Neo4j"
125+
checkRequiredCommand "git" "Version control system (https://git-scm.com/) for managing source code repositories"
126+
checkRequiredJavaVersion "21"
127+
128+
if isFailed "${icon}"; then
129+
echo ""
130+
echo "${icon} One or more minimum required dependencies are missing. Please install them and re-run this script."
131+
echo "--------------------------------"
132+
echo ""
133+
exit 1
134+
fi
135+
136+
# Check dependencies for Typescript project analysis:
137+
icon=$(allOf "npx")
138+
echo ""
139+
echo "${icon} Typescript project analysis dependencies:"
140+
checkRequiredCommand "npx" "Tool to run npm packages without installing them globally (https://docs.npmjs.com/cli/v9/commands/npx)"
141+
142+
# Check dependencies for Python environments
143+
icon=$(oneOf "conda" "venv")
144+
echo ""
145+
echo "${icon} Python environment dependencies (for ./analyze.sh --report Python/Jupyter):"
146+
checkOptionalCommand "conda" "Conda package and environment manager (https://docs.conda.io/en/latest/)"
147+
checkOptionalCommand "virtualenv" "Python virtual environment module (https://docs.python.org/3/library/venv.html)"
148+
149+
# Check dependencies for Python reports
150+
icon=$(allOf "python" "pip")
151+
echo ""
152+
echo "${icon} Python reports dependencies (for ./analyze.sh --report Python/Jupyter):"
153+
checkRequiredCommand "python" "Python interpreter (https://www.python.org/) for running Python scripts"
154+
checkRequiredCommand "pip" "Python package installer (https://pip.pypa.io/en/stable/) for installing Python packages"
155+
156+
# Check dependencies for Jupyter Notebook reports
157+
icon=$(allOf "python" "pip" "jupyter")
158+
echo ""
159+
echo "${icon} Python reports dependencies (for ./analyze.sh --report Jupyter):"
160+
checkRequiredCommand "jupyter" "Jupyter Notebook (https://jupyter.org/) for interactive data analysis and visualization"
161+
162+
# Check dependencies for visualization reports
163+
icon=$(oneOf "npx" "dot")
164+
echo ""
165+
echo "${icon} Visualization report dependencies (for ./analyze.sh --report Visualization):"
166+
checkOptionalCommand "npx" "Tool to run npm packages without installing them globally (https://docs.npmjs.com/cli/v9/commands/npx)"
167+
checkOptionalCommand "dot" "Graph visualization tool from GraphViz (https://graphviz.org/) for visualizing query results as graphs"
168+
169+
echo "--------------------------------"
170+
echo ""

0 commit comments

Comments
 (0)