Next: , Previous: , Up: Borg User Manual   [Contents][Index]


4 Assimilation

A third-party package is assimilated by adding it as a submodule and, if necessary, by configuring it in ~/.config/emacs/init.el. Built-in packages are assimilated merely by configuring them.

To begin the assimilation of a third-party package use the command borg-assimilate, which adds the package’s repository as a submodule and attempts to build the drone.

A safer alternative is to first clone the package without assimilating it, using borg-clone. This gives you an opportunity to inspect the cloned package for broken or malicious code, before it gets a chance to run arbitrary code. Later you can proceed with the assimilation using borg-assimilate, or remove the clone using borg-remove.

Building the drone can fail, for example due to missing dependencies. Failure to build a drone is not considered as a failure to assimilate. If a build fails, then a buffer containing information about the issue pops up. If the failure is due to unsatisfied dependencies, then assimilate those too, and then build any drone, which previously couldn’t be built, by using the Emacs command borg-build or make lib/DRONE. Alternatively you can just rebuild everything using make build.

If you wish to avoid such complications, you should use the command epkg-describe-package before assimilating a package. Among other useful information, it also provides a dependency tree.

Once the packages have been added as a submodules and the drones have been built, the assimilation is completed by creating an assimilation commit.

If you assimilate a single package, then it is recommended that you use a message similar to this:

Assimilate foo v1.0.0

Or if one or more dependencies had to be assimilated, something like:

Assimilate foo and dependencies

Assimilate foo v1.0.0
Assimilate bar v1.1.0
Assimilate baz v0.1.0

It’s usually a good idea not to assimilate unrelated packages in the same commit, but doing it for related packages, which do not strictly depend on one another, it might make sense:

Assimilate ido and extensions

Assimilate flx               v0.6.1-3-gae0981b
Assimilate ido-at-point      v1.0.0
Assimilate ido-ubiquitous    v3.12-2-g7354d98
Assimilate ido-vertical-mode v0.1.6-33-gb42e422
Assimilate smex               3.0-13-g55aaebe

The command borg-insert-update-message can be used to generate such commit messages.

C-c C-b [in git-commit-mode buffer] (borg-insert-update-message)

This command insert information about drones that are changed in the index. Formatting is according to the commit message conventions described above.

Command: borg-assimilate package url &optional partially

This command assimilates the package named PACKAGE from URL.

If epkg is available, then only the name of the package is read in the minibuffer and the url stored in the Epkg database is used. If epkg is unavailable, the package is not in the database, or if a prefix argument is used, then the url too is read in the minibuffer.

If a negative prefix argument is used, then the submodule is added but the build and activation steps are skipped. This is useful when assimilating a package that requires special build steps. After configuring the build steps use borg-build to complete the assimilation.

Command: borg-clone package url

This command clones the package named PACKAGE from URL, without assimilating it. This is useful when you want to inspect the package before potentially executing malicious or broken code.

Interactively, when the epkg package is available, then the name is read in the minibuffer and the url stored in the Epkg database is used. If epkg is unavailable, the package is unknown, or when a prefix argument is used, then the url is also read in the minibuffer.

Command: borg-remove clone

This command removes the cloned or assimilated package named CLONE, by removing the working tree from borg-drones-directory, regardless of whether that repository belongs to an assimilated package or a package that has only been cloned for review using borg-clone. The Git directory is not removed.

Command: borg-build clone &optional activate

This command builds the clone named CLONE. Interactively, or when optional ACTIVATE is non-nil, then also activate the drone using borg-activate.

Function: borg-update-autoloads clone &optional path

This function updates the autoload file for the libraries belonging to the clone named CLONE in the directories in PATH. PATH can be omitted or contain file-names that are relative to the top-level of CLONE’s repository.

Function: borg-compile clone &optional path

This function compiles the libraries for the clone named CLONE in the directories in PATH. PATH can be omitted or contain file-names that are relative to the top-level of CLONE’s repository.

Function: borg-maketexi clone &optional files

This function generates Texinfo files from certain Org files for the clone named CLONE. Org files that are located on borg-info-path are exported if their names match borg-maketexi-filename-regexp and the TEXINFO_DIR_HEADER export keyword is set in their content.

Function: borg-makeinfo clone

This function generates the Info manuals and the Info index for the clone named CLONE.

Function: borg-batch-rebuild &optional quick

This function rebuilds all assimilated drones in alphabetic order, except for Org which is rebuilt first. After that it also builds the user init files using borg-batch-rebuild-init.

This function is not intended for interactive use; instead it is used by the Make target build described in the following section.

When optional QUICK is non-nil, then this function does not build drones for which submodule.DRONE.build-step is set, assuming that those are the drones that take longer to be built.

Function: borg-batch-rebuild-init

This function builds the init files specified by the Make variable INIT_FILES, or if that is unspecified init.el and LOGIN.el, where LOGIN is the value of the variable user-real-login-name. If a file does not exist, then it is silently ignored.

This function is not intended for interactive use; instead it is used by the Make targets build-init and (indirectly) build, which are described in Make targets.


Next: Updating drones, Previous: Startup, Up: Borg User Manual   [Contents][Index]