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