Configuring Visual Studio Code for Programming the P2 on Mac, Windows, and Linux

Share on facebook
Share on twitter
Share on linkedin
Share on email
Share on print
Table of Contents
Description

This Quick Byte details the setup to configure three open source software tools to program the Propeller 2 (the P2, or P2X8C4M64P) on Windows under Visual Studio Code (VSC). The process for Mac, RaspPi, and Linux operating systems is similar and not fully detailed in this post – but the differences are shown on Stephen Moraco’s GitHub (link at bottom).

VSC and the Spin2 extensions provide syntax highlighting, automatic updates, and command-line downloads to the P2 — and the simplicity and familiarity of a very popular and stable programming environment. 

The software required includes Microsoft VSC, Total Spectrum Software’s FlexProp (an IDE package which includes the FlexSpin compiler that runs on Mac, Linux and RaspPi), and the Spin2 extension from the VSC Marketplace from Stephen Moraco’s Iron Sheep Software. All software is open source, freely available, and easily configured to compile and download to the P2. Additionally, an ANSI-compliant terminal program of your choice (Parallax Serial Terminal, TerraTerm, CoolTerm, etc) may also be used for serial debug. You will also have access to other VSC Marketplace extensions [like Error Lens, one of my favorites].

While these instructions are for configuring the P2 with VSC under Windows, we’d eventually like this Quick Byte to reflect the minor differences for Mac and Linux operating systems, if they should also be documented. Post comments at the bottom of this Quick Byte and we will update this document for the differences/exceptions accordingly. In the meantime, you can obtain more specific instructions for these other operating systems from Stephen Moraco’s GitHub.

Note: the bottom of this document includes a summary of links to important resources. 

Thank You to the Contributors

The P2 open source community is motivated by user feedback from the Parallax forums, the Propeller 2 Live Forums and messages of appreciation. If you benefit from this Quick Byte, we encourage you to join Parallax and also recognize their contributions through their Patreon accounts:

Considerations Between PNut (Parallax) and FlexSpin (Total Spectrum Software) Compilers

PNut is the official Parallax compiler and was written in X86 assembly for use in the Propeller Tool for Windows. FlexSpin is the compiler created by Eric Smith of Total Spectrum Software, written in C. While efforts are made to ensure Parallax-published Quick Byte examples run in both compilers and that FlexSpin remains largely compatible, there are likely to be some small differences. PNut includes the graphical debug tools (`debug) and FlexSpin does not. Both compilers support Spin2 and PASM languages, but FlexSpin supports the mixing of objects with BASIC and C, along with some Propeller 1 (P1, or P8X32A) Spin 1 code. 

Details about FlexSpin are available on the Parallax forums FlexProp thread, and details about PNut are on the PNut thread. The PNut Tool is just a test-area for compiler changes before the compiler makes its way into the Propeller Tool for Windows, the official Parallax tool.

If you encounter compilation issues with FlexSpin used in VSC, you can report them on the FlexProp thread or to the Total Spectrum Software GitHub.      

Step1: Download and Unzip FlexProp 

Download FlexProp from the Total Spectrum Software Patreon page. Extract the zip and file place the folder in a location of your choice. FlexProp does not have a software installer that allows you to specify the location; you have control to do this manually. Take note of where you decide to locate the FlexProp directory.  

Step 2: Download and Install VSC

Download Visual Studio Code for your operating system from the Microsoft Visual Studio Code page. Install VSC.

Step 3: Launch VSC, Install the Spin2 Extension

Click on the Extensions icon and type “Spin2” in the search box. Install the extension and choose Set Color Scheme (at present, two exist from forum members Cluso99 and Iron Sheep). 

Step 4: JSON File Setup

Visual Studio Code uses a JSON data format to provide the relative paths to:

  • Compile the P2 Spin/PASM code
  • Download the P2 Spin/PASM code
  • Identify the location of the FlexSpin.exe compiler

To configure your JSON file, first copy the following template and prepare to paste it into the Tasks.JSON template you will create.

{
    // 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",
    		  "osx": {
                "command": "flexspin.mac",
    		  },
    		  "windows": {
                "command": "flexspin.exe",
    		  },
    		  "linux": {
                "command": "flexspin",
    		  },
            "args": [
                "-2",
                "-Wabs-paths",
                "-Wmax-errors=99",
                "${fileBasename}"
            ],
            "problemMatcher": {
                "owner": "Spin2",
                "fileLocation": ["autoDetect", "${workspaceFolder}/src"],
                "pattern": {
                    "regexp": "^(.*):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "severity": 3,
                    "message": 4
                }
            },
            "presentation": {
                "panel": "new",
                "focus": true
            },
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "compileTopP2",
            "type": "shell",
            "osx": {
                "command": "flexspin.mac",
            },
            "windows": {
                "command": "flexspin.exe",
            },
            "linux": {
                "command": "flexspin",
            },
            "args": [
                "-2",
                "-Wabs-paths",
                "-Wmax-errors=99",
                "${config:topLevel}.spin2"
            ],
            "problemMatcher": {
                "owner": "Spin2",
                "fileLocation": ["autoDetect", "${workspaceFolder}"],
                "pattern": {
                    "regexp": "^(.*):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "severity": 3,
                    "message": 4
                }
            },
            "presentation": {
                "panel": "new",
                "focus": true
            },
        },
        {
            "label": "downloadP2",
            "type": "shell",
            "args": [
                "-b230400",
                "${config:topLevel}.binary",
                "-t"
            ],
            "osx": {
                "command": "loadp2.mac",
            },
            "windows": {
                "command": "loadp2.exe",
            },
            "linux": {
                "command": "loadp2",
                "args": [
                    "-b230400",
                    "${config:topLevel}.binary",
                    "-t",
                    "-p/dev/ttyUSB0"
                ],
            },
            "problemMatcher": [],
            "presentation": {
                "panel": "new",
                "focus": true
            },
            "dependsOn": [
                "compileTopP2"
            ]
        }
    ]
}

Next, open the folder where your source code directory is located and you will create the Tasks.JSON template in this location (you will do this for each folder where you will use VSC). Then, choose Terminal / Configure Tasks and choose Others. This is where you will paste your JSON file from above. 

This video shows you the process.

Step 5: Setting Paths for your P2 Compiler and Tools in Windows 

The Tasks.JSON file needs to know where your tools are located. The search path for programs is maintained by the Windows Settings application.

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 a Windows machine 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.

This video shows the process. This only needs to be configured once.

Step 6: Configuring Settings.JSON to Identify your Top P2 File

The compiler needs to know the name of your Spin2 Top file. To do this, copy the following template and create a new file named settings.JSON. Put the name of your top file into the “your_top_file” location and save it in the folder as your Tasks.JSON file.

{
    "topLevel": "your_top_file",
 }

Step 7: Keymappings

You will need to map a few keys to compile and download to the P2. Again, here’s a text file you will use for the next step where I have chosen F10 and F11 for compile and download, respectively:

// Place your key bindings in this file to override the defaults

[
    {
        "key": "F10",
        "command": "workbench.action.tasks.build",
        "args": "compileP2"
    },

    {
        "key": "F11",
        "command": "workbench.action.tasks.runTask",
        "args": "downloadP2"
    },
 ]

Step 8: Compile and Download to the P2!

Using the keymappings identified above, F10 will compile and F11 will download. Close the terminal window after downloads are finished. 

Step 9: Maintain your Tasks.JSON and Settings.JSON Files for Each New Project

Every time you begin a new P2 project with VSC, you will repeat Steps 4 and 6. 

Source Code
Document Author
Source Code Author
Table of Contents
5 2 votes
Article Rating
Subscribe
Notify of
guest
9 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Jaan Doh

The link for FlexProp Presentation by Eric Smith, Total Spectrum Software (YouTube Video) actually takes you to the P2 Google documentation

cockpit

Kudos! Excellent Quick Byte on Integrated FlexSpin with VSC. I was up and running in a matter of minutes. However, there seems to be a missing step. When I closed everything down and executed “Open with Code” directly from my blink1.spin2 file [the example file I was using] I was unable to compile it with F10. It was as if VSC no longer knew my tasks.json file or keybindings existed even though they were where they were suppose to be. After playing with VSC a while I discovered that if I created a workspace and added the source code directories to my workspace everything worked great if I opened the workspace first. I’ll continue to experiment with VSC and look for additional guidance on the forums. Thanks again for the Quick Byte.

Kyle

It might be extremely helpful to give an example of actually creating a folder and project this way. I’ve followed the instructions as best I can make out but when I try to compile I first got errors that looked a lot as though the full path to my source was not included. Then after closing and reopening, F10 simply prompts me to create tasks. I really have no idea where to get going here or if there is some understood way the JSON is supposed to be copied from the master location to a new project folder.

Kyle

Thanks for the reply. I’ll check over the instructions again and see if it helps out. I am a Mac user which is why I’m going this road to begin with as running a VM for coding is a hassle I prefer to avoid. I appreciate the options to code outside Windows so I’ll make another run at it and see if the new method brings more success.

Kyle

That would probably be extremely helpful actually! I greatly appreciate the willingness to do that.