diff --git a/Docs/Building-BE.md b/Docs/Building-BE.md new file mode 100644 index 00000000..99d52653 --- /dev/null +++ b/Docs/Building-BE.md @@ -0,0 +1,84 @@ +# Building Big Endian ASTC Encoder + +**NOTE:** The current code is _NOT_ BE compatible, but we plan to fix this! + +We don't officially support a big-endian compressor build, but ensuring the +code is BE-compatible is good practice and some of the open source +distributions still support BE platforms. + +Even though Arm64 can run in a BE mode, it's now very rare in practice. It's no +longer supported out of the box in the latest Arm upstream compiler releases, +and getting hold of a sysroot is increasingly painful. To test BE builds I +therefore cross-compile Linux builds for MIPS64 and use `qemu-user` to run +them. This doesn't use a real sysroot, so everything must be compiled with +`-static` linkage. + +## Host software + +Install the following host software: + +```bash +# Compiler +sudo apt-get install g++-mips64-linux-gnuabi64 + +# Multi-arch libraries +sudo apt-get install g++-multilib-mips64-linux-gnuabi64 + +# QEMU +sudo apt-get install qemu-user-static +sudo mkdir /etc/qemu-binfmt +sudo ln -s /usr/mips64-linux-gnuabi64 /etc/qemu-binfmt/mips64 +``` + +## CMake toolchain file + +Cross-compiling needs an correctly configured CMake, and the easiest way to +do this consistently is to use a toolchain file. Create a `CMake-BE.toolchain` +file with the following content in the root of the project: + +``` +# Operating system +set(CMAKE_SYSTEM_NAME Linux) + +# Cross-compilers for C and C++ +set(CMAKE_C_COMPILER mips64-linux-gnuabi64-gcc) +set(CMAKE_CXX_COMPILER mips64-linux-gnuabi64-g++) + +# Compiler environment +set(CMAKE_FIND_ROOT_PATH /usr/mips64-linux-gnuabi64) + +# Default compiler and linker flags to use +set(CMAKE_C_FLAGS_INIT -static) +set(CMAKE_CXX_FLAGS_INIT -static) +set(CMAKE_EXE_LINKER_FLAGS_INIT -static) +set(CMAKE_SHARED_LINKER_FLAGS_INIT -static) +set(CMAKE_MODULE_LINKER_FLAGS_INIT -static) + +# Never match host tools +set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) + +# Only match headers and libraries in the compiler environment +set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) +set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) +``` + +## Build astcenc + +Building uses CMake as normal, with the additional specification of the +toolchain file to configure the build for cross-compilation. + +``` +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../ -DASTCENC_ISA_NONE=ON -DCMAKE_TOOLCHAIN_FILE=../CMake-BE.toolchain .. +``` + +## Run astcenc + +The cross-compiled `astcenc` binary runs as normal, and can access host files, but must run through QEMU to do the instruction-set translation. + +``` +qemu-mips64 ./bin/astcenc-none ... +``` + +- - - + +_Copyright © 2025, Arm Limited and contributors._