Skip to content

HTTPS clone URL

Subversion checkout URL

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