https://github.com/10sr/github-elpa
Build and Publish Your Own ELPA Repositories with GitHub Pages
https://github.com/10sr/github-elpa
elpa elpa-repositories github github-page
Last synced: 6 months ago
JSON representation
Build and Publish Your Own ELPA Repositories with GitHub Pages
- Host: GitHub
- URL: https://github.com/10sr/github-elpa
- Owner: 10sr
- License: unlicense
- Created: 2016-09-02T04:46:12.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2025-02-21T04:35:34.000Z (8 months ago)
- Last Synced: 2025-03-27T13:01:53.631Z (7 months ago)
- Topics: elpa, elpa-repositories, github, github-page
- Language: Emacs Lisp
- Homepage: https://10sr.github.io/github-elpa
- Size: 230 KB
- Stars: 31
- Watchers: 5
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](http://melpa.org/#/github-elpa)
[](http://stable.melpa.org/#/github-elpa)
[](https://jcs-emacs.github.io/jcs-elpa/#/github-elpa)
github-elpa
===========
Build and publish your own ELPA repositories with GitHub Pages
Overview
--------
`github-elpa` is an Emacs command-line utility to build your own
`package.el`-compatible package repository in your git repository.
By default this repository will be built into `docs/elpa` directory,
so by just pushing it to GitHub you can publish the repository with
GitHub Pages.
Setting up a repository and updating packages are really easy.
Once you add a [`Cask`][Cask]/[`Eask`][Eask] file and package
recipes in
[MELPA's format](https://github.com/melpa/melpa#recipe-format),
issue just one simple command to update the ELPA repository.
Quick Start
-----------
This section describes how to setup your ELPA repository in your
GitHub repository.
### 0. Prerequisite
* A GitHub account, and a GitHub respository that you have a
write-permission and can change `Settings`
* [Cask][] or [Eask][]
### 1. Prepare Cask/Eask File
Put `Cask` file to the root of the GitHub repository. Typically it
should look like:
```elisp
(source gnu)
(source melpa)
(depends-on "github-elpa")
```
Or `Eask` file,
```elisp
(source 'gnu)
(source 'melpa)
(depends-on "github-elpa")
```
#### [RECOMMENDED] Use Eask to generate the ELPA project
Execute the following command to generate the ELPA project.
```sh
eask create elpa
```
### 2. Add Recipes and Build Archives
Add recipe files in
[MELPA's format](https://github.com/melpa/melpa#recipe-format).
By default `github-elpa` looks for `recipes/` directory, but you can
change this via `-r` command-line option (see below).
Once you put your recipe files, it is time to build your repository!
Issue following commands:
```sh
cask install # Need only once
cask exec github-elpa update
git push
```
The second command will fetch packages described in `recipes/`, build
archives into `docs/elpa`, and git-commit them.
In Eask:
```sh
eask install-deps # Need only once
eask exec github-elpa update
git push
```
### 3. Change Repository Setting
After you push `docs/` directory, you need to change the GitHub
repository setting.
This setting is needed so that the ELPA repository can be
accessed as a GitHub Pages.
1. Go `Settings` page of your GitHub repository
2. In `GitHub Pages`, change `Source` to `master branch /docs folder`
and `Save` it
Now it's all done!
Use and Maintainance
--------------------
### Add to Your Repository List
The published ELPA repository URL is
`https://.github.io//elpa/`.
For example, to use the repository of `github-elpa` itself, add
following to your `init.el`:
```elisp
(add-to-list 'package-archives '("github-elpa" . "https://10sr.github.io/github-elpa/elpa/"))
```
### Update Repository
When package upstreams are updated, you can receive the changes
in the same way as first building the repository:
```sh
cask exec github-elpa update
git push
```
In Eask:
```sh
eask exec github-elpa update
git push
```
Command-Line Arguments
----------------------
### Sub-Commands
github-elpa update
If you just want to do "all", issue `update`.
Actually this is just a combination of the following `build` and
`commit` subcommands.
github-elpa build
Issue `build` to only update packages without committing them.
This command reads recipes in `recipes/` (or the directory specified
by `-r` optiion), fetches packages and builds them by recipes.
In short, this command is just a thin wrapper around
`package-build.el`.
github-elpa commit
`commit` subcommand commit packages to git repository.
This command will git-commit files in `docs/elpa/` (or the directory
given by `-a`), and do not commit any other files.
### Options
| Option | Default | Description |
| --------------------------------- | ---------------------- | ----------- |
| `-r, --recipes-dir ` | `recipes` | Specify directory that contains recipe files |
| `-a, --archive-dir ` | `docs/elpa` | Specify directory in which to keep compiled archives |
| `-w, --working-dir ` | `.github-elpa-working` | Specify directory in which to keep checkouts |
| `-t, --tar ` | (Use value from `package-build.el`) | Specify tar executable name to archive files |
License
-------
This software is unlicensed. See `LICENSE` for details.
[Cask]: https://github.com/cask/cask
[Eask]: https://github.com/emacs-eask/cli