* [gentoo-commits] proj/g-sorcery:master commit in: /, docs/
@ 2013-08-06 20:09 Jauhien Piatlicki
0 siblings, 0 replies; 6+ messages in thread
From: Jauhien Piatlicki @ 2013-08-06 20:09 UTC (permalink / raw
To: gentoo-commits
commit: 4d158c383f10ccc177b93ffeecaff3fce33b1691
Author: Jauhien Piatlicki (jauhien) <piatlicki <AT> gmail <DOT> com>
AuthorDate: Tue Aug 6 20:09:28 2013 +0000
Commit: Jauhien Piatlicki <piatlicki <AT> gmail <DOT> com>
CommitDate: Tue Aug 6 20:09:28 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/g-sorcery.git;a=commit;h=4d158c38
Developer instructions
---
README.md | 4 +-
docs/Makefile | 13 +-
docs/developer_instructions.html | 946 +++++++++++++++++++++++++++++++++++++++
docs/developer_instructions.rst | 640 ++++++++++++++++++++++++++
4 files changed, 1599 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index caa3a7e..dcd8553 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ Installation and using
======================
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`.
+You should [patch it](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
@@ -120,3 +120,5 @@ all in one overlay. Note, that if you call **generate-tree** command your overla
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.
+
+If you want to develop a new backend see [developer's instructions](./docs/developer_instructions.html).
diff --git a/docs/Makefile b/docs/Makefile
index c42c78d..19b6458 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,9 +1,16 @@
-SOURCES=g-sorcery gs-elpa gs-ctan
-MANS=$(SOURCES:=.8)
+HTML_SOURCES=developer_instructions
+HTML_DOCS=$(HTML_SOURCES:=.html)
+MAN_SOURCES=g-sorcery gs-elpa gs-ctan
+MANS=$(MAN_SOURCES:=.8)
+
+RST2HTML=rst2html.py
RST2MAN=rst2man.py
-all: ${MANS}
+all: ${MANS} ${HTML_DOCS}
%.8: %.8.rst
$(RST2MAN) $< $@
+
+%.html: %.rst
+ $(RST2HTML) $< $@
diff --git a/docs/developer_instructions.html b/docs/developer_instructions.html
new file mode 100644
index 0000000..db574e6
--- /dev/null
+++ b/docs/developer_instructions.html
@@ -0,0 +1,946 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
+<title>Developer Instructions</title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 7514 2012-09-14 14:27:12Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
+ overflow: hidden;
+}
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title, .code .error {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin: 0 0 0.5em 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left, .figure.align-left, object.align-left {
+ clear: left ;
+ float: left ;
+ margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right {
+ clear: right ;
+ float: right ;
+ margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.align-left {
+ text-align: left }
+
+.align-center {
+ clear: both ;
+ text-align: center }
+
+.align-right {
+ text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+ text-align: inherit }
+
+/* div.align-center * { */
+/* text-align: left } */
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font: inherit }
+
+pre.literal-block, pre.doctest-block, pre.math, pre.code {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+pre.code .ln { color: grey; } /* line numbers */
+pre.code, code { background-color: #eeeeee }
+pre.code .comment, code .comment { color: #5C6576 }
+pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
+pre.code .literal.string, code .literal.string { color: #0C5404 }
+pre.code .name.builtin, code .name.builtin { color: #352B84 }
+pre.code .deleted, code .deleted { background-color: #DEB0A1}
+pre.code .inserted, code .inserted { background-color: #A3D289}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="developer-instructions">
+<h1 class="title">Developer Instructions</h1>
+
+<div class="section" id="g-sorcery-overview">
+<h1>g-sorcery overview</h1>
+<p><strong>g-sorcery</strong> is a framework aimed to easy development of ebuild
+generators.</p>
+<p>Some terms used in this guide:</p>
+<ul>
+<li><dl class="first docutils">
+<dt><strong>3rd party software provider</strong> or <strong>repository</strong></dt>
+<dd><p class="first last">A system of software distribution like CTAN or CPAN that
+provides packages for some domain (e.g. TeX packages or elisp
+packages for emacs).</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>backend</strong></dt>
+<dd><p class="first last">A tool developed using <strong>g-sorcery</strong> framework that provides
+support for repositories of a given type.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>overlay</strong></dt>
+<dd><p class="first last">Usual Gentoo overlay.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p><strong>g-sorcery</strong> consists of different parts:</p>
+<ul>
+<li><dl class="first docutils">
+<dt><strong>package_db.PackageDB</strong></dt>
+<dd><p class="first last">A package database. It holds information about all available
+packages in a given repository.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>package_db.DBGenerator</strong></dt>
+<dd><p class="first last">A fabric that creates PackageDB object and fills it with information.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>backend.Backend</strong></dt>
+<dd><p class="first last">Backend that processes user commands.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>ebuild</strong></dt>
+<dd><p class="first last">Module with different ebuild generators.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>eclass</strong></dt>
+<dd><p class="first last">Module with eclass generators.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>metadata.MetadataGenerator</strong></dt>
+<dd><p class="first last">Metadata generator.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>Also there are other modules and classes that will be described later.</p>
+<p>Usually repositories of a given type provide some kind of database. It can
+be just a plain ASCII file, xmlrpc interface or just a joint set of web-pages.
+This database describes what packages are available and how to install them.</p>
+<p>Also usually there is an upstream tool for repositories of a given type that
+allows installation of available packages. The main problem when using
+such tools is that package mangler you use is not aware of them and they are
+not aware of your package manager.</p>
+<p>The idea of <strong>g-sorcery</strong> is to convert a database provided by a repository
+into well defined format and then generate an overlay with ebuilds.
+Then available packages can be installed as usual <strong>Gentoo</strong> packages.</p>
+<p>So there are two phases of backend operation:</p>
+<ul class="simple">
+<li>synchronize with repository database</li>
+<li>populate overlay using obtained information</li>
+</ul>
+<p>There are two ways of using backend:</p>
+<ul class="simple">
+<li>run it as a CLI tool manually</li>
+<li>use its integration with layman</li>
+</ul>
+</div>
+<div class="section" id="backend-structure">
+<h1>Backend structure</h1>
+<p>The only mandatory module in a backend is called <strong>backend</strong>. It should contain
+at least one variable called <strong>instance</strong> that has a <strong>__call__</strong> method that
+takes 4 arguments. These arguments are:</p>
+<ul class="simple">
+<li>self</li>
+<li>command line arguments</li>
+<li>backend config</li>
+<li>g-sorcery config</li>
+</ul>
+<p>Usually <strong>instance</strong> variable should be an instance of a class g_sorcery.backend.Backend
+or derived class.</p>
+<p>g_sorcery.backend.Backend constructor takes 8 arguments. They are:</p>
+<ul class="simple">
+<li>self</li>
+<li>Package database generator class</li>
+<li>Two ebuild generator classes</li>
+<li>Eclass generator class</li>
+<li>Metadata generator class</li>
+<li>Package database class</li>
+<li>Boolean variable that defines method of database generation</li>
+</ul>
+<p>There are two ebuild generator classes as there are two scenarios of using backend on user
+side: generate the entire overlay tree (possibly by layman) or generate a given ebuild
+and its dependencies. In a first case it would be very bad idea to have sources in ebuild's
+SRC_URI as during manifest generation for an overlay all the sources would be downloaded
+to the user's comuter that inevitably would made user really happy. So one ebuild generator
+generates ebuild with empty SRC_URI. Note that a mechanism for downloading of sources during
+ebuild merging should be provided. For an example see <strong>git-2</strong> eclass from the main tree or
+any eclass from backends provided with g-sorcery.</p>
+<p>Usually downloading and parsing of a database from a repository is an easy operation. But sometimes
+there could exist some problems. Hence exists the last parameter in Backend constructor that
+allows syncing with already generated database available somewhere in Internet.</p>
+<p>To do something usefull backend should customize any classes from g-sorcery it needs
+and define backend.instance variable using those classes. Other two things backend should do are:</p>
+<ul class="simple">
+<li>install a binary that calls g-sorcery with appropriate backend name (see man g-sorcery)</li>
+<li>install a config that allows g-sorcery find appropriate backend module</li>
+</ul>
+<p>A binary should just pass arguments to g-sorcery. For a backend named gs-elpa it could look like</p>
+<pre class="code literal-block">
+#!/bin/bash
+
+g-sorcery g-elpa $@
+</pre>
+<div class="section" id="backend-config">
+<h2>Backend config</h2>
+<p>Backend config is just a JSON file with a dictionary. There are two mandatory entries:</p>
+<ul>
+<li><dl class="first docutils">
+<dt>package</dt>
+<dd><p class="first last">Its value should be a string with a package containing backend.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>repositories</dt>
+<dd><p class="first last">A dictionary describing available repositories. Should have at least one entry.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>Backend config should have a name BACKEND.js and should be installed under <strong>/etc/g-sorcery</strong>
+directory. BACKEND here is a backend name which was used in a g-sorcery call.</p>
+<p>An entry in repositories dictionary as key should have a repository name and should be a dictionary
+with repository properties. The only mandatory property is <strong>repo_uri</strong> in case database is
+generated using info downloaded from the repository or <strong>db_uri</strong> in case database is
+just synced with another already generated database. Also there can be a <strong>masters</strong> entry that
+contains a list of overlays this repository depends on. If present it should contain at least
+<strong>gentoo</strong> entry.</p>
+<p>A simple backend config:</p>
+<pre class="code literal-block">
+ {
+ "package": "gs_elpa",
+ "repositories": {
+ "gnu-elpa": {
+ "repo_uri": "http://elpa.gnu.org/packages/"
+ },
+ "marmalade": {
+ "repo_uri": "http://marmalade-repo.org/packages/",
+ "masters": ["gentoo", "gnu-elpa"]
+ },
+ "melpa": {
+ "repo_uri": "http://melpa.milkbox.net/packages/",
+ "masters": ["gentoo", "gnu-elpa"]
+ }
+ }
+}
+</pre>
+</div>
+</div>
+<div class="section" id="package-database">
+<h1>Package database</h1>
+<div class="section" id="directory-layout">
+<h2>Directory layout</h2>
+<p>Package database is a directory tree with JSON files. The layout of this tree looks like:</p>
+<pre class="code literal-block">
+db dir
+ manifest.json: database manifest
+ categories.json: information about categories
+ category1
+ packages.json: list of packages
+ package1
+ versions.json: list of versions
+ version1.json: description of a package
+ version2.json: description of a package
+ ...
+ package2
+ ...
+ category2
+ ...
+</pre>
+<p>Files named version.json contain ebuild data which is just a dictionary with information
+relevant for ebuild, eclass and metadata generation for a given package.</p>
+</div>
+<div class="section" id="packagedb-class">
+<h2>PackageDB class</h2>
+<p>PackageDB class is aimed for interaction with package database. It has methods that allow
+to add categories and packages and to do queries on them. Usually you do not want to customize this
+class. But in case you want there is number of methods that can be redifend.</p>
+<p>First of all if you have a database that should be synced with another already generate database
+you can redifine URI to be used for syncing using <strong>get_real_db_uri</strong> method.</p>
+<p>There is a number of hooks that are called after package, category or the whole database is
+written/read:</p>
+<ul class="simple">
+<li>additional_write_version</li>
+<li>additional_write_package</li>
+<li>additional_write_category</li>
+<li>additional_write</li>
+<li>additional_read_version</li>
+<li>additional_read_package</li>
+<li>additional_read_category</li>
+<li>additional_read</li>
+</ul>
+<p>Note that before add any package you should add a category for it using <strong>add_category</strong>.
+Then packages can be added using <strong>add_package</strong>. PackageDB currently does not write changes
+automatically, so you should call <strong>write</strong> after changes are done. This is not relevant
+for database changing in <strong>process_data</strong> method of database generator as there all changes
+are written by other methods it calls internally after <strong>process_data</strong>.</p>
+</div>
+<div class="section" id="json-serializable-objects">
+<h2>JSON serializable objects</h2>
+<p>If you need to store an object in a database it should be JSON serializable in terms of
+g_sorcery.serialization module. It means it should define two methods:</p>
+<ul class="simple">
+<li>usual method <strong>serialize</strong> that returns a JSON serializable object in terms of standard Python
+json module</li>
+<li>class method <strong>deserialize</strong> that takes a value returned by <strong>serialize</strong> and constructs new instance
+of your class using it</li>
+</ul>
+</div>
+<div class="section" id="dependency-handling">
+<h2>Dependency handling</h2>
+<p>There is a special class g_sorcery.g_collections.Dependency aimed to handle dependencies.
+Its constructor takes two mandatory parameters:</p>
+<ul class="simple">
+<li>category</li>
+<li>package</li>
+</ul>
+<p>and two additional parameters:</p>
+<ul class="simple">
+<li>version</li>
+<li>operator</li>
+</ul>
+<p>These two are the same as version and operator used in the usual package atom.</p>
+<p>For storing dependency lists in a database you should use a collection
+g_sorcery.g_collections.serializable_elist. Its constructor takes an iterable and a
+separator that will be used to separate items when this collection is printed. In case of
+storing dependencies for using them in ebuild's DEPEND variable a separator should be "nt".</p>
+<p>Ebuild data for every package version must have a "dependencies" entry. This entry is used
+by backend during deciding which ebuilds should be generated. So make sure it does not have
+any external dependencies.</p>
+</div>
+</div>
+<div class="section" id="package-database-generator">
+<h1>Package database generator</h1>
+<div class="section" id="customizing-dbgenerator">
+<h2>Customizing DBGenerator</h2>
+<p>To do something usefull you should customize package_db.DBGenerator class.
+With this aim you should subclass it and define some methods. Here they are:</p>
+<ul>
+<li><dl class="first docutils">
+<dt>get_download_uries</dt>
+<dd><p class="first">Get a list with download URI entries.
+Each entry has one of the following formats:</p>
+<ol class="arabic">
+<li><p class="first">String with URI.</p>
+</li>
+<li><dl class="first docutils">
+<dt>A dictionary with entries:</dt>
+<dd><ul class="first simple">
+<li>uri: URI.</li>
+<li>parser: Parser to be applied to downloaded data.</li>
+<li>open_file: Whether parser accepts file objects.</li>
+<li>open_mode: Open mode for a downloaded file.</li>
+</ul>
+<p class="last">The only mandatory entry is uri.</p>
+</dd>
+</dl>
+</li>
+</ol>
+<p class="last">The default implementation returns [backend_config["repositories"][REPOSITORY]["repo_uri"]].</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>parse_data</dt>
+<dd><p class="first last">This method parses a file downloaded from a repository
+and returns its content in any form you think useful.
+There is no useful default implementation of this method.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>process_data</dt>
+<dd><p class="first last">This method should fill a package database with entries using
+already downloaded and parsed data.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>Generally speaking these are all the method you should implement.</p>
+</div>
+<div class="section" id="value-convertion">
+<h2>Value convertion</h2>
+<p>During database generation you may need to convert some values provided by repository
+(e.g license names that can not coincide with those used in Gentoo). With this aim
+you can use <strong>convert</strong> function. To understand how it works see its sources in
+g_sorcery.package_db.DBGenerator and as an example CTAN backend.</p>
+<p>Here is a very short example. If you want to convert licenses in the same way for all
+repositories of this type you just add <strong>common_config</strong> entry to backend config which
+looks like:</p>
+<pre class="code literal-block">
+"common_config": {
+ "licenses": {
+ "apache2": "Apache-2.0",
+ "artistic": "Artistic",
+ "Artistic2": "Artistic-2",
+ "gpl": "GPL-1",
+ "gpl2": "GPL-2",
+ "gpl3": "GPL-3",
+ "knuth": "TeX",
+ "lgpl": "LGPL-2",
+ "lgpl2.1": "LGPL-2.1",
+ "lppl": "LPPL-1.2",
+ "lppl1": "LPPL-1.2",
+ "lppl1.2": "LPPL-1.2",
+ "lppl1.3": "LPPL-1.3c"
+ }
+}
+</pre>
+<p>And then call in your <strong>process_data</strong> method</p>
+<pre class="code literal-block">
+license = self.convert([common_config, config], "licenses", repo_license)
+</pre>
+<p>Where <strong>common_config</strong>, <strong>config</strong> are config provided as arguments to your <strong>process_data</strong> method
+and <strong>repo_license</strong> is a license name used by the repository.</p>
+<p>There is a special conversion function used for dependencies: <strong>convert_dependency</strong>. To use it you should
+usually redefine <strong>convert_internal_dependency</strong> and <strong>convert_external_dependency</strong>. To decide whether
+a dependency is external database generator uses <strong>external</strong> entry in config.</p>
+<p>You may want to test whether there is a given value in given entry in config. To do it use
+<strong>in_config</strong> function.</p>
+</div>
+</div>
+<div class="section" id="eclass-generator">
+<h1>Eclass generator</h1>
+<p>Usualy you do not want to modify eclass generator. Currently it is very simple: it just returns eclasses
+from a given directory. So all you should do is populating a directory with eclasses and then
+inheriting g_sorcery.eclass.EclassGenerator and defining a directory in constructor. It should look
+like</p>
+<pre class="code literal-block">
+class ElpaEclassGenerator(EclassGenerator):
+ """
+ Implementation of eclass generator. Only specifies a data directory.
+ """
+ def __init__(self):
+ super(ElpaEclassGenerator, self).__init__(os.path.join(get_pkgpath(__file__), 'data'))
+</pre>
+<p>There is no common eclass currently. I plan to change it in the future, so your eclass code can
+inherit any common functionality.</p>
+</div>
+<div class="section" id="ebuild-generator">
+<h1>Ebuild generator</h1>
+<p>There is a number of ebuild generators in g_sorcery.ebuild module. The DefaultEbuildGenerator
+is a recommended one. To use it you should inherit it and define an ebuild layout in constructor.</p>
+<p>Layout has entries for vars and inherited eclasses. Each entry is a list.
+Entries are processed in the following order:</p>
+<ul class="simple">
+<li>vars_before_inherit</li>
+<li>inherit</li>
+<li>vars_after_inherit</li>
+<li>vars_after_description</li>
+<li>vars_after_keywords</li>
+</ul>
+<p><strong>inherit</strong> entry is just a list of eclass names.</p>
+<p><strong>vars*</strong> entries are lists of variables in two possible formats:</p>
+<ol class="arabic simple">
+<li>A string with variable name</li>
+<li>A tuple (varname, value)</li>
+</ol>
+<p>Variable names are automatically transformed to the upper-case during ebuild generation.</p>
+<p>An example of ebuild generator:</p>
+<pre class="code literal-block">
+Layout = collections.namedtuple("Layout",
+ ["vars_before_inherit", "inherit",
+ "vars_after_description", "vars_after_keywords"])
+
+class ElpaEbuildWithoutDigestGenerator(DefaultEbuildGenerator):
+ """
+ Implementation of ebuild generator without sources digesting.
+ """
+ def __init__(self, package_db):
+
+ vars_before_inherit = \
+ ["repo_uri", "source_type", "realname"]
+
+ inherit = ["g-elpa"]
+
+ vars_after_description = \
+ ["homepage"]
+
+ vars_after_keywords = \
+ ["depend", "rdepend"]
+
+ layout = Layout(vars_before_inherit, inherit,
+ vars_after_description, vars_after_keywords)
+
+ super(ElpaEbuildWithoutDigestGenerator, self).__init__(package_db, layout)
+</pre>
+</div>
+<div class="section" id="metadata-generator">
+<h1>Metadata generator</h1>
+<p>To use metadata generator you should just define some variables in ebuild data.</p>
+<div class="section" id="xml-schema-format">
+<h2>XML schema format</h2>
+<p>Metadata generator uses a XML schema in format defined in g_sorcery.metadata module.
+Schema is a list of entries. Each entry describes one XML tag.
+Entry is a dictionary. Dictionary keys are:</p>
+<ul>
+<li><dl class="first docutils">
+<dt><strong>name</strong></dt>
+<dd><p class="first last">Name of a tag</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>multiple</strong></dt>
+<dd><p class="first last">Defines if a given tag can be used more then one time. It is a tuple. First element
+of a tuple is boolean. If it is set a tag can be repeated. Second element is a string.
+If it is not empty, it defines a name for an attribute
+that will distinguish different entries of a tag.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>required</strong></dt>
+<dd><p class="first last">Boolean that defines if a given tag is required.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><strong>subtags</strong></dt>
+<dd><p class="first last">List of subtags.</p>
+</dd>
+</dl>
+</li>
+</ul>
+</div>
+<div class="section" id="data-dictinonary-format">
+<h2>Data dictinonary format</h2>
+<p>The part of ebuild data used for metadata generation should have data dictionary format
+also defined in g_sorcery.metadata.</p>
+<p>Keys correspond to tags from a schema with the same name.
+If a tag is not multiple without subkeys value is just a
+string with text for the tag.
+If tag is multiple value is a list with entries
+corresponding to a single tag.
+If tag has subtags value is a dictionary with entries
+corresponding to subkeys and <strong>text</strong> entry corresponding
+to text for the tag.
+If tag should have attributes value is a tuple or list with
+0 element containing an attribute and 1 element containing
+a value for the tag as described previously.</p>
+</div>
+<div class="section" id="metadata-xml-schema">
+<h2>Metadata XML schema</h2>
+<p>Metadata XML schema looks like</p>
+<pre class="code literal-block">
+default_schema = [{'name' : 'herd',
+ 'multiple' : (True, ""),
+ 'required' : False,
+ 'subtags' : []},
+
+ {'name' : 'maintainer',
+ 'multiple' : (True, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'email',
+ 'multiple' : (False, ""),
+ 'required' : True,
+ 'subtags' : []},
+ {'name' : 'name',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'description',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ ]
+ },
+
+ {'name' : 'longdescription',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+
+ {'name' : 'use',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'flag',
+ 'multiple' : (True, "name"),
+ 'required' : True,
+ 'subtags' : []}]
+ },
+
+ {'name' : 'upstream',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'maintainer',
+ 'multiple' : (True, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'name',
+ 'multiple' : (False, ""),
+ 'required' : True,
+ 'subtags' : []},
+ {'name' : 'email',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []}]},
+ {'name' : 'changelog',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'doc',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'bugs-to',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'remote-id',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ ]
+ },
+ ]
+</pre>
+<p>So to have metadata.xml filled with e.g. maintainer info you should add to ebuild data
+something like</p>
+<pre class="code literal-block">
+{'maintainer' : [{'email' : 'piatlicki@gmail.com',
+ 'name' : 'Jauhien Piatlicki'}]}
+</pre>
+</div>
+</div>
+<div class="section" id="layman-integration">
+<h1>Layman integration</h1>
+<p>There is a <strong>layman</strong> integration for <strong>g-sorcery</strong> (thanks to Brian Dolbec and Auke Booij here).
+To use it you just need to install and xml file describing your repositories in
+<strong>/etc/layman/overlays</strong> directory. For our example of backend config we could write an xml file
+that looks like</p>
+<pre class="code literal-block">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
+<repositories xmlns="" version="1.0">
+<repo quality="experimental" status="unofficial">
+ <name>gnu-elpa</name>
+ <description>packages for emacs</description>
+ <homepage>http://elpa.gnu.org/</homepage>
+ <owner>
+ <email>piatlicki@gmail.com</email>
+ <name>Jauhien Piatlicki</name>
+ </owner>
+ <source type="g-sorcery">gs-elpa gnu-elpa</source>
+</repo>
+<repo quality="experimental" status="unofficial">
+ <name>marmalade</name>
+ <description>packages for emacs</description>
+ <homepage>http://marmalade-repo.org/</homepage>
+ <owner>
+ <email>piatlicki@gmail.com</email>
+ <name>Jauhien Piatlicki</name>
+ </owner>
+ <source type="g-sorcery">gs-elpa marmalade</source>
+</repo>
+<repo quality="experimental" status="unofficial">
+ <name>melpa</name>
+ <description>packages for emacs</description>
+ <homepage>http://melpa.milkbox.net</homepage>
+ <owner>
+ <email>piatlicki@gmail.com</email>
+ <name>Jauhien Piatlicki</name>
+ </owner>
+ <source type="g-sorcery">gs-elpa melpa</source>
+</repo>
+</repositories>
+</pre>
+<p>In entries <strong><source type="g-sorcery">gs-elpa melpa</source></strong> the source type
+should always be <strong>g-sorcery</strong>, <strong>gs-elpa</strong> is backend name and <strong>melpa</strong> is repository name.</p>
+<p>For full description of format of this file see <strong>layman</strong> documentation.</p>
+<p>Note: at the moment layman-9999 does not support <strong>g-sorcery</strong> overlay type and you should
+patch it with <a class="reference external" href="https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch">https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch</a></p>
+</div>
+<div class="section" id="summary">
+<h1>Summary</h1>
+<p>So to create your own backend you should write a module named <strong>backend</strong> and define there
+a variable named <strong>instance</strong> that is an instance of g_sorcery.backend.Backend class. Or something
+that quacks like this class.</p>
+<p>Before doing it you should have defined classes you pass to it as parameters. They should be database
+generator, two ebuild generators, eclass and metadata generators.</p>
+<p>Also you should write an executable that calls g-sorcery and some configs.</p>
+</div>
+</div>
+</body>
+</html>
diff --git a/docs/developer_instructions.rst b/docs/developer_instructions.rst
new file mode 100644
index 0000000..cd95a2f
--- /dev/null
+++ b/docs/developer_instructions.rst
@@ -0,0 +1,640 @@
+======================
+Developer Instructions
+======================
+
+g-sorcery overview
+==================
+
+**g-sorcery** is a framework aimed to easy development of ebuild
+generators.
+
+Some terms used in this guide:
+
+* **3rd party software provider** or **repository**
+ A system of software distribution like CTAN or CPAN that
+ provides packages for some domain (e.g. TeX packages or elisp
+ packages for emacs).
+
+* **backend**
+ A tool developed using **g-sorcery** framework that provides
+ support for repositories of a given type.
+
+* **overlay**
+ Usual Gentoo overlay.
+
+**g-sorcery** consists of different parts:
+
+* **package_db.PackageDB**
+ A package database. It holds information about all available
+ packages in a given repository.
+
+* **package_db.DBGenerator**
+ A fabric that creates PackageDB object and fills it with information.
+
+* **backend.Backend**
+ Backend that processes user commands.
+
+* **ebuild**
+ Module with different ebuild generators.
+
+* **eclass**
+ Module with eclass generators.
+
+* **metadata.MetadataGenerator**
+ Metadata generator.
+
+Also there are other modules and classes that will be described later.
+
+Usually repositories of a given type provide some kind of database. It can
+be just a plain ASCII file, xmlrpc interface or just a joint set of web-pages.
+This database describes what packages are available and how to install them.
+
+Also usually there is an upstream tool for repositories of a given type that
+allows installation of available packages. The main problem when using
+such tools is that package mangler you use is not aware of them and they are
+not aware of your package manager.
+
+The idea of **g-sorcery** is to convert a database provided by a repository
+into well defined format and then generate an overlay with ebuilds.
+Then available packages can be installed as usual **Gentoo** packages.
+
+So there are two phases of backend operation:
+
+- synchronize with repository database
+
+- populate overlay using obtained information
+
+There are two ways of using backend:
+
+- run it as a CLI tool manually
+
+- use its integration with layman
+
+
+Backend structure
+=================
+
+The only mandatory module in a backend is called **backend**. It should contain
+at least one variable called **instance** that has a **__call__** method that
+takes 4 arguments. These arguments are:
+
+* self
+
+* command line arguments
+
+* backend config
+
+* g-sorcery config
+
+Usually **instance** variable should be an instance of a class g_sorcery.backend.Backend
+or derived class.
+
+g_sorcery.backend.Backend constructor takes 8 arguments. They are:
+
+* self
+
+* Package database generator class
+
+* Two ebuild generator classes
+
+* Eclass generator class
+
+* Metadata generator class
+
+* Package database class
+
+* Boolean variable that defines method of database generation
+
+There are two ebuild generator classes as there are two scenarios of using backend on user
+side: generate the entire overlay tree (possibly by layman) or generate a given ebuild
+and its dependencies. In a first case it would be very bad idea to have sources in ebuild's
+SRC_URI as during manifest generation for an overlay all the sources would be downloaded
+to the user's comuter that inevitably would made user really happy. So one ebuild generator
+generates ebuild with empty SRC_URI. Note that a mechanism for downloading of sources during
+ebuild merging should be provided. For an example see **git-2** eclass from the main tree or
+any eclass from backends provided with g-sorcery.
+
+Usually downloading and parsing of a database from a repository is an easy operation. But sometimes
+there could exist some problems. Hence exists the last parameter in Backend constructor that
+allows syncing with already generated database available somewhere in Internet.
+
+To do something usefull backend should customize any classes from g-sorcery it needs
+and define backend.instance variable using those classes. Other two things backend should do are:
+
+* install a binary that calls g-sorcery with appropriate backend name (see man g-sorcery)
+
+* install a config that allows g-sorcery find appropriate backend module
+
+A binary should just pass arguments to g-sorcery. For a backend named gs-elpa it could look like
+
+.. code-block::
+
+ #!/bin/bash
+
+ g-sorcery g-elpa $@
+
+Backend config
+~~~~~~~~~~~~~~
+
+Backend config is just a JSON file with a dictionary. There are two mandatory entries:
+
+* package
+ Its value should be a string with a package containing backend.
+
+* repositories
+ A dictionary describing available repositories. Should have at least one entry.
+
+Backend config should have a name BACKEND.js and should be installed under **/etc/g-sorcery**
+directory. BACKEND here is a backend name which was used in a g-sorcery call.
+
+An entry in repositories dictionary as key should have a repository name and should be a dictionary
+with repository properties. The only mandatory property is **repo_uri** in case database is
+generated using info downloaded from the repository or **db_uri** in case database is
+just synced with another already generated database. Also there can be a **masters** entry that
+contains a list of overlays this repository depends on. If present it should contain at least
+**gentoo** entry.
+
+A simple backend config:
+
+.. code-block::
+
+ {
+ "package": "gs_elpa",
+ "repositories": {
+ "gnu-elpa": {
+ "repo_uri": "http://elpa.gnu.org/packages/"
+ },
+ "marmalade": {
+ "repo_uri": "http://marmalade-repo.org/packages/",
+ "masters": ["gentoo", "gnu-elpa"]
+ },
+ "melpa": {
+ "repo_uri": "http://melpa.milkbox.net/packages/",
+ "masters": ["gentoo", "gnu-elpa"]
+ }
+ }
+ }
+
+Package database
+================
+
+Directory layout
+~~~~~~~~~~~~~~~~
+
+Package database is a directory tree with JSON files. The layout of this tree looks like:
+
+.. code-block::
+
+ db dir
+ manifest.json: database manifest
+ categories.json: information about categories
+ category1
+ packages.json: list of packages
+ package1
+ versions.json: list of versions
+ version1.json: description of a package
+ version2.json: description of a package
+ ...
+ package2
+ ...
+ category2
+ ...
+
+Files named version.json contain ebuild data which is just a dictionary with information
+relevant for ebuild, eclass and metadata generation for a given package.
+
+PackageDB class
+~~~~~~~~~~~~~~~
+
+PackageDB class is aimed for interaction with package database. It has methods that allow
+to add categories and packages and to do queries on them. Usually you do not want to customize this
+class. But in case you want there is number of methods that can be redifend.
+
+First of all if you have a database that should be synced with another already generate database
+you can redifine URI to be used for syncing using **get_real_db_uri** method.
+
+There is a number of hooks that are called after package, category or the whole database is
+written/read:
+
+* additional_write_version
+
+* additional_write_package
+
+* additional_write_category
+
+* additional_write
+
+* additional_read_version
+
+* additional_read_package
+
+* additional_read_category
+
+* additional_read
+
+Note that before add any package you should add a category for it using **add_category**.
+Then packages can be added using **add_package**. PackageDB currently does not write changes
+automatically, so you should call **write** after changes are done. This is not relevant
+for database changing in **process_data** method of database generator as there all changes
+are written by other methods it calls internally after **process_data**.
+
+JSON serializable objects
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to store an object in a database it should be JSON serializable in terms of
+g_sorcery.serialization module. It means it should define two methods:
+
+* usual method **serialize** that returns a JSON serializable object in terms of standard Python
+ json module
+
+* class method **deserialize** that takes a value returned by **serialize** and constructs new instance
+ of your class using it
+
+Dependency handling
+~~~~~~~~~~~~~~~~~~~
+
+There is a special class g_sorcery.g_collections.Dependency aimed to handle dependencies.
+Its constructor takes two mandatory parameters:
+
+* category
+
+* package
+
+and two additional parameters:
+
+* version
+
+* operator
+
+These two are the same as version and operator used in the usual package atom.
+
+For storing dependency lists in a database you should use a collection
+g_sorcery.g_collections.serializable_elist. Its constructor takes an iterable and a
+separator that will be used to separate items when this collection is printed. In case of
+storing dependencies for using them in ebuild's DEPEND variable a separator should be "\n\t".
+
+Ebuild data for every package version must have a "dependencies" entry. This entry is used
+by backend during deciding which ebuilds should be generated. So make sure it does not have
+any external dependencies.
+
+
+Package database generator
+==========================
+
+Customizing DBGenerator
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To do something usefull you should customize package_db.DBGenerator class.
+With this aim you should subclass it and define some methods. Here they are:
+
+* get_download_uries
+ Get a list with download URI entries.
+ Each entry has one of the following formats:
+
+ 1. String with URI.
+
+ 2. A dictionary with entries:
+ - uri: URI.
+
+ - parser: Parser to be applied to downloaded data.
+
+ - open_file: Whether parser accepts file objects.
+
+ - open_mode: Open mode for a downloaded file.
+
+ The only mandatory entry is uri.
+
+ The default implementation returns [backend_config["repositories"][REPOSITORY]["repo_uri"]].
+
+* parse_data
+ This method parses a file downloaded from a repository
+ and returns its content in any form you think useful.
+ There is no useful default implementation of this method.
+
+* process_data
+ This method should fill a package database with entries using
+ already downloaded and parsed data.
+
+Generally speaking these are all the method you should implement.
+
+Value convertion
+~~~~~~~~~~~~~~~~
+
+During database generation you may need to convert some values provided by repository
+(e.g license names that can not coincide with those used in Gentoo). With this aim
+you can use **convert** function. To understand how it works see its sources in
+g_sorcery.package_db.DBGenerator and as an example CTAN backend.
+
+Here is a very short example. If you want to convert licenses in the same way for all
+repositories of this type you just add **common_config** entry to backend config which
+looks like:
+
+.. code-block::
+
+ "common_config": {
+ "licenses": {
+ "apache2": "Apache-2.0",
+ "artistic": "Artistic",
+ "Artistic2": "Artistic-2",
+ "gpl": "GPL-1",
+ "gpl2": "GPL-2",
+ "gpl3": "GPL-3",
+ "knuth": "TeX",
+ "lgpl": "LGPL-2",
+ "lgpl2.1": "LGPL-2.1",
+ "lppl": "LPPL-1.2",
+ "lppl1": "LPPL-1.2",
+ "lppl1.2": "LPPL-1.2",
+ "lppl1.3": "LPPL-1.3c"
+ }
+ }
+
+And then call in your **process_data** method
+
+.. code-block::
+
+ license = self.convert([common_config, config], "licenses", repo_license)
+
+Where **common_config**, **config** are config provided as arguments to your **process_data** method
+and **repo_license** is a license name used by the repository.
+
+There is a special conversion function used for dependencies: **convert_dependency**. To use it you should
+usually redefine **convert_internal_dependency** and **convert_external_dependency**. To decide whether
+a dependency is external database generator uses **external** entry in config.
+
+You may want to test whether there is a given value in given entry in config. To do it use
+**in_config** function.
+
+Eclass generator
+================
+
+Usualy you do not want to modify eclass generator. Currently it is very simple: it just returns eclasses
+from a given directory. So all you should do is populating a directory with eclasses and then
+inheriting g_sorcery.eclass.EclassGenerator and defining a directory in constructor. It should look
+like
+
+.. code-block::
+
+ class ElpaEclassGenerator(EclassGenerator):
+ """
+ Implementation of eclass generator. Only specifies a data directory.
+ """
+ def __init__(self):
+ super(ElpaEclassGenerator, self).__init__(os.path.join(get_pkgpath(__file__), 'data'))
+
+There is no common eclass currently. I plan to change it in the future, so your eclass code can
+inherit any common functionality.
+
+Ebuild generator
+================
+
+There is a number of ebuild generators in g_sorcery.ebuild module. The DefaultEbuildGenerator
+is a recommended one. To use it you should inherit it and define an ebuild layout in constructor.
+
+Layout has entries for vars and inherited eclasses. Each entry is a list.
+Entries are processed in the following order:
+
+* vars_before_inherit
+
+* inherit
+
+* vars_after_inherit
+
+* vars_after_description
+
+* vars_after_keywords
+
+**inherit** entry is just a list of eclass names.
+
+**vars*** entries are lists of variables in two possible formats:
+
+1. A string with variable name
+2. A tuple (varname, value)
+
+Variable names are automatically transformed to the upper-case during ebuild generation.
+
+An example of ebuild generator:
+
+.. code-block::
+
+ Layout = collections.namedtuple("Layout",
+ ["vars_before_inherit", "inherit",
+ "vars_after_description", "vars_after_keywords"])
+
+ class ElpaEbuildWithoutDigestGenerator(DefaultEbuildGenerator):
+ """
+ Implementation of ebuild generator without sources digesting.
+ """
+ def __init__(self, package_db):
+
+ vars_before_inherit = \
+ ["repo_uri", "source_type", "realname"]
+
+ inherit = ["g-elpa"]
+
+ vars_after_description = \
+ ["homepage"]
+
+ vars_after_keywords = \
+ ["depend", "rdepend"]
+
+ layout = Layout(vars_before_inherit, inherit,
+ vars_after_description, vars_after_keywords)
+
+ super(ElpaEbuildWithoutDigestGenerator, self).__init__(package_db, layout)
+
+Metadata generator
+==================
+
+To use metadata generator you should just define some variables in ebuild data.
+
+XML schema format
+~~~~~~~~~~~~~~~~~
+
+Metadata generator uses a XML schema in format defined in g_sorcery.metadata module.
+Schema is a list of entries. Each entry describes one XML tag.
+Entry is a dictionary. Dictionary keys are:
+
+* **name**
+ Name of a tag
+
+* **multiple**
+ Defines if a given tag can be used more then one time. It is a tuple. First element
+ of a tuple is boolean. If it is set a tag can be repeated. Second element is a string.
+ If it is not empty, it defines a name for an attribute
+ that will distinguish different entries of a tag.
+
+* **required**
+ Boolean that defines if a given tag is required.
+
+* **subtags**
+ List of subtags.
+
+Data dictinonary format
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The part of ebuild data used for metadata generation should have data dictionary format
+also defined in g_sorcery.metadata.
+
+Keys correspond to tags from a schema with the same name.
+If a tag is not multiple without subkeys value is just a
+string with text for the tag.
+If tag is multiple value is a list with entries
+corresponding to a single tag.
+If tag has subtags value is a dictionary with entries
+corresponding to subkeys and **text** entry corresponding
+to text for the tag.
+If tag should have attributes value is a tuple or list with
+0 element containing an attribute and 1 element containing
+a value for the tag as described previously.
+
+Metadata XML schema
+~~~~~~~~~~~~~~~~~~~
+
+Metadata XML schema looks like
+
+.. code-block::
+
+ default_schema = [{'name' : 'herd',
+ 'multiple' : (True, ""),
+ 'required' : False,
+ 'subtags' : []},
+
+ {'name' : 'maintainer',
+ 'multiple' : (True, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'email',
+ 'multiple' : (False, ""),
+ 'required' : True,
+ 'subtags' : []},
+ {'name' : 'name',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'description',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ ]
+ },
+
+ {'name' : 'longdescription',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+
+ {'name' : 'use',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'flag',
+ 'multiple' : (True, "name"),
+ 'required' : True,
+ 'subtags' : []}]
+ },
+
+ {'name' : 'upstream',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'maintainer',
+ 'multiple' : (True, ""),
+ 'required' : False,
+ 'subtags' : [{'name' : 'name',
+ 'multiple' : (False, ""),
+ 'required' : True,
+ 'subtags' : []},
+ {'name' : 'email',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []}]},
+ {'name' : 'changelog',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'doc',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'bugs-to',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ {'name' : 'remote-id',
+ 'multiple' : (False, ""),
+ 'required' : False,
+ 'subtags' : []},
+ ]
+ },
+ ]
+
+So to have metadata.xml filled with e.g. maintainer info you should add to ebuild data
+something like
+
+.. code-block::
+
+ {'maintainer' : [{'email' : 'piatlicki@gmail.com',
+ 'name' : 'Jauhien Piatlicki'}]}
+
+Layman integration
+==================
+
+There is a **layman** integration for **g-sorcery** (thanks to Brian Dolbec and Auke Booij here).
+To use it you just need to install and xml file describing your repositories in
+**/etc/layman/overlays** directory. For our example of backend config we could write an xml file
+that looks like
+
+.. code-block::
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
+ <repositories xmlns="" version="1.0">
+ <repo quality="experimental" status="unofficial">
+ <name>gnu-elpa</name>
+ <description>packages for emacs</description>
+ <homepage>http://elpa.gnu.org/</homepage>
+ <owner>
+ <email>piatlicki@gmail.com</email>
+ <name>Jauhien Piatlicki</name>
+ </owner>
+ <source type="g-sorcery">gs-elpa gnu-elpa</source>
+ </repo>
+ <repo quality="experimental" status="unofficial">
+ <name>marmalade</name>
+ <description>packages for emacs</description>
+ <homepage>http://marmalade-repo.org/</homepage>
+ <owner>
+ <email>piatlicki@gmail.com</email>
+ <name>Jauhien Piatlicki</name>
+ </owner>
+ <source type="g-sorcery">gs-elpa marmalade</source>
+ </repo>
+ <repo quality="experimental" status="unofficial">
+ <name>melpa</name>
+ <description>packages for emacs</description>
+ <homepage>http://melpa.milkbox.net</homepage>
+ <owner>
+ <email>piatlicki@gmail.com</email>
+ <name>Jauhien Piatlicki</name>
+ </owner>
+ <source type="g-sorcery">gs-elpa melpa</source>
+ </repo>
+ </repositories>
+
+In entries **<source type="g-sorcery">gs-elpa melpa</source>** the source type
+should always be **g-sorcery**, **gs-elpa** is backend name and **melpa** is repository name.
+
+For full description of format of this file see **layman** documentation.
+
+Note: at the moment layman-9999 does not support **g-sorcery** overlay type and you should
+patch it with https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch
+
+Summary
+=======
+
+So to create your own backend you should write a module named **backend** and define there
+a variable named **instance** that is an instance of g_sorcery.backend.Backend class. Or something
+that quacks like this class.
+
+Before doing it you should have defined classes you pass to it as parameters. They should be database
+generator, two ebuild generators, eclass and metadata generators.
+
+Also you should write an executable that calls g-sorcery and some configs.
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [gentoo-commits] proj/g-sorcery:master commit in: /, docs/
@ 2013-08-29 1:12 Jauhien Piatlicki
0 siblings, 0 replies; 6+ messages in thread
From: Jauhien Piatlicki @ 2013-08-29 1:12 UTC (permalink / raw
To: gentoo-commits
commit: c76d706a7f8ba9f7a22000fbdf5f478770686108
Author: Jauhien Piatlicki (jauhien) <piatlicki <AT> gmail <DOT> com>
AuthorDate: Thu Aug 29 01:12:34 2013 +0000
Commit: Jauhien Piatlicki <piatlicki <AT> gmail <DOT> com>
CommitDate: Thu Aug 29 01:12:34 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/g-sorcery.git;a=commit;h=c76d706a
upstream layman supports g-sorcery now
---
README.md | 15 +--------------
docs/developer_instructions.html | 2 --
docs/developer_instructions.rst | 3 ---
docs/g-sorcery.8 | 23 +----------------------
docs/g-sorcery.8.rst | 17 +----------------
docs/gs-ctan.8 | 23 +----------------------
docs/gs-ctan.8.rst | 17 +----------------
docs/gs-elpa.8 | 23 +----------------------
docs/gs-elpa.8.rst | 17 +----------------
9 files changed, 7 insertions(+), 133 deletions(-)
diff --git a/README.md b/README.md
index 03358b2..dc8a71a 100644
--- a/README.md
+++ b/README.md
@@ -46,20 +46,7 @@ databases with information about available software and so on.
Installation and using
======================
-At the moment upstream layman does not support g-sorcery overlay type.
-You should [patch it](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
-
-```bash
- post_src_prepare() {
- epatch_user
- }
-```
-
-Then you can emerge **app-portage/layman-9999**.
+You should emerge **app-portage/layman-9999**.
Add `jauhien` overlay: **layman -a jauhien**.
diff --git a/docs/developer_instructions.html b/docs/developer_instructions.html
index 4c506af..03cb53c 100644
--- a/docs/developer_instructions.html
+++ b/docs/developer_instructions.html
@@ -929,8 +929,6 @@ that looks like</p>
<p>In entries <strong><source type="g-sorcery">gs-elpa melpa</source></strong> the source type
should always be <strong>g-sorcery</strong>, <strong>gs-elpa</strong> is backend name and <strong>melpa</strong> is repository name.</p>
<p>For full description of format of this file see <strong>layman</strong> documentation.</p>
-<p>Note: at the moment layman-9999 does not support <strong>g-sorcery</strong> overlay type and you should
-patch it with <a class="reference external" href="https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch">https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch</a></p>
</div>
<div class="section" id="summary">
<h1>Summary</h1>
diff --git a/docs/developer_instructions.rst b/docs/developer_instructions.rst
index f561027..4434628 100644
--- a/docs/developer_instructions.rst
+++ b/docs/developer_instructions.rst
@@ -624,9 +624,6 @@ should always be **g-sorcery**, **gs-elpa** is backend name and **melpa** is rep
For full description of format of this file see **layman** documentation.
-Note: at the moment layman-9999 does not support **g-sorcery** overlay type and you should
-patch it with https://raw.github.com/jauhien/g-sorcery/master/layman-git-g-sorcery.patch
-
Summary
=======
diff --git a/docs/g-sorcery.8 b/docs/g-sorcery.8
index 7e0c614..ebd0afb 100644
--- a/docs/g-sorcery.8
+++ b/docs/g-sorcery.8
@@ -121,29 +121,8 @@ Main g\-sorcery config.
Backend configs.
.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
+.IP 1. 3
At the moment the only package mangler \fBg\-sorcery\fP supports is \fBportage\fP.
.UNINDENT
.SH SEE ALSO
diff --git a/docs/g-sorcery.8.rst b/docs/g-sorcery.8.rst
index 416c358..ca529c7 100644
--- a/docs/g-sorcery.8.rst
+++ b/docs/g-sorcery.8.rst
@@ -107,22 +107,7 @@ FILES
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 **g-sorcery** supports is **portage**.
+1. At the moment the only package mangler **g-sorcery** supports is **portage**.
SEE ALSO
========
diff --git a/docs/gs-ctan.8 b/docs/gs-ctan.8
index e7606d5..8663647 100644
--- a/docs/gs-ctan.8
+++ b/docs/gs-ctan.8
@@ -136,29 +136,8 @@ 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
+.IP 1. 3
At the moment the only package mangler \fBgs\-ctan\fP supports is \fBportage\fP.
.UNINDENT
.SH SEE ALSO
diff --git a/docs/gs-ctan.8.rst b/docs/gs-ctan.8.rst
index 5442cbb..e11be9b 100644
--- a/docs/gs-ctan.8.rst
+++ b/docs/gs-ctan.8.rst
@@ -122,22 +122,7 @@ Generating user ebuilds in user overlay
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-ctan** supports is **portage**.
+1. At the moment the only package mangler **gs-ctan** supports is **portage**.
SEE ALSO
========
diff --git a/docs/gs-elpa.8 b/docs/gs-elpa.8
index a4fdaba..c64afee 100644
--- a/docs/gs-elpa.8
+++ b/docs/gs-elpa.8
@@ -142,29 +142,8 @@ all in one overlay. Note, that if you call \fBgenerate\-tree\fP command your ove
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
+.IP 1. 3
At the moment the only package mangler \fBgs\-elpa\fP supports is \fBportage\fP.
.UNINDENT
.SH BUGS
diff --git a/docs/gs-elpa.8.rst b/docs/gs-elpa.8.rst
index 49d125c..4c38cb9 100644
--- a/docs/gs-elpa.8.rst
+++ b/docs/gs-elpa.8.rst
@@ -128,22 +128,7 @@ Generating user ebuilds in user overlay
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**.
+1. At the moment the only package mangler **gs-elpa** supports is **portage**.
BUGS
====
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [gentoo-commits] proj/g-sorcery:master commit in: /, docs/
@ 2013-09-19 23:50 Jauhien Piatlicki
0 siblings, 0 replies; 6+ messages in thread
From: Jauhien Piatlicki @ 2013-09-19 23:50 UTC (permalink / raw
To: gentoo-commits
commit: 4a192ed519d0c6c7e1616d53bef4f7f81816cd96
Author: Jauhien Piatlicki (jauhien) <piatlicki <AT> gmail <DOT> com>
AuthorDate: Thu Sep 19 23:50:23 2013 +0000
Commit: Jauhien Piatlicki <piatlicki <AT> gmail <DOT> com>
CommitDate: Thu Sep 19 23:50:23 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/g-sorcery.git;a=commit;h=4a192ed5
docs/g-sorcery.cfg: man page added
---
README.md | 2 +-
docs/Makefile | 2 +-
docs/g-sorcery.8 | 2 +-
docs/g-sorcery.8.rst | 2 +-
docs/g-sorcery.cfg.8 | 74 ++++++++++++++++++++++++++++++++++++++++++++++++
docs/g-sorcery.cfg.8.rst | 59 ++++++++++++++++++++++++++++++++++++++
docs/gs-ctan.8 | 2 +-
docs/gs-ctan.8.rst | 2 +-
docs/gs-elpa.8 | 2 +-
docs/gs-elpa.8.rst | 2 +-
10 files changed, 141 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index 8efc4f5..0e26fb6 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ using **g-sorcery**.
Using **g-sorcery** with layman you can populate overlay only with packages you want.
To do so you should add a section named BACKEND (BACKEND here is the name of backend used for
your repo). In this section you can add entries named REPO_packages (REPO here is the name
-of repository you want to add) which are space separated list of packages you need. ebuilds for
+of repository you want to add) which are space separated lists of packages you need. ebuilds for
dependencies will be generated automatically if backend supports this possibility.
Note, that some overlays may depend on other overlays, in this case you'll need to add those
diff --git a/docs/Makefile b/docs/Makefile
index 19b6458..b876790 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,7 +1,7 @@
HTML_SOURCES=developer_instructions
HTML_DOCS=$(HTML_SOURCES:=.html)
-MAN_SOURCES=g-sorcery gs-elpa gs-ctan
+MAN_SOURCES=g-sorcery g-sorcery.cfg gs-elpa gs-ctan
MANS=$(MAN_SOURCES:=.8)
RST2HTML=rst2html.py
diff --git a/docs/g-sorcery.8 b/docs/g-sorcery.8
index ebd0afb..c810d57 100644
--- a/docs/g-sorcery.8
+++ b/docs/g-sorcery.8
@@ -127,7 +127,7 @@ At the moment the only package mangler \fBg\-sorcery\fP supports is \fBportage\f
.UNINDENT
.SH SEE ALSO
.sp
-\fBgs\-elpa\fP(8), \fBgs\-ctan\fP(8), \fBportage\fP(5), \fBemerge\fP(1), \fBlayman\fP(8)
+\fBg\-sorcery.cfg\fP(8), \fBgs\-elpa\fP(8), \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
diff --git a/docs/g-sorcery.8.rst b/docs/g-sorcery.8.rst
index ca529c7..72f6338 100644
--- a/docs/g-sorcery.8.rst
+++ b/docs/g-sorcery.8.rst
@@ -112,4 +112,4 @@ NOTES
SEE ALSO
========
-**gs-elpa**\(8), **gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
+**g-sorcery.cfg**\(8), **gs-elpa**\(8), **gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
diff --git a/docs/g-sorcery.cfg.8 b/docs/g-sorcery.cfg.8
new file mode 100644
index 0000000..bc55811
--- /dev/null
+++ b/docs/g-sorcery.cfg.8
@@ -0,0 +1,74 @@
+.\" Man page generated from reStructuredText.
+.
+.TH G-SORCERY.CFG 8 "2013-09-20" "0.1" "g-sorcery"
+.SH NAME
+g-sorcery.cfg \- custom settings for g-sorcery
+.
+.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
+\fB/etc/g\-sorcery/g\-sorcery.cfg\fP
+.SH DESCRIPTION
+.sp
+\fBg\-sorcery.cfg\fP various \fBg\-sorcery\fP settings aimed to be changeable by user.
+.SH SECTIONS AND VARIABLES
+.SS [main]
+.sp
+Section with common settings. Contains only one variable: \fIpackage_manager\fP.
+Currently it only can have value \fIportage\fP.
+.SS [BACKEND]
+.sp
+Section with settings for a given backend. \fBBACKEND\fP should be a backend name.
+It can contain entries named \fBREPO_packages\fP with a list of space separated names
+of packages which ebuilds should be generated for. \fBREPO\fP is a name of a repository.
+.SH EXAMPLE
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[main]
+package_manager=portage
+
+[gs\-elpa]
+marmalade_packages = clojure\-mode clojurescript\-mode
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBg\-sorcery\fP(8), \fBgs\-elpa\fP(8), \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/g-sorcery.cfg.8.rst b/docs/g-sorcery.cfg.8.rst
new file mode 100644
index 0000000..2a3b18a
--- /dev/null
+++ b/docs/g-sorcery.cfg.8.rst
@@ -0,0 +1,59 @@
+=============
+g-sorcery.cfg
+=============
+
+-----------------------------
+custom settings for g-sorcery
+-----------------------------
+
+: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-09-20
+:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2
+:Version: 0.1
+:Manual section: 8
+:Manual group: g-sorcery
+
+
+SYNOPSIS
+========
+
+**/etc/g-sorcery/g-sorcery.cfg**
+
+DESCRIPTION
+===========
+
+**g-sorcery.cfg** various **g-sorcery** settings aimed to be changeable by user.
+
+SECTIONS AND VARIABLES
+======================
+
+\[main\]
+~~~~~~~~
+Section with common settings. Contains only one variable: *package_manager*.
+Currently it only can have value *portage*.
+
+\[BACKEND\]
+~~~~~~~~~~~
+Section with settings for a given backend. **BACKEND** should be a backend name.
+It can contain entries named **REPO_packages** with a list of space separated names
+of packages which ebuilds should be generated for. **REPO** is a name of a repository.
+
+
+EXAMPLE
+=======
+
+.. code-block::
+
+ [main]
+ package_manager=portage
+
+ [gs-elpa]
+ marmalade_packages = clojure-mode clojurescript-mode
+
+
+SEE ALSO
+========
+
+**g-sorcery**\(8), **gs-elpa**\(8), **gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
diff --git a/docs/gs-ctan.8 b/docs/gs-ctan.8
index 8663647..1cbe225 100644
--- a/docs/gs-ctan.8
+++ b/docs/gs-ctan.8
@@ -142,7 +142,7 @@ At the moment the only package mangler \fBgs\-ctan\fP supports is \fBportage\fP.
.UNINDENT
.SH SEE ALSO
.sp
-\fBgs\-elpa\fP(8), \fBportage\fP(5), \fBemerge\fP(1), \fBlayman\fP(8)
+\fBgs\-elpa\fP(8), \fBg\-sorcery.cfg\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
diff --git a/docs/gs-ctan.8.rst b/docs/gs-ctan.8.rst
index e11be9b..68a749d 100644
--- a/docs/gs-ctan.8.rst
+++ b/docs/gs-ctan.8.rst
@@ -127,4 +127,4 @@ NOTES
SEE ALSO
========
-**gs-elpa**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
+**gs-elpa**\(8), **g-sorcery.cfg**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
diff --git a/docs/gs-elpa.8 b/docs/gs-elpa.8
index c64afee..2a3dfde 100644
--- a/docs/gs-elpa.8
+++ b/docs/gs-elpa.8
@@ -154,7 +154,7 @@ recommended way of using gs\-elpa is using it with layman. Even doing so you sho
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)
+\fBgs\-ctan\fP(8), \fBg\-sorcery.cfg\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
diff --git a/docs/gs-elpa.8.rst b/docs/gs-elpa.8.rst
index 4c38cb9..1104ef2 100644
--- a/docs/gs-elpa.8.rst
+++ b/docs/gs-elpa.8.rst
@@ -141,4 +141,4 @@ gnu-elpa repository: **layman -a gnu-elpa**.
SEE ALSO
========
-**gs-ctan**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
+**gs-ctan**\(8), **g-sorcery.cfg**\(8), **portage**\(5), **emerge**\(1), **layman**\(8)
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [gentoo-commits] proj/g-sorcery:master commit in: /, docs/
@ 2014-05-10 13:31 Jauhien Piatlicki
0 siblings, 0 replies; 6+ messages in thread
From: Jauhien Piatlicki @ 2014-05-10 13:31 UTC (permalink / raw
To: gentoo-commits
commit: 194ed5bae05304e7664c40110b7850b98347b64f
Author: Jauhien Piatlicki <jauhien <AT> gentoo <DOT> org>
AuthorDate: Sat May 10 13:31:10 2014 +0000
Commit: Jauhien Piatlicki <piatlicki <AT> gmail <DOT> com>
CommitDate: Sat May 10 13:31:10 2014 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/g-sorcery.git;a=commit;h=194ed5ba
0.1 release
---
README.md | 133 +++++------------------------------------------
docs/g-sorcery.8 | 4 +-
docs/g-sorcery.8.rst | 4 +-
docs/g-sorcery.cfg.8 | 4 +-
docs/g-sorcery.cfg.8.rst | 4 +-
setup.py | 4 +-
6 files changed, 24 insertions(+), 129 deletions(-)
diff --git a/README.md b/README.md
index f0070a8..9bdd5b7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,15 @@
+Usage
+=====
+
+This project is a framework, you may be interested in it only if
+you want to develop your own ebuild generator.
+
+As user you may be interested in already implemented ones:
+[gs-elpa](https://github.com/jauhien/gs-elpa) and
+[gs-pypi](https://github.com/jauhien/gs-pypi).
+
+User instructions in gs-elpa are more complete, so consult them for how to use.
+
Objective
=========
@@ -10,124 +22,7 @@ maintained ebuilds in Gentoo tree or even in overlays. Installing such
a software with its own distribution system does not seem like a good
idea, especially if one needs to install it system-wide.
-There is a number of solutions for this problem in Gentoo. But here
-another problem lies: there are special dedicated “g-helpers” for a
-number of 3rd party software providers. But, as Rafael Martins states
-“each one tries to solve the very same problems on its own unique and
-"innovative" way”. While it would be really nice to have a solid base
-framework with realization of all the basic algorithms necessary for
-ebuild and overlay generation, with uniform UI and with good
-integration with system package manager.
-
-Deliverables
-
-At the end of the project there should be a framework and number of
-backends for some of the 3rd party software providers. This framework
-should make writing of those g-helpers easier and regular.
-
-At the moment I see this framework as a number of classes in Python
-that can be inherited and expanded in backends with the specific
-logic. All the logic related to the interaction with user, portage and
-overlay tools should be implemented in the framework and normally
-should not be changed by backends. Integration with system may need
-patching of some existing tools (like layman).
-
-Framework should have: - basic logic for ebuild and overlay
-manipulation, dependencies resolving, patching and so on - cli, that
-allows users to generate separate ebuilds and even overlays with
-available backends - integration with other system tools (I mean
-layman, as I'm not really familiar with tools used by other package
-manglers. But supporting them would be a good idea as well).
-
-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.
-
-Installation and using
-======================
-
-You will need **app-portage/layman-9999** (when you emerge a backend you are
-interested in it will be pulled in authomatically).
-
-Add `jauhien` overlay: **layman -a jauhien**.
-
-Currently 2 backends are available: **gs-elpa** and **gs-pypi**.
-
-Here is an example of using gs-elpa backend.
-
-Emerge backend you want to use: **emerge -va gs-elpa**.
-
-There are two ways of using **gs-elpa**:
-
-* use it with **layman**
-
-In this case all you need to do is install **layman-9999** and **g-sorcery**.
-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 **g-sorcery**.
-
-Using **g-sorcery** with layman you can populate overlay only with packages you want.
-To do so you should add a section named BACKEND (BACKEND here is the name of backend used for
-your repo). In this section you can add entries named REPO_packages (REPO here is the name
-of repository you want to add) which are space separated lists of packages you need. ebuilds for
-dependencies will be generated automatically if backend supports this possibility.
-
-Note, that some overlays may depend on other overlays, in this case you'll need to add those
-dependencies first.
-
-
-* 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**
-
-To generate only ebuilds we need such a */etc/g-sorcery/g-sorcery.cfg* file can be used:
-
-```
-[main]
-package_manager=portage
-
-[gs-elpa]
-marmalade_packages = clojure-mode clojurescript-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-pypi** for further information.
+This project is aimed to create a framework for ebuild-generators for
+3rd party software providers.
If you want to develop a new backend see [developer's instructions](https://github.com/jauhien/g-sorcery/blob/master/docs/developer_instructions.rst).
diff --git a/docs/g-sorcery.8 b/docs/g-sorcery.8
index 066e35b..1d2f353 100644
--- a/docs/g-sorcery.8
+++ b/docs/g-sorcery.8
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH G-SORCERY 8 "2013-08-04" "0.1" "g-sorcery"
+.TH G-SORCERY 8 "2014-05-10" "0.1" "g-sorcery"
.SH NAME
g-sorcery \- manage overlays for 3rd party software providers
.
@@ -133,6 +133,6 @@ Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea
and mentorship by Rafael Martins. Lots of help and improvements
by Brian Dolbec. Integration with layman based on work of Auke Booij.
.SH COPYRIGHT
-Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2
+Copyright (c) 2013-2014 Jauhien Piatlicki, License: GPL-2
.\" Generated by docutils manpage writer.
.
diff --git a/docs/g-sorcery.8.rst b/docs/g-sorcery.8.rst
index 9ea702f..86f7e66 100644
--- a/docs/g-sorcery.8.rst
+++ b/docs/g-sorcery.8.rst
@@ -9,8 +9,8 @@ manage overlays for 3rd party software providers
:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea
and mentorship by Rafael Martins. Lots of help and improvements
by Brian Dolbec. Integration with layman based on work of Auke Booij.
-:Date: 2013-08-04
-:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2
+:Date: 2014-05-10
+:Copyright: Copyright (c) 2013-2014 Jauhien Piatlicki, License: GPL-2
:Version: 0.1
:Manual section: 8
:Manual group: g-sorcery
diff --git a/docs/g-sorcery.cfg.8 b/docs/g-sorcery.cfg.8
index 1643315..9167c29 100644
--- a/docs/g-sorcery.cfg.8
+++ b/docs/g-sorcery.cfg.8
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH G-SORCERY.CFG 8 "2013-09-20" "0.1" "g-sorcery"
+.TH G-SORCERY.CFG 8 "2014-05-10" "0.1" "g-sorcery"
.SH NAME
g-sorcery.cfg \- custom settings for g-sorcery
.
@@ -69,6 +69,6 @@ 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
+Copyright (c) 2013-2014 Jauhien Piatlicki, License: GPL-2
.\" Generated by docutils manpage writer.
.
diff --git a/docs/g-sorcery.cfg.8.rst b/docs/g-sorcery.cfg.8.rst
index 7f9790f..930b4db 100644
--- a/docs/g-sorcery.cfg.8.rst
+++ b/docs/g-sorcery.cfg.8.rst
@@ -9,8 +9,8 @@ custom settings for g-sorcery
: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-09-20
-:Copyright: Copyright (c) 2013 Jauhien Piatlicki, License: GPL-2
+:Date: 2014-05-10
+:Copyright: Copyright (c) 2013-2014 Jauhien Piatlicki, License: GPL-2
:Version: 0.1
:Manual section: 8
:Manual group: g-sorcery
diff --git a/setup.py b/setup.py
index 9517fdc..015ec76 100644
--- a/setup.py
+++ b/setup.py
@@ -3,8 +3,8 @@
from distutils.core import setup
setup(name = 'g-sorcery',
- version = '0.1_alpha',
- description = 'g-sorcery framework for automated ebuild generators',
+ version = '0.1',
+ description = 'framework for automated ebuild generators',
author = 'Jauhien Piatlicki',
author_email = 'jauhien@gentoo.org',
packages = ['g_sorcery', 'gs_db_tool'],
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [gentoo-commits] proj/g-sorcery:master commit in: /, docs/
@ 2023-02-24 17:38 Ulrich Müller
0 siblings, 0 replies; 6+ messages in thread
From: Ulrich Müller @ 2023-02-24 17:38 UTC (permalink / raw
To: gentoo-commits
commit: 651199686a7f167adab3fda6e2a843a34539dd04
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Feb 24 17:36:45 2023 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Feb 24 17:36:45 2023 +0000
URL: https://gitweb.gentoo.org/proj/g-sorcery.git/commit/?id=65119968
0.2.3 release
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
docs/g-sorcery.8 | 2 +-
docs/g-sorcery.8.rst | 4 ++--
docs/g-sorcery.cfg.8 | 2 +-
docs/g-sorcery.cfg.8.rst | 4 ++--
setup.py | 2 +-
5 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/docs/g-sorcery.8 b/docs/g-sorcery.8
index f1778a6..1f40b30 100644
--- a/docs/g-sorcery.8
+++ b/docs/g-sorcery.8
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH G-SORCERY 8 "2021-05-04" "0.2.2" "g-sorcery"
+.TH G-SORCERY 8 "2023-02-24" "0.2.3" "g-sorcery"
.SH NAME
g-sorcery \- manage overlays for 3rd party software providers
.
diff --git a/docs/g-sorcery.8.rst b/docs/g-sorcery.8.rst
index 9c2ced7..63bac6f 100644
--- a/docs/g-sorcery.8.rst
+++ b/docs/g-sorcery.8.rst
@@ -9,10 +9,10 @@ manage overlays for 3rd party software providers
:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea
and mentorship by Rafael Martins. Lots of help and improvements
by Brian Dolbec. Integration with layman based on work of Auke Booij.
-:Date: 2021-05-04
+:Date: 2023-02-24
:Copyright: Copyright (c) 2013-2021 Jauhien Piatlicki and others,
License: GPL-2
-:Version: 0.2.2
+:Version: 0.2.3
:Manual section: 8
:Manual group: g-sorcery
diff --git a/docs/g-sorcery.cfg.8 b/docs/g-sorcery.cfg.8
index a6ac615..993c0bb 100644
--- a/docs/g-sorcery.cfg.8
+++ b/docs/g-sorcery.cfg.8
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH G-SORCERY.CFG 8 "2021-05-04" "0.2.2" "g-sorcery"
+.TH G-SORCERY.CFG 8 "2023-02-24" "0.2.3" "g-sorcery"
.SH NAME
g-sorcery.cfg \- custom settings for g-sorcery
.
diff --git a/docs/g-sorcery.cfg.8.rst b/docs/g-sorcery.cfg.8.rst
index 0aa61bf..e7f376a 100644
--- a/docs/g-sorcery.cfg.8.rst
+++ b/docs/g-sorcery.cfg.8.rst
@@ -9,10 +9,10 @@ custom settings for g-sorcery
:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea
and mentorship by Rafael Martins. Lots of help and improvements
by Brian Dolbec.
-:Date: 2021-05-04
+:Date: 2023-02-24
:Copyright: Copyright (c) 2013-2021 Jauhien Piatlicki and others,
License: GPL-2
-:Version: 0.2.2
+:Version: 0.2.3
:Manual section: 8
:Manual group: g-sorcery
diff --git a/setup.py b/setup.py
index 85e20a5..0fd4dea 100644
--- a/setup.py
+++ b/setup.py
@@ -29,7 +29,7 @@ for mod in SELECTABLE:
optional_modules.append('g_sorcery.%s' % SELECTABLE[mod])
setup(name = 'g-sorcery',
- version = '0.2.2',
+ version = '0.2.3',
description = 'framework for automated ebuild generators',
author = 'Jauhien Piatlicki',
author_email = 'jauhien@gentoo.org',
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [gentoo-commits] proj/g-sorcery:master commit in: /, docs/
@ 2023-02-24 18:02 Ulrich Müller
0 siblings, 0 replies; 6+ messages in thread
From: Ulrich Müller @ 2023-02-24 18:02 UTC (permalink / raw
To: gentoo-commits
commit: 7ff05812a4c6d385940ad301abef7d81aace7aec
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Feb 24 18:02:18 2023 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Feb 24 18:02:18 2023 +0000
URL: https://gitweb.gentoo.org/proj/g-sorcery.git/commit/?id=7ff05812
0.2.3 release
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
docs/g-sorcery.8 | 2 +-
docs/g-sorcery.8.rst | 4 ++--
docs/g-sorcery.cfg.8 | 2 +-
docs/g-sorcery.cfg.8.rst | 4 ++--
setup.py | 2 +-
5 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/docs/g-sorcery.8 b/docs/g-sorcery.8
index f1778a6..1f40b30 100644
--- a/docs/g-sorcery.8
+++ b/docs/g-sorcery.8
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH G-SORCERY 8 "2021-05-04" "0.2.2" "g-sorcery"
+.TH G-SORCERY 8 "2023-02-24" "0.2.3" "g-sorcery"
.SH NAME
g-sorcery \- manage overlays for 3rd party software providers
.
diff --git a/docs/g-sorcery.8.rst b/docs/g-sorcery.8.rst
index 9c2ced7..63bac6f 100644
--- a/docs/g-sorcery.8.rst
+++ b/docs/g-sorcery.8.rst
@@ -9,10 +9,10 @@ manage overlays for 3rd party software providers
:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea
and mentorship by Rafael Martins. Lots of help and improvements
by Brian Dolbec. Integration with layman based on work of Auke Booij.
-:Date: 2021-05-04
+:Date: 2023-02-24
:Copyright: Copyright (c) 2013-2021 Jauhien Piatlicki and others,
License: GPL-2
-:Version: 0.2.2
+:Version: 0.2.3
:Manual section: 8
:Manual group: g-sorcery
diff --git a/docs/g-sorcery.cfg.8 b/docs/g-sorcery.cfg.8
index a6ac615..993c0bb 100644
--- a/docs/g-sorcery.cfg.8
+++ b/docs/g-sorcery.cfg.8
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH G-SORCERY.CFG 8 "2021-05-04" "0.2.2" "g-sorcery"
+.TH G-SORCERY.CFG 8 "2023-02-24" "0.2.3" "g-sorcery"
.SH NAME
g-sorcery.cfg \- custom settings for g-sorcery
.
diff --git a/docs/g-sorcery.cfg.8.rst b/docs/g-sorcery.cfg.8.rst
index 0aa61bf..e7f376a 100644
--- a/docs/g-sorcery.cfg.8.rst
+++ b/docs/g-sorcery.cfg.8.rst
@@ -9,10 +9,10 @@ custom settings for g-sorcery
:Author: Written by Jauhien Piatlicki <piatlicki@gmail.com>. GSoC idea
and mentorship by Rafael Martins. Lots of help and improvements
by Brian Dolbec.
-:Date: 2021-05-04
+:Date: 2023-02-24
:Copyright: Copyright (c) 2013-2021 Jauhien Piatlicki and others,
License: GPL-2
-:Version: 0.2.2
+:Version: 0.2.3
:Manual section: 8
:Manual group: g-sorcery
diff --git a/setup.py b/setup.py
index 85e20a5..0fd4dea 100644
--- a/setup.py
+++ b/setup.py
@@ -29,7 +29,7 @@ for mod in SELECTABLE:
optional_modules.append('g_sorcery.%s' % SELECTABLE[mod])
setup(name = 'g-sorcery',
- version = '0.2.2',
+ version = '0.2.3',
description = 'framework for automated ebuild generators',
author = 'Jauhien Piatlicki',
author_email = 'jauhien@gentoo.org',
^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2023-02-24 18:02 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-09-19 23:50 [gentoo-commits] proj/g-sorcery:master commit in: /, docs/ Jauhien Piatlicki
-- strict thread matches above, loose matches on Subject: below --
2023-02-24 18:02 Ulrich Müller
2023-02-24 17:38 Ulrich Müller
2014-05-10 13:31 Jauhien Piatlicki
2013-08-29 1:12 Jauhien Piatlicki
2013-08-06 20:09 Jauhien Piatlicki
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox