Skip to content

Commit

Permalink
Document new Podman support, which is basically the same as Docker fo…
Browse files Browse the repository at this point in the history
…r Eldev's purposes.
  • Loading branch information
doublep committed May 2, 2024
1 parent 054c4eb commit 9285ecb
Show file tree
Hide file tree
Showing 4 changed files with 26 additions and 15 deletions.
3 changes: 2 additions & 1 deletion README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,8 @@ provides only a brief overview.
setups.
* Can run on {uri-documentation}#different-emacs-versions[different
Emacs version] even on the same machine; can also use
{uri-documentation}#docker[Docker] for that.
{uri-documentation}#docker[Docker] or
{uri-documentation}#podman[Podman] for that.
* There are {uri-documentation}#setup-procedure[_four_ levels of
configuration] — you can customize most aspects of Eldev for your
project needs and personal preferences.
Expand Down
1 change: 1 addition & 0 deletions doc/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
:uri-travis: https://travis-ci.org/
:uri-circle: https://circleci.com/
:uri-docker: https://www.docker.com/
:uri-podman: https://podman.io/
:uri-coveralls: https://coveralls.io/
:uri-setup-emacs: https://github.com/jcs090218/setup-emacs
:uri-setup-eldev: https://github.com/emacs-eldev/setup-eldev
Expand Down
34 changes: 21 additions & 13 deletions doc/emacs-versions.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -38,21 +38,28 @@ Therefore, if you use byte-compilation and switch Emacs versions,
don’t forget to clean the directory.

[#docker]
=== Using Docker
=== Using Docker or Podman

Alternatively, if you are on a Linux or macOS system and have
{uri-docker}[Docker] installed, you can run arbitrary Eldev commands
within containers based on the images distributed by
{uri-docker-emacs}[docker-emacs]. For example:
{uri-docker}[Docker] or (since 1.10) {uri-podman}[Podman] installed,
you can run arbitrary Eldev commands within containers based on the
images distributed by {uri-docker-emacs}[docker-emacs]. For example:

$ eldev docker 27.2 emacs --eval '(insert (format "Emacs version: %s" emacs-version))'

will start an Emacs 27.2 container and run `eldev emacs --eval
'(insert (format "Emacs version: %s" emacs-version))'` in it.

[#podman]
{since-1-10} Podman, from Eldev’s point of view, works just the
same. There is a special command for it, but it is basically
indistinguishable (except for the name):

$ eldev podman 27.2 emacs --eval '(insert (format "Emacs version: %s" emacs-version))'

NOTE: You may have to run `xhost +local:root` which allows the Docker
container to make connections to the host X server. However, this
does come with some security considerations, see `man xhost`.
(Podman) container to make connections to the host X server. However,
this does come with some security considerations, see `man xhost`.

This command can be used not only to start Emacs of given version, but
to run _any_ Eldev command. For example, run project’s tests on an
Expand All @@ -64,20 +71,21 @@ or evaluate something using project’s functions:

$ eldev docker 26.3 eval "(my-project-read-data \"foo.bin\")"

Docker’s output is forwarded to normal Eldev output, however, because
of {uri-emacs-forwarding}[Elisp limitations], it all ends up on
Eldev’s stdout! There might also be unwieldy delays, so that output
doesn’t come smoothly as generated by the process inside Docker, but
instead in larger chunks. Before Eldev 1.2 the output would instead
only appear when Docker has exited.
Docker’s (Podman’s) output is forwarded to normal Eldev output,
however, because of {uri-emacs-forwarding}[Elisp limitations], it all
ends up on Eldev’s stdout! There might also be unwieldy delays, so
that output doesn’t come smoothly as generated by the process inside
Docker, but instead in larger chunks. Before Eldev 1.2 the output
would instead only appear when Docker has exited.

It is also possible to use a custom image. For this, replace Emacs
version argument (26.3 in the last example above) with the full image
name. The image must contain a preinstalled Emacs of a version
supported by Eldev (i.e. 24.4 and up), but not Eldev itself.

Additionally, `docker run` arguments are customisable via the variable
`eldev-docker-run-extra-args`. For example, adding the following to
`eldev-docker-run-extra-args` (and likewise for Podman:
`eldev-podman-run-extra-args`). For example, adding the following to
your project’s `Eldev`:

....
Expand Down
3 changes: 2 additions & 1 deletion doc/overview.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ Eldev features:
* Blends nicely into <<continuous-integration,continuous
integration>> setups.
* Can run on <<different-emacs-versions,different Emacs version>> even
on the same machine; can also use <<docker,Docker>> for that.
on the same machine; can also use <<docker,Docker>> or
<<podman,Podman>> for that.
* There are <<setup-procedure,_four_ levels of configuration>> — you
can customize most aspects of Eldev for your project needs and
personal preferences.
Expand Down

0 comments on commit 9285ecb

Please sign in to comment.