\input texinfo.tex    @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
@setfilename ebuild-mode.info
@settitle Major mode for ebuilds and eclasses in Gentoo
@c %**end of header

@copying
This manual is for ebuild-mode, which is a major mode for ebuild
and eclass files.

Copyright @copyright{} 2009-2024 Gentoo Authors

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License, version 2 or any
later version published by the Free Software Foundation.
@end quotation
@end copying

@dircategory Gentoo
@dircategory Emacs
@direntry
* ebuild-mode: (ebuild-mode).   Major mode for ebuild and eclass files.
@end direntry


@titlepage
@title ebuild-mode 1.75
@subtitle Major mode for ebuilds and eclasses in Gentoo
@author Christian Faulhammer
@author Ulrich Müller
@page
@insertcopying
@end titlepage

@node Top

@contents

@top ebuild-mode: An introduction
This collection of modes will help the user to efficiently write and
edit ebuilds and eclasses which are special to Gentoo,
a meta-distribution with various targets (Linux distribution, prefixed
environments in other operating systems, and integration of other
kernels and userlands like the BSDs).

Ebuilds describe the build process and dependencies of a software
package to automatically compile and install it under the control of a
package manager.  They are simple text files, based on Bash shell
scripts and there easy to create.  Eclasses are comparable to a library
which provides generic functions that a set of ebuilds can use by
sourcing it 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.

@menu
* Commands:: What ebuild-mode provides.
* ebuild-mode:: Editing ebuilds.
* ebuild-eclass-mode:: Editing eclasses.
* ebuild-repo-mode:: Minor mode for ebuild repositories.
* devbook-mode:: Editing the Gentoo Devmanual.
* gentoo-newsitem-mode:: Editing GLEP 42 news items.
* glep-mode:: Editing Gentoo Linux Enhancement Proposals.
@end menu

@node Commands, ebuild-mode, Top, Top
@chapter Available functionality
Two packages are available for installation:
@code{app-emacs/ebuild-mode} and @code{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 @code{.ebuild} and @code{.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
@code{https://bugs.gentoo.org/}.

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.

@node ebuild-mode, ebuild-eclass-mode, Commands, Top
@chapter ebuild-mode
@section Writing a new ebuild
Starting a completely new ebuild from scratch is best done by inserting
an ebuild skeleton.  The command @code{ebuild-mode-skeleton} does this
for you and can be called via @kbd{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.

@section Keywording
In ebuild-mode an interface to manipulation of the KEYWORDS variable is
provided in two different ways:
@enumerate
@item
Prompt for actions with tab completion or
@item
ekeyword syntax.
@end enumerate

The first command is called @code{ebuild-mode-keyword} (bound to
@kbd{C-c C-e C-k}) and initially asks for the action to take which is
one out of
@table @code
@item drop
Remove the architecture entirely.
@item mask
State with a prefixed minus sign that the architecture is definitely not
supported.
@item stable
Mark as stable.
@item unstable
Mark as testing.
@end table

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 @code{ebuild-mode-ekeyword} command
(@kbd{C-c C-e C-y} as key binding) is equal what you can pass as
argument to said utility from the @code{app-portage/gentoolkit-dev}
package:
@table @code
@item ^<arch>
Remove the architecture entirely.
@item -<arch>
State with a prefixed minus sign that the architecture is definitely not
supported.
@item <arch>
Mark as stable.
@item ~<arch>
Mark as testing.
@end table
It is possible to use @code{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 @kbd{C-c C-e C-u}
calling the @code{ebuild-mode-all-keywords-unstable} command can be used
for this task.

@section Testing and interfacing with Portage

Apart from the normal external program calls via @kbd{M-!}, ebuild-mode
provides a direct interface to the ebuild utility found in the Portage
program suite.  @kbd{C-c C-e C-e} calls @code{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 @kbd{C-c C-e}
followed by a letter.  For example, the @code{unpack} action is bound
to @kbd{C-c C-e u}.  With a prefix argument, the @code{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
@code{ebuild-run-command} bound to @kbd{C-c C-e C-e}, or via the menu.

The commands @code{ebuild-mode-find-workdir}, @code{ebuild-mode-find-s}
and @code{ebuild-mode-find-image-dir} (bound to @kbd{C-c C-e C-w},
@kbd{C-c C-e C-s} and @kbd{C-c C-e C-d}, respectively) allow to visit
the working directory (@code{$@{WORKDIR@}}), the temporary build
directory (@code{$@{S@}}) and the image directory (@code{$@{D@}}) that
belong to the ebuild in the current buffer.  With a prefix argument,
the directory will be visited in another window.

The command @code{ebuild-mode-find-build-log} (@kbd{C-c C-e C-l}) visits
the @code{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 @file{tty-format} library is
loaded.

@section Running @command{pkgdev} and @command{pkgcheck}

@kbd{C-c C-e C-p} calls the command @code{ebuild-mode-run-pkgdev}
command, which can be used to run @command{pkgdev} tools.  Minibuffer
completion for subcommands is supported.

Similarly, @kbd{C-c C-e C-c} calls @code{ebuild-mode-run-pkgcheck}
which runs @command{pkgcheck}.

@section Key Bindings
@table @kbd
@item C-c C-e C-n
Insert a skeleton ebuild contents, with prompts for desired eclass
inclusions, licenses and USE flags.
@item C-c C-e C-k
Keywording is done via prompts that narrows down your choices which
architectures to mark as testing, dropped among other things.
@item C-c C-e C-y
Generate architecture keywords with the syntax from the ekeyword tool.
@item C-c C-e C-u
Mark all architectures as testing.  Handy for version/revision bumps.
@item C-c C-e C-e
Run Portage's ebuild command, you are prompted for the phase you want.
@item C-c C-e C-w
Visit the working directory (@code{WORKDIR}) that belongs to the ebuild.
@item C-c C-e C-s
Visit the temporary build directory (@code{S}).
@item C-c C-e C-d
Visit the image directory (@code{D}).
@item C-c C-e C-l
Visit the @code{build.log} file.
@item C-c C-e C-p
Run a @command{pkgdev} command.
@item C-c C-e C-c
Run a @command{pkgcheck} command.
@item C-c C-e LETTER
Run an ebuild action/subcommand.
@end table

@node ebuild-eclass-mode, ebuild-repo-mode, ebuild-mode, Top
@chapter ebuild-eclass-mode
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.

@node ebuild-repo-mode, devbook-mode, ebuild-eclass-mode, Top
@chapter ebuild-repo-mode
This is a minor mode intended for editing ebuilds and other files in
an ebuild repository (except patches).

The mode sets the @code{tab-width} to 4, which is the standard value
for ebuilds, and the @code{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 @code{ebuild-mode-fix-whitespace} and
@code{ebuild-mode-update-copyright}, respectively.

Indentation of XML in @code{nxml-mode} can be customized with the
variable @code{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 @kbd{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 @file{package.mask} and other files:

@example
# Larry The Cow <larry@@gentoo.org> (2019-07-01)
@end example

The user's name and e-mail address can be customized with variables
@code{ebuild-mode-full-name} and @code{ebuild-mode-mail-address}.

@node devbook-mode, gentoo-newsitem-mode, ebuild-eclass-mode, Top
@chapter devbook-mode for the Gentoo Devmanual
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 @code{nxml-mode} and inherits its syntax highlighting and editing
functions.  A skeleton for a new Devmanual file can be inserted via
the @code{devbook-insert-skeleton} function bound to @kbd{C-c C-n}.

It is recommended to install the @code{app-emacs/nxml-gentoo-schemas}
package in addition, which will enable on-the-fly syntax validation.

Currently @code{devbook-mode} works with GNU Emacs only, because the
underlying @code{nxml-mode} does not support XEmacs.

@node gentoo-newsitem-mode, glep-mode, devbook-mode, Top
@chapter gentoo-newsitem-mode for GLEP 42 news items
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
@code{gentoo-newsitem-mode} function.  The only available key binding is
@kbd{C-c C-n} which starts a skeleton assistant similar to the one
available in @code{ebuild-mode}.  All mandatory information are asked
from the user so no item is forgotten.

@node glep-mode, , gentoo-newsitem-mode, Top
@chapter glep-mode for Gentoo Linux Enhancement Proposals
This major mode supports editing of Gentoo Linux Enhancement Proposals.
Because GLEPs are written in reStructuredText, this mode is derived
from @code{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 @code{glep-mode-insert-skeleton} function bound to @kbd{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 @code{glep-mode} works with GNU Emacs only, because the
underlying @code{rst-mode} does not support XEmacs.

@bye