Skip to content

Enhance docker image #606

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 5, 2025
Merged

Enhance docker image #606

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eb36e7f
Bump Alpine Linux in Docker final stage
kaiii708 Sep 1, 2025
0f860ce
Enhance Docker image with rv32emu-user, -system, and -histogram binaries
kaiii708 Sep 1, 2025
e5e97c8
Update README for Docker image artifacts
kaiii708 Sep 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,30 @@
FROM alpine:3.21 AS base_gcc

RUN apk add --update alpine-sdk git wget sdl2-dev sdl2_mixer-dev
RUN apk add --update alpine-sdk git wget sdl2-dev sdl2_mixer-dev dtc

# copy in the source code
WORKDIR /home/root/rv32emu
COPY . .

# generate execution file for rv32emu and rv_histogram
RUN make
RUN make tool
# build and rename executables: rv32emu-user, rv32emu-system, and rv32emu-histogram
RUN make -j"$(nproc)"
RUN make tool -j"$(nproc)"
RUN mv ./build/rv32emu ./build/rv32emu-user
RUN mv ./build/rv_histogram ./build/rv32emu-histogram
RUN make distclean
RUN make ENABLE_SYSTEM=1 INITRD_SIZE=32 -j"$(nproc)"

FROM alpine:3.19 AS final
FROM alpine:3.21 AS final
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which parts of this change rely on Alpine 3.21 and wouldn't work on 3.19?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commit 37c9838 mentioned that the end of support for Alpine Linux v3.19.x is on 1 Nov 2025, so I upgraded it to 3.21.


# copy in elf files
COPY ./build/*.elf /home/root/rv32emu/build/

# get rv32emu and rv_histogram binaries and lib of SDL2 and SDL2_mixer
COPY --from=base_gcc /usr/include/SDL2/ /usr/include/SDL2/
COPY --from=base_gcc /usr/lib/libSDL2* /usr/lib/
COPY --from=base_gcc /home/root/rv32emu/build/rv32emu /home/root/rv32emu/build/rv32emu
COPY --from=base_gcc /home/root/rv32emu/build/rv_histogram /home/root/rv32emu/build/rv_histogram
COPY --from=base_gcc /home/root/rv32emu/build/rv32emu-user /home/root/rv32emu/build/rv32emu-user
COPY --from=base_gcc /home/root/rv32emu/build/rv32emu /home/root/rv32emu/build/rv32emu-system
COPY --from=base_gcc /home/root/rv32emu/build/rv32emu-histogram /home/root/rv32emu/build/rv32emu-histogram

ENV PATH=/home/root/rv32emu/build:$PATH

Expand Down
34 changes: 34 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,40 @@ The usage and limitations of Doom and Quake demo are listed in [docs/demo.md](do
### Docker image
The image containing all the necessary tools for development and testing can be executed by `docker run -it sysprog21/rv32emu:latest`. It works for both x86-64 and aarch64 (e.g., Apple's M1 chip) machines.

To keep the Docker image minimal, executables and prebuilt images are not embedded. Follow the steps below to fetch the required artifacts.

##### User-Mode
Fetch and extract the latest prebuilt user-mode ELF artifacts:
```shell
$ wget $(wget -qO- 'https://api.github.com/repos/sysprog21/rv32emu-prebuilt/releases?per_page=100' \
| grep browser_download_url | grep ELF | head -n 1 | cut -d '"' -f4)

$ tar -xzvf rv32emu-prebuilt.tar.gz
```
To run `rv32emu-user`, consider the following examples:
```shell
# Run a local ELF program
build/rv32emu-user build/hello.elf

# Run a prebuilt user-mode program (e.g., pi)
build/rv32emu-user rv32emu-prebuilt/riscv32/pi
```

##### System-Mode
Fetch and extract the latest prebuilt system-mode Linux image artifacts:
```shell
$ wget $(wget -qO- 'https://api.github.com/repos/sysprog21/rv32emu-prebuilt/releases?per_page=100' \
| grep browser_download_url | grep Linux-Image | head -n 1 | cut -d '"' -f4)

$ tar -xzvf rv32emu-linux-image-prebuilt.tar.gz
```
To run `rv32emu-system`, use the following:
```shell
$ build/rv32emu-system \
-k rv32emu-linux-image-prebuilt/linux-image/Image \
-i rv32emu-linux-image-prebuilt/linux-image/rootfs.cpio
```

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we renamed rv_histogram, could we also update the README's Docker section to document how to run the histogram tool in addition to the user/system mode emulators?

### Customization
`rv32emu` is configurable, and you can override the below variable(s) to fit your expectations:
* `ENABLE_RV32E`: RV32E Base Integer Instruction Set
Expand Down
Loading