lf-lang · lhstrh · Aug 17, 2023 · Aug 16, 2023 · Aug 16, 2023 · Aug 16, 2023
diff --git a/docs/book.toml b/docs/book.toml
@@ -1,5 +1,5 @@
 [book]
-authors = ["Abhi Gundrala and Edward A. Lee"]
+authors = ["Abhi Gundrala", "Edward A. Lee", "Marten Lohstroh"]
 language = "en"
 multilingual = false
 src = "src"

diff --git a/docs/src/GettingStarted.md b/docs/src/GettingStarted.md
@@ -0,0 +1,106 @@
+# Getting Started
+
+Before getting started, please make sure you have satisfied all the [prerequisites](Prerequisites.html).
+
+## Set up GitHub account and SSH key
+If you do not yet have a GitHub account, [create one](https://github.com/signup).
+
+### Set up authentication with GitHub
+In order to push to your repo, you need to authenticate. You can either do this using a public/private key pair through SSH, or use token-based authentication via `gh`, the GitHub commandline interface.
+
+#### Using SSH
+In the ⚙️ <kbd>Settings</kbd> of your GitHub account, go to 🔑 <kbd>SSH and GPG keys</kbd> and enter the contents of your `~/.ssh/id_rsa.pub`. If you do not have this file, create it using the following command:
+```bash
+$ ssh-keygen -t rsa -b 4096 -C "your_github@email.com"
+```
+Additional information about setting up public key authentication with GitHub can be found [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
+
+> **_Tip for VM users_**
+> 
+> If you are looking for a convenient way to copy a public/private key pair onto a VM, consider using [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole). It is preinstalled on the [Ubuntu VM](https://vm.lf-lang.org) prepared for this course.
+
+#### Using GitHub CLI
+To authenticate with GitHub through its CLI tool, run:
+```bash
+$ gh auth login
+```
+
+## Create your repository
+Start by creating a new private repository on GitHub based on the [lf-3pi-template](https://github.com/lf-lang/lf-3pi-template) repository, which provides a starting point for students to carry out the exercises in this lab and to develop further applications using the [Raspberry Pi Pico board](https://www.raspberrypi.com/products/raspberry-pi-pico/) and the [Pololu 3pi+ 2040 robot](https://www.pololu.com/docs/0J86).
+
+Navigate to the [lf-3pi-template](https://github.com/lf-lang/lf-3pi-template) repository.  Select "Use this template" and "Create a new repository", as shown here:
+
+<img src="img/3piTemplate.png" alt="Template repo"/>
+
+Give your repo a name and click on "Create repository":
+
+<img src="img/my-3pi.png" alt="new repo"/>
+
+## Clone your repository
+On the command line on your host machine, clone the repo.
+For an SSH-based setup, run:
+
+```bash
+$ git clone git@github.com/<username>/<reponame>.git
+```
+
+Or, for a setup that uses GitHub CLI, run:
+
+```bash
+$ gh repo clone <username>/<reponame>
+```
+
+The template includes [raspberrypi/pico-sdk](https://github.com/raspberrypi/pico-sdk) as a submodule, which itself also has a lot of submodules. We recommend against using the `--recursive` flag because we do not need to recursively clone the submodules inside of `pico-sdk`. Instead, change directory into the root of your clone and run:
+
+```bash
+$ git submodule update --init
+```
+
+If  `pico-sdk` was checked out correctly, `git submodule` will show the hash _without_ a `-` preceding it,
+e.g.: `6a7db34ff63345a7badec79ebea3aaef1712f374 pico-sdk (1.5.1)`.
+
+## Configure Nix
+
+To create a reproducible unix shell environment that installs all required dependency applications, we use the [nix](https://nixos.org) package manager. Install [nix](https://nixos.org/download.html) first for your preferred platform. There is support for Windows (via WSL), MacOS, and Linux.  If possible, use a **multi-user** install, which will require sudo permissions.
+
+After installation, run the following in the shell to enable the experimental nix flakes feature, which helps to create more consistent builds:
+
+```bash
+$ mkdir -p ~/.config/nix
+$ echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
+```
+
+To install the dependencies, run the following in the root of your repository:
+
+```bash
+$ nix develop
+```
+
+This should automatically download and install specific revisions of the `gcc-arm` toolchain, `openocd`, and `picotool`. These packages will be required compiling, flashing and debugging C code for the RP2040.
+(You can alternatively manually [install the Raspberry Pi Pico Tools](InstallingPicoTools.md).)
+
+If you hit any error while running `nix develop`, see trouble shooting instructions below.
+
+> **_Troubleshooting (Linux/WSL)_**
+>
+> You may see an error message like this when running the `nix develop` command:
+> ```bash
+> error:
+>       … while fetching the input 'git+file:///home/osboxes/lf-lang/my-3pi'
+> error:
+>       cannot connect to socket at '/nix/var/nix/daemon-socket/socket': Permission denied
+>
+> ```
+> This means that your user is not a member of the `nix-users` group. To fix this, see [prerequisites](Prerequisites.html#using-nix-on-linuxwsl).
+
+> **_Troubleshooting (ARM/Apple Silicon Mac)_**
+>
+> As of August 1, 2023, the stable version of nix does *not* support ARM/Apple Silicon Macs. You may see an error message like this when running the `nix develop` command:
+> ```
+> is not available on the requested hostPlatform
+> ```
+> You can work around this issue by setting up an environmental variable and running the nix command with an additional argument, `--impure`, like this:
+> ```bash
+> $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1
+> $ nix develop --impure
+> ```
diff --git a/docs/src/InstallVSCode.md b/docs/src/InstallVSCode.md
diff --git a/docs/src/Installation.md b/docs/src/Installation.md
diff --git a/docs/src/InstallingPicoTools.md b/docs/src/InstallingPicoTools.md
@@ -1,58 +1 @@
-# Installing Raspberry Pi Pico Tools
-
-If you use Nix as explained in the [installation instructions](./Installation.md), then you should not need to manually install the Raspberry Pi Pico SDK.  But just in case, we provide here instructions adapted from the [Pololu instructions](../lib/pololu-3pi-2040-robot/c/README.md). See also the [GNU ARM installation instructions](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
-
-## Set the PICO\_SDK\_PATH Environment Variable
-
-Set the `PICO_SDK_PATH` environment variable:
-
-```
-export PICO_SDK_PATH=../lf-pico/lib/pico-sdk
-```
-
-where `...` is replaced by the path to the folder where you cloned the `lf-pico` repository.  For convenience, put the above command in your `~/.bash_profile` file so that the environment variable is available to any bash terminal.  Depending on what operating system and terminal you use, you may need to find some other way to set this environment variable.
-
-Note that the `PICO_SDK_PATH` variable is automatically set by `nix develop` in the shell that  it launches (see the [installation instructions](./Installation.md)).
-Moreover, if you use the template repo, then `PICO_SDK_PATH` will be subsequently automatically set whenever you compile any LF file in your repo even if you are not using the shell launched by `nix develop`.
-
-## Install CMake and ARM cross compiler
-
-### On Linux
-
-```
-sudo apt update
-sudo apt install cmake make gcc gcc-arm-none-eabi libnewlib-arm-none-eabi
-```
-Note:  Ubuntu and Debian users might additionally need to also install `libstdc++-arm-none-eabi-newlib`.
-
-### On MacOS
-
-```
-$ brew install cmake make gcc arm-none-eabi-gcc
-$ brew tap ArmMbed/homebrew-formulae
-```
-
-**NOTE:** If you are running on an Apple M1-based Mac you will need to install Rosetta 2 as the Arm compiler is still only compiled for x86 processors and does not have an Arm native version.
-```
-$ /usr/sbin/softwareupdate --install-rosetta --agree-to-license
-```
-
-## Compile Plain C Examples
-
-To make sure your installation has worked, compile the example programs provided with the pico-sdk.  Assuming you have cloned `lf-pico`, then from the `lf-pico` root directory, do this:
-
-```
-cd pico/pico-examples
-mkdir build
-cd build
-cmake ..
-make
-```
-After a while, the build directory will have subdirectories for many examples.  To load the Blink example onto the robot (which simply blinks an LED):
-
-* Plug the robot into the USB port of your computer.
-* Put the robot in BOOTSEL mode by holding the B button while pressing the reset button. You should see an external disk appear with a name like `RPI-RP2`.
-* Open the `RPI-RP2` folder.
-* Drag the `blink.uf2` (in `lib/pico-examples/build/blink`) into the `RPI-RP2` folder.
-
-The robot should immediately start running the program.
+# Non-nix Setup
diff --git a/docs/src/Non-Nix.md b/docs/src/Non-Nix.md
@@ -0,0 +1,47 @@
+# Non-`nix` Setup
+
+If you use `nix` as explained in the [getting started instructions](./GettingStarted.html#configure-nix), then you should not need to manually install the Raspberry Pi Pico SDK, C library and math library compiled for bare metal Cortex ARM, or the GNU Arm Embedded Toolchain for cross-compilation. To install these manually and not rely on `nix` to provide these dependencies, follow these instructions adapted from the [Pololu instructions](../lib/pololu-3pi-2040-robot/c/README.md). See also the [GNU ARM installation instructions](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
+
+## Install Raspberry Pi Pico SDK
+
+Clone the [raspberrypi/pico-sdk](https://github.com/raspberrypi/pico-sdk) repository and set the `PICO_SDK_PATH` environment variable:
+
+```bash
+$ git clone https://github.com/raspberrypi/pico-sdk.git
+$ cd pico-sdk
+$ export PICO_SDK_PATH=`pwd`
+```
+
+For convenience, set `PICO_SDK_PATH` in your `~/.bash_profile` file so that the environment variable is available to any bash terminal. After completing the steps above, this can be done as follows:
+
+```bash
+$ echo "export PICO_SDK_PATH=$PICO_SDK_PATH" >> ~/.bash_profile
+```
+
+Depending on what operating system and terminal you use, you may need to find some other way to set this environment variable.
+
+## Install CMake, Standard C Library, ARM cross compiler
+
+### On Ubuntu
+
+```
+sudo apt update
+sudo apt install cmake make gcc gcc-arm-none-eabi libnewlib-arm-none-eabi
+```
+**Note:** It might be additionally needed to also install `libstdc++-arm-none-eabi-newlib`.
+
+### On macOS
+
+```
+$ brew install cmake make gcc arm-none-eabi-gcc
+$ brew tap ArmMbed/homebrew-formulae
+```
+
+**NOTE:** If you are running on an Apple M1-based Mac you will need to install Rosetta 2 as the Arm compiler is still only compiled for x86 processors and does not have an Arm native version.
+```
+$ /usr/sbin/softwareupdate --install-rosetta --agree-to-license
+```
+
+## Perform a Smoke Test
+
+To make sure your installation has worked, follow the instructions [here](Tools.html#using-the-command-line).
diff --git a/docs/src/Prerequisites.md b/docs/src/Prerequisites.md
@@ -0,0 +1,73 @@
+# Prerequisites
+
+Before [getting started](./GettingStarted.html), please check whether you have all the necessary software installed and configured properly.
+Alternatively, a pre-configured Ubuntu VM image is available [here](https://vm.lf-lang.org). Instructions for usage of the VM are provided [here](UbuntuVM.html).
+
+## Packages
+Your system must have the following (very common) software packages installed:
+ - `git` — [a distributed version control system](https://git-scm.com/)
+ - `cmake` — [a cross-platform family of tools for building, testing and packaging software](https://cmake.org/)
+ - `code` — [the Visual Studio Code IDE](https://code.visualstudio.com/download)
+ - `curl` — [a CLI tool and library for transfering data with URLs](https://curl.se/)
+ - `java` — [Java 17](https://openjdk.org/projects/jdk/17)
+ - `nix` — [a purely functional package manager](https://nix.dev/tutorials/install-nix)
+ - `screen` — [a terminal multiplexer](https://dev.to/thiht/learn-to-use-screen-a-terminal-multiplexer-gl)
+
+We recommend using your favorite package manager to install them.
+
+### Installation on Ubuntu
+```bash
+$ sudo apt install curl git openjdk-17-jdk openjdk-17-jre nix screen
+$ sudo snap install code --classic
+```
+
+### Installation on macOS
+```bash
+$ brew install --cask visual-studio-code
+$ brew install cmake git curl openjdk@17 screen
+$ curl -L https://nixos.org/nix/install | sh
+```
+
+## Lingua Franca Toolchain
+To install the nightly (recommended) Lingua Franca CLI tools (i.e, the compiler `lfc`, the diagram generator `lfd`, and the code formatter `lff`), run:
+```
+curl -s https://install.lf-lang.org | bash -s nightly cli
+```
+
+## VS Code extensions
+Please ensure that you have the following extensions installed:
+ - `marus25.cortex-debug` — [ARM Cortex-M GDB Debugger support for VSCode](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)
+ - `ms-vscode.cmake-tools` — [Extended CMake support in Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
+ - `ms-vscode.cpptools` — [C/C++ IntelliSense, debugging, and code browsing](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
+ - `lf-lang.vscode-lingua-franca` — [Lingua Franca for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=lf-lang.vscode-lingua-franca)
+
+To install them from the commandline, run:
+```bash
+$ code --install-extension marus25.cortex-debug
+$ code --install-extension ms-vscode.cmake-tools
+$ code --install-extension ms-vscode.cpptools
+$ code --install-extension lf-lang.vscode-lingua-franca
+```
+
+## Permissions
+
+### Using `nix` on Linux/WSL
+To use `nix` on Linux, make sure that your user is a member of the `nix-users` group. To check this, run:
+
+```bash
+$ groups
+```
+
+If `nix-users` is not listed, run:
+
+```bash
+$ sudo usermod -aG nix-users $USER
+```
+
+Please note that you might need to reboot your system after running `usermod` in order for the new group membership to be reflected.
+
+### Using `picotool` on Linux/WSL
+To allow access to the RP2040 via USB without root superuser privileges, add a custom `udev` rules using the following command:
+```bash
+$ curl -s https://raw.githubusercontent.com/raspberrypi/picotool/master/udev/99-picotool.rules | sudo tee -a /etc/udev/rules.d/99-picotool.rules >/dev/null
+```