Installation

Installation

Nightly builds

Every push to the root branch builds BlitzLLVM for Windows (x64), Linux (x64) and macOS (arm64) and publishes the result as the nightly release: https://github.com/Xaymar/BlitzLLVM/releases/tag/nightly

• Linux: there is no zip, because the libraries a program needs differ between systems. Install the package for your system: blitzllvm-<version>-<commit>-ubuntu24.04-x64.deb or -ubuntu26.04-x64.deb (Ubuntu: sudo apt install ./blitzllvm-*.deb; use the one for your release), blitzllvm-<version>-<commit>-fedora-x64.rpm (Fedora) or blitzllvm-<version>-<commit>-arch-x64.pkg.tar.zst (Arch). It installs to /usr and pulls in clang.
• Linux with snap: sudo snap install --classic --dangerous blitzllvm-<version>-<commit>-ubuntu24.04-x64.snap. Classic confinement is needed because the compiler reads your files wherever they are and runs programs outside of the snap.
• macOS: install blitzllvm-<version>-<commit>-macos-universal.pkg.
• Windows: download blitzllvm-<version>-<commit>-windows-x64.zip (or -windows-arm64.zip).

For the zip:

1. Extract it anywhere. The layout is:

   bin/blitzcc          the compiler (blitzcc.exe on Windows)
   bin/blitz-format     formats source code, see [[blitz-format]]
   lib/blitzllvm/runtime/  the runtime sources (inline/) and the libraries per architecture (x86_64/, arm64/; macOS has them directly), keep lib next to bin
   userlibs/            user libraries
   help/                the HTML help in the layout of the Blitz3D help: open help/index.html (the .deb, .rpm and Arch packages install it to /usr/share/doc/blitzllvm/help)
   samples/             the samples and games of the original Blitz3D (blitz3d/) and BlitzPlus (blitzplus/) with their media; share/blitzllvm/samples in the deb, rpm and pkg packages
   

2. Optionally add the bin directory to your PATH.

Tagged releases are published at https://github.com/Xaymar/BlitzLLVM/releases with the same files, see Releasing.

If you built it yourself, cmake --install produces the same layout, see Building.

Clang

BlitzLLVM writes LLVM IR and hands it to clang, which has to be installed and on your PATH. Use another one with --cc <path> or the BLITZLLVM_CC environment variable.

• Windows: install LLVM from https://github.com/llvm/llvm-project/releases, or the "C++ Clang tools for Windows" component of Visual Studio.
• Debian and Ubuntu: sudo apt-get install clang
• macOS: xcode-select --install

Graphics

Programs draw through Vulkan 1.3 into an SDL3 window, so a Vulkan 1.3 capable driver has to be installed. The Vulkan loader is loaded when the program starts, and the result is a single executable. AVIF, JPEG XL, TIFF and WebP images are decoded by shared libraries (avif, dav1d, jxl, tiff, webp and the libraries they use), which blitzcc copies next to programs that open a window; keep them next to the program when you ship it, or those four formats don't load (the program says so on the console). Set BLITZLLVM_HEADLESS=1 to run a program without a window or GPU.

Your first program

Save this as hello.bb:

Print "Hello from BlitzLLVM"

and run it (blitzcc builds it in a temporary directory and runs it, like the original), or build an executable:

blitzcc hello.bb
blitzcc -o hello hello.bb
./hello          # hello.exe on Windows

Useful options:

blitzcc program.bb              # build and run right away (arguments for the program go after --args)
blitzcc -o program program.bb  # only build the executable
blitzcc -O2 -o program program.bb   # a lower optimization level (the default is -O3)
blitzcc --fast-math full -o program program.bb   # also assume that Float math never produces NaN or Infinity (see below)
blitzcc -S program.bb          # only write the LLVM IR (program.ll)
blitzcc --target <triple> program.bb   # cross-compile
blitzcc -q program.bb          # quiet: no version banner and no warnings
blitzcc -W4 -Werror program.bb   # more warnings (-W0 to -W4, -W2 is the default), and any warning is an error, see [[Warnings]]
blitzcc -Wno-implicit-lossy-real-to-int program.bb   # turn off one warning
blitzcc +q program.bb          # very quiet: no messages from the compiler at all, errors included (it still returns a non-zero exit code)
blitzcc -c program.bb          # compile only: check the program, don't create an executable (unless -o is given)
blitzcc -d program.bb          # debug: no optimization, with debug information (DWARF, or CodeView for Windows MSVC)
blitzcc -g -O2 program.bb      # debug information in an optimized build
blitzcc --console -o program program.bb   # Windows: a console program (by default programs have no console window, see [[Differences]])
blitzcc -k                     # list all keywords, runtime functions and userlib functions
blitzcc +k                     # same, with the syntax of the functions, the way Blitz3D lists them (Left$ ( param1$,param2% ))
blitzcc --dump-keywords        # same, with the syntax in our own notation, every type by its name (Left:String param1:String, param2:Int32)
blitzcc -v                     # print the version of the compiler and runtime, like the original
blitzcc --version              # print "blitzcc <version>" and exit

-v prints the version like the original does (and still compiles a file that is given with it), --version prints blitzcc <version> like blitz-format --version and blitz-tidy --version, and --version and --help stop right away, whatever else is given; the verbose output of the commands that are run is --verbose. +k turns every integer type into a % and every float type into a #, so tools that expect the list of Blitz3D can read it; --dump-keywords does not convert anything, and uses the notation of this wiki: the types are written out (Int8, Int32, Int64, Float32, Float64, String, Pointer, ...), a parameter with a default value has it behind an =, and a function that returns nothing has no type behind its name. The userlibs for -k, +k and --dump-keywords are the .decls files in userlibs next to bin (or in share/blitzllvm/userlibs), or in the directory given with --userlibs-dir.

Userlibs work like they do in Blitz3D: a program that calls a function from a .decls file loads the library it names when it runs, with LoadLibrary (Windows) or dlopen (Linux, macOS), and looks the function up with GetProcAddress or dlsym. The library is loaded on the first call of one of its functions, so it does not have to exist when the program is built. It is looked for in the userlibs directory, next to the program, next to the source file, and then by the system, so user32.dll or libm.so.6 work without being copied anywhere. The name in the .lib line is tried as written, and with the extension of the platform (mylib.dll finds libmylib.so or libmylib.dylib), so one .decls file works everywhere. If the library or the function can not be found, the program stops with a runtime error when the function is called. The directory is --userlibs-dir, then the environment variable BLITZLLVM_USERLIBS, then the one of the installation. Functions use the C calling convention; strings are C strings, banks and objects are passed as the address of their memory, and a decorated name (_Name@8) falls back to Name if the library does not export it as written. Static libraries (.a, .lib) can not be loaded this way.

blitzcc --help lists all of them.

Optimization

Programs are built with -O3 and loop unrolling by default; -d builds without optimization. Float math is precise by default (--fast-math precise, also called off): exact IEEE behavior, with no reordering and no fused multiply-add, so the result is the same on every CPU. --fast-math safe compiles with the LLVM fast-math flags reassoc nsz arcp contract afn, which allows reordering, fused multiply-add and reciprocal math; results may then differ from the original and between CPUs in the last digits. --fast-math full also assumes that NaN and Infinity never occur, which makes checks like x <> x (is this NaN?) always false, so it is opt-in. Arguments and operands are evaluated in the order of the original Blitz3D, which is not left to right (see Language Quirks); --sane-evaluation-order evaluates them from left to right. The default targets a generic CPU of the architecture; add --llvm-flag -march=native for a program that only runs on the machine that built it.