Skip to content

HTTPS clone URL

Subversion checkout URL

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