janniklinde commented on code in PR #2388: URL: https://github.com/apache/systemds/pull/2388#discussion_r2745192346
########## docs/site/release_install.md: ########## @@ -0,0 +1,203 @@ +--- +layout: site +title: Install SystemDS from a Release +description: Installation guide for SystemDS using release archives +--- + +# Install SystemDS from a Release + +This guide explains how to install and set up SystemDS using the pre-built release archives. + +--- + +- [1. Download a Release](#1-download-a-release) +- [2. Install on Windows](#2-install-on-windows) +- [3. Install on Ubuntu 22.04](#3-install-on-ubuntu-2204) +- [4. Install on macOS](#4-install-on-macos) + +--- + +# 1. Download a Release + +Download the official release archive from the Apache SystemDS website: + +https://systemds.apache.org/download + +After downloading the file `systemds-<VERSION>.tar.gz`, place the file in any directory you choose for installation. + +### Java Requirement ### +For compatability with Spark execution and parser components, **Java 17** is strongly recommended for SystemDS. + +Verify Java 17: + +```bash +java -version +``` + +If missing, install a JDK 17 distribution. + +--- + +# 2. Install on Windows + +### 2.1 Extract the Release Archive + +Use Windows built-in extractor. + +### 2.2 Verify the Installation by Checking the CLI + +On Windows, the `systemds`CLI wrapper may not be executable. This is expected because the `bin/systemds`launcher is implemented as a shell script, which Windows cannot execute natively. To verify the installation on Windows, navigate to the bin directory and run the JAR directly. Note that running `systemds -help` without JAR may result in a CommandNotFoundExeption: + +```bash +java -jar systemds-<VERSION>.jar -help +``` + +You should see usage information as an output printed to the console. + +### 2.3 Create a Simple Script + +On Windows, especially when using PowerShell, creating text files via shell redirection (e.g., echo...) may result in unexpected encoding or invisible characters. This can lead to parsing errors when executing the script, even though the file appears correct in an editor. Therefore, you may try creating the file explicitly using PowerShell: +```bash +Set-Content -Path .\hello.dml -Value 'print("Hello World!")' -Encoding Ascii +``` + +This ensures the script is stored as plain text without additional encoding metadata. +Note: This behavior depends on the shell and environment configuration and may not affect all Windows setups. + +Verify the file contents: +```bash +Get-Content .\hello.dml +``` + +Expected output: +```bash +print("Hello World!") +``` + +### 2.4 Run the Script + +Now run the script: +```bash +java -jar systemds-3.3.0.jar -f .\hello.dml +``` + +Expected output: +```bash +Hello World! +SystemDS Statistics: +Total execution time: 0.012 sec. +``` + +# 3. Install on Ubuntu + +### 3.1 Extract the Release + +```bash +cd /path/to/install +tar -xvf systemds-<VERSION>-bin.tgz +cd systemds-<VERSION>-bin +``` + +### 3.2 Configure Environment Variables + +The SystemDS CLI requires an environment variable pointing to the SystemDS JAR. Make sure to export both `SYSTEMDS_ROOT` and `SYSTEMDS_JAR_FILE`. + +```bash +export SYSTEMDS_ROOT=$(pwd) +export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1) +export PATH="$SYSTEMDS_ROOT/bin:$PATH" +``` + +Verify that the JAR was found correctly: +```bash +echo "Using SystemDS JAR: $SYSTEMDS_JAR_FILE" +``` + +(Optional but recommended) To make SystemDS available in new terminals, add the following lines to your shell configuration (e.g., ~/.bashrc or ~/.profile): +```bash +export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION> +export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1) Review Comment: Putting this line into `.bashrc` or `.profile` is usually bad practice because this command then runs every time you start a new terminal. Putting a path like `/absolute/path/to/systemds-<VERSION>-bin/systemds-<VERSION>.jar` would be preferred. ########## docs/site/release_install.md: ########## @@ -0,0 +1,203 @@ +--- +layout: site +title: Install SystemDS from a Release +description: Installation guide for SystemDS using release archives +--- + +# Install SystemDS from a Release + +This guide explains how to install and set up SystemDS using the pre-built release archives. + +--- + +- [1. Download a Release](#1-download-a-release) +- [2. Install on Windows](#2-install-on-windows) +- [3. Install on Ubuntu 22.04](#3-install-on-ubuntu-2204) +- [4. Install on macOS](#4-install-on-macos) + +--- + +# 1. Download a Release + +Download the official release archive from the Apache SystemDS website: + +https://systemds.apache.org/download + +After downloading the file `systemds-<VERSION>.tar.gz`, place the file in any directory you choose for installation. + +### Java Requirement ### +For compatability with Spark execution and parser components, **Java 17** is strongly recommended for SystemDS. + +Verify Java 17: + +```bash +java -version +``` + +If missing, install a JDK 17 distribution. + +--- + +# 2. Install on Windows + +### 2.1 Extract the Release Archive + +Use Windows built-in extractor. + +### 2.2 Verify the Installation by Checking the CLI + +On Windows, the `systemds`CLI wrapper may not be executable. This is expected because the `bin/systemds`launcher is implemented as a shell script, which Windows cannot execute natively. To verify the installation on Windows, navigate to the bin directory and run the JAR directly. Note that running `systemds -help` without JAR may result in a CommandNotFoundExeption: + +```bash +java -jar systemds-<VERSION>.jar -help +``` + +You should see usage information as an output printed to the console. + +### 2.3 Create a Simple Script + +On Windows, especially when using PowerShell, creating text files via shell redirection (e.g., echo...) may result in unexpected encoding or invisible characters. This can lead to parsing errors when executing the script, even though the file appears correct in an editor. Therefore, you may try creating the file explicitly using PowerShell: +```bash +Set-Content -Path .\hello.dml -Value 'print("Hello World!")' -Encoding Ascii +``` + +This ensures the script is stored as plain text without additional encoding metadata. +Note: This behavior depends on the shell and environment configuration and may not affect all Windows setups. + +Verify the file contents: +```bash +Get-Content .\hello.dml +``` + +Expected output: +```bash +print("Hello World!") +``` + +### 2.4 Run the Script + +Now run the script: +```bash +java -jar systemds-3.3.0.jar -f .\hello.dml +``` + +Expected output: +```bash +Hello World! +SystemDS Statistics: +Total execution time: 0.012 sec. +``` + +# 3. Install on Ubuntu + +### 3.1 Extract the Release + +```bash +cd /path/to/install +tar -xvf systemds-<VERSION>-bin.tgz +cd systemds-<VERSION>-bin +``` + +### 3.2 Configure Environment Variables + +The SystemDS CLI requires an environment variable pointing to the SystemDS JAR. Make sure to export both `SYSTEMDS_ROOT` and `SYSTEMDS_JAR_FILE`. + +```bash +export SYSTEMDS_ROOT=$(pwd) +export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1) +export PATH="$SYSTEMDS_ROOT/bin:$PATH" +``` + +Verify that the JAR was found correctly: +```bash +echo "Using SystemDS JAR: $SYSTEMDS_JAR_FILE" +``` + +(Optional but recommended) To make SystemDS available in new terminals, add the following lines to your shell configuration (e.g., ~/.bashrc or ~/.profile): +```bash +export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION> +export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1) +export PATH="$SYSTEMDS_ROOT/bin:$PATH" +``` + +### 3.3 Verify the Installation by Checking the CLI + +```bash +systemds -help +``` + +You should see usage information printed to the console. + +### 3.4 Create a Simple Script + +```bash +echo 'print("Hello World!")' > hello.dml +``` + +### 3.5 Run the Script + +With `SYSTEMDS_JAR_FILE` properly set, the script can be executed directly via the CLI: +```bash +systemds -f hello.dml +``` + +Expected output: +```bash +Hello World! +``` + +On some Ubuntu setups (including clean Docker images), running SystemDS directly may fail with `Invalid or corrupt jarfile hello.dml` Error. Ensuring that `SYSTEMDS_JAR_FILE`points to the SystemDS JAR shipped with the release resolves this issue. Review Comment: Can be removed because the manual explicitly states to set `SYSTEMDS_JAR_FILE` -> redundant ########## docs/site/quickstart_extended.md: ########## @@ -0,0 +1,57 @@ +--- +layout: site +title: SystemDS Quickstart +description: Quickstart guide for installing and running SystemDS on Windows, Linux, and macOS +--- + +# Extended Quickstart Guide + +Welcome to the extended quickstart guide for Apache SystemDS. This quickstart page provides a high-level overview of both installation and points you to the detailed documentation for each path. + +SystemDS can be installed and used in two different ways: + +1. Using a **downloaded release** +2. Using a **source build** + +If you are primarily a user of SystemDS, start with the Release installation. If you plan to contribute or modify internals, follow the Source installation. + +Each method is demonstrated in: +- Local mode +- Spark mode +- Federated mode (simple example) + +For detailed configuration topics (BLAS, GPU, federated setup, contributing), see the links at the end. + +--- + +# 1. Install from a Release + +If you simply want to *use* SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release. + +**Full Release Installation Guide:** [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html) + +# 2. Install from Source + +If you plan to contribute to SystemDS or need to modify its internals, you can build SystemDS from source. + +**Full Source Build Guide:** [SystemDS Install from source](https://apache.github.io/systemds/site/source_install.html) Review Comment: Name like title from `source_install` and update reference because it's now called `install.md` ########## docs/site/quickstart_extended.md: ########## @@ -0,0 +1,57 @@ +--- +layout: site +title: SystemDS Quickstart +description: Quickstart guide for installing and running SystemDS on Windows, Linux, and macOS +--- + +# Extended Quickstart Guide + +Welcome to the extended quickstart guide for Apache SystemDS. This quickstart page provides a high-level overview of both installation and points you to the detailed documentation for each path. + +SystemDS can be installed and used in two different ways: + +1. Using a **downloaded release** +2. Using a **source build** + +If you are primarily a user of SystemDS, start with the Release installation. If you plan to contribute or modify internals, follow the Source installation. + +Each method is demonstrated in: +- Local mode +- Spark mode +- Federated mode (simple example) + +For detailed configuration topics (BLAS, GPU, federated setup, contributing), see the links at the end. + +--- + +# 1. Install from a Release + +If you simply want to *use* SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release. + +**Full Release Installation Guide:** [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html) Review Comment: Name like title of `release_install`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
