yiseungmi87 commented on code in PR #2388:
URL: https://github.com/apache/systemds/pull/2388#discussion_r2704082319
##########
docs/site/run_extended.md:
##########
@@ -0,0 +1,269 @@
+# Running SystemDS
+
+This guide explains how to run SystemDS regardless of whether you installed it
from a Release or built it from Source. All execution modes -local, Spark, and
federated- are covered in this document.
+
+---
+
+- [1. Prerequisites](#1-prerequisites)
+- [2. Set SYSTEMDS_ROOT and PATH](#2-set-systemds_root-and-path)
+- [3. Run a Simple Script Locally](#3-run-a-simple-script-locally)
+- [4. Run a Script on Spark](#4-run-a-script-on-spark)
+- [5. Run a Script in Federated Mode](#5-run-a-script-in-federated-mode)
+
+---
+
+# 1. Prerequisites
+
+This guide assumes that SystemDS has already been installed successfully.
+
+Please make sure you have followed one of the installation guides:
+- [Install SystemDS from a Release](release_install.html)
+- [Install SystemDS from Source](source_install.html)
+
+In particular, ensure that:
+- Java 17 is installed
+- Spark 3.x is available if you plan to run SystemDS on Spark
+
+---
+
+# 2. Set SYSTEMDS_ROOT and PATH
+
+This step is required for both Release and Source-build installations. Run the
following in the root directory of your SystemDS installation:
+
+```bash
+export SYSTEMDS_ROOT=$(pwd)
+export PATH="$SYSTEMDS_ROOT/bin:$PATH"
+```
+
+It can be beneficial to persist these variables in your `~/.profile` or
`~/.bashrc`(Linux/macOS) or as environment variables on Windows, so that
SystemDS is available across terminal sessions. Make sure to replace the path
below with the absolute path to your SystemDS installation.
+
+```bash
+echo 'export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION>' >> ~/.bashrc
+echo 'export PATH="$SYSTEMDS_ROOT/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+---
+
+# 3. Run a Simple Script Locally
+
+This mode does not require Spark. It only needs Java 17.
+
+### 3.1 Create and Run a Hello World
+
+```bash
+echo 'print("Hello, World!")' > hello.dml
+```
+
+Run:
+
+```bash
+systemds -f hello.dml
+```
+
+Expected output:
+
+```bash
+Hello, World!
+```
+
+### (Optional) MacOS Note: `realpath: illegal option -- -` Error
+If you are running MacOS and encounter an error message similar to `realpath:
illegal option -- -` when executing `systemds -f hello.dml`. You may try to
replace the system-wide command `realpath` with the homebrew version
`grealpath` that comes with the `coreutils`. Alternatively, you may change all
occurrences within the script accordingly, i.e., by prepending a `g` to avoid
any side effects.
+
+### (Optional) Ubuntu Note: `Invalid or corrupt jarfile hello.dml`
+On some Ubuntu setups (especially clean environments such as Docker images),
running `systemds -f hello.dml` may result in an error like `Invalid or corrupt
jarfile hello.dml`. If this happens, the SystemDS launcher may not
automatically locate the correct JAR. Please refer to the Ubuntu
troubleshooting section in the installation guide for a detailed workaround:
[Release Installation – Ubuntu
Note](release_install.md#optional-ubuntu-note-invalid-or-corrupt-jarfile-hellodml-error)
+
+### (Optional) Windows Note: `systemds` Command Not Found
+On Windows (e.g., PowerShell), running `systemds -f hello.dml` may fail with
an error indicating that `systemds` is not recognized as a command. This is
expected, since the `systemds` launcher in `bin/` is implemented as a shell
script,
+which cannot be executed natively on Windows. In this case, SystemDS should be
invoked directly via the runnable JAR using `java -jar`. For a detailed
Windows-specific walkthrough, please refer to the installation guide: [Release
Installation – Windows Notes](release_install.md#2-install-on-windows)
+
+
+### 3.2 Create a Real Example
+
+This example demonstrates local execution of a real script `Univar-stats.dml`.
The relevant commands to run this example with SystemDS is described in the DML
Language reference guide at [DML Language
Reference](dml-language-reference.html).
+
+Prepare the data (macOS: use `curl`instead of `wget`):
+```bash
+# download test data
+wget -P data/
http://archive.ics.uci.edu/ml/machine-learning-databases/haberman/haberman.data
+
+# generate a metadata file for the dataset
+echo '{"rows": 306, "cols": 4, "format": "csv"}' > data/haberman.data.mtd
+
+# generate type description for the data
+echo '1,1,1,2' > data/types.csv
+echo '{"rows": 1, "cols": 4, "format": "csv"}' > data/types.csv.mtd
+```
+
+Execute the DML Script:
+```bash
+systemds -f scripts/algorithms/Univar-Stats.dml -nvargs \
+ X=data/haberman.data \
+ TYPES=data/types.csv \
+ STATS=data/univarOut.mtx \
+ CONSOLE_OUTPUT=TRUE
+```
+
+### (Optional) MacOS Note: `SparkException` Error
+If SystemDS tries to initialize Spark and you see `SparkException: A master
URL must be set in your configuration`, you can force single-node execution
without Spark/Hadoop initialization via:
+```bash
+systemds -exec singlenode -f scripts/algorithms/Univar-Stats.dml -nvargs \
+ X=data/haberman.data \
+ TYPES=data/types.csv \
+ STATS=data/univarOut.mtx \
+ CONSOLE_OUTPUT=TRUE
+```
+
+### (Optional) Ubuntu Note: `NoClassDefFoundError` Error / JAR Resolution
Issues
+On some Ubuntu setups, executing the example may fail with a class loading
error such as `NoClassDefFoundError:
org/apache/commons/cli/AlreadySelectedException`. This happens when the
SystemDS launcher script does not automatically resolve the correct executable
JAR. In this case, explicitly pass the SystemDS JAR located in the release root
directory:
+```bash
+SYSTEMDS_JAR=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name
"systemds-*.jar" | head -n 1)
+echo "Using SystemDS JAR: $SYSTEMDS_JAR"
+```
+Then run the example again:
+```bash
+systemds "$SYSTEMDS_JAR" -f scripts/algorithms/Univar-Stats.dml -nvargs \
+ X=data/haberman.data \
+ TYPES=data/types.csv \
+ STATS=data/univarOut.mtx \
+ CONSOLE_OUTPUT=TRUE
+```
Review Comment:
Updated the notes to reference exporting jar file.
--
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]
