Next: , Previous: , Up: Top   [Contents]


8 Variables

The values of the following variables are set at startup and should not be changed by the user.

Variable: borg-drone-directory

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 should not be changed.

Variable: borg-user-emacs-directory

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.

Variable: borg-gitmodules-file

The value of this constant is the ".gitmodules" file of the super-repository.

The values of the borg-specific Git variables have to be set in the file ~/.emacs.d/.gitmodules. The variables borg.pushDefault and submodule.DRONE.remote are described in Patching drones.

Variable: borg.collective = REMOTE

This variable specifies the name used for remotes that reference a repository that has been patched by the collective. If a NAME matches REMOTE, then it is configured as the upstream of the current branch of the respective DRONE.

If the file ".hive-maint" exists, then this variable has the same effect as "borg.pushDefault". This special case is only useful for maintainers of the collective (but not for maintainers of individual drones).

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-byte-compile, 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.

Variable: submodule.DRONE.build-step COMMAND

By default drones are built using the lisp functions borg-update-autoloads, borg-byte-compile, 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. Otherwise if the COMMAND begins with a parenthesis, then it is evaluated as an Elisp expression. Otherwise it is assumed to be a shell command and executed with shell-command.

[submodule "mu4e"]
        path = lib/mu4e
        url = git@github.com:djcb/mu.git
        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

To skip generating "autoloads" (e.g. using use-package to create "autoloads" on the fly), just provide the required build steps to build the package, omitting borg-update-autoloads. Borg silently ignores a missing "autoloads" file during initialization (borg-initialize).

[submodule "multiple-cursors"]
        path = lib/multiple-cursors
        url = git@github.com:magnars/multiple-cursors.el.git
        build-step = borg-byte-compile

Note that just because a package provides a Makefile, you do not necessarily have to use it.

Even if make generates the Info file, you might still have add borg-makeinfo as an additional build-step because the former might not generate a Info index file (named dir), which Borg relies on.

Variable: borg-build-shell-command

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.

Variable: submodule.DRONE.load-path PATH

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-byte-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 lisp/ as the drone’s load-path, 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 locaction.

[submodule "org"]
        path = lib/org
        url = git://orgmode.org/org-mode.git
        build-step = make
        load-path = lisp
        load-path = contrib/lisp
        info-path = doc
Variable: submodule.DRONE.no-byte-compile PATH

This variable instructs borg-byte-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. For example emacsql comes with a PostgreSQL back-end, which is implemented in the library emacsql-pg.el, which requires the pg package. The standard Borg collective emacs.g assimilates emacsql, for the sake of the epkg drone, which only requires the SQLite back-end. To avoid an error about pg not being available, emacs.g instructs Borg to not compile emacsql-pg.el. (Of course if you want to use the PostgreSQL back-end and assimilate pg, then you should undo that.)

Variable: submodule.DRONE.recursive-byte-compile BOOLEAN

Setting this variable to true instructs borg-byte-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 elisp files did not provide a feature (which effectivly 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-byte-compile to ignore the containing directory.

Variable: borg-byte-compile-recursive

Setting this variable to a non-nil value instructs borg-byte-compile to compile all drones recursively. Doing so is discouraged.

Variable: submodule.DRONE.info-path PATH

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.

Variable: submodule.DRONE.no-makeinfo PATH

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.

Variable: submodule.DRONE.disabled true|false

If the value of this variable is true, then it is skipped by borg-initialize.


Next: , Previous: , Up: Top   [Contents]