[dev] manage runtime versions with asdf

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2023-11-05 11:07:23 +01:00 committed by Alexandre Flament
parent 79db70f2b7
commit 76b91a3ef6
3 changed files with 124 additions and 0 deletions

2
.tool-versions Normal file
View File

@ -0,0 +1,2 @@
python 3.12.0
shellcheck 0.9.0

View File

@ -6,6 +6,7 @@ Developer documentation
:maxdepth: 2 :maxdepth: 2
quickstart quickstart
rtm_asdf
contribution_guide contribution_guide
engines/index engines/index
search_api search_api

121
docs/dev/rtm_asdf.rst Normal file
View File

@ -0,0 +1,121 @@
==================
Runtime Management
==================
The runtimes are managed with asdf and are activated in this project via the
`.tool-versions <.tool-versions>`_. If you have not yet installed asdf_, then
chapter :ref:`introduce asdf` may be of help to you.
.. contents::
:depth: 2
:local:
:backlinks: entry
Get started
===========
If you have asdf installed you can install the runtimes of this project by:
.. code:: bash
$ cd /path/to/searxng
$ asdf install # will install runtimes listed in .tool-versions
...
Manage Versions
===============
If you want to perform a ``test`` with special runtime versions of nodejs,
python or shellcheck, you can patch the ``.tool-versions``:
.. code:: diff
--- a/.tool-versions
+++ b/.tool-versions
@@ -1,2 +1,2 @@
-python 3.12.0
-shellcheck 0.9.0
+python 3.11.6
+shellcheck 0.8.0
To install use ``asdf install`` again. If the runtime tools have changed, any
existing (nodejs and python) environments should be cleaned up with a ``make
clean``.
.. code:: bash
$ asdf install
...
$ make clean test
.. _introduce asdf:
Introduce asdf
==============
To `download asdf`_ and `install asdf`_:
.. code:: bash
$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch <version>
$ echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
$ echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
Start a new shell and try to `install plugins`_:
.. code:: bash
$ asdf plugin-list-all | grep -E '(golang|python|nodejs|shellcheck).git'
golang https://github.com/asdf-community/asdf-golang.git
nodejs https://github.com/asdf-vm/asdf-nodejs.git
python https://github.com/danhper/asdf-python.git
shellcheck https://github.com/luizm/asdf-shellcheck.git
$ asdf plugin add golang https://github.com/asdf-community/asdf-golang.git
$ asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
$ asdf plugin add python https://github.com/danhper/asdf-python.git
$ asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git
Each plugin has dependencies, to compile runtimes visit the URLs from above and
look out for the dependencies you need to install on your OS, on Debian for the
runtimes listed above you will need:
.. code:: bash
$ sudo apt update
$ sudo apt install \
dirmngr gpg curl gawk coreutils build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
With dependencies installed you can install/compile runtimes:
.. code:: bash
$ asdf install golang latest
$ asdf install nodejs latest
$ asdf install python latest
$ asdf install shellcheck latest
Python will be compiled and will take a while.
In the repository the version is defined in `.tool-versions`_. Outside the
repository, its recommended that the runtime should use the versions of the OS
(`Fallback to System Version`_) / if not already done register the system
versions global:
.. code:: bash
$ cd /
$ asdf global golang system
$ asdf global nodejs system
$ asdf global python system
$ asdf global shellcheck system
.. _asdf: https://asdf-vm.com/
.. _download asdf: https://asdf-vm.com/guide/getting-started.html#_2-download-asdf
.. _install asdf: https://asdf-vm.com/guide/getting-started.html#_3-install-asdf
.. _install plugins: https://asdf-vm.com/guide/getting-started.html#install-the-plugin
.. _Fallback to System Version: https://asdf-vm.com/manage/versions.html#fallback-to-system-version