Skip to content

Commit 3363bc8

Browse files
Kevin7QiKevin7Qi
committed
Add tutorial and Docker support
1 parent 9999a04 commit 3363bc8

21 files changed

Lines changed: 2232 additions & 241 deletions

‎.dockerignore‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Git - keep root .git and .gitmodules for submodule commands
2+
# Exclude submodule contents (cloned fresh by git submodule update in Dockerfile)
3+
modules/
4+
5+
**/.gitignore
6+
7+
# Build artifacts
8+
**/build
9+
**/dist
10+
**/*.egg-info
11+
12+
# Python
13+
**/__pycache__
14+
**/*.py[cod]
15+
**/*.so
16+
17+
# Virtual environments
18+
**/.env
19+
**/.venv
20+
**/env
21+
**/venv
22+
23+
# IDE
24+
**/.vscode
25+
**/.idea
26+
27+
# OS
28+
**/.DS_Store
29+
**/Thumbs.db
30+
31+
# Logs
32+
**/*.log
33+
34+
# User configuration and generated outputs
35+
config/
36+
output/
37+
data/
38+
39+
# Installation progress
40+
.install_progress
41+
42+
# Claude Code guidance (internal)
43+
CLAUDE.md
44+
45+
# Large submodule build artifacts
46+
**/thirdparty/llvm-project/build
47+
**/thirdparty/llvm-project/.git
48+
49+
# Test outputs
50+
**/.pytest_cache
51+
**/htmlcov
52+
**/.coverage

‎.github/workflows/docker-tutorial.yml‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
name: Build Tutorial Docker Image
2+
3+
# This workflow runs on the PUBLIC repo (CIMFlow.git), not the private one.
4+
# It builds Docker images that are fully self-contained - the Dockerfile
5+
# clones from public repos only, no private access needed.
6+
7+
on:
8+
# Manual trigger only - tutorial image is built locally and pushed manually
9+
# This avoids wasting CI minutes on long LLVM builds (~45 min)
10+
workflow_dispatch:
11+
inputs:
12+
push_image:
13+
description: 'Push image to registry'
14+
required: true
15+
default: 'true'
16+
type: choice
17+
options:
18+
- 'true'
19+
- 'false'
20+
21+
env:
22+
REGISTRY: ghcr.io
23+
IMAGE_NAME: buaa-ci-lab/cimflow-tutorial
24+
25+
# Prevent concurrent builds of the same branch/tag
26+
concurrency:
27+
group: docker-${{ github.ref }}
28+
cancel-in-progress: true
29+
30+
jobs:
31+
build-and-push:
32+
name: Build Tutorial Image
33+
runs-on: ubuntu-latest
34+
timeout-minutes: 90 # LLVM build can take 30+ minutes
35+
36+
# Manual dispatch only - build locally for testing, use CI for convenience if needed
37+
38+
permissions:
39+
contents: read
40+
packages: write
41+
42+
steps:
43+
- name: Checkout repository
44+
uses: actions/checkout@v4
45+
# Note: No submodules needed - Dockerfile.tutorial clones from GitHub directly
46+
47+
- name: Verify public repo configuration
48+
# Skip in private repo (manual dispatch for testing)
49+
if: github.repository == 'BUAA-CI-LAB/CIMFlow'
50+
run: |
51+
echo "Checking .gitmodules for private repo references..."
52+
if grep -q "Private" .gitmodules 2>/dev/null; then
53+
echo "::error::ERROR: .gitmodules contains 'Private' references!"
54+
echo "This workflow should only run on the release branch with public submodules."
55+
echo ""
56+
echo "Current .gitmodules:"
57+
cat .gitmodules
58+
exit 1
59+
fi
60+
echo "OK: Using public submodules"
61+
cat .gitmodules
62+
63+
- name: Set up Docker Buildx
64+
uses: docker/setup-buildx-action@v3
65+
66+
- name: Log in to Container Registry
67+
if: github.event_name != 'pull_request'
68+
uses: docker/login-action@v3
69+
with:
70+
registry: ${{ env.REGISTRY }}
71+
username: ${{ github.actor }}
72+
password: ${{ secrets.GITHUB_TOKEN }}
73+
74+
- name: Extract metadata
75+
id: meta
76+
uses: docker/metadata-action@v5
77+
with:
78+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
79+
tags: |
80+
type=ref,event=branch
81+
type=ref,event=tag
82+
type=raw,value=latest,enable={{is_default_branch}}
83+
type=sha,prefix=
84+
85+
- name: Build and push tutorial image
86+
id: build
87+
uses: docker/build-push-action@v5
88+
with:
89+
context: .
90+
file: ./docker/Dockerfile.tutorial
91+
push: ${{ github.event_name != 'pull_request' && (github.event.inputs.push_image != 'false') }}
92+
tags: ${{ steps.meta.outputs.tags }}
93+
labels: ${{ steps.meta.outputs.labels }}
94+
cache-from: type=gha
95+
cache-to: type=gha,mode=max
96+
platforms: linux/amd64
97+
98+
- name: Image digest
99+
run: echo ${{ steps.build.outputs.digest }}
100+
101+
build-dev-base:
102+
name: Build Dev Base Image
103+
runs-on: ubuntu-latest
104+
timeout-minutes: 30 # Base image is much faster (no LLVM build)
105+
106+
# Manual dispatch only - build locally for testing, use CI for convenience if needed
107+
108+
permissions:
109+
contents: read
110+
packages: write
111+
112+
steps:
113+
- name: Checkout repository
114+
uses: actions/checkout@v4
115+
116+
- name: Set up Docker Buildx
117+
uses: docker/setup-buildx-action@v3
118+
119+
- name: Log in to Container Registry
120+
if: github.event_name != 'pull_request'
121+
uses: docker/login-action@v3
122+
with:
123+
registry: ${{ env.REGISTRY }}
124+
username: ${{ github.actor }}
125+
password: ${{ secrets.GITHUB_TOKEN }}
126+
127+
- name: Build and push dev-base image
128+
uses: docker/build-push-action@v5
129+
with:
130+
context: .
131+
file: ./docker/Dockerfile.dev-base
132+
push: ${{ github.event_name != 'pull_request' && (github.event.inputs.push_image != 'false') }}
133+
tags: |
134+
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:dev-base
135+
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:dev-base-${{ github.sha }}
136+
cache-from: type=gha
137+
cache-to: type=gha,mode=max
138+
platforms: linux/amd64

‎README.md‎

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,30 @@ CIMFlow consists of two main components:
2929
1. **CIMFlow Compiler**: Transforms high-level neural network models (ONNX) into optimized instruction sequences (ISA) for the target CIM architecture.
3030
2. **CIMFlow Simulator**: Executes the generated instructions on a cycle-accurate model of the hardware, producing detailed performance and energy reports.
3131

32+
## Docker
33+
34+
CIMFlow provides Docker images for both tutorials and development:
35+
36+
| Image | Purpose | Size |
37+
|-------|---------|------|
38+
| `cimflow-tutorial:latest` | Pre-built with models and demos | ~10GB |
39+
| `cimflow-tutorial:dev-base` | Development base with dependencies | ~4GB |
40+
41+
```bash
42+
# Try the interactive tutorial
43+
docker run -it --rm ghcr.io/buaa-ci-lab/cimflow-tutorial:latest
44+
45+
# Or start a development environment
46+
./docker/dev.sh
47+
```
48+
49+
See [docker/README.md](docker/README.md) for detailed instructions.
50+
3251
## Prerequisites
3352

34-
### Python Environment
53+
### System Requirements
3554

55+
- **Operating System**: Ubuntu 22.04 (other Linux distributions may work but are untested)
3656
- **Python 3.11 or later** is required.
3757

3858
We recommend using Conda for Python environment management:
@@ -53,7 +73,7 @@ source .venv/bin/activate
5373

5474
### System Dependencies
5575

56-
Install the required system packages (Ubuntu/Debian):
76+
Install the required system packages (Ubuntu 22.04):
5777

5878
```bash
5979
# Build tools
@@ -134,6 +154,30 @@ cimflow run pipeline -m model.onnx -o output -l VERBOSE
134154
- **Default**: Simulation reports are saved in the output directory.
135155
- **Debug (`--keep-ir`)**: Saves all intermediate files (IR, ISA, logs) in timestamped folders.
136156

157+
## Tutorial
158+
159+
CIMFlow includes interactive tutorials to help you get started. Run them in Docker or after local installation:
160+
161+
```bash
162+
# Demo 0: Setup verification
163+
source tutorial/demo0_setup.sh
164+
165+
# Demo 1: Quick end-to-end pipeline
166+
source tutorial/demo1_quickstart.sh
167+
168+
# Demo 2: Step-by-step compilation stages
169+
source tutorial/demo2_stages.sh
170+
171+
# Demo 3: Design space exploration
172+
source tutorial/demo3_exploration.sh
173+
```
174+
175+
The tutorials cover:
176+
- **Demo 0**: Verify installation and explore CLI commands
177+
- **Demo 1**: Run a complete compile-simulate pipeline on ResNet-18
178+
- **Demo 2**: Understand each compilation stage (CG, OP, Simulation)
179+
- **Demo 3**: Batch processing for hardware design exploration
180+
137181
## Contributing
138182

139183
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.

‎docker/Dockerfile.dev-base‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# CIMFlow Development Base Image
2+
# Contains all system dependencies - users build from source
3+
#
4+
# Build: docker build -f docker/Dockerfile.dev-base -t cimflow-dev-base .
5+
# Run: docker run -it --rm -v $(pwd):/app/cimflow cimflow-dev-base
6+
# cd /app/cimflow && ./install.sh --shallow
7+
8+
FROM ubuntu:22.04
9+
10+
# Prevent interactive prompts during package installation
11+
ENV DEBIAN_FRONTEND=noninteractive
12+
ENV TZ=UTC
13+
14+
# Install system dependencies
15+
RUN apt-get update && apt-get install -y \
16+
# Build essentials
17+
build-essential \
18+
cmake \
19+
ninja-build \
20+
ccache \
21+
# Version control
22+
git \
23+
# Download tools
24+
curl \
25+
wget \
26+
# Archive tools
27+
zip \
28+
unzip \
29+
# Compilers and toolchains
30+
clang-12 \
31+
lld-12 \
32+
llvm-12 \
33+
# Java (for ANTLR grammar compilation)
34+
openjdk-17-jdk \
35+
# Libraries
36+
libboost-all-dev \
37+
libgflags-dev \
38+
libunwind-dev \
39+
# Python
40+
python3.11 \
41+
python3.11-dev \
42+
python3.11-venv \
43+
python3-pip \
44+
# Utilities
45+
tree \
46+
vim \
47+
&& rm -rf /var/lib/apt/lists/*
48+
49+
# Set Python 3.11 as default
50+
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1 \
51+
&& update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1
52+
53+
# Add LLVM to PATH
54+
ENV PATH="/usr/lib/llvm-12/bin:${PATH}"
55+
56+
# Install PyTorch FIRST (CPU-only for smaller image)
57+
# This must come before sympy to avoid version conflict:
58+
# - torch requires sympy>=1.13.3
59+
# - cim-compiler requires sympy==1.11.1
60+
# Installing torch first, then pinning sympy ensures correct final version
61+
RUN pip3 install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
62+
63+
# Install Python packages for CIM Compiler
64+
# Note: sympy is pinned AFTER torch to override torch's requirement
65+
RUN pip3 install --no-cache-dir \
66+
# Core dependencies
67+
numpy \
68+
pandas \
69+
pyyaml \
70+
# ONNX processing
71+
onnx \
72+
onnxoptimizer \
73+
# Compiler-specific (sympy pinned to override torch's requirement)
74+
bitarray==3.3.1 \
75+
islpy==2023.2.5 \
76+
sympy==1.11.1 \
77+
# Utilities
78+
jinja2 \
79+
tqdm \
80+
networkx \
81+
matplotlib \
82+
# Visualization
83+
plotly \
84+
streamlit \
85+
# Testing
86+
pytest \
87+
pytest-xdist \
88+
ipdb
89+
90+
# Install CIMFlow CLI dependencies
91+
RUN pip3 install --no-cache-dir \
92+
"typer>=0.15,<0.16" \
93+
rich \
94+
"pydantic>=2"
95+
96+
# Install build tools (for pip install -e . with --no-build-isolation)
97+
RUN pip3 install --no-cache-dir \
98+
hatchling \
99+
editables \
100+
packaging \
101+
pathspec \
102+
pluggy
103+
104+
# Trust all git directories (needed for mounted volumes with different ownership)
105+
RUN git config --global --add safe.directory '*'
106+
107+
WORKDIR /app/cimflow
108+
109+
# Default command
110+
CMD ["/bin/bash"]
111+
112+
# Labels
113+
LABEL org.opencontainers.image.title="CIMFlow Development Base"
114+
LABEL org.opencontainers.image.description="Base image with dependencies for building CIMFlow from source"
115+
LABEL org.opencontainers.image.source="https://github.com/BUAA-CI-LAB/CIMFlow"

0 commit comments

Comments
 (0)