From 98632d7c31d9458d0ede7be05b67aa1f3cbddcce Mon Sep 17 00:00:00 2001
From: Egor Savkin <es@m-labs.hk>
Date: Mon, 17 Jun 2024 11:59:46 +0800
Subject: [PATCH] Add setup for building the firmware instructions

Signed-off-by: Egor Savkin <es@m-labs.hk>
---
 src/SUMMARY.md               |  3 +-
 src/sw_sup/setup_build_pc.md | 62 ++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 src/sw_sup/setup_build_pc.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index ad6e651..7cca166 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -29,4 +29,5 @@
   - [Flashing the Firmware](./sw_sup/flashing_firmware.md)
   - [Moninj](./sw_sup/moninj.md)
   - [Clocking](sw_sup/clocking.md)
-  - [device_db.py](sw_sup/device_db.md)
\ No newline at end of file
+  - [device_db.py](sw_sup/device_db.md)
+  - [Setup your PC for building ARTIQ firmware](sw_sup/setup_build_pc.md)
\ No newline at end of file
diff --git a/src/sw_sup/setup_build_pc.md b/src/sw_sup/setup_build_pc.md
new file mode 100644
index 0000000..da62549
--- /dev/null
+++ b/src/sw_sup/setup_build_pc.md
@@ -0,0 +1,62 @@
+# Setup your PC for building ARTIQ firmware
+
+This page should guide you through building the firmware on your own PC. 
+Unfortunately, the building process is not possible on Windows natively (nor MSYS2), 
+but you can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install).
+
+## Prerequisites
+
+You should have a Linux with `nix` and `git` installed. For this purpose you may want to consider NixOS, though it is hard way for everything else. 
+You should have at least 70+ GB of free space (better 100+ GB) on your `/opt` or `/` - most of this space will be taken 
+by Vivado.
+
+## Installation
+
+1. Install Vivado 2022.2 from [Vivado archive](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive.html) into `/opt`.
+2. Check that `ls -al /opt/Xilinx/Vivado/2022.2/settings64.sh` exists and has read and execute permissions for all:
+    ```shell
+    $ ls -al /opt/Xilinx/Vivado/2022.2/settings64.sh
+    -rwxr-xr-x 1 nobody nogroup 245 Dec 17  2022 /opt/Xilinx/Vivado/2022.2/settings64.sh
+    ```
+3. Add following into the `~/.local/share/nix/trusted-settings.json`, by `mkdir -p ~/.local/share/nix/ && nano ~/.local/share/nix/trusted-settings.json` 
+   or with your favorite way (don't forget to save - Ctrl+O in `nano`):
+    ```json
+    {
+       "extra-sandbox-paths":{
+          "/opt":true
+       },
+       "extra-substituters":{
+          "https://nixbld.m-labs.hk":true
+       },
+       "extra-trusted-public-keys":{
+          "nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc=":true
+       }
+    }
+    ```
+4. Enable flakes in Nix by e.g. adding `experimental-features = nix-command flakes` to nix.conf (for example `~/.config/nix/nix.conf`).
+
+From here, you should be able to enter ARTIQ development shell directly from URL, or by cloning the repository.
+The later will allow you to edit the source code in case of need.
+
+For example for Kasli 2.0:
+
+```shell
+git clone https://github.com/m-labs/artiq.git
+cd artiq
+nix develop #boards
+```
+
+For Kasli-SoC:
+```shell
+git clone https://git.m-labs.hk/M-Labs/artiq-zynq.git
+cd artiq-zynq
+nix develop
+```
+
+For building instructions for your JSON, please refer to the [build and test instructions](../build_test_firmware.md).
+The reference uses commands like `nix develop github:m-labs/artiq\?ref=release-8#boards` and `nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-8`.
+You may safely skip such commands if you entered the development shell (`nix develop`) from cloned git repository.
+
+If you want to update the source files, you may use `git pull origin master --rebase`. 
+Please refer to git documentation `https://www.git-scm.com/docs` if you are unfamiliar with `git`. 
+You may also use GUI git tools, like the one integrated into JetBrains IDEs, VS Code, Sublime Merge or others.