GentleOS - Questions and Answers

On this page you can find common questions and answers for GentleOS/32 and GentleOS/16.

General

Why did you make it?

I first started tinkering with a hobby OS around 2007, thanks to the excellent tutorial by JamesM. I kept coming back to it from time to time, but never had a good idea where to take it.

Then, during the pandemic, I got hooked on buying for cheap and restoring vintage laptops from local auction sites, often sold in unknown condition by people clearing out their attics.

A few more years later, as they mostly kept lying on a shelf collecting dust, I finally got the idea to take my latest codebase, remove everything unnecessary, port it back to 32-bit, and turn it into a fantasy OS made specifically for retro PCs.

How to contribute?

I'm making this project for fun in my spare time and sharing it as-is. I don't really accept pull requests because I already have plenty of them to review at work. However, if you do anything interesting with it, please drop me an email! Make sure to mention if you're happy with your changes being included in my branch or on the website.

Are the photos real? The screen on my device doesn't look that good.

All the photos are real. They were taken with an iPhone 16, and lit using a softbox. Only minor adjustments were done in GIMP - trimming, white balance, exposure, and contrast.

GentleOS/32

Will it run on my PC?

Due to quirkiness of old devices, the only way to know for sure is to check. The lowest hardware configuration tested by the author was 386SX/16MHz CPU with 640KB of RAM.

On the high end, the PC must still support BIOS / legacy boot. It won't work on pure-UEFI systems since they don't emulate PS2 keyboard and mouse.

Does it support serial mouse?

Yes, as long as it's compatible with Microsoft serial mouse protocol. You can turn it on in the bootloader menu, or later by pressing Ctrl+Shift+S.

How to add files?

Additional assets like wallpapers and songs can be provided using an initial RAM disk (initrd). To create an initrd and automatically install in a disk image, run:

uv run tools/mkinitrd.py [FILES] -d gentleos32-base.img

The initrd replaces the one already present in the image. Use option -a to also include all the default assets shipped with the prebuilt images.

Certain emulators, including v86, only accept disk images which follow geometry of physical disks. Use option -p to automatically pad the final image with zeros to the right size.

If you're using a 3rd-party bootloader like GRUB, use option -o gentleos.rd to save the initrd to a separate file.

How to add a wallpaper?

To add a wallpaper, save it in PNG/JPG/GIF/BMP/PBM/PPM format and add to initrd.

Three kinds of wallpapers are supported:

• Monochrome - B&W images are stored in 1bpp to save memory and rendered using colors editable in settings. Their width must be a multiple of 8.
• Color - regular images, stored in 8bpp
• Pixel art - images of exactly 64x43px are scaled and rendered in a grid. They're also stored in 8bpp and only supported in 640x480 video mode.

In planar video mode (the default one), wallpapers are supported but only rendered using the first 16 colors.

For best results, in GIMP you can use an indexed mode with the provided vga-256.gpl and vga-16.gpl color palettes.

How to add a song?

To add a song, save it as an uncompressed MusicXML file, convert to the custom SPK format, and add to initrd:

uv run tools/mkspk.py -i song.musicxml -o song.spk

Only a very limited subset of MusicXML is supported: plain notes, grace notes, ties, staccato dots and tempo markings. Songs must only have a single staff with a single voice, and no chords.

Only files exported from MuseScore were tested, other tools may or may not work.

You can also edit SPK files directly, they're plain text consisting of (pitch, milliseconds) pairs, and the song title metadata.

GentleOS/16

Will it run on my PC?

Due to quirkiness of old devices, the only way to be sure is to check. The lowest hardware configuration tested by the author was NEC V20 CPU and 512KB of RAM. On the high end, the PC must still support BIOS / legacy boot. It won't work on pure-UEFI systems.

Why are there 64GB pendrives plugged into PCs from the 80s?!

I've replaced the original 720K floppy drives with Gotek emulators. They are much more convenient for development, especially since modern USB floppy drives don't work very well with 720K disks.