Skip to content

Commit 4843d2f

Browse files
yiseungmi87yiseungmi87
authored andcommitted
Docs: extended quickstart and install/run improvements
1 parent 3779d50 commit 4843d2f

File tree

4 files changed

+583
-0
lines changed

4 files changed

+583
-0
lines changed

docs/site/quickstart_extended.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Extended Quickstart Guide
2+
3+
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.
4+
5+
SystemDS can be installed and used in two different ways:
6+
7+
1. Using a **downloaded release**
8+
2. Using a **source build**
9+
10+
Each method is demonstrated in:
11+
- Local mode
12+
- Spark mode
13+
- Federated mode (simple example)
14+
15+
For detailed configuration topics (BLAS, GPU, federated setup, contributing), see the links at the end.
16+
17+
---
18+
19+
# 1. Install from a Release
20+
21+
If you simply want to *use* SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release.
22+
23+
**Full Release Installation Guide:** [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html)
24+
25+
# 2. Install from Source
26+
27+
If you plan to contribute to SystemDS or need to modify its internals, you can build SystemDS from source.
28+
29+
**Full Source Build Guide:** [SystemDS Install from source](https://apache.github.io/systemds/site/source_install.html)
30+
31+
# 3. After Installation
32+
33+
Once either installation path is completed, you can start running scripts:
34+
35+
- Local Mode - Run SystemDS locally
36+
- Spark Mode - Execute scripts on Spark through `spark-submit`
37+
- Federated Mode - Run operations on remote data using federated workers
38+
39+
For detailed commands and examples: [Execute SystemDS](https://apache.github.io/systemds/site/run_extended.html)
40+
41+
# 4. More Configuration
42+
43+
SystemDS provides advanced configuration options for performance tuning and specialized execution environments.
44+
45+
- GPU Support — [GPU Guide](https://apache.github.io/systemds/site/gpu)
46+
- BLAS / Native Acceleration — [Native Backend (BLAS) Guide](https://apache.github.io/systemds/site/native-backend)
47+
- Federated Backend Deployment — [Federated Guide](https://apache.github.io/systemds/site/federated-monitoring.html)
48+
- Contributing to SystemDS — [Contributing Guide](https://github.com/apache/systemds/blob/main/CONTRIBUTING.md)
49+

docs/site/release_install.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
2+
# Install SystemDS from a Release
3+
4+
This guide explains how to install and set up SystemDS using the pre-built release archives.
5+
6+
---
7+
8+
- [1. Download a Release](#1-download-a-release)
9+
- [2. Install on Windows](#2-install-on-windows)
10+
- [3. Install on Ubuntu 22.04](#3-install-on-ubuntu-2204)
11+
- [4. Install on macOS](#4-install-pon-macos)
12+
- [5. Verify the Installation](#5-verify-the-installation)
13+
14+
---
15+
16+
# 1. Download a Release
17+
18+
Download the official release archive from the Apache SystemDS website:
19+
20+
https://apache.org/dyn/closer.lua/systemds/
21+
22+
After downloading the file `systemds-<VERSION>.tar.gz`, place the file in any directory you choose for installation.
23+
24+
### Java Requirement ###
25+
For compatability with Spark execution and parser components, **Java 17** is strongly recommended for SystemDS.
26+
27+
Verify Java 17:
28+
29+
```bash
30+
java -version
31+
```
32+
33+
If missing, install a JDK 17 distribution.
34+
35+
---
36+
37+
# 2. Install on Windows
38+
39+
### 2.1 Extract the Release Archive
40+
41+
Use Windows built-in extractor.
42+
43+
### 2.2 Set Evironment Variables
44+
45+
To run SystemDS from the command line, configure:
46+
- `SYSTEMDS_ROOT`-> the extracted folder
47+
- Add `%SYSTEMDS_ROOT%\bin` to your `PATH`
48+
49+
Example (PowerShell):
50+
51+
```bash
52+
setx SYSTEMDS_ROOT "C:\path\to\systemds-<VERSION>"
53+
setx PATH "$env:SYSTEMDS_ROOT\bin;$env:PATH"
54+
```
55+
56+
Restart the terminal afterward.
57+
58+
# 3. Install on Ubuntu 22.04
59+
60+
### 3.1 Extract the Release
61+
62+
```bash
63+
cd /path/to/install
64+
tar -xvf systemds-<VERSION>.tar.gz
65+
cd systemds-<VERSION>
66+
```
67+
68+
### 3.2 Add SystemDS to PATH
69+
70+
```bash
71+
export SYSTEMDS_ROOT=$(pwd)
72+
export PATH="$SYSTEMDS_ROOT/bin:$PATH"
73+
```
74+
75+
# 4. Install on macOS
76+
77+
### 4.1 Extract the Release
78+
79+
```bash
80+
cd /path/to/install
81+
tar -xvf systemds-<VERSION>.tar.gz
82+
cd systemds-<VERSION>
83+
```
84+
### 4.2 Add SystemDS to PATH
85+
86+
```bash
87+
export SYSTEMDS_ROOT=$(pwd)
88+
export PATH="$SYSTEMDS_ROOT/bin:$PATH"
89+
```
90+
91+
# Verify the Installation
92+
93+
### 5.1 Check the CLI
94+
95+
```bash
96+
systemds -help
97+
```
98+
99+
You should see usage information printed to the console.
100+
101+
### 5.2 Create a Simple Script
102+
103+
```bash
104+
echo 'print("Hello World!")' > hello.dml
105+
```
106+
107+
### 5.3 Run the Script
108+
109+
```bash
110+
systemds -f hello.dml
111+
```
112+
113+
Expected output:
114+
115+
```bash
116+
Hello World!
117+
```
118+
119+
# Next Steps
120+
121+
For running scripts in Spark mode or experimenting with federated workers, see the Execution Guide: [Execute SystemDS](run_extended.md)
122+

0 commit comments

Comments
 (0)