diff options
author | Jauhien Piatlicki (jauhien) <piatlicki@gmail.com> | 2013-08-05 02:40:05 +0200 |
---|---|---|
committer | Jauhien Piatlicki (jauhien) <piatlicki@gmail.com> | 2013-08-05 02:40:05 +0200 |
commit | 41ff4993d01f5e0daf7cc690c0c9d8b27660e74c (patch) | |
tree | 9862641b567a547af85e92d51acb3055bad4b331 | |
parent | metadata/layout.conf support added (diff) | |
download | gs-elpa-41ff4993d01f5e0daf7cc690c0c9d8b27660e74c.tar.gz gs-elpa-41ff4993d01f5e0daf7cc690c0c9d8b27660e74c.tar.bz2 gs-elpa-41ff4993d01f5e0daf7cc690c0c9d8b27660e74c.zip |
User documentation added
-rw-r--r-- | README | 89 | ||||
-rw-r--r-- | docs/Makefile | 9 | ||||
-rw-r--r-- | docs/gs-elpa.8 | 186 | ||||
-rw-r--r-- | docs/gs-elpa.8.rst | 159 |
4 files changed, 425 insertions, 18 deletions
@@ -1,4 +1,5 @@ Objective +========= There is a lot of 3rd party software providers that resemble overlays or repositories of Linux distributions in some way. For example: pypi, @@ -42,26 +43,78 @@ Backend should have everything specific for a given 3rd party software provider: concrete algorithms for ebuild-generation, eclasses, databases with information about available software and so on. -Note that for tests of an ELPA backend you'll need dev-python/sexpdata -available in `jauhien' overlay (just do `layman -a jauhien') +Installation and using +====================== -An ebuild for g-sorcery was added to `jauhien' overlay. At the moment -package is very alpha and unstable. +At the moment upstream layman does not support g-sorcery overlay type. +You should patch it with `https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch`. -sync, list, install and generate-tree commands work. For layman integration -you'll need patch layman from git with layman-git-g-sorcery.patch. +To do it download above mentioned patch, place it in +**/etc/portage/patches/app-portage/layman-9999/** directory and +create a file **/etc/portage/bashrc** that looks like -Testing process: -a) Ebuild generation in a given overlay: - - create an overlay - - run `gs-elpa -o path_to_overlay -r gnu-elpa sync' - - run `gs-elpa -o path_to_overlay list' - - run `gs-elpa -o path_to_overlay install packagename portage_flags' + post_src_prepare() { + epatch_user + } -b) Integration with layman: - - install layman from git patched with `layman-git-g-sorcery.patch' - - run `sudo layman -a gnu-elpa' +Then you can emerge **app-portage/layman-9999**. -CTAN backend works now. So the same command may be used for testing it. -You only should replace gs-elpa with gs-ctan. And use ctan repository, -e.g. sync will look like `gs-ctan -o path_to_overlay -r ctan sync' +Add `jauhien` overlay: **layman -a jauhien**. + +Emerge g-sorcery: **emerge -va g-sorcery**. + +Currently two backends are available: **gs-elpa** and **gs-ctan**. + +Here is an example of using gs-elpa backend. + +There are two ways of using **gs-elpa**: + +* use it with **layman** + +In this case all you need to do is install **layman-9999**, **g-sorcery** +and **gs-elpa**. Then you should just run `layman -L` as +root and find an overlay you want. Type of overlay will be +displayed as *g-sorcery*. Then you add this overlay as +usual. It's all you need to do and it's the recommended way of +using **gs-elpa**. + +* use it as stand-alone tool + +In this case you should create an overlay (see **portage** documentation), sync it and populate +it with one or more ebuilds. Then ebuilds could be installed by emerge or by **gs-elpa** tool. + +**Using gs-elpa with layman** + +Execute + +**layman -L** + +Find there an overlay you need (there are +3 gs-elpa overlays currently: gnu-elpa, marmalade and melpa). +Add, e.g. + +**layman -a gnu-elpa -a marmalade** + +Emerge any package from it, e.g. + +**emerge -va clojure-mode** + +**Generating user ebuilds in user overlay** + +Create new user overlay. Run + +**gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **sync** + +List packages: + +**gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **list** + +Install any package you want: + +**gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **install** *PACKAGE* + +Repositories you can use are gnu-elpa, marmalade and melpa. You can use them +all in one overlay. Note, that if you call **generate-tree** command your overlay +will be wiped and overlay tree for a given repository will be generated. Be careful! + +See man pages of **gs-elpa** and **gs-ctan** for further information. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c42c78d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,9 @@ +SOURCES=g-sorcery gs-elpa gs-ctan +MANS=$(SOURCES:=.8) + +RST2MAN=rst2man.py + +all: ${MANS} + +%.8: %.8.rst + $(RST2MAN) $< $@ diff --git a/docs/gs-elpa.8 b/docs/gs-elpa.8 new file mode 100644 index 0000000..a4fdaba --- /dev/null +++ b/docs/gs-elpa.8 @@ -0,0 +1,186 @@ +.\" Man page generated from reStructuredText. +. +.TH GS-ELPA 8 "2013-08-04" "0.1" "g-sorcery" +.SH NAME +gs-elpa \- manage overlays for ELPA repositories +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBsync\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBlist\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\fP \fIPACKAGE\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBinstall\fP \fIPACKAGE\fP +.sp +\fBgs\-elpa\fP \fB\-o\fP \fIOVERLAY\fP [\fB\-r\fP \fIREPO\fP] \fBgenerate\-tree\fP [\fB\-d\fP] +.SH DESCRIPTION +.sp +\fBgs\-elpa\fP is an ebuild generator for ELPA repositories \-\- repositories with +elisp packages for emacs. +.sp +There are two ways of using \fBgs\-elpa\fP: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +use it with \fBlayman\fP +.sp +In this case all you need to do is install \fBlayman\-9999\fP, \fBg\-sorcery\fP +and \fBgs\-elpa\fP. Then you should just run \fIlayman \-L\fP as +root and find an overlay you want. Type of overlay will be +displayed as \fIg\-sorcery\fP. Then you add this overlay as +usual. It\(aqs all you need to do and it\(aqs the recommended way of +using \fBgs\-elpa\fP. +.IP \(bu 2 +use it as stand\-alone tool +.sp +In this case you should create an overlay (see \fBportage\fP documentation), sync it and populate +it with one or more ebuilds. Then ebuilds could be installed by emerge or by \fBgs\-elpa\fP tool. +.UNINDENT +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-\-overlay\fP \fIOVERLAY\fP, \fB\-o\fP \fIOVERLAY\fP +Overlay directory. This option is mandatory if there is no +\fBdefault_overlay\fP entry in a backend config. +.TP +.B \fB\-\-repository\fP \fIREPO\fP, \fB\-r\fP \fIREPO\fP +Repository name. Can be one of \fBgnu\-elpa\fP, \fBmarmalade\fP, \fBmelpa\fP. +.UNINDENT +.SH COMMANDS +.INDENT 0.0 +.TP +.B \fBsync\fP +Synchronize a repository database. +.TP +.B \fBlist\fP +List packages available in a repository. +.TP +.B \fBgenerate\fP +Generate a given ebuild and all its dependencies. +.TP +.B \fBinstall\fP +Generate and install an ebuild using your package mangler. +.TP +.B \fBgenerate\-tree\fP +Generate entire overlay structure. Without option \fB\-d\fP after +this command sources are not fetched during generation and there +are no entries for them in Manifest files. +.UNINDENT +.SH FILES +.INDENT 0.0 +.TP +.B \fB/etc/g\-sorcery/gs\-elpa.json\fP +Backend config. +.TP +.B \fB/etc/layman/overlays/gs\-elpa\-overlays.xml\fP +List of available repositories. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.TP +.B Using gs\-elpa with layman +Execute +.sp +\fBlayman \-L\fP +.sp +Find there an overlay you need (there are +3 gs\-elpa overlays currently: gnu\-elpa, marmalade and melpa). +Add, e.g. +.sp +\fBlayman \-a gnu\-elpa \-a marmalade\fP +.sp +Emerge any package from it, e.g. +.sp +\fBemerge \-va clojure\-mode\fP +.TP +.B Generating user ebuilds in user overlay +Create new user overlay. Run +.sp +\fBgs\-elpa \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r gnu\-elpa\fP \fBsync\fP +.sp +List packages: +.sp +\fBgs\-elpa \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r gnu\-elpa\fP \fBlist\fP +.sp +Install any package you want: +.sp +\fBgs\-elpa \-o\fP \fIOVERLAY_DIRECTORY\fP \fB\-r gnu\-elpa\fP \fBinstall\fP \fIPACKAGE\fP +.sp +Repositories you can use are gnu\-elpa, marmalade and melpa. You can use them +all in one overlay. Note, that if you call \fBgenerate\-tree\fP command your overlay +will be wiped and overlay tree for a given repository will be generated. Be careful! +.UNINDENT +.SH NOTES +.sp +1. At the moment upstream layman does not support g\-sorcery overlay type. +You should patch it with \fIhttps://raw.github.com/jauhien/g\-sorcery/master/layman\-git\-g\-sorcery.patch\fP. +.sp +To do it download above mentioned patch, place it in +\fB/etc/portage/patches/app\-portage/layman\-9999/\fP directory and +create a file \fB/etc/portage/bashrc\fP that looks like +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +post_src_prepare() { + epatch_user +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then you can emerge \fBapp\-portage/layman\-9999\fP. +.INDENT 0.0 +.IP 2. 3 +At the moment the only package mangler \fBgs\-elpa\fP supports is \fBportage\fP. +.UNINDENT +.SH BUGS +.sp +Some packages in \fBmarmalade\fP and \fBmelpa\fP depend on packages from gnu\-elpa. \fBinstall\fP and \fBgenerate\fP +commands will fail on them as dependencies between overlays are not supported currently. So the +recommended way of using gs\-elpa is using it with layman. Even doing so you should always add +gnu\-elpa repository: \fBlayman \-a gnu\-elpa\fP. +.SH SEE ALSO +.sp +\fBgs\-ctan\fP(8), \fBportage\fP(5), \fBemerge\fP(1), \fBlayman\fP(8) +.SH AUTHOR +Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea +and mentorship by Rafael Martins. Lots of help and improvements +by Brian Dolbec. +.SH COPYRIGHT +Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +.\" Generated by docutils manpage writer. +. diff --git a/docs/gs-elpa.8.rst b/docs/gs-elpa.8.rst new file mode 100644 index 0000000..49d125c --- /dev/null +++ b/docs/gs-elpa.8.rst @@ -0,0 +1,159 @@ +======= +gs-elpa +======= + +------------------------------------- +manage overlays for ELPA repositories +------------------------------------- + +:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea + and mentorship by Rafael Martins. Lots of help and improvements + by Brian Dolbec. +:Date: 2013-08-04 +:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2 +:Version: 0.1 +:Manual section: 8 +:Manual group: g-sorcery + + +SYNOPSIS +======== + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **sync** + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **list** + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **generate** *PACKAGE* + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **install** *PACKAGE* + +**gs-elpa** **-o** *OVERLAY* [**-r** *REPO*] **generate-tree** [**-d**] + +DESCRIPTION +=========== + +**gs-elpa** is an ebuild generator for ELPA repositories -- repositories with +elisp packages for emacs. + +There are two ways of using **gs-elpa**: + + * use it with **layman** + + In this case all you need to do is install **layman-9999**, **g-sorcery** + and **gs-elpa**. Then you should just run `layman -L` as + root and find an overlay you want. Type of overlay will be + displayed as *g-sorcery*. Then you add this overlay as + usual. It's all you need to do and it's the recommended way of + using **gs-elpa**. + + * use it as stand-alone tool + + In this case you should create an overlay (see **portage** documentation), sync it and populate + it with one or more ebuilds. Then ebuilds could be installed by emerge or by **gs-elpa** tool. + + +OPTIONS +======= + +**--overlay** *OVERLAY*, **-o** *OVERLAY* + Overlay directory. This option is mandatory if there is no + **default_overlay** entry in a backend config. + +**--repository** *REPO*, **-r** *REPO* + Repository name. Can be one of **gnu-elpa**, **marmalade**, **melpa**. + +COMMANDS +======== + +**sync** + Synchronize a repository database. + +**list** + List packages available in a repository. + +**generate** + Generate a given ebuild and all its dependencies. + +**install** + Generate and install an ebuild using your package mangler. + +**generate-tree** + Generate entire overlay structure. Without option **-d** after + this command sources are not fetched during generation and there + are no entries for them in Manifest files. + +FILES +===== +**/etc/g-sorcery/gs-elpa.json** + Backend config. + +**/etc/layman/overlays/gs-elpa-overlays.xml** + List of available repositories. + +EXAMPLES +======== + +Using gs-elpa with layman + Execute + + **layman -L** + + Find there an overlay you need (there are + 3 gs-elpa overlays currently: gnu-elpa, marmalade and melpa). + Add, e.g. + + **layman -a gnu-elpa -a marmalade** + + Emerge any package from it, e.g. + + **emerge -va clojure-mode** + +Generating user ebuilds in user overlay + Create new user overlay. Run + + **gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **sync** + + List packages: + + **gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **list** + + Install any package you want: + + **gs-elpa -o** *OVERLAY_DIRECTORY* **-r gnu-elpa** **install** *PACKAGE* + + Repositories you can use are gnu-elpa, marmalade and melpa. You can use them + all in one overlay. Note, that if you call **generate-tree** command your overlay + will be wiped and overlay tree for a given repository will be generated. Be careful! + +NOTES +===== + +1. At the moment upstream layman does not support g-sorcery overlay type. +You should patch it with `https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch`. + +To do it download above mentioned patch, place it in +**/etc/portage/patches/app-portage/layman-9999/** directory and +create a file **/etc/portage/bashrc** that looks like + +.. code-block:: + + post_src_prepare() { + epatch_user + } + +Then you can emerge **app-portage/layman-9999**. + +2. At the moment the only package mangler **gs-elpa** supports is **portage**. + +BUGS +==== + +Some packages in **marmalade** and **melpa** depend on packages from gnu-elpa. **install** and **generate** +commands will fail on them as dependencies between overlays are not supported currently. So the +recommended way of using gs-elpa is using it with layman. Even doing so you should always add +gnu-elpa repository: **layman -a gnu-elpa**. + +SEE ALSO +======== + +**gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8) |