README.md (6925B)
1 musllvm 2 ======== 3 4 A simple make build system for a musl Clang/LLVM cross toolchain. 5 Targets x86_64 and aarch64 Linux. 6 7 The toolchain includes musl, compiler-rt, libc++, libc++abi, 8 LLVM libunwind and libatomic. Compiler tools run on the build host. 9 10 11 downloads 12 ========= 13 14 [Releases](https://github.com/cowmonk/musllvm/releases) provide archives 15 for x86_64-linux-musl and aarch64-linux-musl. Both run on x86_64 Linux 16 hosts with glibc 2.39 or newer. The compiler tools are included. 17 Target programs use musl. 18 19 Download an archive and SHA256SUMS from the same release, then check 20 the archive you downloaded: 21 22 sha256sum --ignore-missing -c SHA256SUMS 23 tar -xJf musllvm-x86_64-linux-musl-host-x86_64-linux.tar.xz 24 eval "$(musllvm-x86_64-linux-musl/bin/x86_64-linux-musl-env)" 25 26 Each archive includes its source pins, licenses and build information under 27 share/musllvm/. pkg-config is optional and uses the host installation. 28 29 30 dependencies 31 ============ 32 33 Build on a Linux host with: 34 35 clang/llvm Clang 19 or newer, clang++, LLD, LLVM utilities and 36 matching llvm-config and LLVM CMake metadata (system mode) 37 make GNU make 38 cmake 3.20 or newer 39 ninja 40 python3 41 perl 42 curl 43 tar gzip and xz support 44 sha256sum 45 rsync 46 47 pkg-config is needed for the target pkg-config wrapper. qemu-aarch64 is 48 optional for running aarch64 checks on an x86_64 host. 49 50 51 building 52 ======== 53 54 make doctor 55 make 56 57 Defaults to x86_64 with two build jobs. For aarch64: 58 59 make ARCH=aarch64 60 61 LLVM_MODE=system uses the installed host tools and builds the target 62 libraries from pinned sources. Keep the host LLVM installation available. 63 64 To also build Clang, LLD and the LLVM utilities from source: 65 66 make LLVM_MODE=source ARCH=x86_64 JOBS=2 LINK_JOBS=1 \ 67 PREFIX="$PWD/build/x86_64-source" BUILD_DIR="$PWD/build/work/x86_64-source" 68 69 Source mode installs host tools under PREFIX/host. These tools use the 70 host libc. Both modes produce a cross toolchain. 71 72 73 configuration 74 ============= 75 76 Edit [config.mk](config.mk) or override settings through make. 77 78 ARCH x86_64 x86_64 or aarch64 79 TARGET $(ARCH)-linux-musl target triple 80 PREFIX build/$(TARGET) toolchain installation 81 BUILD_DIR build/work/$(TARGET) build files and completed stages 82 LLVM_MODE system system or source 83 JOBS 2 compilation jobs 84 LINK_JOBS 1 parallel links when building LLVM 85 TARGET_CFLAGS -O2 target library flags 86 RUNNER emulator executable (optional) 87 88 Each target has its own prefix and work directory. Downloaded and 89 extracted sources are shared. Build paths must have no whitespace or 90 shell metacharacters. 91 92 93 usage 94 ===== 95 96 After building, load the toolchain into your current shell: 97 98 eval "$(build/x86_64-linux-musl/bin/x86_64-linux-musl-env)" 99 "$CC" hello.c -o hello 100 "$CC" -static hello.c -o hello-static 101 "$CXX" -std=c++20 hello.cpp -o hello-cxx 102 103 The environment command sets CC, CXX, LLVM binutils, LD, PKG_CONFIG, 104 TARGET, MUSLLVM_SYSROOT and CMAKE_TOOLCHAIN_FILE. Use the environment 105 command matching your target and installation path. 106 107 The compiler wrappers select the target, sysroot, LLD and target runtimes 108 through share/musllvm/clang.cfg. They remove host header and library 109 environment paths and ignore host Clang configuration files. 110 111 The configuration also enables the Chimera Linux hardening defaults: 112 -fstack-protector-strong, -fno-semantic-interposition, --as-needed and 113 -z relro -z now. Command-line flags such as -fno-stack-protector, 114 -Wl,--no-as-needed or -Wl,-z,lazy override them. The pkg-config 115 wrapper searches the target sysroot. 116 117 For CMake: 118 119 cmake -S . -B out -G Ninja \ 120 -DCMAKE_TOOLCHAIN_FILE="$CMAKE_TOOLCHAIN_FILE" 121 cmake --build out 122 123 The sysroot is under PREFIX/sysroot, with headers in usr/include, 124 libraries in usr/lib and the musl loader in lib. Compiler-rt is in the 125 toolchain's Clang resource directory. 126 127 Set MUSLLVM_SYSROOT to use another copy of the sysroot. Set 128 MUSLLVM_PKG_CONFIG_PATH to add target pkg-config directories. 129 130 131 sources and resuming 132 ==================== 133 134 [sources.list](sources.list) pins archive names, URLs and SHA-256 digests. 135 Downloads enter the cache after checksum verification. 136 137 make pull 138 make verify-sources 139 make show-config 140 141 Run the same command after a failed build to resume completed stages. 142 Changes to the target, source pins, compiler, paths, build recipes or 143 library flags require make clean with the same ARCH, PREFIX and BUILD_DIR. 144 Cleaning removes that toolchain and its work directory, but keeps the 145 downloaded and extracted sources. Changing JOBS does not require cleaning. 146 147 A running build holds a lock in BUILD_DIR/lock. After a forced termination, 148 check that the build process has stopped before removing a leftover lock 149 with rmdir. 150 151 152 checks 153 ====== 154 155 make check 156 157 Runs shell syntax checks and driver tests with mocked tools. This does 158 no compilation or downloads. 159 160 A completed build also runs make verify. This compiles static, static-pie 161 and dynamic C and C++ programs, directly and through the CMake toolchain 162 file, and checks their ELF architecture and runtime dependencies. It also 163 compiles with -Werror. Programs run when the host architecture matches the 164 target or RUNNER names an emulator. 165 166 make verify ARCH=aarch64 RUNNER=qemu-aarch64 167 168 [CI](.github/workflows/ci.yml) runs offline tests and both target builds. 169 A manual workflow run can build both targets with LLVM from source instead. 170 171 172 publishing 173 ========== 174 175 [The release workflow](.github/workflows/release.yml) runs on pushes to 176 main that change sources.list, config.mk, Makefile, scripts/, files/ 177 or the compiler smoke tests. This covers source version updates 178 and new core components added to the build. README edits do not publish 179 a release. The workflow can also be run manually from main. 180 181 Both targets build with LLVM_MODE=source. Each archive is unpacked into 182 a new location and tested before upload. The release is published after 183 both builds pass, with SHA256SUMS and sources.list attached. 184 Tags use musllvm-YYYY-MM-DD-COMMIT, with the first 12 commit characters. 185 Rerunning a published commit keeps its release assets. 186 187 To package a completed source build yourself: 188 189 make package LLVM_MODE=source ARCH=x86_64 190 191 Archives go to build/releases/. Set DIST_DIR to change the output directory. 192 The first release still needs verification on GitHub Actions. 193 194 195 credits 196 ======== 197 198 * [Chimera Linux](https://chimera-linux.org) - libatomic and the libc++ typeinfo setting 199 * [CMLFS](https://github.com/dslm4515/CMLFS) - build script references 200 * [Mussel](https://github.com/firasuke/mussel) - musl cross compiler references 201 * [musl.cc](https://musl.cc) - cross compiler resources