diff --git a/admin/notes/elpa b/admin/notes/elpa index e06633d098..ce84aacaa4 100644 --- a/admin/notes/elpa +++ b/admin/notes/elpa @@ -35,7 +35,6 @@ It is easy to use the elpa branch to deploy a "local" copy of the package archive. For details, see the README file in the elpa branch. ELPA PACKAGES BUNDLED IN THE DISTRIBUTION TARBALL --- updated 29 Jan 2021 Why Bundle? @@ -61,26 +60,27 @@ special to update a bundled ELPA package; the normal package.el mechanisms recognize all the versions properly. Emacs core code may not depend on (bundled or non-bundled) GNU ELPA -packages unless they are ":core" packages; if that functionality is -required, the package must be moved to Emacs. +packages unless they are ":core" packages. - A simple git clone/checkout of emacs.git master creates a workspace will all code required to build and run Emacs. - Any ELPA package can be changed without affecting Emacs core. -For single file packages, the file can simply be in both elpa.git and -emacs.git master. The package is marked ":core" in the ELPA -"elpa-packages" file. For example, eldoc and flymake are :core -packages. This mechanism is not supported for multi-file packages, -because maintaining sync between the files in emacs.git and elpa.git -is more problematic. +For single file packages whose upstream repository is emacs.git, the +package is marked ":core" in the ELPA "elpa-packages" file. For +example, eldoc and flymake are :core packages. This mechanism is not +supported for packages with a separate upstream repository, because +maintaining sync between the files in emacs.git and upstream is +problematic; it is not a simple 'git push'. To bundle a multi-file package in Emacs, add to elpa.git a branch `emacs-NN/[PKGNAME]` which holds the version to be included in the next Emacs release of version NN: - git branch -c externals/[PKGNAME] emacs-NN/[PKGNAME] + cd elpa/packages/[PKGNAME] + git checkout -b emacs-NN/[PKGNAME] + git checkout externals/[PKGNAME] Note that every GNU ELPA package has a branch `externals/[PKGNAME]` in elpa.git. @@ -94,7 +94,9 @@ Also push the release branch to emacs.git: In emacs/master, add a git submodule for that branch: - git submodule add --reference . -b emacs-NN/[PKGNAME] elpa/[PKGNAME] + cd emacs/master + git submodule add --reference .git -b emacs-NN/[PKGNAME] \ + [USERNAME]@git.savannah.gnu.org:/srv/git/emacs.git ./elpa/[PKGNAME] Emacs developers should add '--recurse-submodules' to the 'git clone' command when cloning Emacs; that will checkout the submodules with the @@ -174,6 +176,9 @@ UNRESOLVED ISSUES/TODO: - emacs/elpa/[PKNAME] vs emacs/lisp/[PKGNAME] + Note that this choice can be made on a per-package basis; + emacs/.gitmodules records where the package is checked out. + The baseline design keeps all bundled ELPA packages in emacs/elpa/[PKNAME], both in the source and installed directory trees. This makes it very easy to distinguish an emacs directory @@ -187,8 +192,8 @@ UNRESOLVED ISSUES/TODO: - Does vc support submodules and nested worktrees? -- Define a useful emacs lisp project (or something simpler), - So `C-x p f' searches `load-path' via `project-find-file' +- Define a useful emacs lisp project, so `C-x p f' searches + `load-path' via `project-find-file' That reduces the need to remember what packages are bundled, and where you have them checked out. @@ -200,8 +205,6 @@ UNRESOLVED ISSUES/TODO: that was in emacs core. - Automating compiling C, Ada, Rust or other language code required by - the package, to executables or modules. This includes defining - standard places to put executables, modules, and other - aritifacts. This is more important for bundled packages; users - expect Emacs to "just work" out of the box. + the package, to executables or modules. This is more important for + bundled packages; users expect Emacs to "just work" out of the box.