melpa/README.md

# MELPA

Repository of code for *MELPA* or *Milkypostman's ELPA* or *Milkypostman's Experimental Lisp Package Repository* 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 `pkglist` file.  By default this will build all packages listed in `pkglist`,
compile the `index.html` file for the [melpa] website front page, and
sync with the site.

    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.

[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.


## Package List

`pkglist` contains a list of all the currently known packages. Entries
are lisp data of the form,

    (name :url "<repo url>" 
     :fetcher [git|svn|darcs] 
     [:files ("<file1>", ...)])
    
The `:files` entry is optional but is required for either single-file
packages or repositories which contain more than one package and
individual packages should be extracted. For example, 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.
The entry for *starter-kit* is,

    (starter-kit
     :url "git://github.com/technomancy/emacs-starter-kit.git"
     :fetcher git
     :files ("starter-kit-defuns.el"
             "starter-kit-misc.el"
             "starter-kit.el"))
             
Here the required elisp files are specified. All other information is
generated by the `package-build.el` script. This include the
*description*, *version*, and *requires*. In single-file packages the
metadata is parsed from the file itself just as `package.el` does. For
packages containing multiple files, metadata will be searched for in
`name-pkg.el`, `name.el`, and `name-pkg.el.in`. If the information
cannot be found the metadata is generated with *requires* set to
`nil`.


## Adding Packages

Open an issue on Github and either paste in the relevant entry for
`pkglist` or add a bunch and send a pull request.


## Developement

Fork away!  Send me some pull requests.


### Notes

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.