The Git variables documented in this section should be set in
~/.config/emacs/.borgconfig.
This Git variable can be used to override the name of the directory that contains the drone submodules. If specified, the value has to be relative to the top-level directory of the repository.
The values of the following variables are set at startup and should not be changed by the user.
The value of this constant is the directory beneath which drone
submodules are placed. The value is set based on the location of
the borg library and the Git variable borg.drones-directory if set,
and should not be changed.
The value of this constant is the directory beneath which additional
per-user Emacs-specific files are placed. The value is set based on
the location of the borg library and should not be changed. The
value is usually the same as that of user-emacs-directory, except
when Emacs is started with emacs -q -l /path/to/init.el.
The value of this constant is the .gitmodules file of the
super-repository.
You should also add the following lines at the top of this file.
This isn’t strictly necessary, but if you don’t, then you must use
.gitmodules whenever this manual says, that you should set some
variable in .borgconfig or .gitremotes.
[include]
path = .gitremotes
path = .borgconfig
If you want to change the value of the following variable, you have to
do so before requiring borg, else it does not have the desired effect.
This variable controls whether the effect of the command-line
argument --debug-init extends to user init files. If non-nil and
--debug-init is used, then debug-on-error is automatically enable
and use-package-verbose is set to debug. Finally these variables
are reset to their default values using after-init-hook.
The value of this Make variable has to be set in
~/.config/emacs/Makefile.
A list of init files to be build by the Make targets build and
build-init. See Make targets.
Because most repositories used to maintain Emacs packages follow some
common-sense conventions, Borg usually does not have to be told how to
build a given drone. Building is done using borg-build, which in turn
usually does its work using borg-update-autoloads, borg-compile,
borg-maketexi, and borg-makeinfo.
However some packages don’t follow the conventions either because they are too complex to do so, or for the sake of doing it differently. But in either case resistance is futile; by using the following variables you can tell Borg how to build such packages.
By default drones are built using the lisp functions
borg-update-autoloads, borg-compile, borg-maketexi, and
borg-makeinfo, but if this variable has one or more values, then
DRONE is built using these COMMANDs instead.
Each COMMAND can be one of the default steps, an S-expression, or a shell command. The COMMANDs are executed in the specified order.
If a COMMAND matches one of default steps, then it is evaluated with the appropriate arguments.
If a COMMAND begins with a parenthesis, then it is evaluated as
a lisp expression. In that case the variable borg-clone holds
the name of the package that is being build. To make a function
available in this context, you usually have to define or load it
in ‘etc/borg/config.el’, relative to borg-user-emacs-directory.
Otherwise COMMAND is assumed to be a shell command and is executed
with shell-command.
An example using several shell commands and one standard build-step function.
[submodule "mu4e"]
build-step = test -e ./configure || autoreconf -i
build-step = ./configure
build-step = make -C mu4e > /dev/null
build-step = borg-update-autoloads
load-path = mu4e
Even if make generates the Info file, you might still have to add
borg-makeinfo as an additional build-step because the former might
not generate an Info index file (named dir), which Borg relies on.
Also see borg.extra-build-step below.
This variable can be used to change how shell commands specified
by submodule.DRONE.build-step are run. The default value is nil,
meaning that each build step is run unchanged using shell-command.
If the value is a string, then that is combined with each build step
in turn and the results are run using shell-command. This string
must contain either %s, which is replaced with the unchanged build
step, or %S, which is replaced with the result of quoting the build
step using shell-quote-argument.
If the value is a function, then that is called once with the drone as argument and must return either a string or a function. If the returned value is a string, then that is used as described above.
If the value returned by the first function is another function, then
this second function is called for each build step with the drone and
the build step as arguments. It must return a string or nil. If the
returned value is a string, then that is used as described above.
Finally the second function may execute the build step at its own
discretion and return nil to indicate that it has done so.
Notice that if the value of this variable is a function, this
function must a) be defined in a drone; and b) be registered as an
autoload. This is because build happens in a separate Emacs process
started with -Q --batch, which only receives the name of the function.
This variable instructs borg-activate to add PATH to the load-path
instead of the directory it would otherwise have added. Likewise it
instructs borg-compile to compile the libraries in that directory.
PATH has to be relative to the top-level of the repository of the
drone named DRONE. This variable can be specified multiple times.
Normally Borg uses elisp/ as the drone’s load-path, if that exists;
otherwise lisp/, if that exists; or else the top-level directory.
If this variable is set, then it overrides the default location.
Therefore, to add an additional directory, you also have to
explicitly specify the default location.
[submodule "vertico"]
load-path = .
load-path = extensions
This variable instructs borg-compile to not compile the library at
PATH. PATH has to be relative to the top-level of the repository of
the drone named DRONE. This variable can be specified multiple
times.
Sometimes a drone comes with an optional library which adds support for some other third-party package, which you don’t want to use. By adding such libraries as a value of this variable, you can avoid compile errors and warnings about unsatisfied dependencies,
Setting this variable to true instructs borg-compile to compile
DRONE’s directories recursively. This isn’t done by default because
there are more repositories in which doing so would cause issues
than there are repositories that would benefit from doing so.
Unfortunately many packages put problematic test files or (usually
outdated) copies of third-party libraries into subdirectories. The
latter is a highly questionable thing to do, but the former would be
perfectly fine, if only the non-library lisp files did not provide
a feature (which effectively turns them into libraries) and/or if a
file named .nosearch existed in the subdirectory. That file tells
functions such as normal-top-level-add-subdirs-to-load-path and
borg-compile to ignore the containing directory.
The function used to compile each individual library.
One of byte-compile-file, borg-byte+native-compile or
borg-byte+native-compile-async.
To enable native compilation when running make, use one of the
respective make targets, as described in Make targets.
Setting this variable to a non-nil value instructs borg-compile
to compile all drones recursively. Doing so is discouraged.
This variable lists the names of files to be excluded from native compilation.
This variable instructs Borg to execute COMMAND after the default
build-steps for each drone (or after submodule.DRONE.build-step, if
that is specified). It has to be set in .borgconfig and can have
multiple values.
If a COMMAND begins with a parenthesis, then it is evaluated as
a lisp expression. In that case the variable borg-clone holds
the name of the package that is being build. To make a function
available in this context, you usually have to define or load it
in ‘etc/borg/config.el’, relative to borg-user-emacs-directory.
Otherwise COMMAND is assumed to be a shell command and is executed
with shell-command.
This variable instructs borg-initialize to add PATH to
Info-directory-list. PATH has to be relative to the top-level of
the repository of the drone named DRONE.
This variable instructs borg-maketexi to not create a Texinfo file
for the Org file at PATH. PATH has to be relative to the top-level
of the repository of the drone named DRONE. This variable can be
specified multiple times.
This variable instructs borg-makeinfo to not create an Info file for
the Texinfo file at PATH. PATH has to be relative to the top-level
of the repository of the drone named DRONE. This variable can be
specified multiple times.
If the value of this variable is true, then it is skipped by
borg-initialize.
An alist that can optionally be used to rewrite certain URLs. Each
element has the form (ORIG . BASE). Each URL that starts with ORIG
is rewritten to start with BASE instead. See Using ssh URLs.
A regexp matching Org files that may be exported to Texinfo by
borg-maketexi. The name of the clone is substituted for %s.
Setting this to nil disables the export of any Org files.