feat(build): Build docker image for XiangShan development

Signed-off-by: Jiuyue Ma <majiuyue@bosc.ac.cn>

.dockerignore

@@ -0,0 +1,3 @@
+# ignore temporary files for docker build
+build/
+.docker-mill-out/

.gitignore

@@ -321,6 +321,10 @@ src_managed/
 project/boot/
 project/plugins/project/
 
+# mill specific
+.mill-jvm-opts
+.docker-mill-out/
+
 # Scala-IDE specific
 .scala_dependencies
 .worksheet

Dockerfile

@@ -0,0 +1,44 @@
+#***************************************************************************************
+# Copyright (c) 2025 Beijing Institute of Open Source Chip (BOSC)
+#
+# XiangShan is licensed under Mulan PSL v2.
+# You can use this software according to the terms and conditions of the Mulan PSL v2.
+# You may obtain a copy of Mulan PSL v2 at:
+#          http://license.coscl.org.cn/MulanPSL2
+#
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
+# EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
+# MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
+#
+# See the Mulan PSL v2 for more details.
+#***************************************************************************************
+
+FROM ghcr.io/openxiangshan/xs-env:latest
+
+# override ENTRYPOINT in verilator image
+ENTRYPOINT [ "/bin/bash" ]
+ENV VERILATOR=/usr/local/bin/verilator-wrap.sh
+
+# explict set LC_ALL to C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+#
+# Mill
+#
+COPY .mill-version /tmp
+RUN cd /tmp && mill -i --version && rm -rf .mill-version out
+
+#
+# XiangShan workspace
+#
+WORKDIR /work
+VOLUME /work/out
+VOLUME /work/build
+
+#
+# download dependencies
+#
+RUN --mount=type=bind,source=.,target=/work,readonly \
+    --mount=type=tmpfs,destination=/work/out,rw <<EOF
+make deps
+EOF

README.md

@@ -100,7 +100,7 @@ make idea
 * Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU).
 * Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project.
 * Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am).
-* Install `mill`. Refer to [the Manual section in this guide](https://mill-build.org/mill/0.11.11/Scala_Installation_IDE_Support.html#_bootstrap_scripts).
+* Install `mill`. Refer to [the Manual section in this guide](https://mill-build.org/mill/cli/installation-ide.html#_bootstrap_scripts).
 * Clone this project and run `make init` to initialize submodules.
 
 ### Run with simulator

scripts/Makefile.docker

@@ -0,0 +1,66 @@
+#***************************************************************************************
+# Copyright (c) 2025 Beijing Institute of Open Source Chip (BOSC)
+#
+# XiangShan is licensed under Mulan PSL v2.
+# You can use this software according to the terms and conditions of the Mulan PSL v2.
+# You may obtain a copy of Mulan PSL v2 at:
+#          http://license.coscl.org.cn/MulanPSL2
+#
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
+# EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
+# MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
+#
+# See the Mulan PSL v2 for more details.
+#***************************************************************************************
+
+#
+# Docker image info
+#
+GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null)
+GIT_BRANCH_CLEAN := $(shell echo $(GIT_BRANCH) | sed -e "s/[^[:alnum:]]/-/g")
+XSDEV_IMAGE := ghcr.io/openxiangshan/xsdev$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN))
+HAVE_XSDEV_IMAGE := $(shell docker image inspect --format '{{.ID}}' $(XSDEV_IMAGE) 2> /dev/null)
+NO_XSDEV_IMAGE := $(if $(HAVE_XSDEV_IMAGE),,1)
+
+# check if fd0 refers to tty
+HAVE_TTY = $(shell [ -t 0 ] && echo y)
+
+# command for docker run
+MILL_WORK_DIR := /work
+MILL_OUTPUT_DIR := .docker-mill-out
+DOCKER_RUN = docker run --init --rm -i $(if $(HAVE_TTY),-t) -e IN_XSDEV_DOCKER=y \
+			-e NOOP_HOME=$(MILL_WORK_DIR) \
+			-v .:$(MILL_WORK_DIR):ro \
+			-v ./$(MILL_OUTPUT_DIR):$(MILL_WORK_DIR)/out:rw \
+			-v $(BUILD_DIR):$(MILL_WORK_DIR)/$(BUILD_DIR):rw \
+		    $(XSDEV_IMAGE) $(1) || exit 1
+
+# mill proxy support
+HTTP_PROXY ?=
+PROXY_HOST := $(shell echo $(HTTP_PROXY) | sed -e 's|http://\(.*\):\(.*\)|\1|')
+PROXY_PORT := $(shell echo $(HTTP_PROXY) | sed -e 's|http://\(.*\):\(.*\)|\2|')
+.mill-jvm-opts:
+	@{ echo -Dhttp.proxyHost=$(PROXY_HOST);		\
+	   echo -Dhttp.proxyPort=$(PROXY_PORT);		\
+	   echo -Dhttps.proxyHost=$(PROXY_HOST);	\
+	   echo -Dhttps.proxyPort=$(PROXY_PORT); } > $@
+__prep_proxy: .mill-jvm-opts
+
+# build docker image
+image: $(if $(HTTP_PROXY),__prep_proxy) init
+	@mkdir -p out $(MILL_OUTPUT_DIR)
+	@docker build -t $(XSDEV_IMAGE) \
+		$(if $(HTTP_PROXY),--build-arg  HTTP_PROXY=$(HTTP_PROXY) \
+				  --build-arg HTTPS_PROXY=$(HTTP_PROXY)) . \
+		|| (echo ""; \
+		    echo "Docker image build failed, maybe you need a proxy?"; \
+		    echo "\n make image HTTP_PROXY=\"http://<proxy-ip>:<port>\"\n"; false)
+
+# run interactive shell
+sh:
+	$(if $(HAVE_XSDEV_IMAGE),,\
+	     $(error Docker unavailable or "$(XSDEV_IMAGE)" image not exist))
+	@mkdir -p out $(MILL_OUTPUT_DIR)
+	@$(call DOCKER_RUN)
+
+.PHONY: image __prep_proxy sh