Installation¶

To install and use Allo, we need to first install the latest LLVM project. You can choose to use our provided docker or build from source.

IMPORTANT: If you are using a coding agent for our codebase, please import AGENTS.md.

Install from Docker¶

To simplify the installation process, we provide a docker image that has already installed the latest LLVM project. Please pull the image from Docker Hub as described below. The LLVM is installed under the /root/llvm-project folder in the docker image.

$ docker pull chhzh123/allo:latest
$ docker run --rm -it chhzh123/allo:latest
(docker) $ git clone https://github.com/cornell-zhang/allo.git && cd allo
(docker) $ python3 -m pip install -v -e .

Install from Source¶

Please follow the instructions below to build the LLVM project from source. You can also refer to the official guide for more details. As the LLVM/MLIR API changes a lot, if you are using a different LLVM version, the Allo package may not work properly. The LLVM version we used can be found in the externals folder.

Note

The current source-installation dependencies target CPython 3.12 on Linux x86-64. Use the Docker installation above on other platforms.

Create and activate the Python environment before configuring LLVM. This makes LLVM and Allo use the same Python interpreter. Keep the repository root in ALLO_ROOT because the LLVM build takes place several directories below it.

git clone --recursive https://github.com/cornell-zhang/allo.git
cd allo
export ALLO_ROOT="$(pwd)"

# Python 3.12 is required by the current dependency set
conda create -n allo python=3.12
conda activate allo

python3 -m pip install --upgrade pip
python3 -m pip install cmake ninja "nanobind>=2.9,<3.0"

# Check the tools that will be used for the build
python3 --version
cmake --version
ninja --version
cc --version
c++ --version
python3 -m pip show nanobind

cd "$ALLO_ROOT/externals/llvm-project"
mkdir -p build && cd build
cmake -G Ninja ../llvm \
    -DLLVM_ENABLE_PROJECTS="clang;mlir;openmp" \
    -DLLVM_BUILD_EXAMPLES=ON \
    -DLLVM_TARGETS_TO_BUILD="host" \
    -DCMAKE_BUILD_TYPE=Release \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_INSTALL_UTILS=ON \
    -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
    -DPython3_EXECUTABLE="$(command -v python3)"
ninja

# Export and verify the completed LLVM/MLIR build
export LLVM_BUILD_DIR="$(pwd)"
export PATH="$LLVM_BUILD_DIR/bin:$PATH"
test -x "$LLVM_BUILD_DIR/bin/llvm-config"
test -f "$LLVM_BUILD_DIR/lib/cmake/mlir/MLIRConfig.cmake"
"$LLVM_BUILD_DIR/bin/llvm-config" --version

You can now install Allo by running the following commands.

cd "$ALLO_ROOT"
python3 -m pip install -v -e .

Testing¶

To make sure the installation is successful, you can run the following command to test the Allo package.

$ python3 -m pytest tests/

Internal Installation (Cornell)¶

For Zhang Group students, we have already prepared a prebuilt version of LLVM on our server, so you do not need to build everything from source. Please follow the instruction below to set up the environment.

Make sure you have the access to the brg-zhang or other Zhang group servers. You can log into the server by SSH or use VSCode Remote SSH extension. Please refer to this website for more details on configuring VSCode. Those servers are only accessible from the campus network. Please use the VPN if you are off-campus.

After logging into the server, the first step is to install an Anaconda environment. We recommend you to install your own Miniconda, which is a lightweight version of Anaconda and contains only the necessary packages. You can download the installer from the link above and install it on your system. After the installation, you can create a new environment for Allo by running the following commands:

$ conda create -n allo python=3.12
$ conda activate allo

We also provide a script to set up the backend LLVM compiler. You can simply run it

$ source /work/shared/common/allo/setup-llvm-main.sh

Note

You can also add this line to your ~/.bashrc file so that you don’t need to run the setup script every time.

Then, you can pull the latest version of Allo from GitHub and install it by running

$ git clone https://github.com/cornell-zhang/allo.git
$ cd allo
$ python3 -m pip install -v -e .

Now, you can run the following command to test if the installation is successful

$ python3 -c "import allo as allo; import allo.ir as air"

If you see no error messages, then the installation is successful. Otherwise, please contact us for help.

Troubleshooting¶

For source-build prerequisites, diagnostic commands, and common installation failures, see Source Installation Troubleshooting.