# Running Vivado & Vitis on your own Mac (EMBS)

Vivado and Vitis have **no macOS version at all**, so you cannot install them on a Mac. Instead we
run them on the University's Linux server (`csteach0.york.ac.uk`) and have their windows drawn on
the Mac by **XQuartz**. That is the whole trick.

**Time: about 15 minutes. Space used on your Mac: ~200 MB** (XQuartz only — the 60 GB of Xilinx
tools lives on the server, not on you).

---

## Before you start

You need:

- [ ] Your **University IT account** and your **ITS username** (looks like `abc500`).
- [ ] Access to the **off-campus SSH gateway** (`ssh.york.ac.uk`). If you can't get in even with
      the right password, ask IT Services or the module staff.
- [ ] **XQuartz** — free, installed in step 3.
- [ ] *Later, only for the FPGA boards:* a **VLAB keyfile** from Ian. You do **not** need this to
      run Vivado — only to program a real board.

You do **not** need to download Vivado, and you do **not** need a licence file.

---

## Step 1 — Tell SSH how to reach the server

The server is behind the University firewall, so you must hop through the IT Services gateway.
Open (or create) `~/.ssh/config` and add the following, replacing `abc500` with **your own** ITS
username:

```
Host ssh.york.ac.uk
    User abc500

Host csteach0.york.ac.uk
    User abc500
    ProxyCommand ssh -A -T -o Compression=no ssh.york.ac.uk -W %h:%p
```

Then lock down the permissions:

```bash
chmod 600 ~/.ssh/config
```

## Step 2 — Make an SSH key and copy it to the server

```bash
ssh-keygen -t ed25519          # just press Enter for every prompt
ssh-copy-id csteach0.york.ac.uk
```

`ssh-copy-id` asks for your password **several times** — once for the gateway, then for the
server. That is expected.

## Step 3 — Install XQuartz

```bash
brew install --cask xquartz
```

No Homebrew? Download it from <https://www.xquartz.org/> instead.

**Then log out and back in.** If `echo $DISPLAY` is still empty afterwards, don't worry about it
— the script in step 4 sets it for you.

## Step 4 — Get the connection script

```bash
git clone https://git.movitzaaron.com/movitz/EMBS.git
cd EMBS
./embs.sh --check
```

You want to see `X server reachable: :0`. Then connect for real:

```bash
./embs.sh
```

## Step 5 — Check it actually works

Once you are logged in to the server, type:

```bash
xeyes
```

**A pair of eyes should appear on your Mac.** If it does, the hard part is over.

## Step 6 — One-off setup on the server

Still on the server. Add the tools to your PATH and point at the department's licence server, so
you don't need a licence of your own:

```bash
echo 'export LM_LICENSE_FILE=2100@cslm0.its.york.ac.uk' >> ~/.bashrc
echo 'export PATH=/opt/york/cs/net/xilinx_vivado-2025.1-x86_64-1/2025.1/Vivado/bin:$PATH' >> ~/.bashrc
```

Disconnect (`exit`) and reconnect (`./embs.sh`), then check the version:

```bash
vivado -version
```

It must say **2025.1**. If it says 2020.x, the PATH hasn't taken effect — reconnect and try again.

## Step 7 — Run Vivado

```bash
vivado &
```

Vitis is launched from inside Vivado: **Tools → Launch Vitis IDE**.

### What the flags do

`embs.sh` is just a wrapper around:

```bash
ssh -Y -C -o ServerAliveInterval=60 csteach0.york.ac.uk
```

| Flag | Meaning |
| --- | --- |
| `-Y` | Forward X11, so the GUI windows are drawn on your Mac. |
| `-C` | Compress the connection — X11 sends a lot of small messages. |
| `-o ServerAliveInterval=60` | Keepalive every 60s, so a long synthesis run isn't dropped. |

It also exports `DISPLAY=:0` and starts XQuartz if needed, which is why it is safer than typing
the `ssh` command by hand.

---

## Troubleshooting

**It asks for my password every single time.**
Normal. The gateway uses two-factor authentication, so it always asks for a password (and maybe a
Duo approval) after using your key. Nothing is broken, and it can't be automated.

**`xeyes` runs but no window appears, or it says "Can't open display".**
`DISPLAY` isn't set. `embs.sh` handles this for you; if you're connecting by hand, run
`export DISPLAY=:0` first, or start XQuartz (`open -a XQuartz`) and reconnect.

**"REMOTE HOST IDENTIFICATION HAS CHANGED" / host key changed.**
Usually just means the relay server was rebuilt. Delete the offending line from
`~/.ssh/known_hosts` and reconnect.

**My own `Host embs` alias hangs, then times out.**
It's missing its `ProxyCommand`. ssh only merges options from `Host` blocks whose pattern
matches, so a new alias does **not** inherit the `ProxyCommand` from the `csteach0` block. Copy
it into the new block, or just use `./embs.sh`.

**Vivado feels slow.**
Expected — the GUI is being sent over the network. Start long synthesis runs and come back to them.
A hardware lab PC is far nicer when you can get one.

## Good to know

- Never put **spaces** in Vivado project names or paths — it genuinely breaks the tools.
- Watch your disk quota on the server (`quota -s`). Synthesis uses a lot; `~/.cache` is usually
  safe to clear out.
- Your home directory on the server is your University filestore, so your projects persist between
  sessions.
- **On Windows** the same server route works from WSL (follow the Linux instructions), but the X11
  part differs — you'd use an X server such as VcXsrv or Xming instead of XQuartz.

## Where the original instructions live

- Working Remotely — <https://iangray001.github.io/embs/docs/setup/>
- VLAB Quickstart — <https://iangray001.github.io/embs/docs/setup/vlab-quickstart/>
- Using the VLAB — <https://iangray001.github.io/embs/docs/setup/vlab/>