~niklaseklund/zuul.el

Interface to Zuul from Emacs

b14fb97 Replace keybinding for eldoc-mode

25 days ago

b14fb97 Replace keybinding for eldoc-mode

25 days ago

#zuul.el

builds.sr.ht status

#Introduction

Browse Zuul build outputs from Emacs. The zuul.el package provides functionality to communicate with Zuul through its Zuul REST API.

The zuul-log-mode major mode makes it as comfortable to browse a build log as it would be to navigate a local compilation. The package implements a custom filename parser for errors in the logs which allows Emacs to open the correct project file when an error is encountered in the log, even though the absolute path may not be found on the local machine.

#Configuration

A minimal use-package configuration.

(use-package zuul
  :custom ((zuul-base-url "https://base.url.to.zuul.net")
           (zuul-tenant "tenant1")
           (zuul-tenant-configs
            '((:name "tenant1"
                     :project-roots (("foo" . "~/git/foo-repo")
                                     ("baz" . "~/git/baz-repo")))
              (:name "tenant2"
                     :project-roots (("bar" . "~/git/bar-repo")))))))

#Usage

The package doesn't provide any commands, except those used by the zuul-log-mode. Other packages, or users themselves, needs to implement commands because retrieving builds or buildsets requires knowledge that might not be general. An example of a package that integrates with zuul.el is egerrit-zuul. It provides the command egerrit-zuul-open-build-log which can be used as inspiration.

The functions zuul-get-builds and zuul-get-buildsets needs to be called to retrieve builds and buildsets from Zuul. Both functions accepts multiple input parameters specified as keys in the call. The simplest example would be to use a change number.

;; For buildsets
(zuul-get-buildsets :change "300203")

;; For builds
(zuul-get-builds :change "300203")

A list of builds, or buildsets, can be passed as input to the zuul-open-build-log in order to view a specific build log.

;; For buildsets
(zuul-open-build-log
   (zuul-get-buildsets
    :change "300203"))

;; For builds
(zuul-open-build-log
   (zuul-get-builds
    :change "300203"))

#Zuul log mode

The major mode zuul-log-mode provides the following commands.

Name Binding Description
zuul-switch-build C-c C-b Switch to another build
zuul-switch-buildset C-c C-s Switch to a build from a specific buildset
zuul-run-build-command C-c C-r Run build command from build log
zuul-previous-build C-c C-p Switch to previous build
zuul-next-build C-c C-n Switch to next build
zuul-open-build-in-browser C-c C-o Open build in browser

It also integrates with the following built in features:

  • imenu: navigate to beginning of tasks in the build log
  • eldoc: echo descriptive information about where in the log point are

#Customization

The package provides the following customizable variables.

Name Description
zuul-base-url Base URL to Zuul
zuul-tenant Zuul tenant
zuul-tenant-configs A list of tenant configurations
zuul-build-annotation A list of annotations to display for a build
zuul-buildset-annotation A list of annotations to display for a buildset
zuul-build-command-annotation A list of annotations to display for a build command
zuul-build-imenu-annotation A list of annotations to display for a imenu
zuul-build-display-buffer-action The configuration for display-buffer when opening a build.
zuul-add-builds-to-buildset If set to t builds will be added to buildsets

#Remote support

The zuul.el package supports Connection Local Variables which allows the user to customize the zuul-tenant-configs variable when running on a remote host. In this example zuul-tenant-configs are configured the same for all remote hosts.

(connection-local-set-profile-variables
 'remote-zuul
 '((zuul-tenant-configs . ((:name "foo"
                            :project-roots (("bar" . "~/other_location/bar")))))))

(connection-local-set-profiles
 '(:application tramp :protocol "ssh") 'remote-zuul)

#Contributions

The author might try to include the package into ELPA in the future, which means that if you want to contribute you must have a copyright assignment.