Z80 Environment VSCode Revision
Welcome to another blog update for the ZX Spectrum Next.
Last time, I posted on how to use Sublime Text to create a dev environment in z80 with sjasmplus and CSpect. Since then I have been thinking, what if I wanted to have some flexibility with the option to code in Visual Studio Code.
I know a lot of people use this and in fact, I use it myself when coding with NextBuild.
So here goes, lets use what we know from the last post and expand on it to include VSCode in our workflow.
Just so you know, I use Windows and I am keeping the same folder structure and download locations of sjasmplus and CSpect. So at this point, it might be a good idea to read the last post and familiarise yourself on what I did before continuing.
If you want to be able to use Sublime Text and VSCode, you can do all parts in both posts; however, if you just want to use VSCode, then the key things to note are, how I set up my folders and downloading sjasmplus and CSpect. You can skip the Sublime Text part as I am using VSCode here instead. I will still use the same sample asm source to test everything works, but we won't need the extra z80asm.zip file or the .bat files setting up. (I will be using the JSON file instead to automate.)
Here is a reminder of my folders, however you can now see an extra folder in projects called ".vscode". This will be used to save a JSON file later.
Make sure you have this structure set up before continuing.
C:\SpecNextDev
\cspect
[All the files from the downloaded CSpect folder placed here]
\sjasmplus
[All the files from the sjasmplus folder placed here]
\Projects
\.vscode
tasks.json (We will create this later)
\Project1
\Project2
\HelloWorld
Downloading the software
See here to direct you to the web sites for downloading:Setting up the software
Again most of this part is really quite simple and I won’t insult your intelligence in explaining how to install for example, Visual Studio Code. Simply run the downloaded install file and follow the steps.For CSpect and sjasmplus, download these zip files to your computer somewhere, unzip them and copy all the folders/files within to the previously created folder structure for each.
Ensure “CSpect.exe” and “sjasmplus.exe” are included with these.
To ensure CSpect works correctly with sound, in the extracted CSpect folder, there is a program called “oalinst.exe”. This is the OpenAL installer.
Just open this and install following the steps.
If you want to test that CSpect is working correctly with sound, navigate to the CSpect folder you created with it’s contents and run a couple of .bat files.
“beast.bat”
“mod_player.bat”
Both are good examples to test.
Now that is all done and before we open VSCode, we will set up the JSON file.
Using notepad or any other text editor, create a blank file called "tasks.json" and save it in the previously created ".vscode" folder. Ensure you use the extension ".json".
Now copy and paste the JSON code below into this file and save it. This will be used by VSCode to build and run the source asm files.
{
"version": "2.0.0",
"tasks": [
{
"label": "Assemble with Sjasmplus",
"type": "shell",
"command": "\"C:\\SpecNextDev\\sjasmplus\\sjasmplus.exe ${file} --zxnext=cspect --msg=all --fullpath --outprefix=${fileDirname}\\",
"group": {
"kind": "test",
"isDefault": true
},
"problemMatcher": []
},
{
"label": "Run in CSpect",
"type": "shell",
"command": "\"C:\\SpecNextDev\\cspect\\CSpect.exe -brk -w3 -50 -vsync -zxnext -nextrom -map=${fileDirname}\\${fileBasenameNoExtension}.map -mmc=${fileDirname}\\ ${fileDirname}\\${fileBasenameNoExtension}.nex\"",
"group": {
"kind": "test",
"isDefault": true
},
"problemMatcher": []
},
{
"label": "Build and Run",
"type": "shell",
"command": "cmd.exe",
"args": [
"/c",
"\"C:\\SpecNextDev\\sjasmplus\\sjasmplus.exe\" ${file} --zxnext=cspect --msg=all --fullpath --outprefix=${fileDirname}\\ && \"C:\\SpecNextDev\\cspect\\CSpect.exe\" -brk -w3 -50 -vsync -zxnext -nextrom -map=${fileDirname}\\${fileBasenameNoExtension}.map -mmc=${fileDirname}\\ ${fileDirname}\\${fileBasenameNoExtension}.nex"
],
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": []
},
]
}
All files created in the build/run process, will be placed in our specific project folder.
For example:
For example:
\HelloWorld
\HelloWorld.asm
\HelloWorld.nex - [created from VSCode]
\HelloWorld.map - [created from VSCode]
This allows us to use the environment for multiple projects with ease. Now let's open VSCode and set it up with some useful extensions for things like, syntax highlighting, etc.
The ones I am using are:
- Z80 Macro-Assembler by mborik
- ASM Code Lens by maziac
- DeZog by maziac
- Z80 Assembly meter by Nestor Sancho
You can see what they are used for before installation.
In the left panel there is an icon for extension selection, you can see in this image that you can search and install extensions here.
For example type z80 in the search bar and then press Z80 Macro-Assembler. This will display a new tab in VSCode explaining what it does and you can then install it.
If you want to use all the ones I am, just repeat this process for all.
We are now ready to try some code!
Code example
The code to try is from the Spectrum Next site.
Click the file icon on the left to go back to this view and close all the extension tabs. Then from the menu select, File and Open Folder. Open our Projects folder from here.
As previously mentioned all our code will be saved in their own folder within "Projects", so create a folder called "HelloWorld" and then a source file inside called "HelloWorld.asm". When saving a ".asm" file, VSCode should now use syntax highlight with Z80 Macro-Assembler, but like with Sublime Text, it can be selected from the bottom right of the VSCode window, by selecting the type and changing from the menu that opens.
We should now see something like this:
C:\SpecNextDev\Projects\HelloWorld\HelloWorld.asm
Now that is all complete, we are ready to put some code in this new ".asm" file.
Copy and paste the code below taken from the Spec Next Site and save with File, Save.
;;
;; Sample code
;;
; Allow the Next paging and instructions
DEVICE ZXSPECTRUMNEXT
; Generate a map file for use with Cspect
CSPECTMAP "NAME.map"
org $8000
Start:
ld a,4 ; Set A to green
out ($fe),a ; Change the border
jr $ ; Loop forever!
;;
;; Set up the Nex output
;;
; This sets the name of the project, the start address,
; and the initial stack pointer.
SAVENEX OPEN "NAME.nex", Start, $ff40
; This asserts the minimum core version. Set it to the core version
; you are developing on.
SAVENEX CORE 2,0,0
; This sets the border colour while loading (in this case white),
; what to do with the file handle of the nex file when starting (0 =
; close file handle as we're not going to access the project.nex
; file after starting. See sjasmplus documentation), whether
; we preserve the next registers (0 = no, we set to default), and
; whether we require the full 2MB expansion (0 = no we don't).
SAVENEX CFG 7,0,0,0
; Generate the Nex file automatically based on which pages you use.
SAVENEX AUTO
Final step is here!!
If you look at the test code, there are 2 file names which create the .map and .nex files. These should be on lines 9 and 24 in this example.
Change where it says NAME to the same name as the .asm file.
For example in this test we named it “HelloWorld.asm”
So change these 2 lines:
CSPECTMAP "NAME.map"
SAVENEX OPEN "NAME.nex", Start, $ff40
To:
CSPECTMAP "HelloWorld.map"
SAVENEX OPEN "HelloWorld.nex", Start, $ff40
Do this for each unique project and everything will be nice and tidy. Now the fun bit!
From within VSCode, select from the menu, Terminal, Run Build Task or press F5.
You should now see VSCode build and run our code!
Of note you can select Terminal, Run Task to complete each step manually.
That is it, you should now see your program running within CSpect!!!
Hope this has helped in some way, have fun. 👾
Comments
Post a Comment