Gentoo Chinese Community – Gentoo Chinese Community

Recent Community Updates: Live ISO, Website, Download Site, and Speedtest

Tue, 09 Jun 2026 00:00:00 +0000

A roundup of what the community has worked on recently, project by project. Each item links to its repo, so you can dig into the full history if you want.

Live ISO

The Chinese community’s custom KDE Plasma 6 desktop Live ISO (Gentoo-zh/Live-ISO):

Three languages out of the box: the boot menu offers Simplified / Traditional / English, and the whole live environment follows your choice; the installed system also keeps whatever language you picked in the installer.
Chinese input methods preinstalled: fcitx5 + rime, ready to type out of the box, with Luna Pinyin, Zhuyin, Wubi86, Cangjie, and Cantonese Pinyin built in.
Proprietary NVIDIA, optional: pick the NVIDIA entry in the boot menu to load the proprietary driver normally (disable Secure Boot first); otherwise it uses open-source nouveau.
Handy live-only desktop switches: the desktop has a few one-click toggles meant just for the live session, there when you need them — temporarily turn off auto-sleep / lock (so a long session or install isn’t interrupted), enable passwordless sudo, and start SSH (handy for a remote install or debugging).
The installed system is clean: those live conveniences (along with the default passwordless SDDM autologin) only exist in the live session; the installer resets / clears them on install, so the installed system goes back to KDE’s normal defaults — login needs a password, sudo needs authorization, and sleep/lock behave normally.
Out-of-the-box details: PipeWire audio, networking connects on boot, and MAKEOPTS / CPU instruction sets adapt to your machine.

For actually installing a system, following the Gentoo Handbook step by step is the more solid route; the live ISO also ships a graphical installer (Calamares) if you want a quick install.

The installer (Calamares)

The installer config lives in Gentoo-zh/calamares-settings-gig: after an install it clears out the live-only leftover settings and configures NVIDIA according to the GPU option you chose in the live session. The install flow has been tested with a real QEMU install.

The overlay the Live ISO uses

The packages the Live ISO builds from come from Gentoo-zh/gig — a fork of the Gig OS overlay, specific to the Live ISO, and not the same thing as the community’s main overlay, gentoo-zh. This round updated its Calamares to 3.3.14-r8 (which supports Python 3.14), fixed an emerge --sync error, and cleaned out a batch of redundant / broken packages.

Build and release

The build pipeline, Zakkaus/gentoozh-liveiso-infra: the Live ISO is compiled automatically every Monday, uploaded to the download site, and the landing page re-rendered. The pipeline does a byte-for-byte check that “what’s on the download site == what was just built”, and only publishes when they match; it also copes with the USE / keyword churn of a rolling-tree transition automatically (see the Python 3.14 post).

Website

The website, www.gentoo.org.cn (source: gentoo-zh.github.io), migrated from Blowfish to Hextra — lighter, faster, and friendlier to docs and text browsers (details in the migration post). The presentation layer was split out into a standalone Hextra patch package, gentoozh-theme, which also rounded out SEO, the footer, and accessibility. The download page was wired up to the download site, with notes on the Live ISO’s features and hardware requirements, plus a new FAQ page. This round also added English to the public pages, so you can switch between Simplified / Traditional / English.

Download site

The download site, mirror.gentoozh.org (source: Zakkaus/gentoozh-mirror): the landing page and the usage guide were reworked into Simplified / Traditional / English (with the i18n pulled into a shared module), it supports light / dark mode, cross-links with the speedtest site, and gained a Telegram channel link and an MIT license; it also fixed the SHA256 checksum overflowing sideways on mobile.

Speedtest site

The speedtest site, speed.gentoozh.org (Zakkaus/gentoozh-speed): a custom LibreSpeed-based speed test page, also in Simplified / Traditional / English.

Want to try the Live ISO? Head to the download page. Questions are welcome on Telegram or each project’s GitHub.

Python 3.14 Becomes the Default (2026-06-01)

Mon, 01 Jun 2026 00:00:00 +0000

As of 2026-06-01, Gentoo switched the system default Python from 3.13 to 3.14.

If you’ve never set PYTHON_TARGETS or PYTHON_SINGLE_TARGET yourself (most people haven’t), there’s basically nothing to do — the next time you run emerge to upgrade, the system will start switching to 3.14 on its own.

Official announcement: Python 3.14 to become the default on 2026-06-01 (posted 2026-04-16; you can also read it locally with eselect news read).

Most people: just let it upgrade

Plenty of packages are still being ported to 3.14, so there’s no rush — let it switch over gradually as part of your normal @world upgrades.

Here’s how the upgrade works: each package switches to the new Python as it gets rebuilt. So a chain of interdependent packages all has to support 3.14 before the upgrade can go through, and along the way a command or two may temporarily fail to find a dependency (programs that are already running are usually fine). That’s all normal for the transition, and it sorts itself out once everything has rebuilt.

If you’ve set a Python version in make.conf, remove it first

If you’ve put PYTHON_TARGETS or PYTHON_SINGLE_TARGET in make.conf, remove them first — upstream recommends against setting Python versions in make.conf, because it overrides the per-package defaults that should apply. Everything below assumes you put the config in the file /etc/portage/package.use/python (package.use is a directory; the filename is up to you — here it’s python).

If you want to control the timing

Pick one of these.

① Go with the default, upgrade automatically

Set nothing, and the system handles it. If it gets stuck partway, run the upgrade commands below by hand.

② Hold off, stay on 3.13 for now

Put this in /etc/portage/package.use/python:

*/* PYTHON_TARGETS: -* python3_13
*/* PYTHON_SINGLE_TARGET: -* python3_13

This only buys you time — you’ll have to migrate eventually.

③ Switch to 3.14 right now

Put this in /etc/portage/package.use/python:

*/* PYTHON_TARGETS: -* python3_14
*/* PYTHON_SINGLE_TARGET: -* python3_14

Then run the upgrade commands below. Once the default officially flips, remember to remove these two lines, or they’ll block the automatic upgrade to 3.15 later on.

④ The more cautious, step-by-step way

Keep both 3.13 and 3.14 enabled first, then drop 3.13. The affected packages get built twice, so it’s slower, but less likely to break partway.

Step one — put this in /etc/portage/package.use/python (both enabled) and run one round of the upgrade commands:

*/* PYTHON_TARGETS: -* python3_13 python3_14
*/* PYTHON_SINGLE_TARGET: -* python3_13

Step two — change it to this and run another round:

*/* PYTHON_TARGETS: -* python3_13 python3_14
*/* PYTHON_SINGLE_TARGET: -* python3_14

Step three — keep only 3.14 and upgrade one last time:

*/* PYTHON_TARGETS: -* python3_14
*/* PYTHON_SINGLE_TARGET: -* python3_14

Upgrade commands

When you switch versions, the old 3.13 has to be cleared out of the whole dependency tree at once; if some straggler package is left behind, you’ll get dependency conflicts. So the upgrade should go through --deep --changed-use @world, and clear out orphaned packages first:

emerge --depclean
emerge -1vUD @world
emerge --depclean

Python 3.11 and PyPy 3.11 are being removed too

This round also drops support for python3_11 and PyPy 3.11 (pypy3_11). PyPy doesn’t have a Python 3.12-compatible release yet, so Gentoo is dropping PyPy support for now and will bring it back once a new version ships.

If an upgrade reports a USE conflict

During the transition, if a package hasn’t been ported to 3.14 yet, a @world upgrade may report The following USE changes are necessary to proceed. This is usually temporary: either pin the Python version for that package as in ② above, or wait a few days for the packages to catch up, and it’ll go through.

Questions are welcome on Telegram or GitHub.

Migrating the Site Theme from Blowfish to Hextra

Fri, 29 May 2026 00:00:00 +0000

Last time we moved the site from Jekyll to Hugo. This time we’ve swapped themes again: from Blowfish to Hextra.

Why Hextra

Blowfish does a lot, but for a community site that’s mostly docs and tutorials it’s a bit heavy: it loads a lot of scripts and styles above the fold, the page overhead runs high, and the default typography isn’t clean enough for long reads.

Hextra is built on Tailwind CSS and made for docs and blogs:

Lighter and faster: zero third-party requests (no external fonts / CDNs / trackers), around 50 KB (gzipped) of above-the-fold text assets; contributor avatars are auto-scaled to their display size, which cuts page overhead a lot;
Cleaner reading: tidy heading hierarchy, line spacing, and code-block typography make long articles easier to read;
Built-in full-text search (FlexSearch), dark mode, and a responsive layout;
Pulled in via Hugo Modules, with no Node toolchain required.

Main Changes

Reworked home page: hero + quick links + latest posts + community contributors;
Contributor list: pulls everyone with 5+ commits in the gentoo-zh Overlay, shows their commit counts, sorts by commit count, and refreshes itself every month;
Article pages show the author’s avatar in the byline;
Articles are now categorized with tags; #tags show up on article pages and lists, and you can click through to the /tags/ aggregation page;
The “Latest posts” section on the home page has an RSS feed; share a link to Telegram or a social platform and you get a branded preview card;
The download page highlights the “Chinese-community-customized KDE desktop Live ISO”, which newcomers can use out of the box;
The whole site runs both Simplified and Traditional Chinese (zh-CN / zh-TW) side by side;
Site-wide full-text search and dark mode.

Friendly to Terminal Browsers (TUI)

lzamora70 suggested this in the @gentoo_zh_offtopic group — a bit of a wild card who’s nuked and remade their account more than once, so that handle may already be out of date — so we did a pass to make the site work well in terminal / text browsers. It is Gentoo, after all:

Semantic HTML and a clean heading hierarchy, so the layout stays readable and links stay reachable in plain-text browsers like lynx / w3m / links;
Every page has a “skip to content” link at the top, so you can jump past the nav and start reading right away;
Every image has sensible alt text; decorative duplicates (the looping copies in the avatar wall, and the light/dark pair of logos) use empty alt so text browsers and screen readers don’t read them out over and over;
In text mode, the contributor avatar wall and article bylines list each person only once;
Pair that with Hextra’s “View as Markdown / Copy as Markdown” page menu and it’s easy to grab a page’s raw text with a script or an LLM.

Try it with lynx https://www.gentoo.org.cn/.

Update: English on the public pages

After the migration we also added English to the public pages — about, download, mirror list, contributing and so on — for the gentoo-zh overlay’s overseas users, so you can now switch between Simplified / Traditional / English. To be clear, not every technical article is in English; only the public pages are translated for now. The English was drafted with translation software and reviewed and polished by Claude Fable 5 (ultracode) — the best and most expensive model we could find to date — so there may still be rough edges; corrections on GitHub are welcome.

Feedback

Telegram channel: @gentoocn · group: @gentoo_zh
File an Issue / PR: GitHub

Thanks to the developers of the Blowfish and Hextra themes.

Migrating the Site from Jekyll to Hugo

Tue, 18 Nov 2025 00:00:00 +0000

With the blessing of founder @biergaizi, @Zakkaus took over day-to-day maintenance of this site in 2025 and migrated it from Jekyll to Hugo.

Why Switch to Hugo

Jekyll needs a Ruby environment, builds are on the slow side, and its theme scene isn’t as lively as it used to be. Hugo is a single Go binary—builds are fast, deployment is simple, and multilingual support is built in. We went with the Blowfish theme.

What Got Migrated

The _posts directory moved to Hugo’s Page Bundles (content/posts/<slug>/index.zh-cn.md)
Front matter went from YAML to TOML
Simplified and Traditional Chinese live side by side (zh-CN / zh-TW)
Author data got pulled together under data/authors/
Deployment moved to GitHub Actions, with the contributor list refreshed automatically on a schedule

Note: that’s the layout from the original Jekyll → Hugo migration. After the site migrated to Hextra in 2026 it changed again: front matter is all YAML now, content is split into per-language directories (content/zh-cn/, content/zh-tw/, files all named index.md), and author credits moved into the front matter as a map (no more data/authors/).

Feedback

Telegram group: @gentoo_zh
Telegram channel: @gentoocn
File an Issue / PR: GitHub

Thanks to @biergaizi and @zhcj for founding and long maintaining the Gentoo Chinese Community, and to the developers of the Blowfish theme.

Gentoo is dropping cache mirrors for third-party repos (gentoo-zh users, update your sync source)

Tue, 07 Oct 2025 00:00:00 +0000

Per the official Gentoo news item, Gentoo has stopped offering cache mirrors for third-party repositories. Starting 2025-10-30, the mirror config for all third-party repos (gentoo-zh included) gets dropped from the official repository list.

What this means

eselect repository, layman and friends keep working as usual
Gentoo no longer mirrors third-party repos; they now sync straight from upstream (GitHub)
Official repos (::gentoo, ::guru, ::kde, ::science) are unaffected and still go through the mirrors

If you already added gentoo-zh

Just update the sync URI — remove it and re-enable it, and the correct upstream source gets picked up automatically:

# List the installed repositories
eselect repository list -i

# Remove the old config
eselect repository remove gentoo-zh

# Re-enable it (automatically uses the correct upstream source)
eselect repository enable gentoo-zh

Then emerge --sync gentoo-zh as usual.

Adding gentoo-zh for the first time? You’re not affected — just enable it normally from the Overlay page. If connecting straight to GitHub from mainland China is slow for you, use the mainland China git mirror.

Installing Gentoo Linux on Apple Silicon Macs (M1/M2 MacBook Install Guide)

Thu, 02 Oct 2025 00:00:00 +0000

This article documents the complete process of installing native ARM64 Gentoo Linux on an Apple Silicon Mac (the M1/M2 series).

Thanks to the Asahi Linux team (especially chadmed), Gentoo now has an official Asahi installation guide. This article builds on that guide and fills in details from actually doing it.

Hardware support (per the current Asahi Feature Support status):

M1, M2 (whole lineup): good enough for daily desktop use
M3: GPU is a work in progress; Wi-Fi / audio and the rest are still TBA, not a good desktop yet
M4: most of the core drivers are TBA, not usable for now
M5: not on the official support table yet

This guide is for M1/M2. Last checked: May 29, 2026.

Process Overview

Required steps:

Download the official Gentoo Asahi live USB image
Set up U-Boot via the Asahi installer
Boot from the live USB
Partition and mount the filesystem
Extract the Stage3 and chroot
Install the Asahi support package set
Reboot to finish the install

Optional steps: LUKS encryption, a custom kernel, PipeWire audio, a desktop environment.

When you’re done you’ll have a macOS + Gentoo Linux ARM64 dual-boot setup on the Mac.

Prerequisites

Hardware Requirements

An Apple Silicon Mac (only M1/M2 work as a desktop; M3/M4 drivers are incomplete, and M5 isn’t on the official support table yet)
At least 80 GB of free disk space, 120 GB or more is better
Stable Wi-Fi or Ethernet
Back up anything you care about

Known Working Status

Working: CPU, RAM, storage, Wi-Fi, keyboard, trackpad, power management, built-in and external displays, USB-C / Thunderbolt.

Partial support: GPU acceleration (OpenGL is partially supported).

Not working: Touch ID, macOS virtualization.

1. Prepare the Gentoo Asahi Live USB

1.1 Download the Image

Use Gentoo’s own ARM64 live USB directly, no Fedora middleman needed:

https://chadmed.au/pub/gentoo/

Go with install-arm64-asahi-latest.iso (a stable symlink chadmed maintains), or pick a dated build so you can reproduce things later. If you hit boot problems, try the previous stable dated build.

1.2 Create the Bootable USB

On macOS:

diskutil list
diskutil unmountDisk /dev/disk4
sudo dd if=install-arm64-asahi-*.iso of=/dev/rdisk4 bs=4m status=progress
diskutil eject /dev/disk4

2. Set Up the Asahi U-Boot Environment

2.1 Run the Asahi Installer

In macOS Terminal:

curl https://alx.sh | sh

It’s a good idea to open https://alx.sh and read the script before you pipe it into a shell.

2.2 Follow the Installer

Choose r (Resize an existing partition to make space for a new OS)
Allocate space for Linux (at least 80 GB recommended; you can enter a percentage or an absolute size)
Choose UEFI environment only (m1n1 + U-Boot + ESP)
Enter Gentoo as the OS name
Shut down as instructed

2.3 Complete the Recovery Setup

Wait 25 seconds to ensure a full shutdown
Hold the power button until “Loading startup options…” appears
Release the power button
Select Gentoo from the list of volumes
Enter macOS Recovery and enter your user password (FileVault)
Follow the prompts to finish setup

If you end up in a boot loop or get asked to reinstall macOS, hold the power button to shut down and start over; or boot into macOS, rerun curl https://alx.sh | sh, and choose p to retry.

3. Boot from the Live USB

Plug in the USB and power on; U-Boot boots GRUB from the USB on its own. If you need to point it there manually:

setenv boot_targets "usb"
setenv bootmeths "efi"
boot

Set up networking (the Gentoo live USB now uses NetworkManager, and nmtui is the quickest way):

nmtui # Select a Wi-Fi network or edit a wired connection
ping -c 3 1.1.1.1 # Verify connectivity by IP first (sidesteps DNS issues)
ping -c 3 www.gentoo.org # Then test DNS

The Apple Silicon Wi-Fi driver is already in the kernel. If it’s flaky, try a 2.4 GHz network.

Optionally enable SSH for remote operation (the live USB uses OpenRC):

passwd # Set the root password
rc-service sshd start # Start SSH (OpenRC command)
ip a | grep inet # Show the IP address

4. Partitioning and Filesystem

Leave the existing APFS container, EFI partition, and Recovery partition alone. Only work inside the space the Asahi installer set aside.

Inspect the partitions:

lsblk
blkid --label "EFI - GENTO"

A typical layout:

nvme0n1p1 500M Apple Silicon boot
nvme0n1p2 307.3G Apple APFS (macOS)
nvme0n1p3 2.3G Apple APFS
nvme0n1p4 477M EFI System (do not touch)
(free) ~150G free space for Linux
nvme0n1p5 5G Apple Silicon recovery

4.1 Create the Root Partition

Use cfdisk /dev/nvme0n1 to create a Linux filesystem-type partition in the free space.

Without encryption:

mkfs.btrfs /dev/nvme0n1p6 # or mkfs.ext4
mount /dev/nvme0n1p6 /mnt/gentoo

With encryption (recommended):

cryptsetup luksFormat --type luks2 --pbkdf argon2id --hash sha512 --key-size 512 /dev/nvme0n1p6
cryptsetup luksOpen /dev/nvme0n1p6 gentoo-root
mkfs.btrfs --label root /dev/mapper/gentoo-root
mount /dev/mapper/gentoo-root /mnt/gentoo

What the parameters do: argon2id resists ASIC/GPU brute-forcing; luks2 works with better security tooling; the M1 has the AES instruction set, so it can hardware-accelerate aes-xts.

4.2 Mount the EFI Partition

mkdir -p /mnt/gentoo/boot
mount /dev/nvme0n1p4 /mnt/gentoo/boot

5. Stage3 and chroot

From here you can follow the AMD64 Handbook up to the kernel installation chapter.

5.1 Download and Extract the Stage3

wget doesn’t do wildcards over HTTPS, so first grab the current Stage3 filename from the latest-stage3-*.txt index file, then download it and verify it with the Gentoo Release Engineering GPG public key:

cd /mnt/gentoo
BASE=https://distfiles.gentoo.org/releases/arm64/autobuilds

# 1. Get the latest Stage3 path from the official index
STAGE3=$(wget -qO- ${BASE}/latest-stage3-arm64-desktop-systemd.txt | grep -v '^#' | cut -d' ' -f1)

# 2. Download the tarball + signature
wget "${BASE}/${STAGE3}"
wget "${BASE}/${STAGE3}.asc"

# 3. Get the Gentoo Release Engineering signing public keys (needed the first time)
gpg --keyserver hkps://keys.gentoo.org --recv-keys 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910 D99EAC7379A850BCE47DA5F29E6438C817072058

# 4. Verify the signature (you must see "Good signature from ...")
gpg --verify "$(basename ${STAGE3}).asc" "$(basename ${STAGE3})"

# 5. Extract (preserve attributes)
tar xpvf "$(basename ${STAGE3})" --xattrs-include='*.*' --numeric-owner

Or pick one by hand with the links text browser:

links https://distfiles.gentoo.org/releases/arm64/autobuilds/current-stage3-arm64-desktop-systemd/

5.2 Configure the Portage Repository

mkdir --parents /mnt/gentoo/etc/portage/repos.conf
cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

5.3 Sync the System Clock

chronyd -q
date

A wrong clock makes SSL certificate verification fail and emerge throw errors.

5.4 Mount and Enter the chroot

cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
mount --types proc /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys
mount --rbind /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount --bind /run /mnt/gentoo/run
mount --make-slave /mnt/gentoo/run

chroot /mnt/gentoo /bin/bash
source /etc/profile
export PS1="(chroot) ${PS1}"

5.5 Edit make.conf

nano -w /etc/portage/make.conf

CHOST="aarch64-unknown-linux-gnu"
COMMON_FLAGS="-march=armv8.5-a+fp16+simd+crypto+i8mm -mtune=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"
RUSTFLAGS="-C target-cpu=native"
LC_MESSAGES=C
MAKEOPTS="-j4"
# The R2 mirror the Asahi community recommends; in mainland China switch to BFSU / USTC / Tsinghua, see /mirrorlist/
GENTOO_MIRRORS="https://gentoo.rgst.io/gentoo"
EMERGE_DEFAULT_OPTS="--jobs 3"
VIDEO_CARDS="asahi"
L10N="zh-CN zh-TW zh en"

Set MAKEOPTS to your core count. Keep a trailing newline at the end of the file.

emerge-webrsync
# Choose the time zone for your location: mainland China Asia/Shanghai, Taiwan Asia/Taipei, Hong Kong Asia/Hong_Kong
ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

Edit /etc/locale.gen to uncomment the locales you need, then:

locale-gen
eselect locale set en_US.utf8
env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

Create a user:

useradd -m -G wheel,audio,video,usb,input <username>
passwd <username>
passwd root

6. Install the Asahi Support Package Set

This section stands in for the “Installing the kernel” chapter of the official Handbook.

6.1 Method A: Automated Script (Recommended)

emerge --sync
emerge --ask dev-vcs/git

cd /tmp
git clone https://github.com/chadmed/asahi-gentoosupport
cd asahi-gentoosupport
./install.sh

The script turns on the Asahi overlay, installs GRUB, sets VIDEO_CARDS="asahi", installs asahi-meta (kernel, firmware, m1n1, and U-Boot), runs asahi-fwupdate and update-m1n1, then updates the system.

If you hit a USE flag conflict:

# Ctrl+C to interrupt the script
emerge --autounmask-write <conflicting-package>
etc-update # Usually choose -3 to auto-merge
cd /tmp/asahi-gentoosupport && ./install.sh

Once the script finishes, skip to 6.3 to set up fstab.

6.2 Method B: Manual Install

Set up Portage and the Asahi overlay (synced via git):

emerge --sync
emerge --ask dev-vcs/git
rm -rf /var/db/repos/gentoo

sudo tee /etc/portage/repos.conf/gentoo.conf << 'EOF'
[DEFAULT]
main-repo = gentoo
[gentoo]
location = /var/db/repos/gentoo
sync-type = git
sync-uri = https://mirrors.bfsu.edu.cn/git/gentoo-portage.git
auto-sync = yes
sync-depth = 1
EOF

sudo tee /etc/portage/repos.conf/asahi.conf << 'EOF'
[asahi]
location = /var/db/repos/asahi
sync-type = git
sync-uri = https://github.com/chadmed/asahi-overlay.git
auto-sync = yes
EOF

emerge --sync

Simplified Chinese users can use the BFSU mirror https://mirrors.bfsu.edu.cn/git/gentoo-portage.git. For other mirrors, see the mirror list.

Keep the official dist-kernel from overriding the Asahi version:

mkdir -p /etc/portage/package.mask
cat > /etc/portage/package.mask/asahi << 'EOF'
virtual/dist-kernel::gentoo
EOF

Set up USE flags and VIDEO_CARDS:

mkdir -p /etc/portage/package.use
cat > /etc/portage/package.use/asahi << 'EOF'
dev-lang/rust-bin rustfmt rust-src
dev-lang/rust rustfmt rust-src
EOF
echo 'VIDEO_CARDS="asahi"' >> /etc/portage/make.conf
echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf

Firmware license:

mkdir -p /etc/portage/package.license
echo 'sys-kernel/linux-firmware linux-fw-redistributable no-source-code' \
 > /etc/portage/package.license/firmware

Install:

emerge -q1 dev-lang/rust-bin
emerge -q sys-apps/asahi-meta virtual/dist-kernel:asahi sys-kernel/linux-firmware

Update the firmware and bootloader:

asahi-fwupdate
update-m1n1

You have to run update-m1n1 after every kernel, U-Boot, or m1n1 update.

Install GRUB:

emerge -q grub:2
grub-install --boot-directory=/boot/ --efi-directory=/boot/ --removable
grub-mkconfig -o /boot/grub/grub.cfg

--removable is required so the system can boot from the ESP; --boot-directory and --efi-directory both point at /boot/; and make.conf must have GRUB_PLATFORMS="efi-64".

Optionally, run emerge --ask --update --deep --changed-use @world to update the system.

6.3 Configure fstab

Get the partition UUIDs (adjust to your actual device paths):

# Root partition (unencrypted: use the device directly; encrypted: use the decrypted mapper device)
blkid /dev/nvme0n1p6 # unencrypted
blkid /dev/mapper/gentoo-root # encrypted

# EFI partition (the "EFI - GENTO" label set by the Asahi installer)
blkid --label "EFI - GENTO"

nano -w /etc/fstab

UUID=<root-uuid> / btrfs defaults 0 1
# If using ext4, change the third column to ext4
UUID=<boot-uuid> /boot vfat defaults 0 2

6.4 Configure LUKS (Encrypted Users Only)

Enable systemd’s cryptsetup support:

mkdir -p /etc/portage/package.use
echo "sys-apps/systemd cryptsetup" >> /etc/portage/package.use/fde
emerge --ask --oneshot sys-apps/systemd

Get the LUKS UUID (note this is the UUID of the encrypted container, not of the filesystem inside it):

blkid /dev/nvme0n1p6

Edit /etc/default/grub:

GRUB_CMDLINE_LINUX="rd.luks.name=<LUKS-UUID>=gentoo-root root=/dev/mapper/gentoo-root rootfstype=btrfs rd.luks.allow-discards"

rd.luks.name=<LUKS-UUID>=gentoo-root: unlock using the LUKS container UUID (blkid /dev/nvme0n1p6) and name the mapper gentoo-root, to match crypttab / luksClose
root=/dev/mapper/gentoo-root: the decrypted btrfs root (so you don’t have to look up the filesystem UUID again)
rd.luks.allow-discards: lets SSD TRIM pass through the encryption layer (a security trade-off)

dracut configuration:

emerge --ask sys-kernel/dracut

# Have dist-kernel updates automatically call dracut to rebuild the initramfs (recommended)
echo 'sys-kernel/installkernel dracut' > /etc/portage/package.use/installkernel
emerge --ask --oneshot sys-kernel/installkernel

nano -w /etc/dracut.conf.d/luks.conf

# Leave kernel_cmdline empty; GRUB's GRUB_CMDLINE_LINUX will override it
kernel_cmdline=""
# The crypt module pulls in cryptsetup automatically, no manual install_items needed
add_dracutmodules+=" btrfs systemd crypt dm "
filesystems+=" btrfs "

You can optionally write to /etc/crypttab so the system prompts for unlocking automatically:

gentoo-root UUID=<LUKS-UUID> none luks,discard

Generate the initramfs:

# Regenerate the initramfs for all installed kernels (recommended for dist-kernel:asahi)
dracut --force --regenerate-all

# Or target only the currently selected kernel:
# KVER=$(uname -r) # Doesn't work inside the chroot, run it on the installed system
# dracut --force --kver "${KVER}"

grub-mkconfig -o /boot/grub/grub.cfg
grep initrd /boot/grub/grub.cfg

You have to redo this step after every kernel update. Installing sys-apps/asahi-scripts gives you an installkernel hook that handles it automatically.

7. Finishing Up and Rebooting

echo "macbook" > /etc/hostname
systemctl enable NetworkManager
passwd root

Exit the chroot and reboot:

exit
umount -R /mnt/gentoo
cryptsetup luksClose gentoo-root # If using encryption
reboot

First boot order: U-Boot → GRUB (pick Gentoo) → (if encrypted) type the LUKS password → login prompt.

8. Post-Install Configuration

8.1 Networking

nmcli device wifi connect <SSID> password <password>
# Or the graphical interface
nmtui

8.2 Desktop Environment

First switch to a suitable profile (the numbers vary between systems, so go by the profile name):

eselect profile list
# Output looks something like:
# default/linux/arm64/23.0/systemd
# default/linux/arm64/23.0/desktop/gnome/systemd
# default/linux/arm64/23.0/desktop/plasma/systemd
# default/linux/arm64/23.0/desktop (generic, Xfce, etc.)

Pick the number that fits. The examples below (use the actual numbers from your own eselect profile list):

# Pick the number for the desktop/plasma/systemd line, for example:
eselect profile set default/linux/arm64/23.0/desktop/plasma/systemd
emerge -avuDN @world

KDE Plasma:

emerge --ask kde-plasma/plasma-meta kde-apps/kate kde-apps/dolphin
systemctl enable sddm

GNOME:

eselect profile set default/linux/arm64/23.0/desktop/gnome/systemd
emerge -avuDN @world
emerge --ask gnome-base/gnome gnome-extra/gnome-tweaks
systemctl enable gdm

Xfce:

eselect profile set default/linux/arm64/23.0/desktop
emerge -avuDN @world
emerge --ask xfce-base/xfce4-meta x11-misc/lightdm
systemctl enable lightdm

The first build of a desktop environment takes about 2–4 hours; stick to --jobs 3 or fewer to avoid OOM.

8.3 Fonts and Chinese Input

emerge --ask media-fonts/liberation-fonts media-fonts/noto media-fonts/noto-cjk media-fonts/dejavu
eselect fontconfig enable 10-sub-pixel-rgb.conf
eselect fontconfig enable 11-lcdfilter-default.conf

emerge --ask app-i18n/fcitx-chinese-addons

In testing, app-i18n/fcitx-rime doesn’t work right in the current version; use fcitx-chinese-addons instead.

8.4 Audio

emerge --ask media-libs/asahi-audio

# If PulseAudio is installed, stop it first to avoid conflicts
systemctl --user disable --now pulseaudio.socket pulseaudio.service 2>/dev/null

# Enable PipeWire (socket-activation; the pipewire daemon starts on demand)
systemctl --user enable --now pipewire-pulse.socket
systemctl --user enable --now wireplumber.service

9. System Maintenance

Update regularly:

emerge --sync # Includes the Asahi overlay
# Or sync only the overlay
emaint sync -r asahi
emerge --ask --update --deep --newuse @world
emerge --ask --depclean # Confirm the packages to be removed before running
dispatch-conf # Handle .__cfg config changes

Mandatory after every kernel update:

update-m1n1
grub-mkconfig -o /boot/grub/grub.cfg

m1n1 Stage 2 holds the devicetree blobs the kernel needs to detect hardware. sys-apps/asahi-scripts provides an installkernel hook that can automate this.

macOS updates ship firmware updates with them, so keep the macOS partition around to pull the latest firmware.

10. Troubleshooting

Can’t boot from USB: U-Boot’s USB driver is picky. Try a different USB drive, a USB 2.0 device, or go through a USB hub.

Boot hangs or black screen: m1n1 / U-Boot / kernel versions don’t match. Rerun curl https://alx.sh | sh from macOS and choose p, and make sure you ran update-m1n1 inside the chroot.

Encrypted partition won’t unlock: check GRUB_CMDLINE_LINUX in /etc/default/grub, double-check the LUKS UUID (blkid /dev/nvme0n1p6), and rerun grub-mkconfig -o /boot/grub/grub.cfg.

Wi-Fi is unstable: usually a WPA3 or 6 GHz band issue. Switch to WPA2, 2.4 GHz, or 5 GHz.

Trackpad dead:

dmesg | grep -i firmware
emerge --ask sys-apps/asahi-meta

11. Advanced Options

The notch: add this to the GRUB kernel parameters

appledrm.show_notch=1

(Before Asahi kernel 6.18 it was apple_dcp.show_notch=1; as of 6.18 the apple_dcp module got renamed to appledrm.)

In KDE Plasma you can add a full-width panel at the top and line its height up with the bottom of the notch.

Custom kernel:

emerge --ask sys-kernel/asahi-sources
cd /usr/src/linux
make menuconfig
make -j$(nproc)
make modules_install
make install
update-m1n1
grub-mkconfig -o /boot/grub/grub.cfg

Keep a working kernel around as a fallback.

Switching between kernels:

eselect kernel list
eselect kernel set <number>
update-m1n1

References

Community support:

Telegram group: @gentoo_zh
Telegram channel: @gentoocn
GitHub
Gentoo Forums
IRC #gentoo / #asahi @ Libera.Chat
Asahi Linux Discord

The Gentoo Chinese Community, Under Construction

Sun, 24 Aug 2014 00:00:00 +0000

Gentoo is a free operating system based on Linux or FreeBSD that can automatically optimize and tune itself for just about any application or need. What makes Gentoo Gentoo: you can configure it to an extreme degree, it chases performance hard, and it has a great community of users and developers.

Gentoo has had two active Chinese communities before, but both were gone by around 2010, leaving only scattered talk on the IRC channel and the mailing list. So this Gentoo Chinese project is the third attempt, you could say. The idea is to pull together the Gentoo-related resources scattered across mainland China, get Gentoo users in one place to talk shop, help newcomers with their problems, and give the experts somewhere to trade technical know-how. Down the road we want more people in mainland China running Gentoo, and through that, raise the local level of Linux know-how and give back to upstream Gentoo.

The Gentoo Chinese Community is still under construction, and the only thing this site can do right now is ~~show off~~ display text, just to prove the project exists.

Work to be done in phase one:

Jekyll template
Form a translation team
- News translation
- Documentation translation
Vector redraw of the Gentoo Chinese Community logo
Flesh out the introductory text for Gentoo and gentoo-zh

Work to be done in phase two:

A mirror of the gentoo-zh overlay
A SquashFS archive of the Portage tree

The Gentoo Chinese Community Is Founded

Tue, 05 Feb 2013 00:00:00 +0000

Where the Gentoo Chinese Community Came From

The Gentoo Chinese project is a technical community where enthusiasts in mainland China get together to talk about Gentoo Linux. This time around is the third try at building one.

The first try, around 2004, was started and run by Gentoo fans over at LinuxSir. It did a lot to spread Gentoo in mainland China, but the project eventually shut down for one reason or another (see [1]).

The second one started in 2007: a Gentoo Chinese docs translation project kicked off by Zhang Le. Its biggest win was translating the whole Gentoo Handbook into Chinese and getting it submitted upstream, which is the official Gentoo Handbook in Chinese you see today. That translation project is still running (see [2]).

This new Gentoo Chinese project makes three. 清风 handled most of the setup work, and we landed on “Gentoo Chinese Community” for the name. Plenty of Gentooers pitched in along the way.

What the Gentoo Chinese Community Aims For

Pull together the scattered Gentoo resources around mainland China, get Gentoo users into one place to talk shop, help newcomers fix their problems, and give the veterans somewhere to trade tricks. Push up Gentoo’s adoption in mainland China, and over the longer haul, raise the level of Linux skill in the region and give back to upstream Gentoo.

How the Gentoo Chinese Community Is Run

Main server setup and admin: 清风, 比尔盖子
Docs translation: we’re sticking with Zhang Le’s translation platform, and a big thanks to him for all he’s done for Gentoo in Chinese!
Forum admin: 清风 (for now), now hiring…

Gentoo China (Mirror) Site Goes Live

Sun, 03 Feb 2013 00:00:00 +0000

Right now this Gentoo site is just a mirror of the official one, but we’re confident it’ll become the main site for the Gentoo Chinese Community down the road!