Summary: (How to make an epackage): Adjust wording
< # Inject utility into Git branch "upstream"
> # Inject extension into Git branch "upstream"
< files, adjust or delete as needed. E.g. we don't need for this simple
< utility files like *-compile, *-examples, *-uninstall and we can just
< delete them. We need to fill in the important /info/ file that defines
< details of the package. We commit chnaged, make this epackage
< available from our public space or share it through Github and annouce
< it in epackage yellow pages; amongst other packages.
> files, adjust or delete them as needed. E.g. we don't need for this
> simple extension files like *-compile, *-examples, *-uninstall and we
> can simply delete them. We have to fill in the important /info/ file
> that defines details of the package. After all chnages, we commit to
> Git, make this new epackage available (push to Github) and annouce its
> availability in epackage yellow pages; amongst other packages.
DELPS - Distributed Emacs Lisp Package System by JariAalto. The DELPS is the framework, the blueprint of the design concepts. An implementation of DELPS in Git is called Epackage which follows the proven Debian packaging concepts applied to Emacs Lisp packages. The Git reference implementation is available in epackage.el. With it, you can install Emacs extensions that have been put available as Git DVCS repositories.
The reference package manager `epackage.el’ is available from the main “project hub” which points to a Git repository. See installation instructions at the end of this page.
To make an Emacs extension available in epackage format, read manual about the directory layout and used files. After that, clone Template files” mentioned below. The Template files link points to README that explains the procedure step-by-step. In Template files repository see
*.shellrc that provides shell functions which helps daily tasks with the packaging work. You must be familiar with Git, somewhat in Emacs Lisp. In Windows, you need <http://cygwin.com> and its command line Bash shell.
Emacs has been around for decades now. Many new version have come and gone. And yet there are wealth of useful extensions available e.g. at <http://emacswiki.org> that add new features not yet available in standard Emacs. The typical procedure to add a new extension to Emacs has been:
That’s quite a bit of work for each extension; reaching thousands out there. Many Linux distributions offer package managers to download and install programs. E.g. Debian has command apt-get/aptitude Redhat uses rpm and Suse uses yast. See also YUM. So why not make one for Emacs as well.
The epackages are in the form of distributed Git version control repositories. The traditional packaging methods, like ELPA, rely on archives like
*.tar.gz. In contrast, the DVCS approach offers interesting features over the traditional archive distribution approach:
In the picture above, the user downloads Sources List yellow pages that contains information about available packages. At upper right: when a prospective developer wants to make an epackage available for others, he first forks the current Sources List (yellow pages), adds new information to it and sends a pull request inside Github.com to ask to merge changes back to the master. The epackage maintainer keeps an eye on new upstream releases and provides new epackages by updating his publicly available Git repository. To the lower right: it is possible that upstream and the epackage maintainer is the same person. This is the ideal situation.
Each Emacs extension is wrapped into epackage format which basically follows the Debian packaging style where a separate control directory named
epackage/ is used for all the packaging details: activation, autoloads and installation etc. In addition, each epackage is imported in and deployed using Git Distributed Version Control System (DVCS). A specific Sources List file lists the available Git repositories where user can download packages. Once an epackage has been downloaded, subsequent downloads are very efficient because only deltas are transferred.
The reference implementation is available at Github. Mirror at Savannah:
# Location where you keep your Emacs extensions mkdir -p $HOME/emacs.d/packages cd $HOME/emacs.d/packages
# Or use mirror: git://git.savannah.nongnu.org/emacs-epackage.git git clone git://github.com/jaalto/project--emacs-epackage.git epackage
cd epackage git checkout --track -b devel origin/devel
# to get new updates from time to time git pull
Add following to your `~/.emacs’ startup InitFile:
;; One big file to boot all installed epackages ;; Automatically generated. Do not edit. (load "~/.emacs.d/epackage/00conf/epackage-loader" 'noerr)
;; M-x epackage-manager to start UI (autoload 'epackage-manager "epackage" "" t)
The epackage manager can also be called from command line UI:
# Start command line UI cd epacakge make ui
# Or if you want to make a shell alias or function, the command needed is emacs --batch --quick --load ~/.emacs.d/packages/epackage/epackage.el --funcall epackage-batch-ui-menu
The big question probably is: “What’s different to ELPA? Where do we need Epackages when Emacs 24 and later already comes with ELPA built-in?” Lots. The DVCS approach is completely different and changes the scene dramatically. The ELPA is based on old design (centralized, need for server and administration). In contrast, the DVCS is the future in both the concept (distributed) and the use of tools (version control).
For the user
‘load-path’support added. You still have to manually configure each and every ELPA package by adding the necessary lines to `~/.emacs’ InitFile.
For the developer
*.tar.gz, no more ensuring that README and NEWS files are up to date, no more mistakenly packaging wrong release, wrong files, missed to generate up-to-date docs etc. Just concentrate on doing what you do best: programming and improving your Emacs Lisp utility. Forget extra administrative tasks required in traditional release processes: Git tag your releases with `release/N.N.N’ and your are done. No distribution hassles: ssh or need for logging to a remote site, updating web pages etc.
*.tar.gzany more. You need to learn Git to distribute your code. Consider learning Git an investment for the future.
How does it all work? Let’s say, we’ve found
example.el which seem quite useful. Note that in this example all the proper comment headers, licensing information, provide calls etc. have been omitted for brevity:
;; example.el -- Major mode for editing example files ;;;###autoload (defun example-mode (&optional mdoe) (interactive "P") (message "example-mode in use")) ;;; example.el end here
To prepare the Emacs Lisp extension into epackage format, we drop into shell. We have already two development directories cloned which provide e.g. shell utilities. See heading For Package Developers for development files. The steps are:
# This example is for the Bash shell # Prepare and use utilities from 2 cloned Git repositories export EPACKAGE_ROOT=~/git/project--emacs-epackage . ~/git/project--emacs-epackage-template/epackage.shellrc # See short help; what commands you can use Ehelp Provides following user commands. The rest are just internal helpers. Use --help for each command for more detailed information. Egit [URL] Import current src, from URL, or emacswiki:FILE.el Ever [file.el ...] Display version and deps information from all, or given files Edir <PACKAGE NAME> FILE From FILE determine and create epackage/ template files Edef [dir] Update loaddefs in epackage/ directory Elint file.el ... Lint files to find QA violations Ecomp file.el ... Byte compile Emacs Lisp files (QA check) Eclone GITURL Clone an existing epackage and set up branches (dev only) # Start packaging cd ~my/elisp/package/example/ # Inject extension into Git branch "upstream" Egit # Tag this realease git tar upstream/YYYY-MM-DD # Change to standard branch which will hold the "epacakage" git branch master upstream # Install templates and epackage/ directory structure Edir example-mode # Fill in package details $EDITOR epacakge/info
That was it in a nutshell. What’s left to do is to check the generated files, adjust or delete them as needed. E.g. we don’t need for this simple extension files like *-compile, *-examples, *-uninstall and we can simply delete them. We have to fill in the important info file that defines details of the package. After all chnages, we commit to Git, make this new epackage available (push to Github) and annouce its availability in epackage yellow pages; amongst other packages.
The directory structure is as follows. For a complete example with all the details, see heading For Package Developers.
example.el | +- epacakge/ example-epackage-0loaddefs.el example-epackage-autoloads.el example-epackage-compile.el example-epackage-examples.el example-epackage-install.el example-epackage-uninstall.el info
Please send comments, suggestion, ideas, bug reports to me directly or to the bug tracker. Please do not add questions to this page as this page is not monitored. Thanks --Jari
‘epackage-manager’available, just the “bare bones”.
CategoryPackaging epackage bare bones Template files