This collection of modes will help the user to efficiently write and edit ebuilds, eclasses and other files that are specific to Gentoo, a meta-distribution with various targets (GNU/Linux distribution, prefixed environments in other operating systems, and integration of other kernels and userlands like the BSDs or the GNU Hurd).
Ebuilds describe the build process and dependencies of a software package to compile and install it automatically under the control of a package manager. They are simple text files based on Bash scripts and are easy to create. Eclasses are comparable to libraries providing generic functions that ebuilds can use by sourcing the eclass on request.
ebuild-mode provides major modes to edit the above two file types. Other features are the execution of often needed commands (like KEYWORDS manipulation) or fast-track creation of new ebuilds by skeleton support.
Two packages are available for installation:
app-emacs/ebuild-mode and app-xemacs/ebuild-mode
(there is support for GNU Emacs and XEmacs from the same source). When
installed through the normal package management in Gentoo and proper
configuration of Emacs, ebuild-mode loads the appropriate mode on
opening files with the extensions .ebuild and .eclass.
As the ebuild format is based on the Bash syntax, sh-mode is called as
a base, where ebuild specific things are added/changed on top.
If font-locking is enabled, keywords are highlighted, both the standard
set defined by the package manager and special functions from all common
eclasses. Missing highlighting should be reported on
https://bugs.gentoo.org/.
Completion for the symbol at point is supported in ebuild-mode
(currently only under GNU Emacs). Pressing C-M-i or
M-TAB invokes the command completion-at-point,
which re-uses the list of package manager and eclass functions as
completion candidates.
Generally all functionality is reachable through direct commands, key bindings (described later) and menu entries, if the latter is activated. So every user has the choice for his/her preferred way of interfacing with Emacs.
pkgdev and pkgcheckStarting a completely new ebuild from scratch is best done by inserting
an ebuild skeleton. The command ebuild-mode-skeleton does this
for you and can be called via C-c C-e C-n. You are prompted for
the always needed information, while having the possibility to give more
than one item (in LICENSE for example) and choose via tab completion
from the possible choices. Giving an empty input on items, that are not
mandatory, will remove it from the buffer. After that adding custom
modifications is simple and straightforward.
In ebuild-mode an interface to manipulation of the KEYWORDS variable is provided in two different ways:
The first command is called ebuild-mode-keyword (bound to
C-c C-e C-k) and initially asks for the action to take which is
one out of
dropRemove the architecture entirely.
maskState with a prefixed minus sign that the architecture is definitely not supported.
stableMark as stable.
unstableMark as testing.
After choosing the action the architectures to handle need to be chosen. Tab completion is available for all possible architectures.
Using the ekeyword syntax for the ebuild-mode-ekeyword command
(C-c C-e C-y as key binding) is equal what you can pass as
argument to said utility from the app-portage/gentoolkit-dev
package:
^<arch>Remove the architecture entirely.
-<arch>State with a prefixed minus sign that the architecture is definitely not supported.
<arch>Mark as stable.
~<arch>Mark as testing.
It is possible to use all instead of an individual architecture
which works on all currently available architectures for the ebuild.
Handy for version/revision bumps is to mark all architectures from a
copied stable ebuild as testing. The key binding C-c C-e C-u
calling the ebuild-mode-all-keywords-unstable command can be used
for this task.
Apart from the normal external program calls via M-!, ebuild-mode
provides a direct interface to the ebuild utility found in the Portage
program suite. C-c C-e C-e calls ebuild-run-command which
asks for one of the possible actions as argument. See the man page of
ebuild what actions are provided.
Some common action (or subcommands) of the ebuild command can be
executed via their own key sequences, all of them using C-c C-e
followed by a letter. For example, the unpack action is bound
to C-c C-e u. With a prefix argument, the clean action
is executed first, additionally. Subcommands that don’t have their own
key sequence — but also those that do — can be executed via the main
ebuild-run-command bound to C-c C-e C-e, or via the menu.
The commands ebuild-mode-find-workdir, ebuild-mode-find-s
and ebuild-mode-find-image-dir (bound to C-c C-e C-w,
C-c C-e C-s and C-c C-e C-d, respectively) allow to visit
the working directory (${WORKDIR}), the temporary build
directory (${S}) and the image directory (${D}) that
belong to the ebuild in the current buffer. With a prefix argument,
the directory will be visited in another window.
The command ebuild-mode-find-build-log (C-c C-e C-l) visits
the build.log of the ebuild in the current buffer. With a prefix
argument, it visits the file in another window. Decoding of ANSI color
escape sequences is also supported when the tty-format library is
loaded.
pkgdev and pkgcheck ¶C-c C-e C-p calls the command ebuild-mode-run-pkgdev
command, which can be used to run pkgdev tools. Minibuffer
completion for subcommands is supported.
Similarly, C-c C-e C-c calls ebuild-mode-run-pkgcheck
which runs pkgcheck.
Insert a skeleton ebuild contents, with prompts for desired eclass inclusions, licenses and USE flags.
Keywording is done via prompts that narrows down your choices which architectures to mark as testing, dropped among other things.
Generate architecture keywords with the syntax from the ekeyword tool.
Mark all architectures as testing. Handy for version/revision bumps.
Run Portage’s ebuild command, you are prompted for the phase you want.
Visit the working directory (WORKDIR) that belongs to the ebuild.
Visit the temporary build directory (S).
Visit the image directory (D).
Visit the build.log file.
Run a pkgdev command.
Run a pkgcheck command.
Run an ebuild action/subcommand.
Complete the symbol at point via the completion-at-point command.
(Supported only under GNU Emacs.)
For editing of eclasses, ebuild-eclass-mode is a derived mode of ebuild-mode and provides all its features. In addition, highlighting of eclass documentation keywords with font-lock is supported.
This is a minor mode intended for editing ebuilds and other files in an ebuild repository (except patches).
The mode sets the tab-width to 4, which is the standard value
for ebuilds, and the fill-column to 72.
Furthermore, it will automatically fix whitespace and update copyright
years when writing the buffer to a file. This can be customized with
variables ebuild-mode-fix-whitespace and
ebuild-mode-update-copyright, respectively.
Indentation of XML in nxml-mode can be customized with the
variable ebuild-mode-xml-indent-tabs. A value of nil (which is
the default) means to use two spaces; non-nil means to use tab
characters.
There is only one key binding, namely C-c - which inserts a tag line with the user’s name, e-mail address and date, in the format that is commonly used in package.mask and other files:
# Larry The Cow <larry@gentoo.org> (2019-07-01)
The user’s name and e-mail address can be customized with variables
ebuild-mode-full-name and ebuild-mode-mail-address.
By default, ebuild-repo-mode will enable
bug-reference-prog-mode. This highlights references to bug
reports and makes it possible to follow them to the Gentoo bug tracker
(typically by pressing C-c RET or clicking mouse-2
on the highlighted text). For example, the reference ‘bug #161121’
in a comment line would link to https://bugs.gentoo.org/161121.
See Bug Reference in The Emacs Editor for further explanation.
You can disable bug references by setting the custom variable
ebuild-mode-enable-bug-reference to nil.
This is a very simple derived major mode for editing the Devmanual.
Because the Devmanual is written in DevBook XML, this mode is derived
from nxml-mode and inherits its syntax highlighting and editing
functions (see nXML Mode). A skeleton for a new
Devmanual file can be inserted via the devbook-insert-skeleton
function bound to C-c C-e C-n.
It is recommended to install the app-emacs/nxml-gentoo-schemas
package in addition, which will enable on-the-fly syntax validation.
Currently devbook-mode works with GNU Emacs only, because the
underlying nxml-mode does not support XEmacs.
This mode supports the highlighting of relevant keywords for GLEP 42 news items. These news items get displayed if special criteria for installed packages or profiles are met on the user’s system. Special upgrade instructions or other important news are then brought to the notice of the user through the package manager. As it is a seldom task for a developer to write a news item, some assistance is surely welcome when doing so, but GLEP 42 stays the reference for the whole process.
It gets automatically loaded when a file name matches the criteria of
GLEP 42 (see there for details), but can also be invoked through the
gentoo-newsitem-mode function. The only available key binding is
C-c C-n which starts a skeleton assistant similar to the one
available in ebuild-mode. All mandatory information are asked
from the user so no item is forgotten.
This major mode supports editing of Gentoo Linux Enhancement Proposals.
Because GLEPs are written in reStructuredText, this mode is derived
from rst-mode and inherits its syntax highlighting and editing
functions. Furthermore, highlighting of known keywords in the GLEP’s
preamble is supported. A skeleton for a new GLEP can be inserted via
the glep-mode-insert-skeleton function bound to C-c C-n.
It will automatically fill some metadata, like creation date and
author’s name, and query the user for other fields.
Currently glep-mode works with GNU Emacs only, because the
underlying rst-mode does not support XEmacs.