This project aims to create custom CRUX-ARM releases for specific ARM architectures. The release creation process is automated using a Makefile to build the necessary packages and generate a root filesystem for ARM-based devices.
*** WORK IN PROGRESS ***
We are currently developing version 3.8 so this document may be temporarily out of date.
- Overview
- Supported Architectures
- Prerequisites
- Getting Started
- Customizing the Build
- Directory Structure
- Root Filesystem Stages:
rootfs-stage0
vs.rootfs-stage1
- Contributing
- License
- Acknowledgements
The release process is split into several stages:
-
Stage 0:
- The required packages (from upstream CRUX core and CRUX ARM overlay variants) are compiled.
- These packages are installed in the
rootfs-stage0
directory.
-
Stage 1:
- Using the packages from Stage 0, the system is chrooted into a fresh environment to build additional packages.
- These packages are installed in the
rootfs-stage1
directory.
-
Release Creation:
- The contents of
rootfs-stage1
are packaged into a compressed archive (crux-arm-VERSION.rootfs.tar.xz
) to create the final CRUX-ARM release.
- The contents of
The goal is to streamline the process of building a minimal, stable CRUX system tailored for ARM-based architectures.
arm64
(aarch64 - 64-bit ARM architecture)arm
(armhf - 32-bit ARM architecture with hard-float support)
To build the CRUX-ARM release, there are two approaches: Native and Dockerized.
- Preferably requires a CRUX-ARM Linux system for the variant of the release you want to build (
arm64
orarm
). - Alternatively, you can use Arch or Debian for ARM (or similar distributions). In this case, ensure that the basic tools
make
,gcc
,git
,xz
, and necessary development headers and libraries are installed.
- You can build the CRUX-ARM release on CRUX Linux for
x86_64
or even on other Linux distributions or macOS capable of running multi-arch Docker containers. - The
tools/dockerize.sh
script will handle the process inside a Docker container, abstracting the need for a native ARM environment. For example, to run the bootstrap it would be something like:tools/dockerize.sh bootstrap
- Note that to run an
arm64
orarmhf
container from a different architecture host (e.g.x86_64
), you must enable multi-architecture support using QEMU. Ensure that Docker is installed, then run:This command registers QEMU to handle non-native architectures. After that, you can run andocker run --rm --privileged multiarch/qemu-user-static --reset -p yes
arm64
orarmhf
container like this to verify that everything is working fine:# on arm64 this will output: aarch64 docker run --rm --platform linux/arm64 -t sepen/crux:arm64 bash -c "uname -m" # on armhf this will output: armv7 or variants (e.g. armv7l) docker run --rm --platform linux/arm/v7 -t sepen/crux:armhf bash -c "uname -m"
WARNING: Launching containers on macOS may have issues when compiling ports on mounted host volumes. This is because the filesystem used by macOS by default is not case-sensitive. For more information, read the comments inside the tools/dockerize.sh file.
For both approaches, ensure your system has internet access to the upstream CRUX repositories for both core and ARM-specific ports.
To begin the process of building the CRUX-ARM release, follow these steps:
First, clone this repository to your local machine:
git clone https://github.com/crux-arm/crux-arm-release.git
cd crux-arm-release
git checkout <branch> # e.g. 3.8
Depending on your target architecture, you can specify the device optimization during the build by setting the OPTIMIZED_DEVICE variable. By default, this is set to arm64.
Run the Makefile to start the bootstrap process:
make bootstrap
This will trigger the following Makefile targets:
stage0
: It will build the necessary base packages from upstream CRUX and ARM repositories for the selected architecture.stage1
: After Stage 0 completes, the system will automatically enter a chroot environment where additional packages will be compiled.release
: The final root filesystem will be packaged ascrux-arm-VERSION.rootfs.tar.xz
, where VERSION will be replaced by the version of the release and the device optimization (e.g. 3.7-arm64).
You can run make bootstrap
to trigger the entire process or alternatively you can run individual stages by using:
make stage0
make stage1
make release
Run make help
to see all available Makefile options and commands.
You can customize the build by specifying a different optimized device. The default value for OPTIMIZED_DEVICE is arm64
.
To see the list of other supported optimizations, browse the devices folder in this repository. Each *.mk
file corresponds to a specific ARM device optimization, and you can select the one that matches your target hardware (or contribute a new one).
Example Build for another device optimization (e.g., raspberrypi4)
make bootstrap OPTIMIZED_DEVICE=raspberrypi4
This will build the release with the optimizations specified for the chosen device.
The following directories are involved in the build process:
devices
: Contains configuration and optimization files for various supported ARM devices.ports
: Stores a clone of the upstream CRUX core ports and additional overlays for specific ARM architectures (e.g., core-arm64, core-armhf) and device-specific optimizations (e.g., raspberrypi4-arm64).packages
: Directory where the different built packages will be stored.sources
:: Contains sources used in ports to build packages.work
: Contains temporary files and pkgmk's work directory.rootfs-stage0
: Contains the initial bootstrap environment and packages from Stage 0.rootfs-stage1
: Contains the packages and configurations created during Stage 1.tools
: Directory with some useful scripts.
Both rootfs-stage0
and rootfs-stage1
are created during the build process (usually executed via make). These stages are progressively populated with files and utilities to prepare the root filesystem.
This is the first stage of creating a root filesystem. It contains a generic, unoptimized set of packages that are suitable for arm64
or armhf
architecture and do not include device-specific optimizations.
This stage contains a generic and unoptimized root filesystem. The goal is to set up a working environment with minimal setup, where packages are compiled or installed without any optimizations for the target device.
- Packages are installed without architecture or device-specific optimizations.
- Generic compiler flags are used to ensure portability across different variants for the same architecture.
- Contains the minimum set of packages like
gcc
,glibc
,binutils
, etc. and basic libraries. - The focus is on getting a basic root filesystem up and running, not on optimizing for performance or power efficiency.
- Basic tools and libraries are installed without performance optimizations.
- This stage is typically faster to build but results in a system that might not be efficient for your target hardware.
This stage applies device-specific optimizations to the root filesystem. It is typically built on the target device (or in a similar cross-compilation environment) to ensure that the system is tailored for the architecture and hardware features of the device.
- Packages are recompiled or reconfigured with device-specific optimizations (e.g., CPU architecture flags, hardware-specific libraries).
- The system is compiled using architecture-specific flags (e.g.,
-march=armv8-a+crc+simd -mtune=cortex-a72
for tuning binaries for the device’s CPU). - Optimizations include considerations for performance, power consumption, and memory usage.
- System libraries and applications are built to be as efficient as possible for the target device’s hardware.
- Device-specific flags are used, such as
-march=armv7-a
for armhf or-mfpu=neon-vfpv4
for optimization. - Additional device-specific drivers and libraries may be included.
- The root filesystem is optimized for performance, making it smaller, faster, and more power-efficient.
-
Built rootfs-stage0 on a development machine (or a neutral environment).
make stage0
At this point, the build contains generic packages with no optimizations for the target hardware.
-
Transfer to Target Device: (Optional if built on host)
If building on a host machine, the root filesystem is copied to the target device.
-
Built rootfs-stage1 on the target device, ensuring the system is optimized for the device's hardware.
make stage1
This stage compiles the packages with architecture-specific flags and optimizations, making the system more efficient for the target device.
-
Finalize the Build (Optional further stages):
You may proceed with additional stages (like
release
) to complete the root filesystem.make release
Contributions to the project are welcome. If you find bugs, or have suggestions for improvements, please open an issue or submit a pull request.
- Fork the repository.
- Create a feature branch.
- Commit your changes.
- Push your branch to your forked repository.
- Open a pull request to the main repository.
Please ensure that all changes maintain the project's standards and include necessary tests or documentation.
This project is licensed under the GPLv3 License - see the LICENSE file for details.
Thanks to the CRUX community and the CRUX-ARM community for their continued contributions and support.