* 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:
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
Paul Bartell
2 years ago
committed by
Paul Bartell