mirror of
https://github.com/correl/melpa.git
synced 2024-12-26 03:00:11 +00:00
183 lines
6.2 KiB
Markdown
183 lines
6.2 KiB
Markdown
# 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](https://github.com/dimitri/el-get), or even
|
|
[homebrew](https://github.com/mxcl/homebrew).)
|
|
|
|
Packages are updated when changes are made to the MELPA repository,
|
|
or at least daily.
|
|
|
|
If you just want to browse and install packages, check out the
|
|
[archive index page](http://melpa.milkbox.net/) for instructions.
|
|
|
|
Adding packages is as simple as submitting a pull request; read on for
|
|
details.
|
|
|
|
### About the name
|
|
|
|
*MELPA* is *Milkypostman's ELPA* or *Milkypostman's Experimental Lisp
|
|
Package Archive* if you're not into the whole brevity thing.
|
|
|
|
## Scripts
|
|
|
|
* `buildpkg` -- Create an archive of the package(s) passed as
|
|
arguments to the script. Built packages are put in the `packages/`
|
|
folder with version corresponding to the newest HEAD revision
|
|
available; given according to the `%Y%m%d` format.
|
|
|
|
* `melpa` -- All the logic for generating everything in the repository
|
|
based on the recipe files. By default this will clean the `packages/` directory,
|
|
build all packages
|
|
listed under `recipes/`, and compile the `index.html` file for the [melpa]
|
|
website front page.
|
|
|
|
The following arguments are accepted:
|
|
|
|
clear
|
|
: clean out the `packages/` directory
|
|
|
|
build
|
|
: build all packages in `pkglist`
|
|
|
|
index
|
|
: build the `index.html` file
|
|
|
|
validate
|
|
: naively validate that the correct number of packages were built.
|
|
|
|
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](http://bit.ly/pkg-el23).
|
|
|
|
[melpa]: http://melpa.milkbox.net
|
|
|
|
## Code
|
|
|
|
The `package-build.el` file contains all the heavy lifting. The
|
|
scripts above call the `package-build-archive` function from the
|
|
command-line to actually build the package(s).
|
|
|
|
Use `(package-build-all)` to build all melpa packages.
|
|
|
|
Alternatively you can
|
|
load this file from within Emacs and issues commands from there.
|
|
|
|
The `package-build.el` automatically generates any required
|
|
information for the package. For multi-file packages this include
|
|
generating the file `<NAME>-pkg.el` which 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.
|
|
|
|
## Contributing New Packages
|
|
|
|
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,
|
|
|
|
```elisp
|
|
(name
|
|
:fetcher [git|github|bzr|hg|darcs|svn|wiki]
|
|
[:url "<repo url>"]
|
|
[:repo "github-user/repo-name"]
|
|
[:files ("<file1>", ...)])
|
|
```
|
|
|
|
`name`
|
|
: a lisp symbol that has the same name as the package being specified.
|
|
|
|
`:url`
|
|
: specifies the URL of the version control repository. *required for
|
|
the `git`, `bzr`, `hg`, `darcs` and `svn` fetchers*
|
|
|
|
`:fetcher`
|
|
: specifies the type of repository that `:url` points to. Right now
|
|
package-build supports [git][git], [github][github],
|
|
[bazaar (bzr)][bzr], [mercurial (hg)][hg],
|
|
[subversion (svn)][svn], [darcs][darcs], and
|
|
[Emacs Wiki (wiki)][emacswiki] as possible mechanisms for checking out
|
|
the repository. With the exception of the Emacs Wiki fetcher,
|
|
package-build uses the corresponding application to update files
|
|
before building the package. The Emacs Wiki fetcher gets the latest
|
|
version of the package from
|
|
`http://www.emacswiki.org/emacs/download/<NAME>.el` where `NAME` is
|
|
the package name. Note that the `:url` property is not needed for the
|
|
`wiki` engine unless the name of the package file on the EmacsWiki
|
|
differs from the package name being built. In the case of the `github`
|
|
fetcher, use `:repo` instead of `:url`; the git URL will then be
|
|
deduced.
|
|
|
|
`:files`
|
|
: optional property specifying the explicit files used to build the
|
|
package. Automatically populated by matching all `.el` files in the
|
|
root of the repository. This is necessary when there are multiple
|
|
`.el` files in the repository but the package should only be built
|
|
from a subset.
|
|
|
|
[git]: http://git-scm.com/
|
|
[github]: https://github.com/
|
|
[bzr]: http://bazaar.canonical.com/en/
|
|
[hg]: http://mercurial.selenic.com/
|
|
[svn]: http://subversion.apache.org/
|
|
[darcs]: http://darcs.net/
|
|
[emacswiki]: http://www.emacswiki.org/
|
|
|
|
|
|
### Single File Repository
|
|
|
|
[ido-ubiquitous](https://github.com/DarwinAwardWinner/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,
|
|
|
|
```elisp
|
|
(ido-ubiquitous
|
|
:url "https://github.com/DarwinAwardWinner/ido-ubiquitous.git"
|
|
:fetcher git)
|
|
```
|
|
|
|
### Multiple Packages in one Repository
|
|
|
|
The
|
|
[emacs-starter-kit](https://github.com/technomancy/emacs-starter-kit)
|
|
contains the *starter-kit* package along with extra packages in the
|
|
`modules` directory; *starter-kit-bindings*, *starter-kit-lisp*, etc.
|
|
|
|
```elisp
|
|
(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.
|
|
|
|
### Submitting the Package
|
|
|
|
You should first fork the MELPA repository, add your new file under
|
|
`recipes`, and confirm your new package builds properly by running
|
|
`buildpkg <NAME>`. You can install the package that you built by
|
|
running the interactive command `package-install-file` in Emacs, and
|
|
specifying the newly built package which should be in the `packages/`
|
|
subdirectory under the melpa directory.
|
|
|
|
After verifying the entry works properly please open a pull request on Github.
|
|
|
|
## 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.
|