Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 267 lines (210 sloc) 11.216 kb
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
1 Agner
2 =====
3
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
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
163e7a1 Yurii Rashkovskii Removed quotes around Agner Krarup's name (README.md)
yrashk authored
11 also pays homage to the Danish statistician Agner Krarup Erlang.
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
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 Jesper Louis Andersen Re-order the sections in the README.md file.
jlouis authored
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
68c3040 Yurii Rashkovskii Added -h/--homepage command line option for showing homepage in the brow...
yrashk authored
68 agner spec PACKAGE [-v/--version package_version] [-b/--browser]
69 [-h/--homepage]
e74c3fa Jesper Louis Andersen Re-order the sections in the README.md file.
jlouis authored
70
71 Will print a specification of a given package on stdout. If the
72 optional version constraint is given (for example `agner spec gproc -v
73 @release`) then the output is of that version. By default, the
74 `@master` flavour is chosen.
75
7e7089d Yurii Rashkovskii Added -b/--browser option that will open browser to show the specificati...
yrashk authored
76 If `-b` or `--browser` is used, it will also open browser with the specification
77 file in its respective `.agner` repository.
78
68c3040 Yurii Rashkovskii Added -h/--homepage command line option for showing homepage in the brow...
yrashk authored
79 If `-h` or `--homepage` is present, it will also open browser with the package's
80 homepage.
81
e74c3fa Jesper Louis Andersen Re-order the sections in the README.md file.
jlouis authored
82 agner fetch PACKAGE [DESTDIR] [-v/--version package_version]
83
84 Fetch a given `PACKAGE` to either the current directory or,
85 optionally, to the `DESTDIR` directory. The version constraint is as
86 were the case for `agner spec`.
87
88 agner versions PACKAGE
89
90 List the versions of the given `PACKAGE`
91
1bb458c Yurii Rashkovskii Added 'verify' command line command
yrashk authored
92 agner verify [SPEC FILENAME (agner.config by default)]
93
94 Verify specification file for correctness; intended to be used to package maintainers to simplify
95 their workflow. Currently checks whether 1) specification is a valid file that can be parsed,
96 2) the URL can be fetched. In the future it will also offer a deeper analysis of specification
97 correctness.
98
e74c3fa Jesper Louis Andersen Re-order the sections in the README.md file.
jlouis authored
99 Packaging
100 =========
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
101
102 Package organization
103 --------------------
104
105 When Agner is invoked, it will scan its *indices* for package
106 lists. The default index is "agner", which is located at
107 [https://github.com/agner/](https://github.com/agner/). The index is
108 scanned by looking for *Agner repositories* which are normal (github)
109 repositories suffixed with `.agner`. An example is the repository
110 [https://github.com/agner/getopt.agner](https://github.com/agner/getopt.agner)
111 which contains the package details of the `getopt` package.
112
113 It is important to nail down that there are three balls in the air:
114
115 * The index user, who has a list of
116 * `.agner` repositories, which points to
117 * Erlang software projects
118
119 By making a split between the repository containing the project and
120 the repository containing the package, we make it easy to identify
121 `.agner` repositories, and we enable a simple way to make the project
122 live in another source control system, for instance Mercurial (hg). It
123 is also way easier to keep the (small) `.agner` repositories in an
124 index and in the long run, it provisions for local caching.
125
126 Further indices can be added to Agner through the environment (TODO:
127 flesh out how that is done). Indices are searched
128 in the order of specification, allowing for overriding of a given
129 index. This allows you to create local indices or special indices for
130 your own use, or try something out on top of other indices.
131
132 The multiple indices approach solves authorization questions by solving it
133 "the git way". You put trust in the indices you add to Agner, so if
134 you don't trust an index, you can simply refrain from adding it. The
135 main "agner" index is intended to be the official source, but we
136 recognize that individuals might have reasons to overlay another index
137 on top. By having a loose index-construction, we hope to alleviate
138 some of the problems with access rights.
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
139
93546e5 Yurii Rashkovskii A little bit more information in the README.md
yrashk authored
140 Package names
141 -------------
142
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
143 Package name is just either a package name such as
60b4def Yurii Rashkovskii Merge branch 'readme-flesh' of https://github.com/jlouis/agner into jlou...
yrashk authored
144 <code>mochiweb</code>, or (in case of github indices, it might also
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
145 take a form of <code>account/package</code>, for example
146 <code>yrashk/misultin</code>). We use package names to identify a
147 given package in Agner - but versions of the package is naturally not
148 part of its name. This allows for packages to exist in multiple
149 versions at a time.
93546e5 Yurii Rashkovskii A little bit more information in the README.md
yrashk authored
150
151 Versions
152 --------
153
154 Agner has two kinds of versions:
155
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
156 * Release versions, normally something like <code>1.2.0</code>,
157 represented using tags in `.agner` repos.
158 * Flavour versions, normally something like <code>@release</code>,
159 represented using branches in `.agner` repos. Note the prefix of "@".
160
161 The intention is that a *release* version marks a given point in time
162 where a given version of the code base was released to the general
163 public. When Erlang/OTP is released as OTP-R14B01 for instance, it
164 signifies a *release* in Agner-terminology. On the other hand, a
165 *flavour* signifies a moving target. Continuing the OTP-R14B01
166 example from before, it would be natural to have a *@dev* flavour
167 which tracks the Erlang/OTP branch called `dev`. The other important
168 flavour is *@release* which will track the latest release.
169
170 ### How to create relases and flavours
171
172 As hinted, a release version is a *tag* in a `.agner` repository. So
173 to create a release, you alter the `.agner` repository to match your
174 liking and then you tag it (with a standard `git tag` command
175 invocation). Agner will now pick up the change.
176
177 Likewise, for a flavour version, you *branch* the `.agner` repository
178 and alter the branch so it does what your flavour intended to
179 do. Flavours can be made for anything you would like to track over
180 time. By default, the advice is to create two flavours, *@master* and
181 *@release* tracking, respectively, the current development of a
182 project and the latest stable release of that project.
183
184 Keeping everything up-to-date is now outsourced to git and you can use
185 usual git-commands to manipulate the `.agner` repository.
186
187 ### The contents of an .agner package
188
189 The `.agner` package repository contains a file of Erlang-terms, called
190 `agner.config`. This file looks like this:
191
192 {name, "etorrent"}.
193 {authors, ["Jesper Louis Andersen <jesper.louis.andersen@gmail.com>"]}.
194 {description, "Etorrent is a bittorrent client implementation in Erlang focusing on fault-tolerance"}.
195 {homepage, "http://github.com/jlouis/etorrent"}.
196 {rebar_compatible, true}.
197 {license, "BSD2", "COPYING"}.
198 {erlang_versions, [otp_r14b, otp_r14b01, otp_r13b04]}.
199 {url, {git, "https://github.com/jlouis/etorrent.git", {branch, "master"}}}.
200
201 Or in a more generic way:
202
203 {name, ProjectName}.
204 {authors, [Author]}.
205 {description, ProjectDescription}.
206 {homepage, ProjectHomepage}.
207 {rebar_compatible, IsRebarCompatible}.
b2cf7aa Yurii Rashkovskii Minor update on optionality of LicenseFile in the spec (README.md)
yrashk authored
208 {license, LicenseType [, LicenseFile]}.
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
209 {erlang_versions, [OTPAtom]}.
210 {url, UrlSpec}.
211
212 * `ProjectName :: string()` - is the project name. This is usually
213 named the same as the `.agner` package to minimize confusion.
214 * `[Author] :: [string()]` - Can really be any string, but it is
215 usually the names of the project authors in a list including their
216 email-addresses for easy contact.
217 * `ProjectDescription :: string()` - A description of the
218 project. Used for searching through projects.
219 * `ProjectHomepage :: string()` - The URL of the homepage of the
220 project.
221 * `IsRebarCompatible :: boolean()` - Set to `true` if this project
2569b0a Yurii Rashkovskii Minor update on rebar_compatible in README.md
yrashk authored
222 uses `rebar` or is compilable by rebar even if it wasn't originally designed for that.
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
223 * `LicenseType :: string(), LicenseFile :: string()` - Two
224 strings. The first one specifies the general license type of the
225 project and the second string explains where the license is to be
226 found from the top level directory (usually file-names like
b2cf7aa Yurii Rashkovskii Minor update on optionality of LicenseFile in the spec (README.md)
yrashk authored
227 `COPYING` or `LICENSE` are used for this). Please note that `LicenseFile` is optional.
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
228 * `[OTPAtom] :: [otp_rXXb | otp_rXXbYY]` - A list of what OTP versions
229 the project can be used with. the `XX` is a major release number in
230 Erlang/OTP (12,13,14,...) and `YY` is a minor release number (01,
231 02, ...).
232 * `UrlSpec :: {git, URL, GitSpec}` - Specifies where to fetch the
8c1d1cb Yurii Rashkovskii Minor update for 'git' URL format in README.md
yrashk authored
233 project. `GitSpec` has type `sha1() | {tag, string()} | {branch, string()}`
234 and points to either string-based sha1 representation, a git *tag* or a *git* branch
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
235 respectively. Notice that you can't specify more than one target in
236 this file. To handle multiple versions, you use *releases* and
237 *flavours* by altering the `.agner` repository wherein this
238 configuration file lies.
1341a02 Yurii Rashkovskii Added mentioning of {hg, URL, Rev} URL format in README.md
yrashk authored
239 * `UrlSpec :: {hg, URL, HgRev}` - Specifies where to fetch the
240 project. `HgSpec` has type `string()` and points to either string-based revision representation
93546e5 Yurii Rashkovskii A little bit more information in the README.md
yrashk authored
241
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
242 Rebar
243 -----
244
be9362f Jesper Louis Andersen Add more description to the README file.
jlouis authored
245 Agner-compatible rebar is available at
246 [agner branch](https://github.com/agner/rebar/tree/agner) of
247 [agner/rebar](https://github.com/agner/rebar). Or you can download
248 ready-made rebar from
249 [agner itself](https://github.com/agner/agner/raw/master/rebar). We
250 hope to get rebar integration in the upstream with time.
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
251
252 Using it with rebar is fairly simple, it uses rebar's deps feature:
253
a26465d Yurii Rashkovskii Markup update in README.md
yrashk authored
254 {deps, [
255 {typespecs, "0.1", {agner, "typespecs"}},
256 {getopt, "0.3.0", {agner, "getopt"}}
257 ]}.
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
258
fec3baa Yurii Rashkovskii Typo fix
yrashk authored
259 You can also specify your own indices:
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
260
a26465d Yurii Rashkovskii Markup update in README.md
yrashk authored
261 {agner_indices, [{github, "yourgithubusername"},{github,"agner"}].
2f3d20a Yurii Rashkovskii Added README.md
yrashk authored
262
ca3ad6d Yurii Rashkovskii Added Contributing article link to README.md
yrashk authored
263 Contributing
264 ------------
265
f4ea6b1 Yurii Rashkovskii Typo fix in README.md
yrashk authored
266 Please read at the [wiki](https://github.com/agner/agner/wiki/Contributing).
Something went wrong with that request. Please try again.