buninu-linux 0.7.0 → 0.7.1

package/README.md

@@ -36,6 +36,7 @@
   * `start` starts the Buninu userspace shell
   * `cfg.disk` + shell `mount` mounts local disks
   * `cfg.net` loads common wired NIC and Android USB-tethering drivers
+  * `cfg.sound` loads every packaged ALSA sound module
   * Android phone USB tethering over RNDIS has been tested successfully, allowing Buninu Linux to access the Internet through an Android phone
   * IP addresses and routes are configured manually because the image does not yet include a DHCP client.
   * The bundled `jmi` editor, jsmdcui App runtime, and local JavaScript execution also work.
@@ -45,6 +46,7 @@
     + Also has mouse click, wheel, and cursor drawing
     + Simplified browser works: @sanohiro/casty in chroot debian
     + (Use at your own risk: We haven't fully examined its code)
+    + Playing YouTube with sound(experimental)
     + See [Commands inside `/bin`](#commands-inside-bin) for browser usage instructions
 
 ---
@@ -142,7 +144,7 @@ display and USB keyboard with a welcome ending like this:
 Welcome to Buninu Linux!
 Bun 1.4.2 is now PID 1
 Type start() to run buninu --local
-Configuration getters: cfg.all, cfg.disk, cfg.net, cfg.power
+Configuration getters: cfg.all, cfg.disk, cfg.net, cfg.power, cfg.sound
 
 bun-repl>
 ```
@@ -157,6 +159,7 @@ Load only the subsystem needed, then enter the Buninu shell:
 cfg.net       // wired NIC and Android USB-tethering drivers
 cfg.disk      // SATA/NVMe/USB storage drivers and detected block devices
 cfg.power     // battery, AC, button and thermal drivers
+cfg.sound     // all packaged ALSA sound modules and detected sound devices
 start()
 ```
 
@@ -208,6 +211,8 @@ bun ./index.js -fbr
 The first boot line from `run-qemu.sh` names the guest, machine, accelerator
 and firmware it picked. A bare `-r` boots whichever architecture `vda.img`
 was last built for; `-br --arch arm64` is the aarch64 edit-and-boot loop.
+To run `bunterm` in a QEMU window on the aarch64 guest, see
+[What differs on aarch64](#what-differs-on-aarch64).
 
 #### amd64 Linux
 
@@ -231,9 +236,32 @@ qemu-efi-aarch64` to run.
   Alpine's aarch64 packages and `bun-linux-aarch64-musl`.
 * The serial console is `ttyAMA0` (QEMU `virt`'s PL011) instead of `ttyS0`.
 * `--real` is x86_64 only: its module set is PC hardware.
-* The current aarch64 QEMU configuration supplies no framebuffer or PS/2
-  devices, so `bunterm` has nothing to draw on yet; the serial REPL and the
-  Buninu shell work as on x86_64.
+* QEMU's `virt` machine has no display or PS/2 devices, so by default
+  `bunterm` has nothing to draw on; the serial REPL and the Buninu shell work
+  as on x86_64. To run `bunterm`, build with `--linux-lts` and give QEMU a
+  `ramfb` display and virtio input devices. On a Mac, `-display cocoa` opens
+  the window:
+
+  ```sh
+  bun ./index.js -fbr --arch arm64 --linux-lts -- \
+      -device ramfb -device virtio-keyboard-pci -device virtio-mouse-pci -display cocoa
+  ```
+
+  Once that image is built, boot it again without rebuilding (and without
+  Docker). `--linux-lts` belongs to the build, so leave it off `-r`:
+
+  ```sh
+  bun ./index.js -r --arch arm64 -- \
+      -device ramfb -device virtio-keyboard-pci -device virtio-mouse-pci -display cocoa
+  ```
+
+  `start()` in the serial REPL, then `bunterm 2` opens bunterm on VT 2 in the
+  QEMU window and returns to the serial shell; type into the window. The
+  serial console is not a VT, so a bare `bunterm` there takes the active VT 1
+  and holds the serial shell until it exits; naming another VT starts it
+  detached (see [Multiple virtual consoles with bunterm](#multiple-virtual-consoles-with-bunterm)). The
+  firmware sets up ramfb at 800×600, and `init.js` loads `simpledrm` so it
+  becomes `/dev/fb0` (see [graphics.md](graphics.md#trying-it)).
 * `--export` writes `buninu-linux-<version>-aarch64.img`.
 * Before the kernel starts, Homebrew's aarch64 EDK2 prints a few
   `Error: Image at … start failed` lines (its own drivers for hardware `virt`
@@ -283,6 +311,7 @@ Load only the hardware subsystem you need:
 cfg.net
 cfg.disk
 cfg.power
+cfg.sound
 ```
 
 `cfg.net` loads the packaged wired-network and Android USB-tethering drivers and prints detected
@@ -298,7 +327,10 @@ ip route add default via 192.168.1.1
 The real image initializes `/etc/resolv.conf` with `1.1.1.1` and `8.8.8.8`;
 replace them if your network requires different DNS servers. `cfg.disk` loads
 common SATA/PATA/SCSI, NVMe/VMD and USB-storage drivers so detected disks and
-partitions appear in `/dev`. To inspect a filesystem without mounting it:
+partitions appear in `/dev`. `cfg.sound` unconditionally loads every sound
+module packaged in the image, then lists the resulting `/dev/snd` devices; it
+does not probe the hardware before loading modules. To inspect a filesystem
+without mounting it:
 
 ```sh
 mount -fv /dev/sda1 /mnt
@@ -475,7 +507,32 @@ below a shown image, and images scroll with the text. When the program you
 started exits, the console returns to text mode. `bunterm --help` has the
 options; [graphics.md](graphics.md) describes how it is built. The image
 needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
-(the default `linux-virt` builds one only as modules the image omits).
+(the default `linux-virt` builds one only as modules the image omits). The
+aarch64 guest also needs a QEMU display; see
+[What differs on aarch64](#what-differs-on-aarch64).
+
+### Clipboard
+
+`bunterm` supports copy and paste through OSC 52, so programs such as
+`casty` and `jsmdcui` can use the clipboard. bunterm keeps nothing itself; it
+passes every copy and paste to Buninu's `xclip -selection clipboard`. For
+now that clipboard is a file, `$HOME/.xclip.clipboard`, read and written in
+the ramdisk, so all bunterm sessions share it and it is gone after a reboot.
+`bunterm --no-clipboard` turns OSC 52 off.
+
+For Chinese input, run the pinyin input method
+[jspinyin](https://www.npmjs.com/package/@drxiaozhi/jspinyin) in a bunterm
+that is not inside a chroot, so it uses Buninu's `xclip`:
+
+```sh
+bun x @drxiaozhi/jspinyin
+```
+
+- jspinyin → casty: press `Ctrl-C` in jspinyin to copy its result box, then
+  `Ctrl-V` in casty pastes it through OSC 52.
+- casty → jsmdcui / jspinyin: `Alt-C` in casty copies the selection through
+  OSC 52, and `Ctrl-V` pastes it in jsmdcui or jspinyin, since jsmdcui reads
+  from `xclip` first by default.
 
 ## Commands inside /bin
 
@@ -561,7 +618,10 @@ git clone https://github.com/jjtseng93/casty
 cd casty/bin
 # When clicking around, don’t release the mouse button immediately after pressing it, to make sure the mouse-down event is triggered
 bun casty.js buninu.org
-
+# Playing YouTube with sound(experimental)
+# make sure you have run `cfg.sound` in bun-repl
+# follow the dumped instructions
+bun x bunproot --setup.pulse
 
 
 # Download and enter an x64 Alpine minirootfs
@@ -753,7 +813,7 @@ its own.
 ```text
 index.js                  entry point: -f / -b / -r / --arch / --docker / --export / --linux-lts / --real
 Dockerfile                the Debian 13 build toolchain for --docker (and macOS)
-fetch-alpine.sh           [fetch]  kernel, EFI stub, musl, network/input modules
+fetch-alpine.sh           [fetch]  kernel, EFI stub, musl, network/input/display modules
 fetch-bun.sh              [fetch]  Bun, libstdc++, libgcc
 build-uki.sh              [build]  UKI; calls scripts/pack-initramfs.sh
 build-image.sh            [build]  GPT disk image; shared with the hello-world EFI
@@ -1089,7 +1149,7 @@ until `cfg.net` loads the packaged drivers and the user assigns an address and
 route.
 
 On a `--real` image the REPL also offers the getter-based `cfg` namespace:
-`cfg.net`, `cfg.disk`, `cfg.power` and `cfg.all` run as soon as the property is read, without
+`cfg.net`, `cfg.disk`, `cfg.power`, `cfg.sound` and `cfg.all` run as soon as the property is read, without
 parentheses. `cfg.net` loads every packaged network module (including PHY and bus support),
 then reads the `modalias` of every PCI and USB network device, matches it
 against the `pci:`/`usb:` lines
@@ -1101,7 +1161,10 @@ declared dependencies. `--real` ships Intel `e1000`/`e1000e`/`igb`/`igc`,
 Realtek `r8169`, Atheros `alx`, Broadcom `tg3`, common USB dongles, and
 `rndis_host`/`cdc_ether`/`cdc_ncm`/`cdc_eem`/`cdc_subset`/`zaurus` for Android
 USB tethering. `cfg.net` unconditionally attempts all of these packaged
-network modules. `cfg.power` loads the ACPI
+network modules. `cfg.sound` likewise unconditionally attempts every packaged
+module below `kernel/sound/`, then lists `/dev/snd`; it does no hardware probe.
+The packaged sound set covers QEMU ES1371/HDA and common PC HDA/HDMI and USB
+audio where the selected kernel flavor provides them. `cfg.power` loads the ACPI
 `battery`, `ac`, `button` and `thermal` modules through `/lib/modprobe.js`
 and lists `/sys/class/power_supply` (a desktop without a battery simply
 reports nothing registered). Nothing loads them at boot. PID 1 also installs
@@ -1136,6 +1199,7 @@ for the userspace session.
       - [Pane and tab controls](#pane-and-tab-controls)
   * [Using Bun Modern Shell](#using-bun-modern-shell)
   * [Showing images](#showing-images)
+  * [Clipboard](#clipboard)
 - [Commands inside /bin](#commands-inside-bin)
 - [Environment and dependencies](#environment-and-dependencies)
   * [Build environment](#build-environment)

package/fetch-alpine.sh

@@ -81,6 +81,22 @@ if [ "$arch" = x86_64 ]; then
 else
     select_module virtio_input
 fi
+# The framebuffer for bunterm. Both lts kernels set CONFIG_SYSFB_SIMPLEFB, so
+# the UEFI GOP (QEMU's ramfb on aarch64 virt) becomes a simple-framebuffer
+# device that only simpledrm drives: x86_64 lts builds it in, aarch64 lts has
+# it as a module. init.js loads it at boot, which is what makes /dev/fb0.
+if [ "$linux_flavor" = lts ]; then
+    select_optional_module simpledrm
+fi
+
+# Sound: a compact set covering QEMU's emulated AC97/HDA devices and the
+# usual PC HDA/HDMI and USB-audio paths. Dependencies pull in the ALSA core,
+# PCM, timer, codec and USB support needed by each available leaf driver.
+# Some kernel flavors build fewer of these, so keep every leaf optional.
+for module in snd-ens1371 snd-hda-intel snd-hda-codec-generic \
+              snd-hda-codec-hdmi snd-usb-audio; do
+    select_optional_module "$module"
+done
 
 if [ "${REAL_MACHINE:-}" = 1 ]; then
     # USB keyboard for the console; common storage paths (SATA/AHCI HDD and

package/graphics.md

@@ -174,13 +174,22 @@ needs about 1 GB.
 
 ## Trying it
 
-The framebuffer needs a kernel that provides one. Alpine's `linux-lts` has
-`CONFIG_FB`, `CONFIG_FB_EFI` and `CONFIG_DRM_SIMPLEDRM` built in; the default
-`linux-virt` builds them as modules, and the image ships only the network,
-storage, USB and HID modules, so there `/dev/fb0` never appears. Build with
-`./index.js -b --linux-lts` (or `--real`); under QEMU the lts kernel gets a
-1280×800 `simpledrm` framebuffer from the UEFI GOP even with `-display none`,
-and the monitor's `screendump` shows it. From a virtual console in the guest:
+The framebuffer needs a kernel that provides one. Both `linux-lts` kernels
+set `CONFIG_SYSFB_SIMPLEFB`, so the UEFI GOP becomes a `simple-framebuffer`
+device, which only `simpledrm` drives (`efifb` never sees it). The x86_64
+`linux-lts` builds `simpledrm` in. The aarch64 one has it as a module:
+`fetch-alpine.sh` ships it and its DRM dependencies for lts builds, and
+`init.js` loads it at boot. The default `linux-virt` builds the framebuffer
+drivers as modules, and the image ships only the network, storage, USB and
+HID modules, so there `/dev/fb0` never appears. Build with
+`./index.js -b --linux-lts` (or `--real` on x86_64). Under QEMU, the x86_64
+lts kernel gets a 1280×800 `simpledrm` framebuffer from the UEFI GOP even
+with `-display none`, and the monitor's `screendump` shows it. QEMU's aarch64
+`virt` machine has no display until you add `-device ramfb`; EDK2 then
+provides an 800×600 GOP, and `virtio-keyboard-pci` gives the VTs a keyboard
+(see the README's
+[What differs on aarch64](README.md#what-differs-on-aarch64)). From a virtual
+console in the guest:
 
 ```sh
 bunterm                                  # /bin/sh on this console
@@ -206,6 +215,13 @@ host, `jsmdcui --tui` on a Markdown file with a JPEG (bunterm sets
 `JSMDCUI_KITTY_MODE=extended` for the program it runs) places the image
 through its transmit / `a=p` / `a=d` sequence exactly as in the browser.
 
+Verified on aarch64 (lts kernel, Hypervisor.framework, `-device ramfb
+-device virtio-keyboard-pci -device virtio-mouse-pci`, `-display none`):
+`/proc/fb` lists `simpledrmdrmfb`; `bunterm 2` from the serial shell returns
+at once and draws on VT 2; and keys sent with the monitor's `sendkey` reach
+it: `showimg /buninu/icon.png` places the kitty image, and the prompt's
+colour emoji and the pointer render, all checked with `screendump`.
+
 ## Not done yet
 
 - Selection and scrollback viewing in `bunterm` (the pointer itself works,

package/initramfs/bin/bunterm

@@ -11,7 +11,7 @@ const CANONICAL_BUNTERM = "/bin/bunterm";
 
 const usage = () => {
   console.error(`Usage:
-  bunterm [N | /dev/ttyN] [-s N | --font-size N] [--fb /dev/fb0] [--no-mouse] [-e command [argument...]]
+  bunterm [N | /dev/ttyN] [-s N | --font-size N] [--fb /dev/fb0] [--no-mouse] [--no-clipboard] [-e command [argument...]]
   bunterm -h | --help`);
 };
 
@@ -58,6 +58,8 @@ const main = async () => {
       options.mouse = true;
     } else if (argument === "--no-mouse") {
       options.mouse = false;
+    } else if (argument === "--no-clipboard") {
+      options.clipboard = false;
     } else if (/^[1-9][0-9]*$/.test(argument) || argument.startsWith("/dev/")) {
       const number = /^[1-9][0-9]*$/.test(argument) ? Number(argument) : virtualConsoleNumber(argument);
       if (number === null) throw new Error(`expected N or /dev/ttyN, got ${argument}`);

package/initramfs/init.js

@@ -179,6 +179,16 @@ try {
   console.error(`init.js: input modules: ${error?.message ?? error}`);
 }
 
+// The framebuffer for bunterm: the firmware's GOP is a simple-framebuffer
+// device, and simpledrm turns it into /dev/fb0. x86_64 linux-lts builds it
+// in and linux-virt images do not ship it; tryModprobe skips both.
+try {
+  const { tryModprobe } = await import("/lib/modprobe.js");
+  if (tryModprobe("simpledrm")?.length) console.log("init.js: loaded simpledrm");
+} catch (error) {
+  console.error(`init.js: simpledrm: ${error?.message ?? error}`);
+}
+
 const { default: repl } = await import("node:repl");
 const { mkdirSync, writeFileSync } = await import("node:fs");
 
@@ -549,11 +559,26 @@ const configureDisks = () => {
   return devices;
 };
 
+// Load the complete sound stack packaged in the image. Like cfg.net this is
+// deliberately unconditional: it does not probe modaliases first, so codec
+// and helper modules without their own discoverable device are loaded too.
+const configureSound = () => {
+  const { modprobeAll } = require("/lib/modprobe.js");
+  const { readdirSync } = require("node:fs");
+  const report = modprobeAll({ accept: (_module, path) => path.startsWith("kernel/sound/") });
+  console.log(`sound: loaded all packaged sound modules (${report.inserted.length} newly loaded, ${report.errors.length} failed)`);
+  for (const { module, error } of report.errors) console.log(`sound: ${module}: ${error}`);
+  const devices = (() => { try { return readdirSync("/dev/snd"); } catch { return []; } })();
+  console.log(`sound: ${devices.length ? devices.map((name) => `/dev/snd/${name}`).join(" ") : "no sound devices registered"}`);
+  return devices;
+};
+
 globalThis.cfg = Object.freeze(Object.defineProperties({}, {
   all: { enumerable: true, get: configureModules },
   disk: { enumerable: true, get: configureDisks },
   net: { enumerable: true, get: configureEthernet },
   power: { enumerable: true, get: configureBattery },
+  sound: { enumerable: true, get: configureSound },
 }));
 
 // Compatibility aliases for images and notes that used the original API.
@@ -562,6 +587,7 @@ globalThis.cfgNet = configureEthernet;
 globalThis.cfgDisk = configureDisks;
 globalThis.cfgMod = configureModules;
 globalThis.cfgBat = configureBattery;
+globalThis.cfgSound = configureSound;
 
 const showWelcome = () => {
   console.log(`

package/initramfs/lib/bunterm/clipboard.js

@@ -0,0 +1,51 @@
+// /lib/bunterm/clipboard.js — OSC 52 clipboard for bunterm, backed by xclip.
+//
+//   program ── ESC ] 52 ; c ; <base64> BEL ──▶ xclip -selection clipboard
+//   program ── ESC ] 52 ; c ; ? BEL ─────────▶ xclip -selection clipboard -o
+//           ◀── ESC ] 52 ; c ; <base64> BEL ──
+//
+// bunterm keeps nothing itself: every copy and paste goes through xclip, so
+// all bunterm sessions (and anything else using xclip) share one clipboard.
+// Buninu's xclip prints status lines on stderr, which must not reach the
+// console under the framebuffer, so stderr is discarded.
+
+const runXclip = async (args, input) => {
+  const command = ["xclip", "-selection", "clipboard", ...args];
+  const proc = Bun.spawn(command, {
+    stdin: input === undefined ? "ignore" : input,
+    stdout: input === undefined ? "pipe" : "ignore",
+    stderr: "ignore",
+  });
+  const [output, exitCode] = await Promise.all([
+    input === undefined ? new Response(proc.stdout).arrayBuffer() : null,
+    proc.exited,
+  ]);
+  if (exitCode !== 0) throw new Error(`${command.join(" ")} exited with ${exitCode}`);
+  return output;
+};
+
+// Registers the OSC 52 handler on an xterm.js terminal. `reply` sends bytes
+// back to the program, as the terminal's other replies do. A read the xclip
+// call cannot answer is still answered, with empty contents, so the program
+// does not wait out its own timeout.
+export const attachClipboard = ({ term, reply, onError = () => {} }) =>
+  term.parser.registerOscHandler(52, (data) => {
+    const separator = data.indexOf(";");
+    if (separator < 0) return true;
+    const target = data.slice(0, separator);
+    const payload = data.slice(separator + 1);
+
+    if (payload === "?") {
+      // The reply is sent after xclip returns, when the program may have exited
+      // and the PTY closed; writing then throws, and an unhandled rejection
+      // would end bunterm before it restores the console.
+      runXclip(["-o"])
+        .catch((error) => { onError(error); return new ArrayBuffer(0); })
+        .then((bytes) => reply(`\u001b]52;${target};${Buffer.from(bytes).toString("base64")}\u0007`))
+        .catch(onError);
+      return true;
+    }
+
+    runXclip([], Buffer.from(payload, "base64")).catch(onError);
+    return true;
+  });

package/initramfs/lib/bunterm/terminal.js

@@ -21,6 +21,7 @@ import { Renderer, defaultTheme } from "./renderer.js";
 import { ImageStore } from "./images.js";
 import { openKeyboard, translateKeys } from "./input.js";
 import { claimVirtualConsole } from "./vt.js";
+import { attachClipboard } from "./clipboard.js";
 
 const require = createRequire(import.meta.url);
 
@@ -52,6 +53,7 @@ export const createSession = ({
   scrollback = 1000,
   cursorBlink = true,
   mouse = true,
+  clipboard = true,
   env = {},
   onError = (error) => console.error(`bunterm: ${error?.stack ?? error}`),
 }) => {
@@ -158,6 +160,9 @@ export const createSession = ({
   });
   backend.onData(pump);
   term.onData((data) => backend.write(Buffer.from(data, "utf8")));
+  // OSC 52 copy and paste go straight to xclip; replies return to the program.
+  // Without it (--no-clipboard) xterm.js ignores OSC 52 and nothing reaches xclip.
+  if (clipboard) attachClipboard({ term, reply: (text) => backend.write(Buffer.from(text, "utf8")), onError });
 
   // Keyboard bytes from the console, rewritten for the program's key mode.
   const input = (bytes) => {

package/initramfs/usr/share/doc/buninu-linux/bunterm.md

@@ -12,6 +12,7 @@ bunterm /dev/tty1            # the full virtual-console spelling also works
 bunterm -s 20                # short for --font-size 20
 bunterm -e bun /buninu/apps/jsmdcui/src/index.js --demo
 bunterm --no-mouse          # keyboard only
+bunterm --no-clipboard      # ignore OSC 52 copy and paste
 bunterm -h
 ```
 
@@ -39,6 +40,7 @@ identified from the process task name and its open console descriptor under
 | `--fb /dev/fbN` | The framebuffer device (default `/dev/fb0`). |
 | `--no-blink` | A steady cursor. |
 | `--no-mouse` | Do not attach a pointing device; nothing then reads `/dev/input`. |
+| `--no-clipboard` | Ignore OSC 52: programs can neither copy to nor read from the clipboard, and `xclip` is never run. |
 
 ## What is drawn
 
@@ -101,6 +103,16 @@ mouse also needs the `usbhid` stack, which a `--real` image carries and
 ones (a tablet or touchscreen) alike; a device that cannot be opened is
 reported and the session continues without it.
 
+## Clipboard
+
+Programs copy and paste through OSC 52, as `casty` and `jsmdcui` do.
+bunterm keeps no clipboard of its own: `ESC ] 52 ; c ; <base64>` is passed to
+`xclip -selection clipboard`, and a query (`ESC ] 52 ; c ; ?`) is answered
+with the output of `xclip -selection clipboard -o`, so every bunterm session
+shares the same clipboard as `xclip`. A query xclip cannot answer is replied
+to with empty contents. `--no-clipboard` turns this off, so a program can
+neither set nor read the clipboard through the terminal.
+
 ## Limits
 
 - Needs a framebuffer: `linux-lts` has one built in, while the default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "A Linux distribution running Bun as PID 1 with the Buninu userspace.",
   "type": "module",
   "main": "./index.js",