MakingPackages

ELPA packages come in two forms. The first is a relatively simple single file package, the second is a more complicated multi-file format. Most of this page discusses the multi-file format because it causes the most problems.

Singlefile packages

These are very simple, they just follow a standard markup. This is almost exactly as you would get with AutoInsertMode:

;;; test.el --- a simple package                     -*- lexical-binding: t; -*-

;; Copyright (C) 2014  Nic Ferrier

;; Author: Nic Ferrier <nferrier@ferrier.me.uk>
;; Keywords: lisp
;; Version: 0.0.1

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; Put a description of the package here

;;; Code:

;; code goes here

(provide 'test)
;;; test.el ends here

Things that people tend to forget or not notice about this:

One more note, the LexicalBinding declaration is optional. Although these days you should consider it a default.

Multifile packages

ELPA multifile packages have a complex structure. They are not simple tar archives. This page attempts to describe how to make them.

When do you need to build a multifile package?

MELPA builds packages for you, with it’s own build system. You don’t build packages with MELPA.

ELPA requires you to have the directory sturcture here checked into the ELPA git repository. You don’t build the actual tar file.

Marmalade requires that you submit the actual tar file of your built package.

Emacs requires that you build tar file packages if you want to install them from the file system with:

M-x package-install-file

for example.

An example package

Let’s imagine you have a package `alchemist`, basically you need to create a directory that looks like this:

alchemist-0.0.2/alchemist-buffer.el
alchemist-0.0.2/alchemist-compile.el
alchemist-0.0.2/alchemist-execute.el
alchemist-0.0.2/alchemist-hooks.el
alchemist-0.0.2/alchemist-mix.el
alchemist-0.0.2/alchemist-utils.el
alchemist-0.0.2/alchemist.el
alchemist-0.0.2/alchemist-pkg.el

and then tar that.

The pkg file, `alchemist-pkg.el`, must look like this:

(define-package
    "alchemist"
    "0.0.2"
  "A package to help with alchemy.")

In other words: package name, version, summary. All strings.

Marmalade has a demo multifile package with a Makefile that shows how you can build a package with simple unix tools, do it but also tools like Cask and ELPAKit will help you build packages as well.

Advantages and Disadvantages of manually building packages

NicFerrier says that the requirement of Marmalade to take a package tar file is a feature:

Some things, like MELPA just build the packages for you. I don’t like that on principle because then you can’t actually test what you’re building. There are certain things about packages that are good to test yourself (especially after you have a user base already using your package - you want to just release a broken one?). The best way of doing that is to make the package yourself.
NicFerrier

Cask

You can use cask package and it does the right thing:

Then you can install or upload somewhere.

ELPAKit

ELPAKit does the right thing too. With no python:

M-x elpakit-make-multi

in the package directory of a multi-file package.

Marmalade peculiarities

MarmaladeRepo has some odd stuff about how it displays commentary about a package. Commentary isn’t normally part of multi-file packages, but is there a way to add more information which will be shown in the about part on the marmalade website.

What Marmalade does to try to find commentary for a package is to try to present any README it can find. If you add a plain text README it will get displayed.

In fact Marmalade will display *any* README it finds

I could add more logic to this if you think there are better ways to find package description. One thing that springs to mind is: