Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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