From 7f56c57c58b96388060727b68bcc27118fee4a21 Mon Sep 17 00:00:00 2001 From: meichuanyi <35057768+meichuanyi@users.noreply.github.com> Date: Sat, 6 Jun 2026 17:11:20 +0800 Subject: [PATCH] docs: Add FAQ section for common questions --- README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 17f5c7b2..972efad3 100644 --- a/README.md +++ b/README.md @@ -327,7 +327,161 @@ The same `.xlings.json` drives CI and the release pipeline. - **QQ Groups**: 167535744 / 1006282943 - **Issues**: [github.com/openxlings/xlings/issues](https://github.com/openxlings/xlings/issues) -### Contributing +# +## ❓ FAQ (Frequently Asked Questions) + +### What is xlings? + +xlings is a **universal package infrastructure** with OS-like SubOS isolation. Key features: + +| Feature | Description | +|---------|-------------| +| **Multi-version coexistence** | N versions side-by-side without conflicts | +| **Rootless operation** | No sudo needed for shell/FS-level isolation | +| **3-level SubOS** | shell / FS sandbox / image isolation | +| **Decentralized index** | Official + 3rd-party + self-hosted packages | +| **Agent interface** | JSON protocol for AI agents and automation | + +Used by [MCPP](https://github.com/mcpp-community/mcpp) and upcoming **Luban Linux**. + +### How does xlings compare to other tools? + +| Tool | Multi-version | Rootless | No daemon | Isolation | Agent-ready | +|------|---------------|----------|-----------|-----------|-------------| +| **apt/brew** | ❌ | ❌ | ✅ | ❌ | ❌ | +| **nix** | ✅ | ⚠️ | ✅ | ✅ | ❌ | +| **docker** | ✅ | ⚠️ | ❌ | ✅+ | ⚠️ | +| **xlings** | ✅ | ✅ | ✅ | 🔒 3 levels | ✅ | + +**xlings unique advantages:** +- ⚡ **Instant startup** (no daemon, no image pull) +- 🔄 **Storage reuse** (N envs ≈ 1× storage via version-view) +- 🤖 **Native agent interface** (NDJSON protocol) + +### What are the 3 SubOS isolation levels? + +| Level | Technology | Permissions | Use Case | +|-------|------------|-------------|----------| +| **Shell-level** | Env switch | 🔓 Host access | Quick version switching | +| **FS-level** | bwrap/proot | 🔓 Host access | Project isolation (rootless) | +| **Image-level** | ext4 sparse | 🔒 Root needed | Full isolation (strongest) | + +**FS-level sandbox is recommended** for most use cases: lightweight, rootless, host untouched. + +### How do I install xlings? + +**Linux/macOS:** +```bash +curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash +``` + +**Windows (PowerShell):** +```powershell +irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex +``` + +**Via AI agent:** +Copy this prompt to your AI assistant: +``` +Install xlings package manager: +- Linux/macOS: curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash +- Windows: irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex +Project: https://github.com/openxlings/xlings +``` + +### How do I use multi-version packages? + +```bash +# Install multiple versions +xlings install gcc@16 gcc@11 node@24 cmake + +# Switch versions instantly +xlings use gcc@16 # → gcc 16.x active +xlings use gcc@11 # → gcc 11.x active, no conflict + +# Check active versions +xlings list +``` + +All versions coexist in `xpkgs/` with **version-view + reference counting** for efficient storage. + +### How does project-level SubOS work? + +When you enter a project directory with `.xlings.json`: + +```json +{ + "workspace": { + "mcpp": "0.0.33", + "gcc": { "linux": "16.1.0" } + } +} +``` + +```bash +cd my-project/ # Automatically enters project SubOS +xlings install # Installs into project-local isolation +mcpp build # Everything works, isolated from host +``` + +**Team benefits:** Same env across teammates + CI. Clone → `cd` → build. No manual activation needed. + +### Can AI agents use xlings? + +**Yes!** xlings has a native **JSON interface** for AI agents: + +```bash +# NDJSON protocol for programmatic control +xlings interface + +# Run agents inside SubOS +xlings subos new claude-workspace --from subos:dev-env@latest +xlings subos use claude-workspace --sandbox +# → Agent runs inside isolated world with full permissions +# → Host remains completely safe +``` + +**Why this matters for agents:** +- 🔓 Agent has full permissions inside SubOS +- 🔁 Multiple agent instances on one host (each in own SubOS) +- ⚡ Lightweight — not a VM or container + +### What package types are supported? + +| Type | Description | +|------|-------------| +| **binary** | Pre-built executables | +| **script** | Shell/Python scripts | +| **config** | Configuration packages | +| **subos** | Complete environment images | +| **tutorial** | Learning packages | + +Decentralized index: **official** (openxlings/xim-pkgindex) + **3rd-party** + **self-hosted**. + +### Is xlings free to use? + +**Yes!** xlings is **completely free** and open-source. + +- **License:** MIT +- **No registration required** +- **No API keys needed** +- **No hidden costs** + +Community-driven development with support from [MCPP](https://github.com/mcpp-community/mcpp) and [d2learn](https://forum.d2learn.org/). + +### Where can I get help? + +| Resource | Link | +|----------|------| +| **Website** | [openxlings.github.io](https://openxlings.github.io/) | +| **Docs** | [docs/](docs/) | +| **Package Index** | [xim-pkgindex](https://openxlings.github.io/xim-pkgindex) | +| **Forum** | [forum.d2learn.org](https://forum.d2learn.org/category/9/xlings) | +| **GitHub Issues** | [Report issues](https://github.com/openxlings/xlings/issues) | + +--- + +## Contributing - [Issue handling & bug fixing](https://xlings.d2learn.org/en/documents/community/contribute/issues.html) - [Adding new packages](https://xlings.d2learn.org/en/documents/community/contribute/add-xpkg.html)