From 999fee2de4e6bcd46536a66b84f6ae7b2cfe620f Mon Sep 17 00:00:00 2001 From: Dongha Kim Date: Wed, 4 Sep 2024 15:15:23 -0700 Subject: [PATCH 01/10] Add sudo apt update, due to "Unable to locate package" errors. --- src/Prerequisites.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/src/Prerequisites.md b/src/Prerequisites.md index 9acc26b..8fc1568 100644 --- a/src/Prerequisites.md +++ b/src/Prerequisites.md @@ -4,23 +4,28 @@ Before [getting started](./GettingStarted.html), please check whether you have a 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 (we recommend using your favorite package manager to install them): - - `gh` — [a CLI tool for interaction with GitHub](https://cli.github.com/) - - `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) + +- `gh` — [a CLI tool for interaction with GitHub](https://cli.github.com/) +- `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) ### Installation on Ubuntu + ```bash +$ sudo apt update $ sudo apt install gh git curl 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 gh git cmake curl openjdk@17 screen @@ -28,12 +33,15 @@ $ 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 -Ls https://install.lf-lang.org | bash -s nightly cli ``` If you prefer an Eclipse-based IDE over the Lingua Franca VS Code extension, install the nightly build of `epoch` using the following command: + ``` curl -Ls https://install.lf-lang.org | bash -s nightly epoch ``` @@ -41,11 +49,14 @@ curl -Ls https://install.lf-lang.org | bash -s nightly epoch > **_Troubleshooting for permission denied error_** > > If you get a permission denied error while running the command above (the error will look like below): +> > ``` > > Creating directory /usr/local/share/lingua-franca > mkdir: /usr/local/share/lingua-franca: Permission denied > ``` +> > Try running the following commands which download the installation shell script and run the script with sudo: +> > ```bash > wget https://raw.githubusercontent.com/lf-lang/installation/main/install.sh > chmod +x install.sh @@ -53,15 +64,19 @@ curl -Ls https://install.lf-lang.org | bash -s nightly epoch > ``` ## VS Code extensions + Please ensure that you have the following extensions installed: - - `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.cpptools) - - `lf-lang.vscode-lingua-franca` — [Lingua Franca for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=lf-lang.vscode-lingua-franca) + +- `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.cpptools) +- `lf-lang.vscode-lingua-franca` — [Lingua Franca for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=lf-lang.vscode-lingua-franca) For debugging support in VS Code: - - `marus25.cortex-debug` — [ARM Cortex-M GDB Debugger support for VSCode](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) + +- `marus25.cortex-debug` — [ARM Cortex-M GDB Debugger support for VSCode](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) To install them from the command line, run: + ```bash $ code --install-extension ms-vscode.cmake-tools $ code --install-extension ms-vscode.cpptools @@ -72,6 +87,7 @@ $ code --install-extension marus25.cortex-debug ## 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 @@ -87,7 +103,9 @@ $ 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 superuser privileges, add 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 ``` From a2a3d90c1d433af284ee9be4d071e4a1e3f42b08 Mon Sep 17 00:00:00 2001 From: Dongha Kim Date: Wed, 4 Sep 2024 17:36:15 -0700 Subject: [PATCH 02/10] Add cmake --- src/Prerequisites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Prerequisites.md b/src/Prerequisites.md index 8fc1568..a459d8f 100644 --- a/src/Prerequisites.md +++ b/src/Prerequisites.md @@ -20,7 +20,7 @@ Your system must have the following (very common) software packages installed (w ```bash $ sudo apt update -$ sudo apt install gh git curl openjdk-17-jdk openjdk-17-jre nix screen +$ sudo apt install gh git curl openjdk-17-jdk openjdk-17-jre nix screen cmake $ sudo snap install code --classic ``` From 81fad52979c439d47d75a8d006397209bd037eb7 Mon Sep 17 00:00:00 2001 From: Dongha Kim Date: Wed, 4 Sep 2024 17:56:31 -0700 Subject: [PATCH 03/10] Checkout to commit before version update. --- src/Tools.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Tools.md b/src/Tools.md index 1795911..af049fb 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -92,6 +92,7 @@ First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pic $ cd ~ $ git clone https://github.com/raspberrypi/pico-examples.git $ cd pico-examples +$ git checkout c95295f830a68a4854f822f07ef1b9b5abc3079e ``` Make a blank `build` directory and use it to compile all the examples: From df0254840442c628d95876c003f1cccc47b4f35d Mon Sep 17 00:00:00 2001 From: Dongha Kim Date: Wed, 4 Sep 2024 18:04:29 -0700 Subject: [PATCH 04/10] Add instructions to checkout to older version. --- src/Tools.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/Tools.md b/src/Tools.md index af049fb..7b98275 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -86,10 +86,11 @@ If the environment variable `PICO_SDK_PATH` is not set, simply run `nix develop` ### Using the Command Line -First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pico-examples) repository (for example, in your home directory) and make it your current working directory: +First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pico-examples) repository **inside the cloned directory in `my-3pi`** and make it your current working directory. +Also, make sure to checkout to `c95295f830a68a4854f822f07ef1b9b5abc3079e` since SDK version updates have been made in the newest version of the `pico-examples`. ```bash -$ cd ~ +$ cd /path/to/my-3pi $ git clone https://github.com/raspberrypi/pico-examples.git $ cd pico-examples $ git checkout c95295f830a68a4854f822f07ef1b9b5abc3079e From 5f829f64bb2c69aef9de94d12190c45c35b0da32 Mon Sep 17 00:00:00 2001 From: Dongha Kim Date: Wed, 4 Sep 2024 18:10:39 -0700 Subject: [PATCH 05/10] Revert "Add sudo apt update, due to "Unable to locate package" errors." This reverts commit 999fee2de4e6bcd46536a66b84f6ae7b2cfe620f. --- src/Prerequisites.md | 41 ++++++++++++----------------------------- 1 file changed, 12 insertions(+), 29 deletions(-) diff --git a/src/Prerequisites.md b/src/Prerequisites.md index a459d8f..6bb505d 100644 --- a/src/Prerequisites.md +++ b/src/Prerequisites.md @@ -4,20 +4,17 @@ Before [getting started](./GettingStarted.html), please check whether you have a 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 (we recommend using your favorite package manager to install them): - -- `gh` — [a CLI tool for interaction with GitHub](https://cli.github.com/) -- `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) + - `gh` — [a CLI tool for interaction with GitHub](https://cli.github.com/) + - `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) ### Installation on Ubuntu - ```bash $ sudo apt update $ sudo apt install gh git curl openjdk-17-jdk openjdk-17-jre nix screen cmake @@ -25,7 +22,6 @@ $ sudo snap install code --classic ``` ### Installation on macOS - ```bash $ brew install --cask visual-studio-code $ brew install gh git cmake curl openjdk@17 screen @@ -33,15 +29,12 @@ $ 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 -Ls https://install.lf-lang.org | bash -s nightly cli ``` If you prefer an Eclipse-based IDE over the Lingua Franca VS Code extension, install the nightly build of `epoch` using the following command: - ``` curl -Ls https://install.lf-lang.org | bash -s nightly epoch ``` @@ -49,14 +42,11 @@ curl -Ls https://install.lf-lang.org | bash -s nightly epoch > **_Troubleshooting for permission denied error_** > > If you get a permission denied error while running the command above (the error will look like below): -> > ``` > > Creating directory /usr/local/share/lingua-franca > mkdir: /usr/local/share/lingua-franca: Permission denied > ``` -> > Try running the following commands which download the installation shell script and run the script with sudo: -> > ```bash > wget https://raw.githubusercontent.com/lf-lang/installation/main/install.sh > chmod +x install.sh @@ -64,19 +54,15 @@ curl -Ls https://install.lf-lang.org | bash -s nightly epoch > ``` ## VS Code extensions - Please ensure that you have the following extensions installed: - -- `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.cpptools) -- `lf-lang.vscode-lingua-franca` — [Lingua Franca for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=lf-lang.vscode-lingua-franca) + - `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.cpptools) + - `lf-lang.vscode-lingua-franca` — [Lingua Franca for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=lf-lang.vscode-lingua-franca) For debugging support in VS Code: - -- `marus25.cortex-debug` — [ARM Cortex-M GDB Debugger support for VSCode](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) + - `marus25.cortex-debug` — [ARM Cortex-M GDB Debugger support for VSCode](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) To install them from the command line, run: - ```bash $ code --install-extension ms-vscode.cmake-tools $ code --install-extension ms-vscode.cpptools @@ -87,7 +73,6 @@ $ code --install-extension marus25.cortex-debug ## 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 @@ -103,9 +88,7 @@ $ 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 superuser privileges, add 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 ``` From b9f4d9e600f1c4b1b2c014b3636852e08423a1cc Mon Sep 17 00:00:00 2001 From: Hokeun Kim Date: Thu, 5 Sep 2024 10:31:16 +0200 Subject: [PATCH 06/10] Change the target directory back to ~ --- src/Tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Tools.md b/src/Tools.md index 7b98275..6052fe9 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -90,7 +90,7 @@ First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pic Also, make sure to checkout to `c95295f830a68a4854f822f07ef1b9b5abc3079e` since SDK version updates have been made in the newest version of the `pico-examples`. ```bash -$ cd /path/to/my-3pi +$ cd ~ $ git clone https://github.com/raspberrypi/pico-examples.git $ cd pico-examples $ git checkout c95295f830a68a4854f822f07ef1b9b5abc3079e From 47779ef63e19729039639ed44908aa020f06a9af Mon Sep 17 00:00:00 2001 From: Hokeun Kim Date: Thu, 5 Sep 2024 10:32:38 +0200 Subject: [PATCH 07/10] Revert unnecessary change. --- src/Tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Tools.md b/src/Tools.md index 6052fe9..33052ee 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -86,7 +86,7 @@ If the environment variable `PICO_SDK_PATH` is not set, simply run `nix develop` ### Using the Command Line -First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pico-examples) repository **inside the cloned directory in `my-3pi`** and make it your current working directory. +First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pico-examples) repository (for example, in your home directory) and make it your current working directory: Also, make sure to checkout to `c95295f830a68a4854f822f07ef1b9b5abc3079e` since SDK version updates have been made in the newest version of the `pico-examples`. ```bash From 9705ebb434e290f04a8f64ab6ef1b67c937ed21a Mon Sep 17 00:00:00 2001 From: Hokeun Kim Date: Thu, 5 Sep 2024 10:39:02 +0200 Subject: [PATCH 08/10] Clarify the reason why the specific commit is needed to be checked out --- src/Tools.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/Tools.md b/src/Tools.md index 33052ee..a5e4039 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -87,7 +87,13 @@ If the environment variable `PICO_SDK_PATH` is not set, simply run `nix develop` ### Using the Command Line First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pico-examples) repository (for example, in your home directory) and make it your current working directory: -Also, make sure to checkout to `c95295f830a68a4854f822f07ef1b9b5abc3079e` since SDK version updates have been made in the newest version of the `pico-examples`. + +> **_Note_** +> +> As of September 2024, we need to check out the specific commit version (`c95295f830a68a4854f822f07ef1b9b5abc3079e`) as shown below +> because the current template uses Raspberry Pi Pico SDK version 1.5.1, +> while the current version of `pico-examples` requires Pico SDK version 2.0.0. + ```bash $ cd ~ From b4790694e1c0b444cdc280aacd80e9a850d13ec1 Mon Sep 17 00:00:00 2001 From: Hokeun Kim Date: Thu, 5 Sep 2024 10:41:34 +0200 Subject: [PATCH 09/10] Add clarification to the template --- src/Tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Tools.md b/src/Tools.md index a5e4039..2e2e335 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -91,7 +91,7 @@ First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pic > **_Note_** > > As of September 2024, we need to check out the specific commit version (`c95295f830a68a4854f822f07ef1b9b5abc3079e`) as shown below -> because the current template uses Raspberry Pi Pico SDK version 1.5.1, +> because the current template (`lf-3pi-template`) uses Raspberry Pi Pico SDK version 1.5.1, > while the current version of `pico-examples` requires Pico SDK version 2.0.0. From 1e36b8530620d21de2f61910d859acb9cbd117c1 Mon Sep 17 00:00:00 2001 From: Hokeun Kim Date: Thu, 5 Sep 2024 10:44:23 +0200 Subject: [PATCH 10/10] Remove unnecessary line. --- src/Tools.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/Tools.md b/src/Tools.md index 2e2e335..0cebc9d 100644 --- a/src/Tools.md +++ b/src/Tools.md @@ -94,7 +94,6 @@ First, clone the [raspberry-pi/pico-examples](https://github.com/raspberrypi/pic > because the current template (`lf-3pi-template`) uses Raspberry Pi Pico SDK version 1.5.1, > while the current version of `pico-examples` requires Pico SDK version 2.0.0. - ```bash $ cd ~ $ git clone https://github.com/raspberrypi/pico-examples.git