a9222d9225
This reverts commit
|
||
---|---|---|
cfg | ||
features | ||
html | ||
packages | ||
recipes | ||
resources | ||
scripts | ||
service | ||
working | ||
.gitignore | ||
.travis.yml | ||
Cask | ||
LICENSE.md | ||
Makefile | ||
migrate | ||
package-build.el | ||
README.md | ||
run-travis-ci.sh |
MELPA
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,
-
One pull request per recipe. You can create multiple branches and create a pull request for each branch.
-
Upstream source must be stored in an authoritative SCM repository. Emacswiki recipes are discouraged but can be accepted.
-
Packages should be built from the official package repository. Forks of the official repository will not be accepted except in extreme circumstances.
-
The package name should match the name of the feature provided. See the
package
function for more information. -
Packages should adhere to the
package.el
format as specified by(info "(elisp) Packaging")
. More information on this format is provided by the marmalade package manual. -
Recipes should try to minimize the size of the resulting package by specifying only files relevant to the package. See the Recipe Format section for more information on specifying package files.
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,
-
Use flycheck-package to help you identify common errors in your package metadata.
-
Include the following information in the pull request:
-
A brief summary of what the package does.
-
A direct link to the package repository.
-
Your association with the package (e.g., are you the maintainer? have you contributed? do you just like the package a lot?).
-
Relevant communications with the upstream package maintainer (e.g.,
package.el
compatibility changes that you have submitted).
-
-
Test that the package builds properly via
make recipes/<recipe>
, or pressingC-c C-c
in the recipe buffer. -
Test that the package installs properly via
package-install-file
, or entering "yes" when prompted after pressingC-c C-c
in the recipe buffer. -
If you are not the original author or maintainer of the package you are submitting, please consider notifying the author prior to submitting and make reasonable effort to include them in the pull request process.
Testing
Let <NAME>
denote the name of the recipe to submit.
-
Fork the MELPA repository.
-
Add your new file under the directory specified by
package-build-recipes-dir
(default:recipes/
directory wherepackage-build
was loaded). If you prefer, the interactive commandpackage-build-create-recipe
inpackage-build.el
will guide you through this process. -
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.
- Install the file you built by running
package-install-file
from within Emacs and specifying the newly built package in the directory specified bypackage-build-archive-dir
(default:packages/
directory wherepackage-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|bzr|hg|darcs|fossil|svn|cvs|wiki]
[:url "<repo url>"]
[:repo "github-user/repo-name"]
[:module "cvs-module"]
[:files ("<file1>" ...)])
-
package-name
a lisp symbol that has the same name as the package being specified. -
:fetcher
(one ofgit, github, bzr, hg, darcs, fossil, svn, cvs, wiki
) specifies the type of repository that:url
points to. Right now package-build supports git, github, bazaar (bzr), mercurial (hg), subversion (svn), cvs, darcs, fossil, and Emacs Wiki (wiki) as possible mechanisms for checking out the repository.package-build uses the corresponding application to update files before building the package. In the case of the
github
fetcher, use:repo
instead of:url
; the git URL will then be deduced.The Emacs Wiki fetcher gets the latest version of the package from
http://www.emacswiki.org/emacs/download/<NAME>.el
whereNAME
is the package name. Note that the:url
property is not needed for thewiki
engine unless the name of the package file on the EmacsWiki differs from the package name being built. -
:url
specifies the URL of the version control repository. required for thegit
,bzr
,hg
,darcs
,fossil
,svn
andcvs
fetchers. -
:repo
specifies the github repository and is of the formgithub-user/repo-name
. required for thegithub
fetcher. -
:commit
specifies the commit of the git repo to checkout. The value will be passed togit reset
in a repo whereupstream
is the original repository. Can therefore be either a sha, if pointing at a specific commit, or a full ref prefixed with "origin/". Only used by thegit
andgithub
fetchers. -
:branch
specifies the branch of the git repo to use. This is like:commit
, but it adds the "origin/" prefix automatically. -
:module
specifies the module of a CVS repository to check out. Defaults to topackage-name
. Only used with:fetcher cvs
, and otherwise ignored. -
:files
optional property specifying the elisp and info files used to build the package. Automatically populated by matching all.el
,.info
anddir
files in the root of the repository and thedoc
directory. Excludes all files in the root directory ending intest.el
ortests.el
. See the default value below,("*.el" "*.el.in" "dir" "*.info" "*.texi" "*.texinfo" "doc/dir" "doc/*.info" "doc/*.texi" "doc/*.texinfo" (:exclude ".dir-locals.el" "test.el" "tests.el" "*-test.el" "*-tests.el"))
This option is necessary when there are multiple packages in the repository and thus the package should only be built from a subset of
.el
files. For example, elisp test files should not normally be packaged. Any file specified at any path in the repository is copied to the root of the package. More complex options are available, submit an Issue if the specified package requires more complex file specification.If the the package merely requires some additional files, for example for bundling external dependencies, but is otherwise fine with the defaults, it's recommended to use
:defaults
as the very first element of this list, which causes the default value shown above to be prepended to the specified file list.
Example: Single File Repository
ido-ubiquitous is a repository that contains two files:
README.md
ido-ubiquitous.el
Since there is only one .el
file, this package only needs the :url
and :fetcher
specified,
(ido-ubiquitous
:url "https://github.com/DarwinAwardWinner/ido-ubiquitous.git"
:fetcher git)
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
.
-
all
-- Builds all packages under therecipes/
directory and compiles theindex.html
file for the melpa website. -
recipes/<NAME>
-- Build individual recipe<NAME>
. Built packages are put in thepackages/
folder with version corresponding to the newest HEAD revision available; given according to the%Y%m%d
format. -
json
-- build all JSON files. -
archive.json
-- construct thearchive.json
file that will contain a JSON object of all compiled packages. -
recipes.json
-- construct therecipes.json
file containing a JSON object of all packages available for building. -
clean
-- clean everything. -
html
-- buildindex.html
. -
clean-working
-- remove all repositories that have been checked out to theworking/
directory. -
clean-packages
-- remove all compiled packages from thepackages
directory. -
clean-json
-- remove all JSON files.
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
-
(package-build-all)
: build packages for all recipes in the directory specified bypackage-build-recipes-dir
. -
(package-build-archive NAME)
: interactive elisp function to build a single archive. NAME is a symbol for the package to be built. Packages are staged in the directory specified bypackage-build-working-dir
and built packages are placed in the directory specified bypackage-build-archive-dir
. Packages are versioned based on the most recent commit date to package files based on commits to upstream package repository. For multi-file packages, the file<NAME>-pkg.el
is automatically generated and contains description, version, and requires information determined by searching<NAME>-pkg.el
,<NAME>.el
, and<NAME>-pkg.el.in
, if they exist in the repository.
Variables
-
package-build-working-dir
: Staging area containing package repositories and package directories being built. -
package-build-archive-dir
: Location to storearchive-contents
and any built packages. -
package-build-recipes-dir
: Directory containing MELPA compatible recipes. See Recipe Format section for more details.
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,
- Hosted using git or hg.
- Tag names are version strings compatible parseable by the
version-to-list
function, optionally prefixed withv
,v.
orv-
.
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/") t)
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,
-
If you leave the original MELPA server in your
package-archives
then by default you will get the development versions of packages and not the stable ones. -
You will probably want to remove all packages and then reinstall them. Any packages you already have installed from MELPA will never get "updated" to the stable version because of the way version numbering is handled.