diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index fdd979abf..d6a4b6257 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -5,6 +5,10 @@ # Asterinas NixOS * [Getting Started](distro/README.md) +* [Popular Applications](distro/popular-applications/README.md) + * [Package Management](distro/popular-applications/package-management.md) + * [Desktop Environment](distro/popular-applications/desktop-environment.md) + * [Containerization](distro/popular-applications/containerization.md) # Asterinas Kernel diff --git a/book/src/distro/popular-applications/README.md b/book/src/distro/popular-applications/README.md new file mode 100644 index 000000000..ca66b01dc --- /dev/null +++ b/book/src/distro/popular-applications/README.md @@ -0,0 +1,8 @@ +# Popular Applications + +The [Nix package collection](https://search.nixos.org/packages) contains over 120,000 packages. +Many of them may already work out of the box on Asterinas NixOS, +but it is impractical to test every package +and document its support status. +Instead, we group popular applications into categories +and document the ones we have verified to work. diff --git a/book/src/distro/popular-applications/containerization.md b/book/src/distro/popular-applications/containerization.md new file mode 100644 index 000000000..3e53b7c1a --- /dev/null +++ b/book/src/distro/popular-applications/containerization.md @@ -0,0 +1,56 @@ +# Containerization + +## Podman + +[Podman](https://docs.podman.io/en/stable/Introduction.html) is a modern, daemonless container engine +that provides a Docker-compatible command-line interface, +making it easy for users familiar with Docker to transition. + +### Installation + +To install Podman, add the following line to `configuration.nix`: + +```nix +virtualization.podman.enable = true; +``` + +### Verified Usage + +#### `podman run` + +`podman run` runs a command in a new container. + +```bash +# Start a container, execute a command, and then exit +podman run --name=c1 docker.io/library/alpine ls /etc + +# Start a container and attach to an interactive shell +podman run -it docker.io/library/alpine +``` + +#### `podman image` + +`podman image` manages local images. + +```bash +# List downloaded images +podman image ls +``` + +#### `podman ps` + +`podman ps` lists containers. + +```bash +# Show the status of all containers (including exited ones) +podman ps -a +``` + +#### `podman rm` + +`podman rm` removes one or more containers. + +```bash +# Remove a container named foo +podman rm foo +``` diff --git a/book/src/distro/popular-applications/desktop-environment.md b/book/src/distro/popular-applications/desktop-environment.md new file mode 100644 index 000000000..293266387 --- /dev/null +++ b/book/src/distro/popular-applications/desktop-environment.md @@ -0,0 +1,56 @@ +# Desktop Environment + +## Xfce + +[Xfce](https://www.xfce.org/) is a lightweight desktop environment for UNIX-like operating systems. + +### Installation + +Add the following lines to the `configuration.nix` file: + +```nix +services.xserver.enable = true; +services.xserver.desktopManager.xfce.enable = true; +``` + + + +### Verified Backends + +* Display server: + * Xorg display server +* Graphics drivers: + * Standard UEFI VGA framebuffer + +### Verified Functionality + +* Changing desktop wallpapers and background settings +* Adjusting font size, style, and system theme +* Creating application shortcuts and desktop launchers +* Managing panels and window behavior +* Using the settings manager and file browser + +### Verified GUI Applications + +Utilities: + +* `galculator`: Calculator +* `mousepad`: The default Xfce text editor +* `mupdf`: A lightweight PDF and XPS viewer + +Games: + +* `fairymax`: Chess +* `five-or-more`: GNOME alignment game +* `lbreakout2`: Breakout/Arkanoid clone +* `gnome-chess`: GNOME chess +* `gnome-mines`: Minesweeper +* `gnome-sudoku`: GNOME sudoku +* `tali`: GNOME dice game +* `xboard`: Chess +* `xgalaga`: Galaga-style arcade game diff --git a/book/src/distro/popular-applications/package-management.md b/book/src/distro/popular-applications/package-management.md new file mode 100644 index 000000000..bc86fe74a --- /dev/null +++ b/book/src/distro/popular-applications/package-management.md @@ -0,0 +1,95 @@ +# Package Management + +NixOS provides a set of [tools](https://nix.dev/manual/nix/2.28/command-ref/main-commands) +for building, installing, and managing packages. + +## Verified Usage + +### `nix-build` + +`nix-build` builds Nix derivations and produces outputs in the Nix store. +It is the preferred way to build software reproducibly. + +```bash +# Step 1: Create a clean workspace +rm -rf /tmp/nix-hello-c && mkdir -p /tmp/nix-hello-c && cd /tmp/nix-hello-c + +# Step 2: Write a C program +cat > hello.c <<'EOF' +#include + +int main(void) { + puts("Hello, World!"); + return 0; +} +EOF + +# Step 3: Write a default.nix +cat > default.nix <<'EOF' +{ pkgs ? import {} }: + +pkgs.stdenv.mkDerivation { + pname = "hello-c"; + version = "0.1.0"; + src = ./.; + + dontConfigure = true; + + buildPhase = '' + cc hello.c -o hello + ''; + + installPhase = '' + mkdir -p $out/bin + install -m755 hello $out/bin/hello + ''; +} +EOF + +# Step 4: Build and run +nix-build +./result/bin/hello +``` + +### `nix-env` + +`nix-env` installs or removes individual packages in your user profile. + +```bash +# Install the `hello` package +nix-env -iA nixos.hello + +# Remove the `hello` package +nix-env -e hello +``` + +### `nix-shell` + +`nix-shell` creates a temporary development environment with the specified dependencies. +This is useful for testing software without modifying your system environment. + +```bash +# Enter a shell with the `hello` package available +nix-shell -p hello +``` + +### `nixos-rebuild` + +`nixos-rebuild` manages the entire system configuration declaratively. +It applies changes defined in `configuration.nix`, +and is the recommended approach for installing packages system-wide. + +```bash +# Edit the system configuration file +vim /etc/nixos/configuration.nix + +# Apply configuration changes and rebuild the system without rebooting +nixos-rebuild test +``` + +