NOTE: This page describes creating tasks common to all of your projects/workspaces. If, instead, you wish to have your P2 compile and download tasks unique to each your projects then go to the Project Tasks page.
This document is being developed over time as we prove-out a working environment for Windows.
To date, we have installations, compilation and downloading from Windows (this page), MacOS, and RaspiOS (the Raspberry Pi OS - a Debian derived distribution).
Also, to date, we have building and download for flexprop, PNut-TS, and PNut (PNut is windows or windows emulator only.) with direct USB-attached boards.
In the future, we are also expecting to document building and download with via Wifi with the Wx boards attached to our development board, and with more compilers as they come ready for multi-platform use, etc.
On this Page:
- VSCode development of P2 Projects - basic development life-cycle
- P2 Code Development with FlexProp - setting up
- P2 Code Development with PNut - setting up
- Being consistent in your machine configuration - why we are doing things this way
- Installation and Setup - preparing your machine for P2 development using tools from within vscode
- Tasks in VScode - this provides more detail about vscode tasks and lists work that is still needing to be done
Additional pages:
- TOP Level README - Back to the top page of this repo
- Migrate to v2.3.0 - checklist to ensure you have migrated to our latest configuration which supports locating installed compilers and compiling and downloading with any of the installed compilers to your USB attached P2
- Setup focused on macOS only - All macOS notes
- Setup focused on RPi only - All Raspberry Pi notes
- VSCode REF: Tasks - Offsite: VSCode Documentation for reference
NOTE: The "P2 Code Development..." sections below provide step-by-step setup instructions
Latest Updates:
31 Aug 2024
- Add PNut-TS notes and installation
12 Jun 2024
- Updated to reflect new Spin2 Extension built-in compile/download support
18 Jul 2023
- Adopting formal install locations
- Made FlexProp and PNut setup the same steps for each
10 Apr 2023
- Awakened this Windows-specific setup page
By choosing to adopt the Custom Tasks described in this document along with the keybindings your work flow is now quite sweet.
- Create a new project
- Add existing files you have already created or are using from P2 Obex.
- Create your new top-level file.
- Add
{project}/.vscode/settings.jsonfile to identify the top-level file for the build tasks.
Iterate until your project works as desired:
- Make changes to file(s)
- Compile the files to see if they compile cleanly (cmd-shift-B) on which ever file you are editing
- Once the files compile cleanly
- Download and test (ctrl-shift-D, F10) [if you use keybindings shown in examples on this page]
- Alternatively, download your project to FLASH and test (ctrl-shift-F, F11) [if you use keybindings shown in examples on this page]
To complete your setup so you can use FlexProp on your Windows machine under VScode you'll need to:
One time:
- Install FlexProp for all users to use on your windows machine
- Add our tasks to the user tasks.json file (works across all your P2 projects)
- Remove any old compile/download keybindings you may have.
- Optionally add a couple of VSCode extensions if you wish to have the features I demonstrated
- "Error Lens" which adds the compile errors messages to the associated line of code
- "Explorer Exclude" which allows you to hide file types (e.g., .p2asm, .binary) from the explorer panel
For each P2 Project:
- Install a settings.json file identifying the project top-level file
- Make sure the name of your top-level file is correctly placed in this settings.json file
To complete your setup so you can use PNut-TS on your Windows machine under VScode you'll need to:
One time:
- Install PNut-TS for all users to use on your windows machine
- Add our tasks to the user tasks.json file (works across all your P2 projects)
- Remove any old compile/download keybindings you may have.
- Optionally add a couple of VSCode extensions if you wish to have the features I demonstrated
- "Error Lens" which adds the compile errors messages to the associated line of code
- "Explorer Exclude" which allows you to hide file types (e.g., .p2asm, .binary) from the explorer panel
For each P2 Project:
- Install a settings.json file identifying the project top-level file
- Make sure the name of your top-level file is correctly placed in this settings.json file
To complete your setup so you can use PNut on your Windows machine under VScode you'll need to install PNut and then:
One time:
- Install a tasks.json file (works across all your P2 projects)
- Remove any old compile/download keybindings you may have.
- Optionally add a couple of VSCode extensions if you wish to have the features I demonstrated
- "Error Lens" which adds the compile errors messages to the associated line of code
- "Explorer Exclude" which allows you to hide file types (e.g., .p2asm, .binary) from the explorer panel
For each P2 Project:
- Install a settings.json file identifying the project top-level file
- Make sure the name of your top-level file is correctly placed in this settings.json file
I have mostly macs for development but I also have a Windows machine and a number of Raspberry PIs (derived from Debian Linux Distribution (distro.)) and even some larger Ubuntu Machines (also derived from Debian Linux distro.). If you, like me, intend to be able to run VSCode on many of your development machines and you want to make your life easier then there are a couple of things we know already that can help you.
-
Synchronize your VSCode settings and extensions automatically by installing and using the Settings Sync VScode extension. Any changes you make to one machine then will be sync'd to your other VScode machines.
-
Be very consistent in where you install tools for each type of OS. (e.g., for all Windows machines make sure you install FlexProp, PNut-TS, and PNut, in the same location on each Windows machine.) By being consistent your tasks will run no matter which machine your are running on. There is nothing worse than trying to remember where you installed a specific tool on the machine you are currently logged into. Because you install say FlexProp in the same place on all your Raspberry Pi's you will know where to find it no matter which RPi you are logged in to.
- All like operating systems should have a specific tool installed in the same location on each. (e.g., all Windows machines have FlexProp installed in one location, all macOS machines have FlexProp installed in a different location that on Windows but it is the same location across all Macs, etc.)
- During the first-time installation of a tool on a machine, finish the process by configuring the PATH to the tool so that terminals/consoles can access the tool by name. This allows VSCode to run the tool from its build tasks.json file without needing to know where the tool is installed! On Windows machines this is done by editing the User Environment PATH variable from within the Settings Application. On Mac's and Linux machines (RPi's) this is done by editing the shell configuration file (e.g., Bash you edit the ~/.bashrc file) and adjusting the
export PATH=...line/lines.
[Optional] if you want to remote into your windows machine from a another desktop running VSCode on your network then you want to install OpenSSH client and server by following: Install OpenSSH.
On Windows machines we get the latest binaries by downloading a flexprop-{version}.zip file from the FlexProp Releases Page and unpacking the zip file to produce a FlexProp folder containing the new version.
NOTE: The FlexProp tool-set does not have a standard install location. So we will likely have many locations amongst all of us P2 users. You have to take note of where you installed it and then adjust the following examples to point to where your binaries ended up on your file system. Alternatively, it should be safe to just follow what I do in these instructions explicitly. This has the benefit that more of us will be able to help each other out with tools problems as more of us will be set up the same.
Next we move this new version into place.
Get the latest binaries by downloading a flexprop-{version}.zip file from the FlexProp Releases Page.
We are making a new program install location in these steps. We can't use C:\Program Files (x86) as FlexProp expects to be able to write to its own directory. So, Create a new program files directory called C:\Programs\TotalSpectrum\FlexProp and unpack the .zip file into that directory. Make sure that this directory is writable.
Finish up by adding C:\Programs\TotalSpectrum\FlexProp to PATH as described in add a new PATH element.
Like we do on the other platforms here's the suggested update strategy:
- Download and zip the latest version from FlexProp Releases Page
- Remove any
C:\Programs\TotalSpectrum\FlexProp-prior(the prior version of FlexProp) - Rename your existing
C:\Programs\TotalSpectrum\FlexPropfolder toC:\Programs\TotalSpectrum\FlexProp-prior - Create a new empty directory
C:\Programs\TotalSpectrum\FlexPropand make it writeable - Unpack the latest downloaded .zip into the newly re-created
C:\Programs\TotalSpectrum\FlexPropfolder
NOTE: We use this move-aside technique for updating the FlexProp compiler. When a language compiler is updated more frequently it is not uncommon to one or twice a year experience a breaking change in how the new compiler handles your existing code. Assuming the version you are moving aside works well against all your projects, we move it aside and install the new version. Should you find that the new version doesn't work well against one of your projects you will still have the prior version so you can build the project with the older version that would fail with the new version. You can always skip this move-aside step if you don't care about this issue.
On Windows machines we get the latest binaries by downloading a {os-arch}.zip file from the PNut-TS Releases page under the [Assets] dropdown, and unpacking the zip file to produce a pnut_ts folder containing the new version.
NOTE: The PNut_TS tool-set does not have a standard install location on Windows. So we will likely have many locations amongst all of us P2 users. You have to take note of where you installed it and then adjust the following examples to point to where your binaries ended up on your file system. Alternatively, it should be safe to just follow what I do in these instructions explicitly. This has the benefit that more of us will be able to help each other out with tools problems as more of us will be set up the same.
Next we move this new version into place.
Architecture specific PNut-TS .zip files available for Windows:
| Archive Name | Operating System | Architecture | Unpack Leaves |
|---|---|---|---|
| win-arm64.zip | Windows | Arm 64 bit | pnut_ts/ |
| win-x64.zip | Windows | Intel x86-64 bit | pnut_ts/ |
Get the latest binaries by downloading a {os-arch}.zip file from the PNut-TS Releases page under the [Assets] dropdown.
We are making a new program install location in these steps. We are going to use the same root directory as FlexProp but we have a new vendor. So, Create a new program files directory called C:\Programs\IronSheepProductions\ and unpack the .zip file into that directory. Depnding upon which command you use to do this you may have created a folder named after the .zip file. If this happens then inside that folder is the pnut_ts folder. Just move it out of the .zip-named folder into this folder. Then remove the now empty .zip-named folder. In the end you should have a C:\Programs\IronSheepProductions\pnut_ts\ folder with a pnut_ts.exe file within it along with other documentation.
Finish up by adding C:\Programs\IronSheepProductions\pnut_ts to PATH as described in add a new PATH element.
Like we do on the other platforms here's the suggested update strategy:
- Download and zip the latest version from PNut-TS Releases page under the [Assets] dropdown.
- Remove any
C:\Programs\IronSheepProductions\pnut_ts-prior(the prior version of PNut-TS) - Rename your existing
C:\Programs\IronSheepProductions\pnut_tsfolder toC:\Programs\IronSheepProductions\pnut_ts-prior - Create a new empty directory
C:\Programs\IronSheepProductions\pnut_ts - Unpack the latest downloaded .zip into the newly re-created
C:\Programs\IronSheepProductions\pnut_tsfolder
NOTE: We use this move-aside technique for updating the PNut-TS compiler. When a language compiler is updated more frequently it is not uncommon to one or twice a year experience a breaking change in how the new compiler handles your existing code. Assuming the version you are moving aside works well against all your projects, we move it aside and install the new version. Should you find that the new version doesn't work well against one of your projects you will still have the prior version so you can build the project with the older version that would fail with the new version. You can always skip this move-aside step if you don't care about this issue.
The PNut compiler/debug tool does not have a standard install location. So we will likely have many locations amongst all of us P2 users. You have to take note of where you installed PNut and then add a new PATH element using the windows settings app. to point to where your binaries ended up on your file system.
Download the latest .zip file from PNut/Spin2 Latest Version Forum thread into my Downloads folder. Unpack the .zip into its own folder.
Propeller Tool installs into C:\Program Files (x86)\Parallax Inc\Propeller Tool\. So I just created a sibling directory: C:\Program Files (x86)\Parallax Inc\PNut and copied all of the unpacked files into that directory.
NOTE: if you experience problems with the tasks running PNut it is generally that the .bat files are not identifying the PNut executable by the correct name. At each install check the content of \PNut\pnut_shell.bat and \PNut\pnut_report.bat and make sure the PNut versioned name is correct with what's in the folder. Occasionally Chip forgets to modify these .bat files before release.
I right-mouse on the PNut_{version}.exe file and select "Pin to taskbar".
I then add a new PATH element using the windows settings app. to point to where your binaries ended up on your file system. In my case I added a path segment pointing to C:\Program Files (x86)\Parallax Inc\PNut.
I haven't found the need to keep any prior version. I simply:
- Download the latest version of PNut from PNut/Spin2 Latest Version into my Downloads folder
- Unpack the .zip file
- In my taskbar I right-mouse on the PNut icon and select "Unpin from taskbar"
- Select all content within
C:\Program Files (x86)\Parallax Inc\PNut\and Delete it - Move all of unpacked content into the now empty folder
C:\Program Files (x86)\Parallax Inc\PNut - I right-mouse on the newly copied PNut_{version}.exe file and select "Pin to taskbar".
NOTE: if you experience problems with the tasks running PNut it is generally that the .bat files are not identifying the PNut executable by the correct name. At each install check the content of \PNut\pnut_shell.bat and \PNut\pnut_report.bat and make sure the PNut versioned name is correct with what's in the folder. Occasionally Chip forgets to modify these .bat files before release.
Once we've installed our compiler(s) we need to make sure that all users can use them from the command line. We do this by adding the path to each compiler to the System Envrironment settings PATH variable.
We have three compilers mentioned above. If you are using the paths i use then we have:
| Compiler | Path |
|---|---|
| FlexProp | C:\Programs\TotalSpectrum\FlexProp |
| PNut-TS | C:\Programs\IronSheepProductions\pnut_ts |
| PNut | C:\Program Files (x86)\Parallax Inc\PNut |
On windows the search path for programs is maintained by the Windows Settings App. Open Window Settings and search for "environment" and you should see two choices: "Edit the system environment variables" and "Edit environment variables for your account". If you want the tools to work for all users on this Windows machine (Preferred) then adjust the PATH values by editing the "system environment variables". If, instead, you only need the tools to work for your account then edit the "environment variables for your account".
If you routinely install these compilers in the same place
NOTE the above is referring to Windows 10 settings names. On earlier versions of Windows the concept is the same. Locate the environment values and make the appropriate changes.
From here on, when we run in terminal windows, we can invoke the FlexProp and PNut binaries by name without using the path to them.
A Task is how we integrate with External tools in VScode.
See: VSCode "Tasks" Reference Page
There are a number of types of tasks and places Task definitions live. These include Auto-detected Tasks, User level tasks, and Custom Tasks. Tasks when run, can be crafted to depend upon the running of other tasks See: Compound Tasks Some tasks can be run in background such as file watchers which execute when a file has been changed.
When you run VScode on multiple operating systems and want to be able to run a projects tasks on whichever machine you are on then you can specify os-specific alternatives to be used withing the task. See Operating system specific properties
Another VSCode mechanism we are determining if it will be useful is the: Task Provider Extension. If we find this is useful we can add a Task Provider element to our existing extension in order to facilitate our updating task files we use for P1 and P2 development.
...More TBA...
Tasks can be invoked with the search, identify, run technique or they can have keyboard shortcuts assigned to them.
A project can have a single default build task which is, by default, invoked with command-shift-B.
We'll configure our compileP2 task to be the default.
We'll add a downloadP2 task and assign command-shift-D to it. It will depend upon the compile task which makes it run first and then we download the newly compiled result.
We'll add a flashP2 task and assign command-shift-F to it. It will depend upon the compile task which makes it run first and then we download the newly compiled result and write it to FLASH.
TODO-1: We need to ensure download or flash doesn't proceed if compile fails
TODO-2: We'll also test using the file-watch technology to automatically compile and download our project files when they are modified.
To define the tasks we are going to use with our P2 development in most of our projects we place the task definitions in a central "User Tasks" .json file.
To get to this file type in Ctrl+Shift+P (Cmd+Shift+P on mac) to get to the command search dialog. Then type in "tasks". Lower down in the resulting filtered list you should now see "Tasks: Open User Tasks". If prompted for a Task Template, select Others. Select it and you should now have a file open in the editor which should contain at least:
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": []
}In between the [] you can place your new task definitions. You should end up with something like:
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "compileP2",
"type": "shell",
"command": "${config:spin2.fSpecCompiler}",
"args": [
{
"value": "${command:spinExtension.getCompArguments}",
"quoting": "weak"
},
"${fileBasename}"
],
"problemMatcher": {
"owner": "Spin2",
"fileLocation": ["autoDetect", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.*):(\\d+):\\s*(warning|error):\\s*(.*)$",
"file": 1,
"line": 2,
"severity": 3,
"message": 4
}
},
"presentation": {
"panel": "dedicated",
"focus": false,
"showReuseMessage": false,
"echo": true,
"clear": true,
"close": false,
"reveal": "always",
"revealProblems": "onProblem"
},
"group": {
"kind": "build",
"isDefault": true
}
},
{
"label": "compileTopP2",
"type": "shell",
"command": "${config:spin2.fSpecCompiler}",
"args": [
{
"value": "${command:spinExtension.getCompArguments}",
"quoting": "weak"
},
"${config:spin2.fNameTopLevel}"
],
"problemMatcher": {
"owner": "Spin2",
"fileLocation": ["autoDetect", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.*):(\\d+):\\s*(warning|error):\\s*(.*)$",
"file": 1,
"line": 2,
"severity": 3,
"message": 4
}
},
"presentation": {
"panel": "dedicated",
"focus": false,
"showReuseMessage": false,
"echo": true,
"clear": true,
"close": false,
"reveal": "always",
"revealProblems": "onProblem"
},
"group": {
"kind": "build",
"isDefault": true
}
},
{
"label": "downloadP2",
"type": "shell",
"command": "${config:spin2.fSpecLoader}",
"args": [
{
"value": "${command:spinExtension.getLoaderArguments}",
"quoting": "weak"
},
"${config:spin2.optionsBinaryFname}"
],
"problemMatcher": {
"owner": "Spin2",
"fileLocation": ["autoDetect", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.*):(\\d+):\\s*(warning|error):\\s*(.*)$",
"file": 1,
"line": 2,
"severity": 3,
"message": 4
}
},
"presentation": {
"panel": "dedicated",
"focus": false,
"showReuseMessage": false,
"echo": true,
"clear": true,
"close": false,
"reveal": "always",
"revealProblems": "onProblem"
},
"group": {
"kind": "test",
"isDefault": true
}
}
]
}This provides the following Build and Test tasks:
Under Task: Run Build Task:
- CompileP2 - Compile current file
- CompileTopP2 - Compile the top-file of this project
Under Task: Run Test Task:
- DownloadP2 - Download the binary to RAM/FLASH in our connected P2
As written, downloadP2 for flexpsin will always be preceeded by a compileTopP2.
This new build system no longer uses custom keybindings. However, when migrating from the older build support we used you should remove any older P2 related keybindings as they can interfere with correct operation of the new build support.
The custom key bindings are found in the keybindings.json file.
To get to this file type in Ctrl+Shift+P (Cmd+Shift+P on mac) to get to the command search dialog. Then type in "keyboard". Lower down in the resulting filtered list you should now see "Preferences: Open Keyboard Shortcuts (JSON)". Select it and you should now have a file open in the editor which should contain something like:
// Place your key bindings in this file to override the defaultsauto[]
[
]NOTE: If you find entries like the following, then they need to be removed.
{
"key": "ctrl+shift+d",
"command": "workbench.action.tasks.runTask",
"args": "downloadP2"
},
{
"key": "ctrl+shift+f",
"command": "workbench.action.tasks.runTask",
"args": "flashP2"
},
{
"key": "F8",
"command": "workbench.action.tasks.build",
"args": "compileP2"
},
{
"key": "F10",
"command": "workbench.action.tasks.runTask",
"args": "downloadP2"
},
{
"key": "F11",
"command": "workbench.action.tasks.runTask",
"args": "flashP2"
}
If you still want to use these keys for build shortcuts, then you should remove the entries, and interactively specify keystrokes in the Keyboard Shortcuts editor. It will make entries that are correct for the new build system.
In order to support our notion of top-level file and to prevent us from occasionally compiling and downloading a file other than the project top-level file we've adopted the notion of adding a CompileTopP2 (CompileTopPNut2) build task a DownloadP2 (DownloadPNut2) download task, and in some cases a FlashP2 (FlashPNut2) task.
When we request a download or flash the automation will first compile the top-level project source which produces a new binary. It is this new binary that will be downloaded/flashed.
We have multiple tasks that need to know the name of our top-level file. So we add a new settings file with a topLevel value to our project:
.vscode/settings.json file contains the following contents:
{
"topLevel": "jm_p2-es_matrix_control_demo"
}Once we have this file in place, then our tasks.json file can access this value using the form: ${config:topLevel}
Now our CompileTopP2 task can create the toplevel filename using ${config:topLevel}.spin2
You need to find the line containing "jm_p2-es_matrix_control_demo" and replace this name with the name of your top-level file.
And our DownloadP2 task can reference the binary file using ${config:topLevel}.binary
Licensed under the MIT License.
Follow these links for more information: