Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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