From 636ac968ad3ef904ae4ee22928057a2c8f298bd8 Mon Sep 17 00:00:00 2001 From: Lucas Bollen Date: Fri, 13 Dec 2024 12:01:45 +0100 Subject: [PATCH] Extend readme with CI info The readme contains information about the purpose of CI and building and pushing the docker image --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5bcc2e1..8528fe2 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ well as a black-box for Verilog synthesis. The core interfaces with other components via [Wishbone](https://cdn.opencores.org/downloads/wbspec_b4.pdf) interfaces, using [`clash-protocols`](https://github.com/clash-lang/clash-protocols) types. -## Building +## Building the project For building the CPU, the following software needs to be installed and available in the `PATH`: @@ -29,7 +29,7 @@ For building the CPU, the following software needs to be installed and available - `verilator`, at least version 5.001 (development version at time of writing) - `make` for building the verilated library and FFI code -## Notes for using the core +### Notes for using the core - VexRiscv has a "reset vector" for the instruction bus. This is the initial PC that gets fetched. This address only gets presented to the IBUS after at least one cycle of RST being asserted. @@ -37,3 +37,43 @@ For building the CPU, the following software needs to be installed and available - The contents of memories need to be stored in little endian. This means that for example the contents of an ELF file need to be endian-swapped before being used as the contents of the instruction storage. This applies to all storages. +___ + +# Continuous Integration Setup + +The Continuous Integration (CI) flow for this project is defined in the `ci.yml` file. The CI has the following goals: +* Verify that the project builds successfully. +* Prevent warnings and errors in the codebase. +* Ensure functional correctness by running tests. +* Ensure code quality by running linters and formatters. + +CI uses a separate cabal project file that turns warnings into errors. + +### Building and Pushing the Docker Image + +To build the Docker image for this project, follow these steps: + +1. Navigate to the docker directory: + ```sh + cd .github/docker + ``` + +2. Run the `build-and-publish-docker-image.sh` script: + ```sh + ./build-and-publish-docker-image.sh + ``` + +This script builds the Docker image using the specified Ubuntu and GHC versions. It also installs the necessary dependencies and tools required for the project. + +### Authentication for Pushing to GitHub + +If you have an authentication token, you can use `docker login ` to log in using your docker username and token as password. + +If you don't have an authentication token, you can request the maintainers to build and push the image. Please email [devops@qbaylogic.com](mailto:devops@qbaylogic.com) with the following information: +- Repository +- Commit hash +- Branch name + +## Additional Support + +For other problems or questions, please refer to one of the communication channels listed on [clash-lang.org](https://clash-lang.org).