Linux Development Virutal Machine for 32blit SDK

October 23, 2021, at 04:21 AM by mgarcia in 2021, PC, Pics, GameDev, Blog (0 comments)

Title: Linux Development Virutal Machine for 32blit SDK Author: mgarcia Date: 2021-10-23 04:21 +0200 Tags: 2021, PC, Pics, GameDev, Blog Comments: Open

Image: Blog.2021-10-23-Linux-Development-Virutal-Machine-for-32blit-SDK

Click to view original image: 224kb


Introduction

The VM is 32blit.7z, it is a 3.2 GB download and is 13.5 GB extracted.

It was created with Virtual Box 6.1, so you'll probably want to reinstall virtual box's guest tools. Auto log in as user dev
All passwords are: dev

It's MX-21_x64, set up with Eclipse CDT C/C++ 2021-09-R and builds for the following targets:

  1. Linux 64bit
  2. Windows 64bit (wine64 is also installed)
  3. Emscripten (chrome browser)
  4. Pimoroni 32blit
  5. Pimoroni PicoSystem
  6. Pimoroni VGA Board (aka Raspberry Pi Pico reference board, you can find it in chapter 3 of Hardware Design with RP2040 along with more general info about the VGA reference board.)

To install create a new Virtual Box application without the harddrive, then extract the 32blit.vbi into that folder and add the drive to the "virtual media manager" then add the drive to your VM application, configure it similarly to the images included and it should start fine. I recommend configuring the USB devices to auto connect to the VM guest, bidirectional copy and paste and a shared folder. How to use Eclipse and build the examples for each target is described at the end.

This is my personal VM, shared in the interest of helping the community. To my knowledge, there is nothing malicious or none GNU/free software.

Use at own risk, etc.

The challenge

ETA prime, did a review of the PicoSystem and threw down a challenge to play some community made games on his next video!

   

A New Handheld Powered By The Same Raspberry Pi Pico Chip!

PicoSystem's limitations makes it it's strength, by focusing on small 8bit or 16bit retro games, which also makes it ideal for game jams.

PicoSystem and VGA Board are very similar, so if you choose to get a VGA Board instead, I think that should be fine.

I see the VGABoard, as a console version, of a PicoSystem.

I'm not an expert, there's a lot of noob hacks here, but to encourage others, here are my notes on setting up.

32blit is very impressive how it can target so many platforms! Sorry I wont be mentioning Mac or chrome OS's, I'm not familiar at all with them.

I'm mostly in the 32blit discord (Chat) - https://discord.gg/7qM9ftC But I can try and answer/help here to.


General noob tips

The 32blit documentation is pretty good, but I still got caught out here and there. Keep folders names simple, ie no spaces or none ASCI chars, including user name!

Make sure your .profile or .bash_profile etc can be run correctly in your window terminal before starting! Sometimes they have access issues, ie a quick fix can be:

chmod 777 $HOME/.bash_profile

If you want to build faster use:

make -j2

The number is the threads to run, the more the faster

I'm a git,cmake,arm noob, it's best to git clone each repo then to download them as zips, this is required by some, but best to do for all, IE:

git clone -b master https://github.com/raspberrypi/pico-sdk.git

Each target has it's own build folder in the 32blit-sdk (or your game) folder

ie build.stm32 build.em etc.

Here is the directory structure, I've used:

 
> $HOME/	
>> 	emsdk
>> 	pico-sdk
>> 	32blit-tools
>> 	pico-extras
>> 	pico-sdk
>> 	gcc-arm-none-eabi-9-2020-q2-update (not required, and probably a me thing) 	
>>	.local/bin (auto generated - location of the 32blit tool)
>>	32blit-beta (latest branch for pico devices)
>>	  
>>	32blit-sdk/
>>>>>   	build
>>>>> 		build.picosystem
>>>>> 		build.vgaboard
>>>>> 		build.win64
>>>>> 		build.em 
>>>>> 		build.stm32

My setup.

I thought I would use a new linux flavor, I went with MX (debian based) and picked XFCE (and unknowingly stable).

Here are the links:

https://distrowatch.com/?newsid=11206

–Xfce (our flagship desktop) MX-21_x64, with a standard 64 bit kernel and hardware support from Debian Stable. Suitable if your PC is a few years old.

https://mxlinux.org/download-links/#Mirrors

https://sourceforge.net/projects/mx-linux/files/Final/Xfce/MX-21_x64.iso/download?use_mirror=ixpeering&use_mirror=ixpeering&r=https%3A%2F%2Fmxlinux.org%2F

Eclipse, my IDE of choose for over 20years now!

https://www.eclipse.org/downloads/packages/release/2021-09/r/eclipse-ide-cc-developers

I installed this to a Virtual Box image, so it's self contained, the USB devices are automatically forward to the VM. To access the usb device from your account, enter:
sudo gpasswd -a yourusername vboxusers

log out and back in.


GNU/Linux

After install, run: sudo apt update

add gdb to the list of things to install, if you plan on debugging natively!

Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/Linux.md

sudo apt install git gcc g++ gdb gcc-arm-none-eabi cmake make python3 python3-pip python3-setuptools libsdl2-dev libsdl2-image-dev libsdl2-net-dev unzip

The OS app control keys are (see hardware-test app):

 
Dpad = arrow keys or WASD
A = Z key
B = X key
X = C key
Y = V key

Home = 1 key
Menu = 2 or ESC key

Joystick = Mouse within app screen
Joystick press = 3 key

Tilt controls, I don't know.


32blit tool

I found this part a bit confusing.

In your $HOME folder (not 32blit root)

https://github.com/32blit/32blit-tools

It also requires:

https://github.com/pimoroni/boilerplate-python

Run:

git clone https://github.com/32blit/32blit-tools.git

cd 32blit-tools

git clone https://github.com/pimoroni/boilerplate-python.git

cp -a boilerplate-python/* .

Next, I had issues running pip3, not in the path (of sudo possibly), again, I brought forced scripts that used pip3, replacing it with: python3 -m pip

Run:

pip3 install 32blit

or

python3 -m pip install 32blit

or to update it, run:

python3 -m pip install --upgrade 32blit

That will build tool and install the tool into ~/.local/bin and add the path to your env file setting, ie .profile

Setup and build the linux native

From: https://github.com/32blit/32blit-sdk/blob/master/docs/Linux.md

Setup it, in user root (ie ~):

git clone https://github.com/32blit/32blit-sdk.git

Building it is unnecessary, except to test the toolchain and see the demo's etc.

 
cd ~/32blit-sdk
mkdir build
cd build
cmake .. -D32BLIT_DIR=$HOME/32blit-sdk
make -j2

run and test the exe's


stm32 (32blit)

AKA 32blit: https://32blit.com/blog Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/32Blit-Firmware.md#building--flashing-the-32blit-firmware

Make sure to have a fat32 formated SD card handy!

  
cd ~/32blit-sdk
mkdir build.stm32
cd build.stm32
cmake .. -DCMAKE_TOOLCHAIN_FILE=$HOME/32blit-sdk/32blit.toolchain -D32BLIT_DIR=$HOME/32blit-sdk

make -j2


When linking the executables, you'll see a warning like this:


[ 97%] Building CXX object CMakeFiles/game.dir/assets.cpp.obj
[100%] Linking CXX executable game.elf
/home/dev/gcc-arm-none-eabi-9-2020-q2-update/bin/../lib/gcc/arm-none-eabi/9.3.1/../../../../arm-none-eabi/bin/ld:
warning: cannot find entry symbol Reset_Handler; defaulting to 00000000900001a0

Building game.bin
   text	   data	    bss	    dec	    hex	filename
  21688	    904	   2280	  24872	   6128	/home/dev/eclipse-workspace/test/build.stm32/game.elf

There are 42 section headers, starting at offset 0x988a0:

The reason for this is because games don't have a reset handler (only the firmware does).

On my debian stable, or the MX repo the gcc-arm-none-eabi package (from 2018) couldn't build the stm32. I had to "brute force it"... and downloaded the tar.bz2 file and extracted it and manually fixed up the paths in .profile PATH="$HOME/gcc-arm-none-eabi-9-2020-q2-update/bin:$PATH"

gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 from https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads

I had to specify -DPICO_TOOLCHAIN_PATH=$HOME/gcc-arm-none-eabi-9-2020-q2-update in stm32/pico cmake commands below.

TTY permissions

Before plugging in 32blit or a pico device, do this, give your user access to serial device! On linux, both devices uses: /dev/ttyACM0 https://github.com/esp8266/source-code-examples/issues/26

sudo usermod -a -G tty username

update firmware.

Updated the firmware, if it's old.

cd ~/32blit-sdk/build.stm32

Put the 32blit in DFU mode (hold X/Y and press reset) , plug the USB cable in.

32blit flash firmware/firmware.bin

or

make firmware-update.flash

next install the launcher:

32blit install launcher/launcher.blit

or

make launcher.flash

If the 32blit is disconnected while flashing, it will kill the launcher, just reflash/install as above.

I recommend copying all .blit files (including the launcher.blit) to SD card first, and installing from there, using: 32blit install filename.blit /

Install all the other demos (see bottom of Makefile for more info):

make install DEMO-NAME.flash

You now should have a working and demo loaded 32blit!


Emscripten

Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/Emscripten.md

  
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh


make sure paths are correctly executed when a new shell/terminal is open,it should automatically run source $HOME/emsdk/emsdk_env.sh


cd ~/32blit-sdk
mkdir build.em
cd build.em

emcmake cmake .. -D32BLIT_DIR=$HOME/32blit-sdk 


************* hitting 16MB default limit *************

edit CMakeCache.txt

add -s TOTAL_MEMORY=67108864 to the LINKFLAGS


32MB = 33554432 
64MB = 67108864 
etc.. 

//Flags used by the linker during all build types.
CMAKE_EXE_LINKER_FLAGS:STRING= -s TOTAL_MEMORY=67108864


It should automatically update the linker settings: CMakeFiles/game.dir/link.txt
If not, add it to the line after em++


Looking at the link.txt file above it also lets you change the shell-file which is normally at /home/dev/32blit-sdk/32blit-sdl/emscripten-shell.html, this HTML file sets the title


************* hitting 16MB default limit *************



make -j2 (or more, takes a long time!)

I like to create a script file that starts the server is helpful:

#!/bin/bash
python3 -m http.server


Run in a terminal and CTRL C to stop it.


I don't know why, but firefox doesn't like it, chrome browser works fine.
The keyboard buttons (from hardware-test app): 
http://0.0.0.0:8000/32blit-sdk/build.em/examples/hardware-test/hardware-test.html

Same as the native OS controls.

windows exe

 

I use:
sudo apt-get install mingw-w64
Not the documented:
sudo apt install gcc-mingw-w64 g++-mingw-w64


after: sudo mkdir -p /opt/local/

make it accessible:
sudo chmod -R 777 /opt/local

cd  /opt/local 

and download and extract as per instructions.

Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/Windows-WSL.md#installing-the-mingw-compilertools

 
in 32blit-sdk root
mkdir build.win64
cd build.win64

cmake .. -DCMAKE_TOOLCHAIN_FILE=$HOME/32blit-sdk/mingw.toolchain -D32BLIT_DIR=$HOME/32blit-sdk
make -j2


optionally install wine
sudo apt install wine64 
recommend installing wine32, also.

installs as: /usr/bin/wine64-stable or just wine.
test: /usr/bin/wine64-stable examples/geometry/geometry.exe

setting up PicoSystem / VGA BOARD

VGA BOARD

https://shop.pimoroni.com/products/pimoroni-pico-vga-demo-base

PicoSystem

https://shop.pimoroni.com/products/picosystem

Both being based on the RP Pico, require the same source code, nothing is built in these folders.

https://github.com/raspberrypi/pico-sdk

Also read the PDF section 2.1. Get the SDK and examples

https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf

 
In your $HOME folder (not 32blit root)
git clone -b master https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init


cd ~

git clone -b master https://github.com/raspberrypi/pico-extras.git

cd into ~/32blit-sdk

Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/pico.md

PicoSystem Bleeding edge!

Both devices are under heavy development currently!

The newer branches of 32blit-sdk has better performance and feature support ie USB support for VGA board, it's called 32blit-beta instead of 32blit-sdk. But the two can be used together by using the beta folder with pico devices, ie:

cd $HOME

git clone -b pico-all-the-boards --single-branch https://github.com/Daft-Freak/32blit-beta.git

This branch requires the latest tinyUSB

cd $HOME/pico-sdk/lib/

mv tinyusb tinyusb.orig

git clone https://github.com/hathach/tinyusb

The new source code is referenced from the 32blit-sdk root builds, ie:

In 32blit-sdk root

mkdir build.picosystem

cd build.picosystem

cmake .. -D32BLIT_DIR=$HOME/32blit-beta -DPICO_SDK_PATH=$HOME/pico-sdk -DPICO_EXTRAS_PATH=$HOME/pico-extras -DPICO_BOARD=pimoroni_picosystem

make -j2

The VGA board is similar as above, but with -DPICO_BOARD=vgaboard instead of -DPICO_BOARD=pimoroni_picosystem

repeat for vgaboard into new build folder, ie:

in 32blit-sdk root

mkdir build.vgaboard

cd build.vgaboard

mkdir build.vgaboard

cd build.vgaboard

cmake .. -D32BLIT_DIR=$HOME/32blit-beta -DPICO_SDK_PATH=$HOME/pico-sdk -DPICO_EXTRAS_PATH=$HOME/pico-extras -DPICO_BOARD=vgaboard

make -j2


Pico, VGA & 32blit USB TTY printing

Make use TTY permissions is correct.

32blit can printf to the TTY terminal using:
blit::debugf("Play Sound \n");

Text is output via USB using the TTY, so install one, ie:
sudo apt-get install putty cu minicom screen

I found screen to work the easiest (no params)
display text output screen:
screen /dev/ttyACM0 115200

log file:
screen -L /dev/ttyACM0 115200

make; 32blit install game.blit ; screen -L /dev/ttyACM0 115200

In my experience, the logging can sometimes lock the 32blit and the terminal!


new project

read https://github.com/32blit/32blit-boilerplate/

cd into the folder you want to start a in project, ie:

cd $HOME/eclipse-workspace

git clone https://github.com/32blit/32blit-boilerplate.git PROJECT_NAME

cd PROJECT_NAME

next you have to build it to set the executable, same process as above:

mkdir build

cd build

cmake .. -D32BLIT_DIR=$HOME/32blit-sdk -DCMAKE_BUILD_TYPE=Debug

make -j2

run it: ./game

You can create a new build folder for a release target, etc

To debug in 32blit, you need to tell GDB that it's multithreaded, in your build directory create a .gdbinit file with this line: set scheduler-locking step

I use a new release build directory, just run the same cmake command but with: -DCMAKE_BUILD_TYPE=Release

About setting the scheduler-locking.

Options: on, off, step, replay.

It applies to normal execution, record mode, and replay mode.
If it is off, then there is no locking and any thread may run at any time.
If on, then only the current thread may run when the inferior is resumed.

The step mode optimizes for single-stepping; it prevents other threads from preempting the current thread while you are stepping, so that the focus of debugging does not change unexpectedly.
Other threads never get a chance to run when you step, and they are completely free to run when you use commands like ‘continue’, ‘until’, or ‘finish’.
However, unless another thread hits a breakpoint during its time slice, GDB does not change the current thread away from the thread that you are debugging.

The replay mode behaves like off in record mode and like on in replay mode.

If you are targeting linux, I would suggest building with standard libraries statically linked... add the follow to the top (after project(32blit)) of CMakeLists.txt:

  
project(32blit)

IF(CMAKE_SYSTEM_NAME MATCHES "Linux")
       set(CMAKE_SHARED_LINKER_FLAGS "-static-libgcc -static-libstdc++ -static")
       LINK_DIRECTORIES(additions/libstdc)
       ADD_DEFINITIONS(-static-libgcc)
       SET(CMAKE_CXX_LINK_EXECUTABLE “${CMAKE_CXX_LINK_EXECUTABLE} -static-libgcc”)

        MESSAGE(DEBUG "Linux os: ${outOS}")
ELSEIF(CMAKE_SYSTEM_NAME MATCHES "Windows")
        MESSAGE(DEBUG "Windows")       
ELSE()
        MESSAGE(DEBUG "No OS detected!")
ENDIF(CMAKE_SYSTEM_NAME MATCHES "Linux")


How To Use Eclipse

I'm sure there's better ways to work with eclipse and cmake projects, but here's how I do it:

import the PROJECT_NAME folder as an existing code as makefile project. 

right click build->game -> run as -> local C++ app - double click C/C++ app.

click menu run -> run configuration, click 'build configuration' append build/ to  build director: ie ${workspace_loc/PROJECT_NAME:}/build/ click apply

Now if you change game.cpp it'll compile first before running.

Next, set the default header full paths for include SDL2/32blit-sdl/32blit.

right click main project -> properties -> C/C++ general -> Paths and symbols,  add to include directories individual, tick add to all config and languages:

/opt/local/x86_64-w64-mingw32/include/SDL2
/home/dev/32blit-sdk/32blit-sdl
/home/dev/32blit-sdk/32blit

Note: change dev to your username.

click apply.

right click main project, index -> rebuild 

CTRL left mouse click a 32blit classes/function and you should drill down into it, ect.

To debug, set a break point and click debug icon



To target other platforms, create a new build folder and use the same cmake parameters as above when building the 32blit-sdk examples.

IE:

cd PROJECT_NAME
mkdir build.em
cd build.em
emcmake cmake .. -D32BLIT_DIR=$HOME/32blit-sdk
make


python3 -m http.server

now, launch chrome browser, click game.html, close browser

ctrl -c to cancel server.



My 32blit Unboxing

Originally from: 2020 28th March - Warning, it's uses Text To Speech!

  32Blit, A modern day Net Yaroze, Retro hardware game development 

32Blit, A modern day Net Yaroze, Retro hardware game development


What to do next?

Using Eclipse (or your favorite IDE), import the 32blit examples, to look through the source code.

In Eclipse, the easy way is to create a new Project, by:
File -> New -> Project

Select "Makefile Project with Existing Code", next.

Click brows and select ~/32blit-sdk/examples

Next, pick Linux GCC and click finish.

Now, set the default header full paths for include SDL2/32blit-sdl/32blit as explained prior.

You'll have all the examples ready to read, however, you can't launch, compile or debug them.


32blit API Documentation

Although, there's not much documentation in 32blit API, it's included here, in a separate file.

But to recreate the doxygen doc's run:

sudo apt update && sudo apt install doxygen graphviz python3-setuptools

cd $HOME/32blit-sdk/32blit && doxygen doxygen.conf


Change text size

MX Tweak - appearance (button bot right) - fonts tab - default font.


File browser shortcuts

Create shortcuts on the file browser, right click and send to -> side pane.


Launch exe's

https://askubuntu.com/questions/876567/ask-before-running-script-in-thunar


#!/bin/bash
zenity --question --text="What to do with the executable file '$1'?" \
       --ok-label=Run \
       --cancel-label=Edit

case $? in
    0)xfce4-terminal -e "$1"
    ;;
    1)geany $1
    ;;
esac



[Desktop Entry]
Type=Application
Name=Edit-or-run
Icon=geany
Categories=Utility;
MimeType=application/x-sh;application/x-executable;
Exec=bash -c '/home/dev/editorrun.sh %f'




Updating 32blit SDK

The VM image is pretty old now, and require new sources to be updated. Start with building the 32blit tool and the 32blit SDK for each target... it should just work!


More...

In general, if you have any windows issue search it with Xfce.

If you have a file browser issue search it with thunar or MX linux.

I like having all my tools in the VM, so I install gimp etc.




Comments are open.


Your name or alias (required):

Your plain text comment (required):


Your entered name and comment will be displayed above this form.
There is no reply notifications or editing of comments.

 Enter value: 3023  



RSS Feed @mgarcia_org Twitter Feeder my random Youtube videos
An IndieWeb Webring 🕸💍



Page last modified on July 22, 2022, at 03:03 AM and visited 574 times.

Powered by PmWiki