James Stringer
52f71115ea
Delete the abandoned cloud-image/cidata Linux install path (zero live
callers — linux_create_thread builds the VHDX directly from the ISO):
- disk_util.c: drop iso_create_resources_ubuntu, generate_autoinstall_*,
generate_network_config, generate_ubuntu_setup_sh, find_repo_root +
copy helpers, the DEAD_ #if0 block, and the entire qcow2/VHD/inflate/
cloud-image converter incl. ensure_ubuntu_cloud_image_cached
(4492 -> 2315 lines). Shared helpers kept (create_iso_from_dir,
remove_staging_dir, unix_password_hash, stage_linux_agent_and_extras).
- disk_util.h: drop the two now-dead prototypes.
Rename the guest first-boot identifier poc-firstboot -> appsandbox-firstboot
(service/script/marker) in ubuntu_vhdx.c and reword stale "POC gpt.c"/
"f361def"/"old flow"/"subiquity"/"cidata" comment references to describe
the current direct-ISO->VHDX flow.
Fix factually-wrong comments found in a line-by-line audit:
- asb_core.c: NAT comment claimed DHCP; it's a static IP baked into the
HCN endpoint + pushed by the agent. SHA-512-crypt / Secure Boot /
create-path comments reworded off the removed flow.
- appsandbox-agent.c: gdm UID-range claim (gdm is <1000); netplan
"renderer detect" actually probes the NetworkManager service.
- appsandbox-display.c: cursor cadence said 30fps (TARGET_FPS is 60);
card-selection "connected output" claim corrected (driver-name match).
- appsandbox-audio.c: wire-proto doc said 16-bit/4-align (it's 32/8);
snd-aloop subdev comment.
Move the internal IMPLEMENTATION_PLAN.md design doc out of the repo
(it now lives in the gitignored docs/).
tools/linux — Linux-side build of AppSandbox guest components
Everything in this tree compiles on a Linux box and produces artifacts that the Windows AppSandbox host needs in order to stage a Linux VM. The components:
| Subdir | What it builds | Where it ends up in the guest |
|---|---|---|
agent/ |
5 userspace daemons (ELF) | /usr/local/bin/appsandbox-{agent,audio,clipboard,display,input} |
dxgkrnl/ |
Hyper-V GPU paravirt kernel module | /lib/modules/<kver>/updates/dxgkrnl.ko (or DKMS) |
asb_drm/ |
Stub DRM driver for KMS capture | /lib/modules/<kver>/updates/asb_drm.ko (or DKMS) |
wsl-mesa/ |
(optional) Mesa with d3d12 + dzn | tarball extracted to /opt/wsl-mesa/ |
wsl-deps/ (Microsoft's proprietary libd3d12.so etc.) is not built
here — it's fetched by the Windows host from Microsoft's public NuGet feed
into C:\ProgramData\AppSandbox\wsl-deps\. See tools/wsl-deps/README.md.
Build
Prereqs (Ubuntu 26.04+; package names may differ on other distros):
sudo apt-get install -y \
build-essential dkms zstd \
linux-headers-$(uname -r) \
libdrm-dev libasound2-dev libxcb1-dev libxcb-xfixes0-dev
Then from this directory:
make
That builds the 5 daemons, both kernel modules against your running kernel,
and installs them under tools/linux/dist/:
tools/linux/dist/
├── appsandbox-agent ← strip'd ELF
├── appsandbox-audio
├── appsandbox-clipboard
├── appsandbox-display
├── appsandbox-input
└── modules/
└── <uname-r>/
├── dxgkrnl.ko
└── asb_drm.ko
dist/ is gitignored — it's only valid on this machine for this kernel.
Other targets:
| Target | What it does |
|---|---|
make compile |
builds in place but doesn't copy to dist/ |
make agents |
builds only the userspace daemons |
make modules |
builds only the kernel modules |
make clean |
removes *.o, *.ko, daemon ELFs from source dirs |
make distclean |
clean + removes dist/ |
Transfer to the Windows host
This step is manual on purpose — there's no assumption of network connectivity between your Linux build box and the Windows machine that runs AppSandbox.
After a successful build, get dist/'s contents over to your Windows host
and place them at:
<appsandbox-repo>\release\resources\linux\
The simplest approach is a tarball:
tar -C dist -czf ~/asb-linux.tar.gz .
Then transfer asb-linux.tar.gz to the Windows host by whatever means you
normally use to move files between these two systems (USB stick, shared
filesystem, file-share VM, scp, manual upload — whatever works for your
setup). On the Windows side, in your appsandbox checkout:
mkdir release\resources\linux
tar xzf C:\path\to\asb-linux.tar.gz -C release\resources\linux\
tar.exe ships with Windows 10+; if it isn't on your PATH the Git for
Windows / 7-Zip / WinRAR equivalents all handle .tar.gz fine.
How the staged files reach a running VM
release/resources/linux/is a committed staging dir on the Windows side — same model as the existingrelease/resources/appsandbox-*.exefiles used for Windows guests.AppSandbox.vcxproj's PostBuildEvent xcopiesrelease/resources/intobin/<cfg>/resources/next toAppSandbox.exeandAppSandboxCore.dll. That happens on every build, so a rebuild after copying the new files makes them runtime-visible.- When you create a Linux VM,
disk_util.c::iso_create_resources_ubuntubuilds acidata.isowithuser-data(autoinstall) + anextras/tree that includes everything from<exe_dir>/resources/linux/. - On first boot of the VM, autoinstall mounts the cidata ISO, copies
extras/into/opt/appsandbox/, then runssetup.shviacurtin in-target.setup.shinstalls the agent ELFs into/usr/local/bin/, the kernel modules into/lib/modules/<kver>/updates/, wires up systemd units, and enables them.
Kernel module version skew
Kernel modules built here only load against an identical kernel version
in the guest (uname -r must match exactly). If the guest is on a different
kernel from your build machine, setup.sh automatically falls back to the
DKMS build path — it copies the source from extras/dxgkrnl/src/ to
/usr/src/dxgkrnl-<ver>/ and runs dkms install. DKMS handles future
kernel upgrades automatically. The committed .ko is just a fast path.