diff --git a/README.md b/README.md index 1813dea..d00491f 100644 --- a/README.md +++ b/README.md @@ -1,155 +1 @@ - - -# GitHub Action to setup Common Lisp for CI - -## Table of Contents - -- [1 What this action does for you?][f73c] -- [2 A typical usage][ff56] -- [3 Overriding qlfile][d1d0] - -###### \[in package DOCS with nicknames DOCS/DOCS\] -This is a Github Action to setup Common Lisp, Roswell and Qlot. - -It is useful to call it before running tests or building docs -for your Common Lisp libraries. Action encapsulates all steps -necessary to make available [Roswell](https://github.com/roswell/roswell) -and [Qlot](https://github.com/fukamachi/qlot) inside the Github CI. - - - -## 1 What this action does for you? - -- It installs Roswell and all it's dependencies, doing right thing depending on - the operating system. It should work on Ubuntu, OSX and maybe Windows. - -- Upgrade `ASDF` to the latest version. - -- Installs Qlot. - -- Adds to `PATH` these directories: `~/.roswell/bin` and `.qlot/bin` - -- Creates `.qlot` by running `qlot install`. How to override content of the - `qlfile`, see "Overriding qlfile" section. - -- And finally, it can install a specified `ASDF` system and all it's dependencies. - But this step is optional. - - - - -## 2 A typical usage - -Here is how a minimal GitHub Workflow might look like: - -```yaml -name: 'CI' - -on: - push: - branches: - - 'main' - - 'master' - pull_request: - -jobs: - tests: - runs-on: ubuntu-latest - - strategy: - matrix: - lisp: - - sbcl-bin - - ccl-bin - - env: - LISP: ${{ matrix.lisp }} - - steps: - - uses: actions/checkout@v1 - - uses: 40ants/setup-lisp@v1 - with: - asdf-system: cl-info - - uses: 40ants/run-tests@v2-beta - with: - asdf-system: cl-info -``` - -The part, corresponding to an actionn call is: - -```yaml -- uses: 40ants/setup-lisp@v1 - with: - asdf-system: cl-info -``` - -If you remove `with` part, then action will skip the `ASDF` system -installation. - -The last step in this workflow runs tests for the specified `ASDF` -system. It is documented [here](https://40ants/run-tests). - - - -## 3 Overriding qlfile - -Sometimes you might want to generate content of qlfile -depending on matrix parameters. For example with matrix like this one: - -```yaml -matrix: - os: - - ubuntu-latest - - macos-latest - quicklisp-dist: - - quicklisp - - ultralisp - lisp: - - sbcl-bin - - ccl-bin - - ecl -``` - -you might want to add an [ultralisp](https://ultralisp.org) source -to the qlfile. Here is how this can be archived: - -```yaml -env: - LISP: ${{ matrix.lisp }} - OS: ${{ matrix.os }} - QUICKLISP_DIST: ${{ matrix.quicklisp-dist }} - -steps: - - uses: actions/checkout@v1 - - uses: 40ants/setup-lisp@v1 - with: - asdf-system: cl-info - qlfile-template: | - {% ifequal quicklisp_dist "ultralisp" %} - dist ultralisp http://dist.ultralisp.org - {% endifequal %} - - github mgl-pax svetlyak40wt/mgl-pax :branch mgl-pax-minimal -``` - -Here we see a few important things. - -1. We put into the env var the type of the quicklisp distribution we want to - our library to test against. - -2. We pass a multiline argument `qlfile-template` to the action. - -3. Template refers to `quicklisp_dist` to conditionally include a line - into `qlfile` when `quicklisp_dist == "ultralisp"`. - -You can refer any environment variable inside the `qlfile` templater. -Also note, it is using [Djula](https://github.com/mmontone/djula) -markup, similar to [Django](https://docs.djangoproject.com/en/3.1/topics/templates/) -and [Jinja2](https://jinja.palletsprojects.com/). - - [d1d0]: #x-28DOCS-3A-40QL-FILE-20MGL-PAX-MINIMAL-3ASECTION-29 "Overriding qlfile" - [f73c]: #x-28DOCS-3A-40FEATURES-20MGL-PAX-MINIMAL-3ASECTION-29 "What this action does for you?" - [ff56]: #x-28DOCS-3A-40TYPICAL-USAGE-20MGL-PAX-MINIMAL-3ASECTION-29 "A typical usage" - -* * * -###### \[generated by [MGL-PAX](https://github.com/melisgl/mgl-pax)\] +1