Next: Updating drones, Previous: Startup, Up: Borg User Manual [Contents][Index]
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.
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.
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.
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.
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.
This command builds the clone named CLONE. Interactively, or when
optional ACTIVATE is non-nil, then also activate the drone using
borg-activate.
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.
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.
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.
This function generates the Info manuals and the Info index for the clone named CLONE.
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.
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]