Getting started

In this guide you will set up the CDM-16 LLVM toolchain and learn the basic usage.

Installation

If you are using WSL, Linux (x86_64) or macOS (aarch64), you can use the automatic install script.

Dependencies

The script has some external dependencies that you will need to install manually:

• Python 3.10 or later
  • pip
  • venv
• Curl 7.61 or later

Here are package manager commands for various popular OS distributions:

Debian 12+, Ubuntu 22.04+, Linux Mint, Pop!_OS

sudo apt-get update
sudo apt-get install curl python3 python3-venv python3-pip

Fedora

sudo dnf install curl python3 python3-pip

Arch Linux, Manjaro, CachyOS

sudo pacman -S curl python python-pip

The command above may fail due to outdated repositories. In this case, use this command to also perform a full system upgrade:

sudo pacman -Syu curl python python-pip

macOS

brew install curl python

If you don't want to use Homebrew, you can install Python with the official installer. Curl should already come pre-installed.

CDM-16 LLVM

After installing the required packages, run this command and follow the on-screen instructions:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ylab-nsu/cdm16-llvm-neo/main/llvm/utils/cdm/install.sh | sh -s -- -v nightly

The script will ask you to specify the toolchain version and the install directory. You can use the defaults by pressing Enter without typing anything. The default install location is ~/.llvm-cdm. You can update the toolchain later by re-running the command above.

When the install script finishes, you will need to manually add the toolchain binary directory to your PATH environment variable. The exact step depends on the shell you use. Change ~/.llvm-cdm to the actual install path if you didn't use the default one.

Bash (default on most Linux distributions)

Add this line to ~/.bashrc

export PATH="$HOME/.llvm-cdm/bin:$PATH"

Zsh (default on macOS)

Add this line to ~/.zprofile or ~/.zshrc

export PATH="$HOME/.llvm-cdm/bin:$PATH"

Fish

Run this line once or add it to ~/.config/fish/config.fish

fish_add_path "$HOME/.llvm-cdm/bin"

After adding the PATH line to your shell's configuration file, close and reopen your terminal emulator for the changes to take effect.

Verify the installation by running this command:

clang-cdm --version

It should output something similar to the following:

clang version 21.1.2 (https://github.com/ylab-nsu/cdm16-llvm-neo <commit hash>)
Target: cdm-unknown-unknown-cocas
Thread model: posix
InstalledDir: <directory>
Build config: +assertions

Usage

After completing the installation, you will have a subset of LLVM tools with support for targeting the CDM-16 processor. The names of these tools are suffixed with -cdm to differentiate them from the system LLVM toolchain. You will likely only need clang-cdm and llvm-objcopy-cdm.

clang-cdm

This is a GCC-like compilation driver for the C programming language and assembly.

Compile C and assembly code into object files with -c:

clang-cdm -O2 -c -o main.obj main.c
clang-cdm -c -o io.obj io.asm

Link object files and make memory images with no special flags:

clang-cdm -o program.img io.obj main.obj

The compilation driver will call Cocas under the hood and use its proprietary assembly syntax and object file format. Linking will produce a Logisim-compatible hex image.

ELF target

There is an alternative LLVM target that does not depend on Cocas. To use it, pass --target=cdm to Clang both at compile and link time:

clang-cdm --target=cdm -O2 -c -o main.o main.c
clang-cdm --target=cdm -c -o io.o io.s
clang-cdm --target=cdm -o program.elf io.o main.o

This target uses different formats, which are not compatible with Cocas. Linker output files also need to be converted into Logisim images with llvm-objcopy-cdm. For more info, see LLVM targets.

llvm-objcopy-cdm

This tool can be used to convert ELF files into Logisim images and raw binaries. Use the -O logisim and -O binary options respectively.

llvm-objcopy-cdm -O logisim program.elf program.img
llvm-objcopy-cdm -O binary program.bin program.img