LLVM-MOS: a compiler backend for the MOS 65xx series

A fork with a new backend, not a fork of the project

LLVM-MOS is a LLVM fork supporting the MOS 65xx series of microprocessors, and the project description says it plainly: it is a fork of LLVM that provides a new backend or target, and the project is based on LLVM, not a part of LLVM.

The notice spells out the legal position in more detail, which is worth reading because it is unusually careful. The llvm-mos project is not officially affiliated with or endorsed by the LLVM Foundation or LLVM project, and the use of LLVM or other related trademarks does not imply affiliation or endorsement.

That distinction is more than a formality in practice, because the repository contains a large amount of LLVM source. The top level listing is effectively the LLVM monorepo with the additions: clang/, lld/, lldb/, mlir/, polly/, openmp/, flang/, libc/, libcxx/, compiler-rt/, runtimes/, utils/ and third-party/, plus the bolt/ directory, which is the newer LLVM BOLT component, and cross-project-tests/ which is where the cross target test suites live.

So the fork is a patch set against upstream LLVM rather than a rewrite, and a contributor to LLVM-MOS is contributing to something that tracks a very large upstream tree.

The project is licensed under a custom licence GitHub cannot classify, with the file at LICENSE.TXT alongside a NOTICE file, and the last push was on 2026-10-19. The primary language recorded for the repository is LLVM, and the default branch is main.

This repository is not a toolchain

The most important sentence in the README is the one that says what this repository is not. This repository only contains the core llvm-mos utilities, and it does not form a complete toolchain. Accordingly, there are no official binary releases for this repository; it's for internal development only.

That means there is nothing to install from here and nothing to download. If you want to build programs for the hardware, the README points you at the SDK repository, llvm-mos-sdk, and its getting started page.

The distinction between the two repositories is a common arrangement in compiler work. The core repository is where the backend lives and where the changes are reviewed, and the SDK is what assembles a working toolchain and distributes it. Splitting them means a user does not need a full LLVM checkout to get a compiler, and the compiler project does not have to take on the release engineering of packaging for every platform.

The three most recent release tags are named for platforms rather than versions, llvm-mos-windows-debug, llvm-mos-linux-debug and llvm-mos-darwin-debug, all from 2024-01-30. Debug builds of the SDK for three platforms, tagged in the repository, is a reasonable shape for a project that needs to test on the systems its users have.

The homepage is llvm-mos.org, and the project is not archived, so the fork is still being developed.

Cloning, and the one Windows flag that matters

Building LLVM-MOS follows the same convention as compiling LLVM, and the README says to review the hardware and software requirements for building LLVM first, then use the formula in your build environment.

The clone is the same on Linux and MacOS:

git clone https://github.com/llvm-mos/llvm-mos.git

On Windows it needs one extra flag:

git clone --config core.autocrlf=false https://github.com/llvm-mos/llvm-mos.git

And the reason is stated: if you fail to use the --config flag as above, then verification tests will fail on Windows. That is a line ending problem, and the symptom is the test suite rather than the compiler, which is the confusing way round. A fork that carries line ending handling wrong across a test suite with thousands of text fixtures is going to fail in a way that has nothing to do with the backend.

The single flag is the whole difference between a working and a broken Windows build, and it is the kind of detail that belongs in a README and usually does not.

The MOS.cmake cache does the configuration for you

The configure step is one CMake command, and the interesting part is the -C flag:

cd llvm-mos
cmake -C clang/cmake/caches/MOS.cmake [-G <generator>] -S llvm -B build [...]

The -C option seeds the CMake cache with values from MOS.cmake, and the README says to feel free to review and adjust these values for your environment. Additional options can be added to the cmake command, which override the values provided in MOS.cmake.

So the target configuration is a checked-in cache file rather than a long command line, and the command line is for the things that vary per machine. That is a better arrangement than a list of a hundred -D flags in the documentation, because the defaults for the 6502 and related processors live in one file that a user can read before overriding anything.

The documented options are a short list. The -G option lets you choose the CMake generator, and CMake will try to detect your build tools, but it is recommended to install Ninja and pass Ninja as the parameter to the -G command. -DLLVM_ENABLE_PROJECTS takes a semicolon-separated list of the LLVM sub-projects you want to additionally build, and can include any of clang, clang-tools-extra, lldb or lld. -DCMAKE_INSTALL_PREFIX specifies the full path where the LLVM tools and libraries are installed, defaulting to /usr/local. -DCMAKE_BUILD_TYPE takes Debug, Release, RelWithDebInfo or MinSizeRel, with the default being MinSizeRel if you are using the MOS.cmake cache file. And -DLLVM_ENABLE_ASSERTIONS compiles with assertion checks enabled, defaulting to Yes for Debug builds and No for all other build types.

The MinSizeRel default is the detail that tells you the target. This is a compiler for a processor with very little memory, so the default build type is the one that produces the smallest binaries.

Building it is a long serial job unless you use a parallel generator

The build step is:

cmake --build build [-- [options]] distribution

And then the warning that matters for your afternoon. Running a serial build will be slow, and the advice is to try running a parallel build. That is done by default in Ninja, and for make you use the option -j NNN, where NNN is the number of parallel jobs, for example the number of CPUs you have.

So the generator choice from the previous section pays off here, and it is worth insisting on Ninja for exactly this reason. A serial LLVM build on a modern machine is measured in hours, and the same build with parallelism is a fraction of that.

The distribution target at the end of the command is what produces the installable artefacts, the compilers, the linker and the runtime libraries, and the build directory layout is the standard LLVM one, with the build output going to a build directory that you then point your installation prefix at.

The surrounding toolchain is standard LLVM as well, with the addition of the new backend, and the repository carries the .clang-format and .clang-tidy configuration files that the project expects contributors to use, along with a .clang-format-ignore for the parts that are not hand written, which in a fork like this is the third-party and upstream directories.

Contributing to a compiler fork has its own rules

The Help us out section is direct about what the project needs and what it does not have the bandwidth for.

We need your help, and the asks are specific: please review the issue tracker, please review the current state of the code, and jump in and help us with pull requests for bug fixes. All LLVM-MOS code should observe the LLVM coding standards, and clang-format and clang-tidy are aids to this, with the repository containing appropriate configuration files for them.

The quality bar is stated with a comparison rather than a rule. Code should be appropriately documented and well tested, and the project says it is not quite as picky as the upstream LLVM project, but that a compiler is too complex a project to thrive without a high bar for code quality.

Then the part that saves everyone time. Issue requests go through the issue tracker, and the README notes they do not have the bandwidth yet to handle why dosent my pogrem compil type requests, and that it helps to do at least some legwork to figure out what is going on first. Small reproducers are tremendously helpful, and for more finnicky issues they are essentially required.

That is not a discouragement, it is a request for a minimal test case, and for a compiler target it is the right request. The smallest reproducer for a backend bug is usually a three line C file and a target triple, and asking for that up front is the difference between a bug fixed in a week and a bug report that goes nowhere.

The documentation gets the same treatment, with the note that the current state of the documentation at llvm-mos.org can always use improvements and clarifications, and the project page for more information is llvm-mos.org.

Editorial conclusion

Adopt LLVM-MOS if you are targeting MOS 65xx hardware and want an LLVM-based toolchain rather than a hand written assembler, and you are prepared to build LLVM from source. Do not expect this repository to give you a working toolchain on its own, because the README says it only contains the core utilities and does not form a complete toolchain, with no official binary releases. Before you start, use the SDK linked from the README, and on Windows clone with core.autocrlf disabled, because the verification tests fail otherwise.

Frequently asked questions

Official sources

1. Issues
2. llvm-mos/llvm-mos on GitHub
3. README
4. Releases