diff --git a/README.md b/README.md index 3fa1c13df2..e58e828921 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,8 @@ Here is the final diagram for [step A](process/guide.md#stepA): ![stepA_mal architecture](process/stepA_mal.png) If you are interested in creating a mal implementation (or just -interested in using mal for something), you are welcome to to join our -[Discord](https://discord.gg/CKgnNbJBpF) or join #mal on -[libera.chat](https://libera.chat/). In addition to the [make-a-lisp +interested in using mal for something) you are welcome to to join our +[Discord](https://discord.gg/CKgnNbJBpF). In addition to the [make-a-lisp process guide](process/guide.md) there is also a [mal/make-a-lisp FAQ](docs/FAQ.md) where I attempt to answer some common questions. @@ -1452,7 +1451,7 @@ make "docker-build^IMPL" **Notes**: -* Docker images are named *"kanaka/mal-test-IMPL"* +* Docker images are named *"ghcr.io/kanaka/mal-test-IMPL"* * JVM-based language implementations (Groovy, Java, Clojure, Scala): you will probably need to run this command once manually first `make DOCKERIZE=1 "repl^IMPL"` before you can run tests because diff --git a/docs/FAQ.md b/docs/FAQ.md index 49af1d7eee..b045de0867 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -154,11 +154,57 @@ into the main repository: `time-ms` function which is needed to run the micro-benchmark tests). * Create a `Dockerfile` in your directory that installs all the - packages necessary to build and run your implementation. Refer to other - implementations for examples of what the Dockerfile should contain. - Build your docker image and tag it `kanaka/mal-test-[IMPL_NAME]`. - The top-level Makefile has support for building/testing within - docker with the `DOCKERIZE` flag: + packages necessary to build and run your implementation. In order to + integrate fully with the Github Actions CI workflow, the + `Dockerfile` needs to include the following boilerplate (with your + name, email, and implementation filled in): + ``` + MAINTAINER Your Name + LABEL org.opencontainers.image.source=https://github.com/kanaka/mal + LABEL org.opencontainers.image.description="mal test container: Your_Implementation" + ``` + + In addition, the docker image should provide python3 (with a python + symlink to it) to enable running tests using the image. Here is the + typical `Dockerfile` template you should use if your + implementation does not require a special base distro: + + ``` + FROM ubuntu:24.04 + MAINTAINER Your Name + LABEL org.opencontainers.image.source=https://github.com/kanaka/mal + LABEL org.opencontainers.image.description="mal test container: Your_Implementation" + ########################################################## + # General requirements for testing or common across many + # implementations + ########################################################## + + RUN apt-get -y update + + # Required for running tests + RUN apt-get -y install make python3 + RUN ln -sf /usr/bin/python3 /usr/bin/python + + # Some typical implementation and test requirements + RUN apt-get -y install curl libreadline-dev libedit-dev + + RUN mkdir -p /mal + WORKDIR /mal + + ########################################################## + # Specific implementation requirements + ########################################################## + + ... Your packages ... + ``` + +* Build and tag your docker image. The image tag will have the + form `ghcr.io/kanaka/mal-test-[IMPL_NAME]:[VOOM_VERSION]`. + ``` + make "docker-build^[IMPL_NAME]" + +* The top-level Makefile has support for building/testing using + the docker image with the `DOCKERIZE` flag: ```bash make DOCKERIZE=1 "test^[IMPL_NAME]" make DOCKERIZE=1 MAL_IMPL=[IMPL_NAME] "test^mal" @@ -170,6 +216,9 @@ into the main repository: ./ci.sh test [IMPL_NAME] ``` +* Push your code to a branch and make sure that the automated Github + Actions CI passes for your implementation. + * If you are creating a new implementation for an existing implementation (or somebody beats you to the punch while you are working on it), there is still a chance I will merge your diff --git a/process/guide.md b/process/guide.md index e0f18b1208..3f0ee86c81 100644 --- a/process/guide.md +++ b/process/guide.md @@ -1716,9 +1716,7 @@ implementation. ### Next Steps -* Join the #mal IRC channel. It's fairly quiet but there are bursts of - interesting conversation related to mal, Lisps, esoteric programming - languages, etc. +* Join our [Discord](https://discord.gg/CKgnNbJBpF) channel. * If you have created an implementation for a new target language (or a unique and interesting variant of an existing implementation), consider sending a pull request to add it into the main mal