-*- 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 , 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 . If you want to receive these notifications, please subscribe at . Alternatively, these notifications can be read via gmane at . The messages contain a URL to the log file of the failed job, like . * 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 . 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 , 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 . * 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 .