Skip to content
Newer
Older
100644 256 lines (202 sloc) 10.5 KB
2f3d20a @yrashk Added README.md
yrashk authored Jan 26, 2011
1 Agner
2 =====
3
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
4 Agner is a rebar-friendly Erlang package index inspired by Clojars and
5 Homebrew.
6
7 Essentially, Agner is an index of Erlang packages with some extra
8 capabilities such as versioning, downloads and so on.
9
10 Agner is a shorthand for *A Giant Nebula of Erlang Repositories*. It
11 also pays homage to the Danish statistician "Agner Krarup Erlang".
12
13 Motivation
14 ----------
15
16 By now, there is a large set of Erlang tools and libraries out there,
17 all of them highly useful. The problem however is to provide an index
18 of these packages, so other people
19
20 * Know of their existence
21 * Can easily use a package in their own projects
22
23 Agner aims to provide such an index, by focusing on a number of
24 points:
25
26 * The index is loose in the sense that anyone can overlay the index
27 and add their own packages to the repository
28 * The tool is as simple as possible, utilizing git (for the time
29 being) to maintain the indexes
30 * Recognize the ideas of simplicity Joe Armstrong had in mind on
31 the erlang-questions@ mailing list the
32 [22-Jul-2010](http://www.erlang.org/cgi-bin/ezmlm-cgi?4:mss:52415:201007:npnohnblfemjooohecnk)
33
34 Use
35 ===
36
37 This section introduces the terminology of Agner:
38
39 * **index/indices:** Where Agner finds its package index. Usually this
40 is a github user with one or more packages among the users git
41 repositories.
42 * **package:** A separate library or program indentified by the
43 index. It is a `.agner` repository underneath the index-user, so one
44 example would be `agner/gproc.agner` specifying a package for the
45 `gproc` library undernath the `agner`-user.
46 * **project:** A software project, program or library, that contains
47 the actual source code for the program or library. In the example,
48 this is `esl/gproc` on github.
49 * **release:** A release of a package signifying a point in time
50 where the package was deemed to be in a certain state. Is usually
51 used when a new version of the software is released to the
52 general public so you can refer to package X version Y
53 * **flavour:** A moving target of a package with some specified
54 behaviour. It is used for tracking the development of a package
55 over time. Common flavours include the *@master* flavour, used to
56 track the development branch of a package and the *@release*
57 flavour, used to track the latest release of the package.
58
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored Jan 27, 2011
59 Command invocation
60 ------------------
61
62 agner list [-d/--descriptions]
63
64 Will list all agner-packages. With the `-d` or `--descriptions`
65 option, it will also print out the descriptions of the packages, for
66 easy grepping to find relevant packages.
67
7e7089d @yrashk Added -b/--browser option that will open browser to show the specific…
yrashk authored Jan 27, 2011
68 agner spec PACKAGE [-v/--version package_version] [-b/--browser]
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored Jan 27, 2011
69
70 Will print a specification of a given package on stdout. If the
71 optional version constraint is given (for example `agner spec gproc -v
72 @release`) then the output is of that version. By default, the
73 `@master` flavour is chosen.
74
7e7089d @yrashk Added -b/--browser option that will open browser to show the specific…
yrashk authored Jan 27, 2011
75 If `-b` or `--browser` is used, it will also open browser with the specification
76 file in its respective `.agner` repository.
77
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored Jan 27, 2011
78 agner fetch PACKAGE [DESTDIR] [-v/--version package_version]
79
80 Fetch a given `PACKAGE` to either the current directory or,
81 optionally, to the `DESTDIR` directory. The version constraint is as
82 were the case for `agner spec`.
83
84 agner versions PACKAGE
85
86 List the versions of the given `PACKAGE`
87
88 Packaging
89 =========
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
90
91 Package organization
92 --------------------
93
94 When Agner is invoked, it will scan its *indices* for package
95 lists. The default index is "agner", which is located at
96 [https://github.com/agner/](https://github.com/agner/). The index is
97 scanned by looking for *Agner repositories* which are normal (github)
98 repositories suffixed with `.agner`. An example is the repository
99 [https://github.com/agner/getopt.agner](https://github.com/agner/getopt.agner)
100 which contains the package details of the `getopt` package.
101
102 It is important to nail down that there are three balls in the air:
103
104 * The index user, who has a list of
105 * `.agner` repositories, which points to
106 * Erlang software projects
107
108 By making a split between the repository containing the project and
109 the repository containing the package, we make it easy to identify
110 `.agner` repositories, and we enable a simple way to make the project
111 live in another source control system, for instance Mercurial (hg). It
112 is also way easier to keep the (small) `.agner` repositories in an
113 index and in the long run, it provisions for local caching.
114
115 Further indices can be added to Agner through the environment (TODO:
116 flesh out how that is done). Indices are searched
117 in the order of specification, allowing for overriding of a given
118 index. This allows you to create local indices or special indices for
119 your own use, or try something out on top of other indices.
120
121 The multiple indices approach solves authorization questions by solving it
122 "the git way". You put trust in the indices you add to Agner, so if
123 you don't trust an index, you can simply refrain from adding it. The
124 main "agner" index is intended to be the official source, but we
125 recognize that individuals might have reasons to overlay another index
126 on top. By having a loose index-construction, we hope to alleviate
127 some of the problems with access rights.
2f3d20a @yrashk Added README.md
yrashk authored Jan 27, 2011
128
93546e5 @yrashk A little bit more information in the README.md
yrashk authored Jan 26, 2011
129 Package names
130 -------------
131
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
132 Package name is just either a package name such as
60b4def @yrashk Merge branch 'readme-flesh' of https://github.com/jlouis/agner into j…
yrashk authored Jan 27, 2011
133 <code>mochiweb</code>, or (in case of github indices, it might also
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
134 take a form of <code>account/package</code>, for example
135 <code>yrashk/misultin</code>). We use package names to identify a
136 given package in Agner - but versions of the package is naturally not
137 part of its name. This allows for packages to exist in multiple
138 versions at a time.
93546e5 @yrashk A little bit more information in the README.md
yrashk authored Jan 27, 2011
139
140 Versions
141 --------
142
143 Agner has two kinds of versions:
144
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
145 * Release versions, normally something like <code>1.2.0</code>,
146 represented using tags in `.agner` repos.
147 * Flavour versions, normally something like <code>@release</code>,
148 represented using branches in `.agner` repos. Note the prefix of "@".
149
150 The intention is that a *release* version marks a given point in time
151 where a given version of the code base was released to the general
152 public. When Erlang/OTP is released as OTP-R14B01 for instance, it
153 signifies a *release* in Agner-terminology. On the other hand, a
154 *flavour* signifies a moving target. Continuing the OTP-R14B01
155 example from before, it would be natural to have a *@dev* flavour
156 which tracks the Erlang/OTP branch called `dev`. The other important
157 flavour is *@release* which will track the latest release.
158
159 ### How to create relases and flavours
160
161 As hinted, a release version is a *tag* in a `.agner` repository. So
162 to create a release, you alter the `.agner` repository to match your
163 liking and then you tag it (with a standard `git tag` command
164 invocation). Agner will now pick up the change.
165
166 Likewise, for a flavour version, you *branch* the `.agner` repository
167 and alter the branch so it does what your flavour intended to
168 do. Flavours can be made for anything you would like to track over
169 time. By default, the advice is to create two flavours, *@master* and
170 *@release* tracking, respectively, the current development of a
171 project and the latest stable release of that project.
172
173 Keeping everything up-to-date is now outsourced to git and you can use
174 usual git-commands to manipulate the `.agner` repository.
175
176 ### The contents of an .agner package
177
178 The `.agner` package repository contains a file of Erlang-terms, called
179 `agner.config`. This file looks like this:
180
181 {name, "etorrent"}.
182 {authors, ["Jesper Louis Andersen <jesper.louis.andersen@gmail.com>"]}.
183 {description, "Etorrent is a bittorrent client implementation in Erlang focusing on fault-tolerance"}.
184 {homepage, "http://github.com/jlouis/etorrent"}.
185 {rebar_compatible, true}.
186 {license, "BSD2", "COPYING"}.
187 {erlang_versions, [otp_r14b, otp_r14b01, otp_r13b04]}.
188 {url, {git, "https://github.com/jlouis/etorrent.git", {branch, "master"}}}.
189
190 Or in a more generic way:
191
192 {name, ProjectName}.
193 {authors, [Author]}.
194 {description, ProjectDescription}.
195 {homepage, ProjectHomepage}.
196 {rebar_compatible, IsRebarCompatible}.
b2cf7aa @yrashk Minor update on optionality of LicenseFile in the spec (README.md)
yrashk authored Jan 27, 2011
197 {license, LicenseType [, LicenseFile]}.
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
198 {erlang_versions, [OTPAtom]}.
199 {url, UrlSpec}.
200
201 * `ProjectName :: string()` - is the project name. This is usually
202 named the same as the `.agner` package to minimize confusion.
203 * `[Author] :: [string()]` - Can really be any string, but it is
204 usually the names of the project authors in a list including their
205 email-addresses for easy contact.
206 * `ProjectDescription :: string()` - A description of the
207 project. Used for searching through projects.
208 * `ProjectHomepage :: string()` - The URL of the homepage of the
209 project.
210 * `IsRebarCompatible :: boolean()` - Set to `true` if this project
2569b0a @yrashk Minor update on rebar_compatible in README.md
yrashk authored Jan 27, 2011
211 uses `rebar` or is compilable by rebar even if it wasn't originally designed for that.
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
212 * `LicenseType :: string(), LicenseFile :: string()` - Two
213 strings. The first one specifies the general license type of the
214 project and the second string explains where the license is to be
215 found from the top level directory (usually file-names like
b2cf7aa @yrashk Minor update on optionality of LicenseFile in the spec (README.md)
yrashk authored Jan 27, 2011
216 `COPYING` or `LICENSE` are used for this). Please note that `LicenseFile` is optional.
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
217 * `[OTPAtom] :: [otp_rXXb | otp_rXXbYY]` - A list of what OTP versions
218 the project can be used with. the `XX` is a major release number in
219 Erlang/OTP (12,13,14,...) and `YY` is a minor release number (01,
220 02, ...).
221 * `UrlSpec :: {git, URL, GitSpec}` - Specifies where to fetch the
8c1d1cb @yrashk Minor update for 'git' URL format in README.md
yrashk authored Jan 27, 2011
222 project. `GitSpec` has type `sha1() | {tag, string()} | {branch, string()}`
223 and points to either string-based sha1 representation, a git *tag* or a *git* branch
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
224 respectively. Notice that you can't specify more than one target in
225 this file. To handle multiple versions, you use *releases* and
226 *flavours* by altering the `.agner` repository wherein this
227 configuration file lies.
1341a02 @yrashk Added mentioning of {hg, URL, Rev} URL format in README.md
yrashk authored Jan 27, 2011
228 * `UrlSpec :: {hg, URL, HgRev}` - Specifies where to fetch the
229 project. `HgSpec` has type `string()` and points to either string-based revision representation
93546e5 @yrashk A little bit more information in the README.md
yrashk authored Jan 27, 2011
230
2f3d20a @yrashk Added README.md
yrashk authored Jan 27, 2011
231 Rebar
232 -----
233
be9362f @jlouis Add more description to the README file.
jlouis authored Jan 27, 2011
234 Agner-compatible rebar is available at
235 [agner branch](https://github.com/agner/rebar/tree/agner) of
236 [agner/rebar](https://github.com/agner/rebar). Or you can download
237 ready-made rebar from
238 [agner itself](https://github.com/agner/agner/raw/master/rebar). We
239 hope to get rebar integration in the upstream with time.
2f3d20a @yrashk Added README.md
yrashk authored Jan 27, 2011
240
241 Using it with rebar is fairly simple, it uses rebar's deps feature:
242
a26465d @yrashk Markup update in README.md
yrashk authored Jan 26, 2011
243 {deps, [
244 {typespecs, "0.1", {agner, "typespecs"}},
245 {getopt, "0.3.0", {agner, "getopt"}}
246 ]}.
2f3d20a @yrashk Added README.md
yrashk authored Jan 27, 2011
247
fec3baa @yrashk Typo fix
yrashk authored Jan 26, 2011
248 You can also specify your own indices:
2f3d20a @yrashk Added README.md
yrashk authored Jan 27, 2011
249
a26465d @yrashk Markup update in README.md
yrashk authored Jan 27, 2011
250 {agner_indices, [{github, "yourgithubusername"},{github,"agner"}].
2f3d20a @yrashk Added README.md
yrashk authored Jan 27, 2011
251
ca3ad6d @yrashk Added Contributing article link to README.md
yrashk authored Jan 26, 2011
252 Contributing
253 ------------
254
f4ea6b1 @yrashk Typo fix in README.md
yrashk authored Jan 27, 2011
255 Please read at the [wiki](https://github.com/agner/agner/wiki/Contributing).
Something went wrong with that request. Please try again.