emacs/admin/notes/emba

-*- mode: outline; coding: utf-8 -*-

Copyright (C) 2019-2024 Free Software Foundation, Inc.
See the end of the file for license conditions.

NOTES FOR EMACS CONTINUOUS BUILD ON EMBA

A continuous build for Emacs can be found at
<https://emba.gnu.org/emacs/emacs>, a Gitlab instance.  It watches the
Emacs git repository and starts a pipeline (jobset) if there are new
changes.  This happens for all Emacs branches which belong to the
defined workflow (see below).

* Mail notifications

In addition to the web interface, emba can send notifications by email
when a job fails.  It sends notifications about test status to
<emacs-buildstatus@gnu.org>.

If you want to receive these notifications, please subscribe at
<https://lists.gnu.org/mailman/listinfo/emacs-buildstatus>.

Alternatively, these notifications can be read via gmane at
<nntp+news.gmane.io:gmane.emacs.buildstatus>.

The messages contain a URL to the log file of the failed job, like
<https://emba.gnu.org/emacs/emacs/-/jobs/739/raw>.

* Emacs jobset

The Emacs jobset is defined in the Emacs source tree, file
'.gitlab-ci.yml'.  All related files are located in directory
'test/infra'.  They could be adapted for every Emacs branch, see
<https://emba.gnu.org/help/ci/yaml/README.md>.

Only branches whose name starts with 'master', 'emacs', 'feature', or
'fix' are considered.  This is declared in the workflow rules of file
'test/infra/gitlab-ci.yml'.

A jobset on Gitlab is called a pipeline.  Emacs pipelines run through
the stages 'build-images', 'platform-images' and 'native-comp-images'
(create an Emacs instance by 'make bootstrap' with different
configuration parameters) as well as 'normal', 'platforms' and
'native-comp' (run respective test jobs based on the produced images).

The jobs for stage 'normal' are contained in the file
'test/infra/test-jobs.yml'.  This file is generated by calling 'make
-C test generate-test-jobs' in the Emacs source tree, and the
resulting file should be pushed to the Emacs git repository afterwards.

Every job runs in a Debian docker container.  It uses the local clone
of the Emacs git repository to perform a bootstrap and test of Emacs.
This could happen for several jobs with changed configuration, compile,
and test parameters.

The 'build-image-*' jobs of the different '*-images' stages run only
if there are severe changes in the Emacs sources, like in Makefiles
etc.  Otherwise they are skipped, and the corresponding 'test-*' jobs
run just 'make -C test ...' in the respective Docker image from a
previous build run.

Jobs in the 'build-images' and 'normal' stages are triggered by
changes of respective files in the Emacs git repository.  All other
jobs run scheduled in a pipeline every 8 hours.

The log files for every test job are kept on the server for a week.
They can be downloaded from the server, visiting the URL
<https://emba.gnu.org/emacs/emacs/-/pipelines>, and selecting the job
in question.

Every pipeline generates a JUnit test report for the respective test
jobs, which can be inspected on the pipeline web page.  This test
report counts completed ERT tests, aborted tests are not counted.

* Emba configuration

The emba configuration files are hosted on
<https://gitlab.com/emacs-ci/emba-ansible>.

* Identifying emba

Lisp packages, Makefiles, scripts, and other software could determine
whether they run on emba by checking for the environment variable
EMACS_EMBA_CI.

* Running Emba tests locally

As usual in GitLab, the tests run in containers, which could be
applied also locally.  Unfortunately, the Emba container registry,
emba.gnu.org:5050, is not accessible publicly.  Instead, the container
images must be build locally.  Change the current directory to a
recent Emacs branch (not a worktree), and apply the command

  docker build --target emacs-inotify --tag emacs-inotify \
    -f test/infra/Dockerfile.emba .

This creates the Debian-based image emacs-inotify, based on the
instructions in the file Dockerfile.emba.  This image is good for the
majority of tests.  However, there are also other image build
instructions like emacs-filenotify-gio, emacs-eglot,
emacs-tree-sitter, emacs-gnustep and emacs-native-comp-speed{0,1,2}.
Use the appropriate one.

The image contains a directory "/checkout", which is a copy of your
local Emacs git repository.  Emacs has been built in this directory
via "make bootstrap".  In order to use the image, start a container
like

  docker run --interactive --tty --env EMACS_EMBA_CI=1 --name emacs-inotify \
    emacs-inotify /bin/bash -i

In this container, your working directory is "/checkout".  Now you can
apply all commands known for Emacs, like

  make -C test files-tests.log

While this container runs, you can also access its filesystem from
your local Emacs via Tramp.  For example, in order to see the result
of the above test run, open the log file in your local Emacs with

  C-x C-f /docker:emacs-inotify:/checkout/test/lisp/files-tests.log

Note: On local Red Hat-based systems, use "podman" instead of "docker"
in the shell commands and Tramp file names.


This file is part of GNU Emacs.

GNU Emacs is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.