Skip to main content

50.5.1 Specifying Package Sources

To install a package from source, Emacs must know where to get the package's source code (such as a code repository) and basic information about the structure of the code (such as the main file in a multi-file package). A package specification describes these properties.

When supported by a package archive (see Package Archives in The Emacs Lisp Reference Manual), Emacs can automatically download a package's specification from said archive. If the first argument passed to package-vc-install is a symbol naming a package, then Emacs will use the specification provided by the archive for that package.

;; Emacs will download BBDB's specification from GNU ELPA:
(package-vc-install 'bbdb)

The first argument to package-vc-install may also be a package specification. This allows you to install source packages from locations other than the known archives listed in the user option package-archives. A package specification is a list of the form (name . spec), in which spec should be a property list using any of the keys in the table below.

For definitions of basic terms for working with code repositories and version control systems, see VCS Concepts in The GNU Emacs Manual.

:url​

A string providing the URL that specifies the repository from which to fetch the package's source code.

:branch​

A string providing the revision of the code to install. Do not confuse this with a package's version number.

:lisp-dir​

A string providing the repository-relative name of the directory to use for loading the Lisp sources, which defaults to the root directory of the repository.

:main-file​

A string providing the main file of the project, from which to gather package metadata. If not given, the default is the package name with ".el" appended to it.

:doc​

A string providing the repository-relative name of the documentation file from which to build an Info file. This can be a Texinfo file or an Org file.

:make​

A string or list of strings providing the target or targets defined in the repository Makefile which should run before building the Info file. Only takes effect when package-vc-allow-build-commands is non-nil.

:shell-command​

A string providing the shell command to run before building the Info file. Only takes effect when package-vc-allow-build-commands is non-nil.

:vc-backend​

A symbol naming the VC backend to use for downloading a copy of the package's repository (see Version Control Systems in The GNU Emacs Manual). If omitted, Emacs will attempt to make a guess based on the provided URL, or, failing that, the process will fall back onto the value of package-vc-default-backend.

;; Specifying information manually:
(package-vc-install
  '(bbdb :url "https://git.savannah.nongnu.org/git/bbdb.git"
         :lisp-dir "lisp"
         :doc "doc/bbdb.texi"))