Enjoy Your Assassyn

笔者配置Assassyn环境的过程中遇到了一些问题，特此记录以备后续参考。

特别感谢Coffish 添加了另一种解决assassyn编译产生大量文件占用过多内存空间问题的方案——限制make并行数

首先贴上配置的具体流程：（值得注意的是，笔者在物理机上配置了Assassyn，不过Anyway还是贴上docker的配置流程好了）

Docker

It is also recommended to use Docker to
automatically manage the dependences. We decide to adopt a hybrid style
of coding, tooling, and development, where this repo is located
in your physical machine, while the execution is in the docker virtual
machine (VM).

Still, before doing anything, make sure you have this repo fully initialized:

1	`git submodule update --init --recursive`

Build the Docker Image

Assuming you are at the root of this source tree:

1	`docker build -t assassyn:latest .`

Run the Docker Container

At least read point 3 below before typing your command!!!

-v <src>:<dst> mounts a physical source directory into the VM destination.
--name specifies the name of this VM container, which avoids a random <adj>_<noun> name.
-m specifies the memory limit of a container. However, this flag only works on Linux.
- If you are using Docker client on Windows or Mac OS with UI, memory should be tuned in the client.
- Click the bottom bar of the client .
- A resource slide bar will pop up as shown .
- Tune the memory usage before starting your VM container.

1
2
3

docker run --rm -tid -v `pwd`:/app --user $(id -u):$(id -g) \
  -m 32g \
  --name assassyn assassyn:latest

Build Initialization

If it is the first time, the repo should be initialized using the command below.

1	`docker exec -it ./init.sh`

LLVM linkage is super memory consuming, while ninja build can only use fixed #thread
parallelization, which may overwhelm the memory. Feel free to tune your own parameters to have
a balance between performance and machine limit. If you see something like g++ is killed Signal 9
or truncated file, with high probability it is caused by out of memory (OOM).
Feel free to give a different parameter and run again.

Physical Machine

It can also be built on your physical machine. The instructions below are Ubuntu based:

Make sure you have all the repos propoerly cloned:

1	`git submodule update --init --recursive`

Install dependences:

sudo apt-get update
sudo apt-get install -y $(
  awk '/apt-get install/,/apt-get clean/' Dockerfile \
  | sed '1d;$d; s/[\\[:space:]]*$//; s/^[[:space:]]*//' \
  | grep -v '^$' \
  | tr '\n' ' '
)

Have this repo built from source:

1 2	`source setup.sh # Set up environment variables make build-all # Build all components`

If you do not have enough memory, a lower job number is recommended.

Verify your installation.

python -c 'import assassyn' # import this module
echo $? # 0 is expected
make test-all # Optional, runs all the tests.
echo $?

食用指南

Step 1：submodule 更新

首先是clone，老规矩还是SSH方式：

1	`git clone git@github.com:Synthesys-Lab/assassyn.git`

接着打开你的assassyn 目录，执行：

1	`git submodule update --init --recursive`

该过程耗时较长，大约在30分钟左右，且受网络影响较大，请耐心等待，一遍Failed就多来几遍，笔者试了至少3次才成功。

Step 2：环境依赖安装

Assassyn的依赖安装可以参考上面的Dockerfile，笔者在物理机上安装的命令如下：

sudo apt-get update
sudo apt-get install -y build-essential cmake git python3 python3-pip \
    libboost-all-dev libeigen3-dev libtbb-dev libgoogle-glog-dev libgflags-dev \
    libomp-dev clang llvm libclang-dev ninja-build

很平稳的一步，无事发生

Step 4：编译

最关键的一步，也是笔者卡壳的地方。Assassyn的编译分为两步，第一步是环境变量的配置，第二步是make all。

1 2	`source setup.sh make build-all`

Assassyn的编译文件很大很大，所以至少要留有32GB的内存空间，否则会出现编译失败的情况，故开Swap是必须的。

笔者的轻薄本属实拉跨，16GB内存完全不够，而且笔者是唐诗，大一上分盘的时候C盘只分了176GB，本来C盘所剩空间不到25GB，wsl还装在了C盘里，试图开个32GB的swap，显然不行，但抱着侥幸心理的笔者还是试了，结果可想而知，编译直接失败，而且成功把wsl搞炸了，是的，三个月内第四次灾难性故障，此时的笔者已经几乎崩溃。

笔者硬着头皮开始了迁盘，把wsl迁到了D盘，腾出了足够的空间后，重新开了32GB的swap，这次终于顺利编译成功。

下面讲一讲迁盘，适用于笔者这种唐诗：

打开windows powershell（管理员权限），输入以下命令：

1	`wsl --list --verbose`

得到类似如下的输出：

1 2	`NAME STATE VERSION * Ubuntu Running 2`

Ubuntu即为发行版名，接下来进行下一步。

导出 WSL 发行版为 .tar 文件

1	`wsl --export <DistroName> <FileName>.tar`

这个操作会把整个 Linux 文件系统打包成一个 .tar 文件。

注销原来的 WSL 发行版

1	`wsl --unregister <发行版名>`

这一步会删除原来的 WSL 实例，所以确保你已经导出了 .tar 文件。

在新位置导入 WSL，在 D 盘创建一个存放 WSL 的文件夹，然后导入：

1	`wsl --import <DistroName> <InstallLocation> <FileName>.tar --version 2`

这里的 <InstallLocation> 是你在 D 盘创建的文件夹路径。

验证迁移

1	`wsl --list --verbose`

完成迁移！

接下来就可以正常的开swap，编译Assassyn了。

新建一个大 swap 文件

1	`sudo fallocate -l 32G /swapfile`

设置正确的权限

1
2
3

sudo chmod 600 /swapfile2
sudo mkswap /swapfile2
sudo swapon /swapfile2

验证 swap 是否启用

1	`swapon --show`

你现在应该能看到新的 swap 文件已经启用

1
2
3

NAME        TYPE      SIZE  USED  PRIO
/dev/sdc    partition   4G   0B   -2
/swapfile2  file       32G   0B   -3

验证总内存

free -h

接下来就可以开始编译了

1 2	`source setup.sh make build-all`

我向你保证，这次一定能成功！

Another Approach：限制make并行数

你可以在make命令后面加上-jN，其中 $N$ 是你希望限制的并行作业数。
例如，如果你想限制为4个并行作业，可以这样做：

1	`make build-all -j4`

如果你的内存非常有限，你可能需要尝试更低的数字，比如 $2$ 或 $1$ ：

1	`make build-all -j2`

或者

1	`make build-all -j1`

通过限制并行作业数，你可以减少同时运行的编译任务数量，从而降低内存使用峰值，帮助避免内存不足的问题。

但很抱歉，这种解决方案在这里依然不行。

这是因为wj 在 Makefile 里调用了一些子项目的 make，并且调用的时候传的参数是 -j，这意味着不会限制任何并行数。

因此，临时的解决方案是用这个脚本把所有的 make -j 都改成比如说 make -j 8 ：

1	`find scripts -name "*.inc" -type f -exec sed -i 's/make -j\b/make -j 8/g' {} +`

Step 5：验证安装，跑一些测试

python -c 'import assassyn' # import this module
echo $? # 0 is expected
make test-all # Optional, runs all the tests.
echo $?

你又会遇到一些问题，首先是:

error: externally-managed-environment × This environment is externally managed ╰─> To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install. If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed. If you wish to install a non-Debian packaged Python application, it may be easiest to use pipx install xyz, which will manage a virtual environment for you. Make sure you have pipx installed. See /usr/share/doc/python3.12/README.venv for more information. note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages. hint: See PEP 668 for the detailed specification. Failed to install CIRCT via pip. Fall back to building from source using PyCDE setup. /usr/bin/python: No module named build make: *** [scripts/init/circt.inc:23: install-circt] Error 1

这是在新版 Ubuntu/Debian（或 WSL Ubuntu）中 Python 系统环境被 “保护” 了，不允许直接用 pip 安装包到系统 Python。所以我们建议使用虚拟环境 (推荐)。
笔者不常写py，故借此机会装了anaconda/miniconda(二者皆可)，顺便学习了一下虚拟环境的使用。

安装conda：

# 下载 Miniconda 安装脚本
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 安装
bash Miniconda3-latest-Linux-x86_64.sh

# 按提示操作，安装路径建议放在 home 目录下

创建 Conda 环境

# 创建名为 assassyn 的 Python 3.12 环境（根据需求可选）
conda create -n assassyn python=3.12

# 激活环境
conda activate assassyn

很不幸，当你再跑一遍的时候

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
Failed to install CIRCT via pip. Fall back to building from source using PyCDE setup.
/usr/bin/python: No module named build
make: *** [scripts/init/circt.inc:23: install-circt] Error 1

你的整个项目同样需要在一个虚拟环境下运行，故在激活的conda环境下再创建一个虚拟环境：

1 2	`python -m venv assassyn-env source assassyn-env/bin/activate`

别忘了重新编译

1	`make build-all`

哈哈还没结束，你大概还会遇到：

Running all tests...
ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: -n
  inifile: None
  rootdir: /home/zhuyihan/code/assassyn

make: *** [Makefile:30: test-all] Error 4

pytest -n 是用来并行运行测试的参数。它并不是 pytest 本体的内置功能，而是来自插件 pytest-xdist。

也就是说：你的 pytest 已经安装，但缺少插件 pytest-xdist。

解决方案：

1	`conda install pytest-xdist`

笑死我了，接下来你会意识到，你的test程序根本找不到assassyn这个包，🤡🤡🤡

ImportError while importing test module '/home/zhuyihan/code/assassyn/python/unit-tests/test_ramulator2_combined.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
../../anaconda3/envs/assassyn/lib/python3.11/importlib/__init__.py:126: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
python/unit-tests/test_ramulator2_combined.py:14: in <module>
    from assassyn.utils import repo_path
E   ModuleNotFoundError: No module named 'assassyn'

说明你的 Python 解释器在运行测试时找不到 assassyn 这个包。make build-all 已经执行过了，说明包本身可能编译好了，只是没让 Python 知道它的位置。

你自然可以临时地通过修改 PYTHONPATH 环境变量来解决这个问题：

1	`export PYTHONPATH=/home/zhuyihan/code/assassyn/python:$PYTHONPATH`

如果希望执行脚本的时候一个环境变量能够一直存在于bash中怎么办？

在你的 WSL 用户主目录下的 .bashrc 文件末尾添加上面那行命令即可。

1 2	`echo 'export PYTHONPATH=/home/zhuyihan/code/assassyn/python:$PYTHONPATH' >> ~/.bashrc source ~/.bashrc`

或者说，你每次跑程序的时候都要重新设置环境变量：

1	`source setup.sh # Set up environment variables`

祝你成功！

#Arch #Assassyn

Enjoy Your Assassyn

https://janezair.site/2025/10/21/Enjoy-your-Assassyn/

Author

JaneZ

Posted on

October 21, 2025

Updated on

October 31, 2025

Licensed under

GPU-Acceleration Next

Enjoy Your Assassyn

笔者配置Assassyn环境的过程中遇到了一些问题，特此记录以备后续参考。

特别感谢Coffish 添加了另一种解决assassyn编译产生大量文件占用过多内存空间问题的方案——限制make并行数

Docker

Build the Docker Image

Run the Docker Container

Build Initialization

Physical Machine

食用指南

Step 1：submodule 更新

Step 2：环境依赖安装

Step 4： 编译

Another Approach：限制make并行数

Step 5：验证安装，跑一些测试

祝你成功！

Step 4：编译