package-build

https://github.com/milkypostman/melpa.git

git clone 'git://github.com/milkypostman/melpa.git'
676

MELPA

Build Status

MELPA is a growing collection of package.el-compatible Emacs Lisp packages built automatically on our server from the upstream source code using simple recipes. (Think of it as a server-side version of el-get, or even homebrew.)

Packages are updated at intervals throughout the day.

To browse available packages, check out the archive index page.

Adding packages is as simple as submitting a pull request; read on for details.

Table of Contents

Usage

To use the MELPA repository, you'll need an Emacs with package.el. Emacs 24 has package.el bundled with it, and there's also a version you can use with Emacs 23.

Enable installation of packages from MELPA by adding an entry to package-archives after (require 'package) and before the call to package-initialize in your init.el or .emacs file:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)
(when (< emacs-major-version 24)
  ;; For important compatibility libraries like cl-lib
  (add-to-list 'package-archives '("gnu" . "http://elpa.gnu.org/packages/")))
(package-initialize)

Then just use M-x package-list-packages to browse and install packages from MELPA and elsewhere.

Note that MELPA packages will always have higher versions than those from other archives like Marmalade, so if you decide you need non-MELPA versions of specific packages for some reason, extra configuration will be required:

If your Emacs has the variable package-pinned-packages, you can customize or modify that variable as needed. Otherwise, use the separate package-filter.el package which we provide.

Contributing New Recipes

New recipe submissions should adhere to the following guidelines,

Expediting Recipe Reviews

Because we care about the quality of packages that are part of MELPA we review all submissions. The following steps can help us with this process and expedite the recipe review process,

Testing

Let <NAME> denote the name of the recipe to submit.

  1. Fork the MELPA repository.

  2. Add your new file under the directory specified by package-build-recipes-dir (default: recipes/ directory where package-build was loaded). If you prefer, the interactive command package-build-create-recipe in package-build.el will guide you through this process.

  3. Confirm your package builds properly by running

    make recipes/<NAME>
    

(Be sure that the emacs on your path is at least version 23, or set $EMACS_COMMAND to the location of a suitable binary.)

Alternatively, open the recipe in Emacs and press C-c C-c in the recipe buffer: this will also prompt you to install the freshly-built package.

  1. Install the file you built by running package-install-file from within Emacs and specifying the newly built package in the directory specified by package-build-archive-dir (default: packages/ directory where package-build was loaded).

You can optionally run a sandboxed Emacs in which locally-built packages will be available for installation along with those already in MELPA:

EMACS=/path/to/emacs make sandbox

then M-x package-list-packages, install and test as appropriate. This is a useful way to discover missing dependencies!

Submitting

After verifying the entry works properly please open a pull request on Github. Consider the hub command-line utility by defunkt which helps simplify this process.

Recipe Format

Packages are specified by files in the recipes directory. You can contribute a new package by adding a new file under recipes using the following form ([...] denotes optional or conditional values),

(<package-name>
 :fetcher [git|github|gitlab|bzr|hg|darcs|fossil|svn|cvs|wiki]
 [:url "<repo url>"]
 [:repo "github-or-gitlab-user/repo-name"]
 [:module "cvs-module"]
 [:files ("<file1>" ...)])

Example: Single File Repository

smex is a repository that contains two files:

Since there is only one .el file, this package only needs the :url and :fetcher specified,

(smex :repo "nonsequitur/smex" :fetcher github)

Example: Multiple Packages in one Repository

The emacs-starter-kit contains the starter-kit package along with extra packages in the modules directory; starter-kit-bindings, starter-kit-lisp, etc.

(starter-kit
 :url "https://github.com/technomancy/emacs-starter-kit.git"
 :fetcher git)
(starter-kit-bindings
 :url "https://github.com/technomancy/emacs-starter-kit.git"
 :fetcher git
 :files ("modules/starter-kit-bindings.el"))

Notice that :files is not specified for starter-kit since package-build will automatically add all .el files in the root directory of the repository. The starter-kit-bindings repository is contained in the modules/ subdirectory and thus needs the packages files specified explicitly.

Example: Multiple Files in Multiple Directories

There are special cases where creation of the package comes from many different sub-directories in the repository and the destination sub-directories need to be explicitly set.

Consider the flymake-perlcritic recipe,

(flymake-perlcritic :repo "illusori/emacs-flymake-perlcritic"
                    :fetcher github
                    :files ("*.el" ("bin" "bin/flymake_perlcritic")))

which will result in a package structure of,

flymake-perlcritic-YYYMMDD
|-- bin
|   `-- flymake_perlcritic
|-- flymake-perlcritic-pkg.el
`-- flymake-perlcritic.el

Notice that specifying an entry in :files that is a list takes the first element to be the destination directory. These can be embedded further, such as the following—hypothetical—entry for :files,

("*.el" ("snippets"
         ("html-mode" "snippets/html-mode/*")
         ("python-mode" "snippets/python-mode/*")))

which would result in a package with *.el in something like,

package-YYYYMMDD
|-- snippets
|   |-- html-mode
|   |   |-- div
|   |   `-- html
|   `-- python-mode
|       |-- for
|       `-- main
`-- package.el

But a better solution, given that we probably want to copy the entire snippets directory to the root of the package, we could just specify that directory. Consider the pony-mode recipe,

(pony-mode
 :repo "davidmiller/pony-mode"
 :fetcher github
 :files ("src/*.el" "snippets"))

which generates the package,

pony-mode-YYYYMMDD
|-- pony-mode-pkg.el
|-- pony-mode.el
|-- pony-tpl.el
`-- snippets
    |-- html-mode
    |   |-- bl
    |   |-- ex
    |   |-- for
    |   |-- if
    |   |-- loa
    |   |-- sup
    |   |-- testc
    |   `-- {{
    `-- python-mode
        |-- auth-view
        |-- bn
        |-- model
        |-- modelform
        |-- render-to
        |-- testc
        `-- view

Build Scripts

Building MELPA is all based around using the Makefile included in the root repository directory. Described below are the actions that accepted by the Makefile.

Note that these scripts require an Emacs with package.el installed, such as Emacs 24. If you have an older version of Emacs, you can get a suitable package.el here.

API

All repository code is contained in the package-build.el.

Functions

Variables

Configuration

Packages end up in the packages/ directory by default. This can be configured using the package-build-archive-dir variable.

Repositories are checked out to the working/ directory by default. This can be configured using the package-build-working-dir variable.

About

MELPA is Milkypostman's ELPA or Milkypostman's Experimental Lisp Package Archive if you're not into the whole brevity thing.

Stable Packages

MELPA now includes a mechanism to build stable versions of packages given that the repositories meet the following criteria,

  1. Hosted using git or hg.
  2. Tag names are version strings compatible parseable by the version-to-list function, optionally prefixed with v, v. or v-.

To use the stable versions of packages you should use the stable server in your package-archives list.

(add-to-list 'package-archives
             '("melpa-stable" . "http://stable.melpa.org/packages/"))

An online list of available packages can be found at http://stable.melpa.org.

Stable Version Generation

To have a stable version generated for your package simply tag the repository using a naming compatible with version-to-list, optionally prefixed with v, v. or v-. The repo state of this tag will be used to generate the stable package.

Notes

Versions for packages on the original MELPA server are based on the date of the last commit and will likely be higher than any version on the stable server. Keep the following things in mind,