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


4 Assimilation

A third-party package is assimilated by adding it as a submodule and, if necessary, by configuring it in ~/.emacs.d/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 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 something like this might make sense:

Assimilate ido and extensions

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

Version strings as those shown above can be obtained using git describe --tags, or by looking inside the "Modules" section of the Magit status buffer of the ~/.emacs.d repository.

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 require 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-drone-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-byte-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-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. It also rebuilds init.el and USER-REAL-LOGIN-NAME.el.

This function is not intended for interactive use, but used to implement the make targets described in the following section.

When optional QUICK is non-nil, then do 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 rebuilds init.el and USER-REAL-LOGIN-NAME.el. It is not intended for interactive use.


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