snakeware

Python-based Linux distro for x86-64 and RPi
git clone git://squid-tech.com/snakeware.git
Log | Files | Refs | README

README.md (6349B)


      1 # snakeware
      2 snakeware is a free Linux distro with a Python userspace inspired by the Commodore 64. You are booted directly into a
      3 Python interpreter, which you can use to do whatever you want with your computer.
      4 
      5 [Check out our latest demo on YouTube!](https://www.youtube.com/watch?v=PYKUnC-k5bA)
      6 
      7 [Official Snakeware Discord](https://discord.gg/SAdFjWG)
      8 
      9 IRC Channel: `#snakeware` on `irc.rizon.net`.
     10 
     11 ![snakeware/snakewm running in QEMU](screenshot.png)
     12 
     13 ## Motivation
     14 The idea is that a Python OS would be fun to use and very easy to contribute to. Even relative beginners might be able
     15 to find ways to meaningfully contribute apps and other code to this distro.
     16 
     17 Our window manager, snakewm, is based on pygame/pygame_gui. We do not use X11; snakewm draws directly to `/dev/fb0`.
     18 
     19 We also are not going to be using any other huge and opaque software such as systemd, etc. The goal is to eventually
     20 have a usable set of userspace apps and utilities written entirely in Python, because Python is fun and it Just Werks™.
     21 
     22 ## Running
     23 [Download the latest release image.](https://github.com/joshiemoore/snakeware/releases)
     24 
     25 You can burn the x86-64 ISO file to a flash drive and boot it, or launch the ISO in VirtualBox. Instructions to run it 
     26 in QEMU are below.
     27 
     28 The rpi4 image can be flashed to an SD card and run on your Raspberry Pi 4, with no further setup required.
     29 
     30 ### Flash Drive / SD Card
     31 
     32 To run snakeware on real hardware, simply write the image file to the flash drive or SD card using `dd`, then boot it.
     33 No further setup is required if you just need a live, non-persistent environment.
     34 
     35 To create a persistent snakeware drive:
     36 
     37 1. Note the virtual device corresponding to the drive you wrote the snakeware image to. For this example, we will
     38 assume `/dev/sdc`.
     39 2. Use `cfdisk` to add another partition to the drive, after the snakeware partition(s). This partition can be any size, but you'll likely want to fill the rest of the drive. Take note of the number of the new partition. This will be your "snakeuser" partition, where all of your scripts and data will be stored.
     40 3. Once you have written the partition to the drive, format the partition to ext4. For example, `mkfs.ext4 /dev/sdc2`.
     41 4. Finally, give the paritition the SNAKEUSER label, ex: `e2label /dev/sdc2 SNAKEUSER`.
     42 
     43 Once you've completed these steps, the snakeuser partition will be automatically mounted as `/snakeuser` and chdir'd
     44 into on boot. Files and data stored on this partition will persist between boots.
     45 
     46 ### QEMU
     47 
     48 To run snakeware on QEMU:
     49 
     50 1. [Download and install QEMU](https://www.qemu.org/download/). Supports Linux, macOS, and Windows.
     51 2. Open your terminal/command prompt.
     52 3. Navigate to the directory/folder where the snakeware image image was downloaded.
     53 4. Launch the snakeware ISO using a script similar to this:
     54 ```
     55 RAM="2G"
     56 ISO="snakeware_x86-64.iso"
     57 
     58 AUDIO="pa" # also available: alsa
     59 
     60 exec qemu-system-x86_64 \
     61         -drive file="$ISO",media=cdrom,if=virtio \
     62         -m "$RAM" \
     63         -cpu host \
     64         -machine type=q35,accel=kvm \
     65         -smp $(nproc) \
     66         -audiodev "$AUDIO,id=snd" \
     67         -device ich9-intel-hda \
     68         -device hda-output,audiodev=snd
     69 ```
     70 5. Wait for it to load.
     71 6. You will be be taken to a Python environment/shell.
     72 
     73 ### VirtualBox
     74 
     75 To run snakeware on VirtualBox:
     76 
     77 1. [Download and install VirtualBox](https://www.virtualbox.org/wiki/Downloads).  Supports Linux, macOS, and Windows.
     78 2. Open and create a new virtual machine with `Type: Linux` and `Version: Other Linux (64-bit)`.
     79 3. Set virtual hard disk size and RAM (recommended 2GB) to your liking.
     80 4. After snakeware VM is created, open vm settings, go to `Storage`.
     81 5. Click small disk icon next to `Controller: IDE`, then `Add`.
     82 6. Add `snakeware.iso` and click `Choose`
     83 7. Go to `Display` and set `Graphics Controller: ` to `VBoxVGA`
     84 8. Click `Okay` and then `Start` to run VM.
     85 9. You will be loaded into a Python environment/shell.
     86 
     87 ### Launching snakewm
     88 
     89 To load snakewm from Python shell:
     90 
     91 1. Launch snakewm with either of the following Python commands:
     92 ```
     93 >>> snakewm
     94 ```
     95 or
     96 ```
     97 >>> from snakewm.wm import SnakeWM
     98 >>> SnakeWM().run()
     99 ```
    100 2. To open the app menu press the left WinKey (Left CMD key ⌘ on macOS).
    101 
    102 ## Building
    103 The snakeware build system is based on buildroot. See the `snakeware/` directory in this repo for resources and
    104 documentation on how to build your own snakeware distro image.
    105 
    106 **NOTE:** If you are only contributing apps or other code to snakewm, you don't need to build a whole snakeware distro 
    107 image to test your changes. Simply make your changes to snakewm then run `sudo python wm.py` in the `snakewm/` 
    108 directory. snakewm will then start drawing itself directly to the framebuffer and you can test out your changes. 
    109 Press `ALT+ESC` to return to your normal desktop. (It would still be good to test your changes in an actual
    110 snakeware environment though.)
    111 
    112 ## Contributing
    113 Developers of all experience levels are welcome and encouraged to contribute to snakeware. Python enthusiasts that are
    114 familiar with pygame and pygame_gui will be able to write their own snakeware apps very easily. See existing apps
    115 in `snakewm/apps/` for examples of how to get started, and feel free to ask questions if you need help.
    116 
    117 Those with experience building Linux systems are encouraged to contribute to the underlying aspects of the distro,
    118 such as the build/package scripts and configuration for the kernel, GRUB, etc.
    119 
    120 I would also like to eventually stop using Busybox for intialization and find a way to perform all necessary init from
    121 the Python environment, so ideas about that are welcome.
    122 
    123 ## TODO
    124 This is an abridged list of future plans:
    125 
    126 * ~~Raspberry Pi configs for buildroot and kernel!!!!!!!~~
    127 * ~~Fix pip module installation - won't work when cross-compiling~~
    128 * Many more snakewm apps
    129 * ~~App menu for choosing apps to run~~
    130 * ~~Improved/streamlined build system~~
    131 * Improved kernel config
    132 * snake-games - full-screen user games separate from SnakeWM
    133 * ~~Modify partition scheme for faster boot - /usr on its own partition?~~
    134 * Take advantage of pygame_gui's theme functionality
    135 * ~~Dynamic/interactive desktop backgrounds~~
    136 * ~~Sound support~~
    137 * Networking -> web browser
    138     + snakechat - chat with everyone else who's using snakeware
    139     + Gopher client?
    140 * Ditch busybox, init via Python somehow
    141 * ...