diff --git a/.gitignore b/.gitignore index 125ebf7..2720985 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -/docs/build/ +/docs/ /env/ /.qlot /README diff --git a/ChangeLog.md b/ChangeLog.md new file mode 100644 index 0000000..2b471f3 --- /dev/null +++ b/ChangeLog.md @@ -0,0 +1,33 @@ + + +# ChangeLog + + + +## 1.1.0 (2021-06-06) + +Added a new input variable `asdf-version`. By default, the latest +`ASDF` will be used. + + + +## 1.0.2 (2021-04-04) + +Fixed installation of `libcurl4-openssl-dev` on Ubuntu Focal. + + + +## 1.0.1 (2021-02-22) + +Fixed error when there is no `qlfile` in the repository. + + + +## 1.0.0 (2021-01-07) + +Initial version. + + + +* * * +###### [generated by [40ANTS-DOC](https://40ants.com/doc/)] diff --git a/ChangeLog.rst b/ChangeLog.rst deleted file mode 100644 index 0dba86b..0000000 --- a/ChangeLog.rst +++ /dev/null @@ -1,24 +0,0 @@ -=========== - ChangeLog -=========== - -1.1.0 (2021-06-06) -================== - -Added a new input variable ``asdf-version``. By default, the latest -ASDF will be used. - -1.0.2 (2021-04-04) -================== - -Fixed installation of ``libcurl4-openssl-dev`` on Ubuntu Focal. - -1.0.1 (2021-02-22) -================== - -Fixed error when there is no ``qlfile`` in the repository. - -1.0.0 (2021-01-07) -================== - -Initial version. diff --git a/README.md b/README.md index 959dba9..ad7e0fd 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,36 @@ - + # GitHub Action to Setup Common Lisp for CI -## Table of Contents - -- [1 What this action does for you?][57c1] -- [2 A typical usage][6952] -- [3 Overriding qlfile][cd23] -- [4 Caching][33c1] -- [5 Roadmap][bc0f] -- [6 Contribution][b507] - -###### \[in package PROJECT-DOCS with nicknames PROJECT-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. +necessary to make available [Roswell][795a] +and [Qlot][e3ea] inside the Github `CI`. - + -## 1 What this action does for you? +## 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. +* 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. +* Upgrade `ASDF` to the latest version. -- Installs Qlot. +* Installs Qlot. -- Adds to `PATH` these directories: `~/.roswell/bin` and `.qlot/bin` +* Adds to `PATH` these directories: `~/.roswell/bin` and `.qlot/bin` -- Creates `.qlot` by running `qlot install`. How to override content of the +* 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. +* And finally, it can install a specified `ASDF` system and all it's dependencies. But this step is optional. + - - -## 2 A typical usage +## A typical usage Here is how a minimal GitHub Workflow might look like: @@ -77,7 +66,6 @@ jobs: with: asdf-system: cl-info ``` - The part, corresponding to an action call is: ```yaml @@ -85,7 +73,6 @@ The part, corresponding to an action call is: with: asdf-system: cl-info ``` - If you remove `with` part, then action will skip the `ASDF` system installation. @@ -97,13 +84,24 @@ to `sbcl`: env: LISP: ${{ matrix.lisp }} ``` - The last step in this workflow runs tests for the specified `ASDF` -system. It is documented [here](https://40ants.com/run-tests). +system. It is documented [here][8469]. - + -## 3 Overriding qlfile +## Overriding qlfile + +By default, action will install the latest `ASDF` version. But sometimes you might +want to fix an `ASDF` version. In such case, use `asdf-version` argument: + +``` +- uses: 40ants/setup-lisp@v1 + with: + asdf-version: 3.3.4.18 +``` + + +## Overriding qlfile Sometimes you might want to generate content of qlfile depending on matrix parameters. For example with matrix like this one: @@ -121,8 +119,7 @@ matrix: - ccl-bin - ecl ``` - -you might want to add an [ultralisp](https://ultralisp.org) source +you might want to add an [ultralisp][2a0d] source to the qlfile. Here is how this can be archived: ```yaml @@ -141,7 +138,6 @@ steps: dist ultralisp http://dist.ultralisp.org {% endifequal %} ``` - Here we see a few important things. 1. We put into the env var the type of the quicklisp distribution we want to @@ -153,13 +149,13 @@ Here we see a few important things. 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/). +Also note, it is using [Djula][3dbd] +markup, similar to [Django][04b3] +and [Jinja2][dd23]. - + -## 4 Caching +## Caching Usually installing Roswell, a lisp implementation and dependencies take from 2 to 10 minutes. Multiply this to the number of @@ -201,13 +197,12 @@ To make caching work, add such sections into your workflow file: - uses: 40ants/setup-lisp@v1 if: steps.cache.outputs.cache-hit != 'true' ``` - There are two important lines here. -- The last line `if: steps.cache.outputs.cache-hit != 'true'` skips +* The last line `if: steps.cache.outputs.cache-hit != 'true'` skips running lisp installation, it it was take from the cache. -- The `key` value: +* The `key` value: ` key: "${{ steps.current-month.outputs.value }}-${{ env.cache-name }}-${{ runner.os }}-${{ hashFiles('qlfile.lock') }}" @@ -216,32 +211,35 @@ There are two important lines here. It controls when your cache will be matched. If you are using `matrix`, put all it's components into the key. - I also added a current month there, to make sure cache will be renewed at least monthly. +I also added a current month there, to make sure cache will be renewed at least monthly. This way a new Roswell, Qlot and `ASDF` will be used in a build. - + -## 5 Roadmap +## Roadmap -- Support [CLPM](https://gitlab.common-lisp.net/clpm/clpm). +* Support [`CLPM`][2c45]. -- Vendor all dependencies, to make action more reliable and secure. +* Vendor all dependencies, to make action more reliable and secure. + - - -## 6 Contribution +## Contribution If you want to contribute to this system, join development at GitHub: - +[https://github.com/40ants/setup-lisp][cbff] - [33c1]: #x-28PROJECT-DOCS-3A-40CACHING-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 "Caching" - [57c1]: #x-28PROJECT-DOCS-3A-40FEATURES-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 "What this action does for you?" - [6952]: #x-28PROJECT-DOCS-3A-40TYPICAL-USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 "A typical usage" - [b507]: #x-28PROJECT-DOCS-3A-40CONTRIBUTION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 "Contribution" - [bc0f]: #x-28PROJECT-DOCS-3A-40ROADMAP-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 "Roadmap" - [cd23]: #x-28PROJECT-DOCS-3A-40QL-FILE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 "Overriding qlfile" + +[8469]: https://40ants.com/run-tests +[04b3]: https://docs.djangoproject.com/en/3.1/topics/templates/ +[cbff]: https://github.com/40ants/setup-lisp +[e3ea]: https://github.com/fukamachi/qlot +[3dbd]: https://github.com/mmontone/djula +[795a]: https://github.com/roswell/roswell +[2c45]: https://gitlab.common-lisp.net/clpm/clpm +[dd23]: https://jinja.palletsprojects.com/ +[2a0d]: https://ultralisp.org * * * -###### \[generated by [40ANTS-DOC](https://40ants.com/doc)\] +###### [generated by [40ANTS-DOC](https://40ants.com/doc/)] diff --git a/changelog.lisp b/changelog.lisp new file mode 100644 index 0000000..b449dac --- /dev/null +++ b/changelog.lisp @@ -0,0 +1,17 @@ +(defpackage #:project-docs/changelog + (:use #:cl) + (:import-from #:40ants-doc/changelog + #:defchangelog)) +(in-package project-docs/changelog) + + +(defchangelog (:ignore-words ("ASDF")) + (1.1.0 2021-06-06 + "Added a new input variable `asdf-version`. By default, the latest + ASDF will be used.") + (1.0.2 2021-04-04 + "Fixed installation of `libcurl4-openssl-dev` on Ubuntu Focal.") + (1.0.1 2021-02-22 + "Fixed error when there is no `qlfile` in the repository.") + (1.0.0 2021-01-07 + "Initial version.")) diff --git a/docs.lisp b/docs.lisp index c8553f6..a45769a 100644 --- a/docs.lisp +++ b/docs.lisp @@ -2,13 +2,35 @@ (:use #:cl) (:nicknames #:project-docs/docs) (:import-from #:40ants-doc - #:defsection)) + #:defsection + #:defsection-copy) + (:import-from #:project-docs/changelog + #:@changelog) + (:import-from #:docs-config + #:docs-config) + (:export #:@index + #:@readme + #:@changelog)) (in-package project-docs) +(defmethod docs-config ((system (eql (asdf:find-system "project-docs")))) + ;; 40ANTS-DOC-THEME-40ANTS system will bring + ;; as dependency a full 40ANTS-DOC but we don't want + ;; unnecessary dependencies here: + (ql:quickload :40ants-doc-theme-40ants) + (list :theme + (find-symbol "40ANTS-THEME" + (find-package "40ANTS-DOC-THEME-40ANTS")))) + + (defsection @index (:title "GitHub Action to Setup Common Lisp for CI" :ignore-words ("OSX" - "LISP")) + "LISP" + "ASDF" + "CI" + "CLPM" + "PATH")) " This is a Github Action to setup Common Lisp, Roswell and Qlot. @@ -26,6 +48,9 @@ and [Qlot](https://github.com/fukamachi/qlot) inside the Github CI. (@contribution section)) +(defsection-copy @readme @index) + + (defsection @features (:title "What this action does for you?") " * It installs Roswell and all it's dependencies, doing right thing depending on diff --git a/project-docs.asd b/project-docs.asd index 29e8c0f..ff3d918 100644 --- a/project-docs.asd +++ b/project-docs.asd @@ -1,4 +1,5 @@ (defsystem "project-docs" :class :package-inferred-system :depends-on ("project-docs/docs") + :homepage "https://40ants.com/setup-lisp/" :source-control (:git "https://github.com/40ants/setup-lisp")) diff --git a/qlfile.lock b/qlfile.lock index 1018bba..82b7368 100644 --- a/qlfile.lock +++ b/qlfile.lock @@ -1,12 +1,12 @@ ("quicklisp" . (:class qlot/source/dist:source-dist :initargs (:distribution "http://beta.quicklisp.org/dist/quicklisp.txt" :%version :latest) - :version "2021-04-11")) + :version "2021-08-07")) ("ultralisp" . (:class qlot/source/dist:source-dist :initargs (:distribution "http://dist.ultralisp.org" :%version :latest) - :version "20210422152500")) + :version "20210909150500")) ("sly" . (:class qlot/source/github:source-github :initargs (:repos "svetlyak40wt/sly" :ref nil :branch "patches" :tag nil) - :version "github-62eaa8112b926b328a9838e7d5b21c15")) + :version "github-489a6b628f809dd2b1c392346a70a0d2"))