From 07a8701d1bdf42612f011e2a51285213052eefbe Mon Sep 17 00:00:00 2001 From: Paul Bartell Date: Fri, 14 Oct 2022 14:24:42 -0700 Subject: [PATCH] demo: GCC Posix: Clarify toolchain installation steps --- FreeRTOS/Demo/Posix_GCC/Readme.md | 210 ++++++++++++++++++++++++++---- 1 file changed, 184 insertions(+), 26 deletions(-) diff --git a/FreeRTOS/Demo/Posix_GCC/Readme.md b/FreeRTOS/Demo/Posix_GCC/Readme.md index def1dcda25..ce46aa1105 100644 --- a/FreeRTOS/Demo/Posix_GCC/Readme.md +++ b/FreeRTOS/Demo/Posix_GCC/Readme.md @@ -1,28 +1,189 @@ -# Running with VSCode - -## Prerequisites -* Install [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) in VSCode. -* For MacOS or Linux: - * Install gcc. - * Install GNU make utility. - * Install lldb. -* For Windows with Ubuntu WSL: - * Install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install). - * Install [Remote Development Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack). -* For Windows with MSYS2: - * Install [MSYS2](https://www.msys2.org/). - * Install gcc with ```pacman -S gcc```. -* For all platforms, ensure the required binaries are in PATH with ```gcc --version```, ```make --version```, and either ```lldb --version``` or ```gdb --version```. - -## On MacOS or Linux -1. Open VSCode to the folder FreeRTOS/Demo/Posix_GCC. -2. On the VSCode left side panel, select “Run and Debug”. Then select the “Launch lldb” and press the play button to begin debugging. + +# Setup your Development Environment +This demo requires the following packages to build and debug: +* Shell: A posix-like shell environmnet. (e.g., sh, bash, or zsh +* Posix Compatible Environment: (e.g., linux, macos, MSYS2, or Cygwin) +* Compiler: gcc or clang (with gcc frontend) +* Debugger: gdb or lldb +* Build Tool: make +* IDE (optional): Microsoft Visual Studio Code (VS Code) + +## Microsoft Windows with MSYS2 +### Install the MSYS2 Runtime +*Option A*: Download the gui installer from [msys2.org](https://www.msys2.org/) or + +*Option B*: Instally msys2 using the [Microsoft winget](https://github.com/microsoft/winget-cli/releases) package manager: +>```powershell +>winget install msys2 +>``` + +### Install the GCC MinGW Toolchain with pacman +Open the MSYS2 terminal ( *MSYS2 MSYS* in the start menu ). + +Using the MSYS2 terminal, install the required packages with the pacman command: +>*MSYS2: bash* +>```bash +>pacman -S --needed --noconfirm base-devel mingw-w64-x86_64-toolchain +>``` + +Optionally, install the llvm / clang toolchain +>*MSYS2: bash* +>```bash +>pacman -S --needed mingw-w64-x86_64-lldb mingw-w64-x86_64-llvm mingw-w64-x86_64-clang +>``` + +Finally, determine the windows path for your MinGW bin directory with the following command: +>*MSYS2: bash* +>```bash +>cygpath -w $(dirname $(which gcc)) +>``` + +### Add MinGW to your windows PATH +Add the Mingw-w64 bin folder to the Windows PATH with the following steps: + +1. In the Windows search bar, search for and select ```Edit environment variables for your account```. +3. Under the *User Variables for YourUserName* header, Select the **Path** entry and select the **Edit** button. +4. Select the **New** button and add the MinGW bin directory path determined in the previous step (usually ```C:\msys64\mingw64\bin```) to the list. +5. Select the **OK** to save the updated PATH environment variable. +6. Select the **OK** to close the *Environment Variables* editor. + +> Note: You will need to reopen any apps for the new PATH settings to take effect. + +## Install Windows Subsystem for Linux (WSL) +Windows Subsystem for Linux provides a more or less complete linux distribution tightly integrated into Microsoft Windows. + +Open an elevated Windows Powershell session: +1. Click the start button +2. Search for ```PowerShell``` +3. Select ```Run as Administator``` + +In the elevated PowerShell console run the following command to install [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install): + +>*PowerShell* +> ```powershell +>wsl --install +>``` + +Open a terminal in your WSL linux environment and follow the instructions below for setting up the toolchain for your chosen Windows Subsystem for Linux Distibution. + +## Debian / Ubuntu Linux and derivatives +From a terminal, install the required pakages wth apt-get: +>``` +>sudo apt-get install -y build-essential gcc gdb make +>``` + +Optionally, install the LLVM toolchain with the following command: +>``` +>sudo apt-get install -y llvm clang lldb +>``` + +## Redhat Linux and derivatives +From a terminal, install the required pakages with dnf: +>``` +>sudo dnf install gcc gdb make +>``` + +Optionally, install the LLVM toolchain with the following command: +>``` +>sudo dnf install -y llvm clang lldb +>``` + +## MacOS +Install the Apple commandline developer tools including the AppleClang toolchain with lldb using the following command in Terminal: +>``` +>xcode-select --install +>``` +Due to code signing requirments in MacOS, running gdb is challenging. For this reason, we suggest using the included clang compiler and lldb debugger. + +Note: Apple's command line developer tools installer adds a clang wrapper in ```/usr/bin/gcc``` for compatibility. + +## Install and Configure Visual Studio Code +Download the [Visual Studio Code package for your platform](https://code.visualstudio.com/Download) from the Visual Studio Code website and install it in the normal way for your platform. + +> Note: For the Windows Subsystem for Linux platform, ensure that you install the native windows VS Code package. +> For more information, you may refernce the [Visual Studio Code WSL documentation](https://code.visualstudio.com/docs/remote/wsl). + +### Install VS Code Extensions +Next, Install the following Visual Studio Code extensions by selecting the "install" button on the extension web page linked below or by searching for the relevant extension in the Visual Studio Code **Extensions** tab in the left-hand sidebar. + +* [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) Extension, used to enable code syntax hilighting and debugging +* [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) Extension Pack, paritcularly useful for WSL + +### Add the VS Code launcher to your PATH +Launch Visual Studio Code and open the **Command Palette* with ```CTRL+SHIFT+P``` (windows, linux) or ```CMD+SHIFT+P``` (MacOS). + +Search for "Shell Command: Install ‘code’ command in Path" and select the command with the ```ENTER``` or ```RETURN``` key. + +This allows you to launch VS Code from your system's commandline with the ```code``` commnd. + +## Validate your installation: + +Check that the necessary binaries are available in your terminal PATH by running the following commands: +>*bash* +>```bash +>gcc --version +>make --version +>lldb --version +>gdb --version +>``` + +# Build on the command line +Navigate to the Posix_GCC directory in your FreeRTOS download and build +>*bash* +>```bash +> cd /path/to/FreeRTOS/Demo/Posix_GCC +>``` +## Building with GCC +>*bash* +>```bash +> make clean +> make CC=gcc +>``` +## Building with Clang +>*bash* +>```bash +> make clean +> make CC=clang +>``` + +# Debugging with Visual Studio Code +## Open the Project in VS Code on Linux, MacOS, or Windows with MSYS2 +Ooen the project directory in Visual Studio Code using one of the +>*bash* +>``` +> code /path/to/FreeRTOS/Demo/Posix_GCC +>``` + +Alternatively, open VSCode from your system launcher, select **File**->**Open Folder** and navigate to the ```FreeRTOS/Demo/Posix_GCC``` directory. + +## Open the Project in VS Code with Windows Subsystem for Linux +From your WSL Terminal, run the following command: + +>*WSL Terminal* +>```bash +> code /path/in/wsl/to/FreeRTOS/Demo/Posix_GCC +>``` + +To open the project without using the command line: +1. Open VSCode from the start menu +2. Press the ```F1``` key or ```CTRL+SHIFT+P``` to open the VS Code command palette +3. Select **WSL: New WSL Window** for the default distro or **WSL: New WSL Window using Distro** for a specific distro. +4. Finally, select the **File**->**Open Folder** menu item and navigate to the ```FreeRTOS/Demo/Posix_GCC``` directory. + +## Build the demo and run it in the debugger + +1. On the VSCode left side panel, select **Run and Debug** +2. Select the relevant launch configuration for your preferred debugger: + - Linux: select either **Launch lldb** or **Launch gdb** depending on your preferred debugger + - Windows with MSYS2: select **Launch GDB MSYS2** + - Window Subsystem for Linux: select **Launch GDB Ubuntu WSL** + +Finally, select the green triangle button to begin debugging. ## On Windows using Ubuntu WSL -1. Navigate to ```FreeRTOS/Demo/Posix_GCC``` in Ubuntu WSL and use ```code .``` to open the folder in VSCode. - 1. If ```code``` is not a recognized command, open VSCode and press ```CTRL+SHIFT+P```. Search for "Shell Command: Install ‘code’ command in Path". -2. On the VSCode left side panel, select the “Run and Debug” button. Then select the “Launch GDB Ubuntu WSL” and press the play button. This will build, run, and attach a debugger to the demo program. - 1. If the demo was previously built by MSYS2, make sure to ```make clean``` before building on Ubuntu WSL. +On the VSCode left side panel, select the **Run and Debug** button, then select and press the green triangle button. This will build, run, and attach a debugger to the demo program. + +For additional information, you may refer to the [Visual Studio Code mingw documentation](https://code.visualstudio.com/docs/cpp/config-mingw) page. ## On Windows using MSYS2 2. Open VSCode to the folder ```FreeRTOS/Demo/Posix_GCC```. @@ -87,9 +248,6 @@ bugs executables and the executable is linked against a library that overrides malloc and other allocator functions -## Requirements -### gcc -Version as tested: gcc (GCC) 11.0.0 ## Building and Running the Application ``` $ make SANITIZE_ADDRESS=1