github/melpa
1
0
Fork 0
mirror of https://github.com/correl/melpa.git synced 2024-11-15 03:00:14 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #54 from bbatsov/master

Browse source 
Updated README for bzr and hg fetcher support
This commit is contained in:
Donald Ephraim Curtis 2012-04-11 07:52:36 -07:00
commit ba8f1f4afa
1 changed files with 72 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
README.md
View file

@ -1,6 +1,6 @@
# MELPA
MELPA is a growing collection of `package.el`-compatible elisp
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
@ -33,19 +33,21 @@ build all packages
listed under `recipes/`, and compile the `index.html` file for the [melpa]
website front page.
The following arguments are accepted,
The following arguments are accepted:
clear
: clean out the `packages/` directory
```
clear
: clean out the `packages/` directory
build
: build all packages in `pkglist`
build
: build all packages in `pkglist`
index
: build the `index.html` file
index
: build the `index.html` file
validate
: naively validate that the correct number of packages were built.
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
@ -53,7 +55,6 @@ 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
@ -72,31 +73,55 @@ generating the file `<NAME>-pkg.el` which contains *description*,
`<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,
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,
(name
:fetcher [git|github|svn|darcs|wiki]
[:url "<repo url>"]
[:repo "github-user/repo-name"]
[:files ("<file1>", ...)])
```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.
: 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`, `svn` and `darcs` fetchers*
: 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], [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.
: 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.
: 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/
@ -111,10 +136,11 @@ Packages are specified by files in the `recipes` directory. You can contribute
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)
```elisp
(ido-ubiquitous
:url "https://github.com/DarwinAwardWinner/ido-ubiquitous.git"
:fetcher git)
```
### Multiple Packages in one Repository
@ -123,28 +149,35 @@ The
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.
```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.
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.