Build and Run

Build, install, and run

Return to the repository README. The README is the single maintained location for build dependencies and version requirements. This page covers the path from source package to first run, guest runtime, and Wine.

Before you begin

• Build and run LATX on LoongArch Linux.
• LATX requires the host CPU and kernel to expose LSX and LBT_X86. Ordinary SIMD translations use LASX when the host supports it. If LASX is not detected at startup, LATX disables its LASX paths and uses 128-bit LSX instruction translations instead.
• Configuration detects LoongArch ABI 1.0 or ABI 2.0 automatically. Build in an environment matching the ABI of the installation target.
• LATX runs x86 Linux programs directly. x86 Windows programs also need x86 Wine and a guest runtime matching that Wine build.

For distribution-specific dependency commands and Meson and Python version requirements, see Build dependencies in the README.

Build

git clone --depth=1 --recursive https://github.com/lat-opensource/lat
cd lat
./latxbuild/build-release.sh

On success, the repository root contains lat-<version>-<date>.tar.xz. The package includes i386 and x86_64 translators, the installation status tool, binfmt configuration, and sysctl configuration.

If the target program needs AVX, reconfigure and build the translator required:

./latxbuild/build32.sh -c -a
./latxbuild/build64.sh -c -a

-a passes --enable-latx-avx-opt during configuration, enabling x86 AVX instruction translation for the selected build target. The outputs are build32/latx-i386 and build64/latx-x86_64; these commands do not create or update the release tar package. Include -c whenever changing AVX support so that the build configuration is regenerated. The default release package does not enable AVX.

Install

Install the newest release package produced in the repository root:

package=$(ls -1t lat-*.tar.xz | head -n 1)
sudo tar -Jxf "$package" -C / --strip-components=1

It installs:

/usr/bin/latx-i386
/usr/bin/latx-x86_64
/usr/bin/latu-runtime-manager
/usr/lib/binfmt.d/latx-i386.conf
/usr/lib/binfmt.d/latx-x86_64.conf
/usr/lib/sysctl.d/mmap_min_addr.conf

Rebooting loads the binfmt and sysctl configuration. On a systemd system, load them immediately with:

sudo systemctl restart systemd-binfmt.service
sudo systemctl restart systemd-sysctl.service

Confirm that both translators are installed:

latu-runtime-manager status

Expected output includes:

translator_x86_64=present
translator_i386=present

First run: static program

A statically linked program does not need an additional x86 guest runtime, so it distinguishes an installation issue from missing runtime libraries. The following example uses the static Arch Linux BusyBox:

wget -O busybox.pkg.tar.zst \
    https://archlinux.org/packages/extra/x86_64/busybox/download/
tar xf busybox.pkg.tar.zst
file ./usr/bin/busybox
latx-x86_64 ./usr/bin/busybox uname -m

After binfmt is active, direct execution also works:

./usr/bin/busybox uname -m

If explicit latx-x86_64 execution works but direct execution fails, reload binfmt and see the FAQ.

Run dynamically linked programs

A dynamically linked program needs at least an x86 dynamic linker and glibc. First inspect its architecture and linking mode:

file /path/to/program
readelf -l /path/to/program | grep interpreter

Then inspect the guest runtime currently selected by LATX:

latx-x86_64 -runtime-info
latx-i386 -runtime-info

The default directories are:

Host ABI	i386	x86_64
ABI 1.0	/usr/gnemul/latx-i386	/usr/gnemul/latx-x86_64
ABI 2.0	/usr/gnemul/lat-i386	/usr/gnemul/lat-x86_64

The guest program, dynamic linker, and shared libraries must come from compatible x86 distribution environments. Do not copy only the .so named by an error; install or build a complete runtime instead.

Prepare a guest runtime

Recommended: Loongnix runtime packages

The Loongnix repository provides i386-runtime-base and i386-runtime-extra. Install both packages for the same ABI and choose their current versions from the same repository:

• ABI 1.0 (Loongnix 20): runtime-base, runtime-extra
• ABI 2.0 (Loongnix 25): runtime-base, runtime-extra

Download the two .deb packages matching the host ABI and install them:

sudo dpkg -i i386-runtime-base_*.deb i386-runtime-extra_*.deb

Run latx-x86_64 -runtime-info and latx-i386 -runtime-info again and confirm that the directories exist and contain the corresponding dynamic linker.

Build a runtime yourself

Create a custom runtime only when the official packages do not satisfy the guest distribution or Wine version requirement. This example creates basic root filesystems on an x86 Debian 12 host:

sudo debootstrap --no-check-gpg --arch=i386 bookworm i386-root \
    https://deb.debian.org/debian
sudo debootstrap --no-check-gpg --arch=amd64 bookworm x86_64-root \
    https://deb.debian.org/debian
sudo chroot i386-root apt-get update
sudo chroot x86_64-root apt-get update

Install the guest program and required libraries in each root filesystem, then copy the complete tree to the target LoongArch system's ABI-specific directory. Keep etc/, usr/, the dynamic linker, and the original root filesystem's library-directory symbolic links.

# ABI 1.0                         # ABI 2.0
/usr/gnemul/latx-i386/            /usr/gnemul/lat-i386/
/usr/gnemul/latx-x86_64/          /usr/gnemul/lat-x86_64/

Before running Wine, verify that a simple dynamically linked x86 Linux program can load its dynamic linker and shared libraries.

Run Wine

To run x86 Wine with LATX, you also need:

1. latx-i386 and/or latx-x86_64;
2. x86 Linux Wine;
3. i386 and x86_64 guest runtimes matching the Wine build environment.

Wine source and build documentation:

• Wine source
• Building Wine

Wine and its runtime using different distributions or versions of glibc or graphics libraries can easily look like a LATX compatibility problem. Verify the Wine/runtime combination on native x86 first, then move it to LoongArch.

Configuration

Runtime options, configuration files, environment-variable precedence, and common settings are maintained in Configuration and environment variables. This page intentionally does not repeat the option list.

Upgrade

To upgrade from a new release tar package, repeat the installation command and reload binfmt. Release packages do not include /etc/latx-*.conf, so they do not overwrite manually maintained system configuration. After upgrading, run:

latu-runtime-manager status
latx-x86_64 -version
latx-i386 -version

The guest runtime is managed by separate packages or directories and is not upgraded by the LATX tar package.

Uninstall

These steps apply only to installations made by extracting the tar package as described here. If LATX was installed by a distribution package manager, use the package manager instead of deleting files manually.

sudo rm -f \
    /usr/bin/latx-i386 \
    /usr/bin/latx-x86_64 \
    /usr/bin/latu-runtime-manager \
    /usr/lib/binfmt.d/latx-i386.conf \
    /usr/lib/binfmt.d/latx-x86_64.conf \
    /usr/lib/sysctl.d/mmap_min_addr.conf
sudo systemctl restart systemd-binfmt.service

Removing the sysctl file does not restore the previous vm.mmap_min_addr value automatically. Restore that value or reboot. The guest runtime does not belong to the release tar package; remove it through its original package manager and do not delete /usr/gnemul together with LATX files.