Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 357 lines (271 sloc) 15.801 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
b951250 @yrashk Added installation instructions
yrashk authored
13 Installation
14 ------------
15
16 In order to install, simply run `make` and `make install` (it will
6dd50f9 @yrashk Minor markup improvements in README.md
yrashk authored
17 install to `/usr/local/bin`).
18
19 If you are a **Homebrew** user on **OS X**,
b951250 @yrashk Added installation instructions
yrashk authored
20 feel free to use it:
21 `brew install https://github.com/agner/homebrew/raw/master/Library/Formula/agner.rb`
22 or `brew --HEAD https://github.com/agner/homebrew/raw/master/Library/Formula/agner.rb`
23 (if you want the very best and newest).
24 As of the time of this writing, agner formula hasn't been merged into the official repo yet.
25
be9362f @jlouis Add more description to the README file.
jlouis authored
26 Motivation
27 ----------
28
29 By now, there is a large set of Erlang tools and libraries out there,
30 all of them highly useful. The problem however is to provide an index
31 of these packages, so other people
32
33 * Know of their existence
34 * Can easily use a package in their own projects
35
36 Agner aims to provide such an index, by focusing on a number of
37 points:
38
39 * The index is loose in the sense that anyone can overlay the index
40 and add their own packages to the repository
41 * The tool is as simple as possible, utilizing git (for the time
42 being) to maintain the indexes
43 * Recognize the ideas of simplicity Joe Armstrong had in mind on
44 the erlang-questions@ mailing list the
45 [22-Jul-2010](http://www.erlang.org/cgi-bin/ezmlm-cgi?4:mss:52415:201007:npnohnblfemjooohecnk)
46
47 Use
48 ===
49
50 This section introduces the terminology of Agner:
51
52 * **index/indices:** Where Agner finds its package index. Usually this
53 is a github user with one or more packages among the users git
54 repositories.
55 * **package:** A separate library or program indentified by the
56 index. It is a `.agner` repository underneath the index-user, so one
57 example would be `agner/gproc.agner` specifying a package for the
58 `gproc` library undernath the `agner`-user.
59 * **project:** A software project, program or library, that contains
60 the actual source code for the program or library. In the example,
61 this is `esl/gproc` on github.
62 * **release:** A release of a package signifying a point in time
63 where the package was deemed to be in a certain state. Is usually
64 used when a new version of the software is released to the
65 general public so you can refer to package X version Y
66 * **flavour:** A moving target of a package with some specified
67 behaviour. It is used for tracking the development of a package
68 over time. Common flavours include the *@master* flavour, used to
69 track the development branch of a package and the *@release*
70 flavour, used to track the latest release of the package.
71
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
72 Command invocation
73 ------------------
74
e1ec98c @yrashk Added -p option to 'list' command so that arbitrary properties can be…
yrashk authored
75 agner list [-d/--descriptions] [-p/--properties PROPERTY1,PROPERTY2]
cb4746d @yrashk Added 'agner list --search'/'agner search' functionality
yrashk authored
76 [-s/--search SEARCH_TERM]
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
77
78 Will list all agner-packages. With the `-d` or `--descriptions`
79 option, it will also print out the descriptions of the packages, for
80 easy grepping to find relevant packages.
81
e1ec98c @yrashk Added -p option to 'list' command so that arbitrary properties can be…
yrashk authored
82 If `-p` or `--properties` with a comma-separated list of properties is specified, they will be also
83 included into each listing (when present).
84
cb4746d @yrashk Added 'agner list --search'/'agner search' functionality
yrashk authored
85 If `-s` or `--search` option is supplied, packages name, descriptions and keywords are matched against
86 SEARCH_TERM and only matching items are shown.
87
88 agner search SEARCH_TERM [-d/--description] [-p/--properties PROPERTY1,PROPERTY2]
89
90 This is an alias for `agner list -s`
91
2df68bb @yrashk Minor styling update in README.md
yrashk authored
92 agner spec PACKAGE [-v/--version VERSION] [-b/--browser]
61cb23f @yrashk Added 'spec --property' option
yrashk authored
93 [-h/--homepage] [-p/--property PROPERTY]
d87929f @yrashk Added -s/--spec-file option to fetch, spec & install commands (allows…
yrashk authored
94 [-s/--spec-file SPECFILE]
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
95
96 Will print a specification of a given package on stdout. If the
97 optional version constraint is given (for example `agner spec gproc -v
98 @release`) then the output is of that version. By default, the
99 `@master` flavour is chosen.
100
7e7089d @yrashk Added -b/--browser option that will open browser to show the specific…
yrashk authored
101 If `-b` or `--browser` is used, it will also open browser with the specification
102 file in its respective `.agner` repository.
103
68c3040 @yrashk Added -h/--homepage command line option for showing homepage in the b…
yrashk authored
104 If `-h` or `--homepage` is present, it will also open browser with the package's
105 homepage.
106
61cb23f @yrashk Added 'spec --property' option
yrashk authored
107 If `-p` or `--property` is supplied, agner will only render particular PROPERTY value
108 instead of a full specification (example: `agner spec -p rebar_compatible yaws`).
109
d87929f @yrashk Added -s/--spec-file option to fetch, spec & install commands (allows…
yrashk authored
110 Option `-s` or `--spec-file` is primarily intended for package maintainers. This way they can specify their
111 local `agner.config` files to test their package.
112
113
2df68bb @yrashk Minor styling update in README.md
yrashk authored
114 agner fetch PACKAGE [DESTDIR] [-v/--version VERSION] [-b/--build]
048b3e2 @yrashk Added support for install_command and 'fetch --install/-i' option, al…
yrashk authored
115 [-a/--add-path] [-i/--install]
b929dfa @yrashk Added support for AGNER_PACKAGE_REPO variable
yrashk authored
116 [-s/--spec-file SPECFILE] [--package-path PACKAGEPATH]
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
117
118 Fetch a given `PACKAGE` to either the current directory or,
119 optionally, to the `DESTDIR` directory. The version constraint is as
120 were the case for `agner spec`.
121
5141e6b @yrashk Renamed --compile/-c to --build/-b
yrashk authored
122 If `-b` or `--build` is supplied, Agner will try to build fetched package. Only rebar-compatible
123 packages or packages with `build_command` can be built. If you also specify
6e75a53 @yrashk Added --add-path option for fetch --compile
yrashk authored
124 `-a` (or `--add-path`) Agner will add path to a newly built package to your
125 HOME/.erlang
58ac308 @yrashk Added --compile option to README.md
yrashk authored
126
048b3e2 @yrashk Added support for install_command and 'fetch --install/-i' option, al…
yrashk authored
127 If `-i` or `--install` is supplied and package has `install_command` property defined, Agner will also
128 install this package. Please note that in most cases you should also specify `--build`/`-b` in order for
129 installation to make sense.
130
d87929f @yrashk Added -s/--spec-file option to fetch, spec & install commands (allows…
yrashk authored
131 Option `-s` or `--spec-file` is primarily intended for package maintainers. This way they can specify their
b929dfa @yrashk Added support for AGNER_PACKAGE_REPO variable
yrashk authored
132 local `agner.config` files to test their package. Can be used in conjunction with `--package-path` to point to a
133 checkout copy of an `.agner` repo (will be used to set `$AGNER_PACKAGE_REPO` variable for shell commands, defaults to
134 `.`)
d87929f @yrashk Added -s/--spec-file option to fetch, spec & install commands (allows…
yrashk authored
135
a2e653e @yrashk Added agner build command (an alias to agner fetch --build)
yrashk authored
136 agner build PACKAGE [DESTDIR] [-v/--version VERSION] [-s/--spec-file SPECFILE] [-a/--add-path] [-i/--install]
137
138 Alias for `agner fetch --build PACKAGE`.
139
d8cc1d2 @yrashk Added -s/--spec-file option to agner install documentation in README.md
yrashk authored
140 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
141
0c09d0b @yrashk Improved documentation on 'agner install'
yrashk authored
142 Alias for `agner fetch --build --install PACKAGE /tmp/<uniq_filename>`. A typical example would be `agner install rebar`
143 or `agner install rebar -v @agner` to get `rebar` binary in your PATH. It is assumed that `install_command`
144 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
145
dd5550e @yrashk Added 'uninstall' command
yrashk authored
146 agner uninstall PACKAGE [-v/--version VERSION] [-s/--spec-file SPECFILE]
147
148 Uninstall given package (and a particular VERSION of it, if specified). Will use local SPECFILE is `--spec-file`/`-s`
149 option is passed.
150
8b10007 @yrashk Added --no-releases and --no-flavours options for 'spec versions'
yrashk authored
151 agner versions PACKAGE [--no-flavours] [--no-releases]
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
152
8b10007 @yrashk Added --no-releases and --no-flavours options for 'spec versions'
yrashk authored
153 List the versions of the given `PACKAGE`. Specifying `--no-flavours` will omit flavour versions; and specifying
154 `--no-releases` will omit release versions respectively.
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
155
8d04acd @yrashk Renamed 'installed' command to 'prefix'
yrashk authored
156 agner prefix PACKAGE [-v/--version VERSION]
157
158 Prints prefix where package is installed. If package is not installed, prints nothing.
159
7677742 @yrashk Added documentation for 'config' command
yrashk authored
160 agner config [VARIABLE]
161
162 Shows main environmental variables. If `VARIABLES` is omitted, then lists `key=value` for each variable. If not omitted,
163 prints just its value. Currently supported variables are: `prefix` and `bin`.
164
1563446 @yrashk Added 'agner create' command to simply process of creating new .agner…
yrashk authored
165 agner create PACKAGE [--github-account ACCOUNT]
166
167 Contributor's tool that clones `.agner` repo template and sets its origin to ACCOUNT (by default, equals `agner`,
168 so if you don't have a permission to create repos in `agner`, set --github-account to your personal or organization account.
169
1bb458c @yrashk Added 'verify' command line command
yrashk authored
170 agner verify [SPEC FILENAME (agner.config by default)]
171
172 Verify specification file for correctness; intended to be used to package maintainers to simplify
173 their workflow. Currently checks whether 1) specification is a valid file that can be parsed,
174 2) the URL can be fetched. In the future it will also offer a deeper analysis of specification
175 correctness.
176
e74c3fa @jlouis Re-order the sections in the README.md file.
jlouis authored
177 Packaging
178 =========
be9362f @jlouis Add more description to the README file.
jlouis authored
179
180 Package organization
181 --------------------
182
183 When Agner is invoked, it will scan its *indices* for package
184 lists. The default index is "agner", which is located at
185 [https://github.com/agner/](https://github.com/agner/). The index is
186 scanned by looking for *Agner repositories* which are normal (github)
187 repositories suffixed with `.agner`. An example is the repository
188 [https://github.com/agner/getopt.agner](https://github.com/agner/getopt.agner)
189 which contains the package details of the `getopt` package.
190
191 It is important to nail down that there are three balls in the air:
192
193 * The index user, who has a list of
194 * `.agner` repositories, which points to
195 * Erlang software projects
196
197 By making a split between the repository containing the project and
198 the repository containing the package, we make it easy to identify
199 `.agner` repositories, and we enable a simple way to make the project
200 live in another source control system, for instance Mercurial (hg). It
201 is also way easier to keep the (small) `.agner` repositories in an
202 index and in the long run, it provisions for local caching.
203
204 Further indices can be added to Agner through the environment (TODO:
205 flesh out how that is done). Indices are searched
206 in the order of specification, allowing for overriding of a given
207 index. This allows you to create local indices or special indices for
208 your own use, or try something out on top of other indices.
209
210 The multiple indices approach solves authorization questions by solving it
211 "the git way". You put trust in the indices you add to Agner, so if
212 you don't trust an index, you can simply refrain from adding it. The
213 main "agner" index is intended to be the official source, but we
214 recognize that individuals might have reasons to overlay another index
215 on top. By having a loose index-construction, we hope to alleviate
216 some of the problems with access rights.
2f3d20a @yrashk Added README.md
yrashk authored
217
93546e5 @yrashk A little bit more information in the README.md
yrashk authored
218 Package names
219 -------------
220
be9362f @jlouis Add more description to the README file.
jlouis authored
221 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
222 <code>mochiweb</code>, or (in case of github indices, it might also
be9362f @jlouis Add more description to the README file.
jlouis authored
223 take a form of <code>account/package</code>, for example
224 <code>yrashk/misultin</code>). We use package names to identify a
225 given package in Agner - but versions of the package is naturally not
226 part of its name. This allows for packages to exist in multiple
227 versions at a time.
93546e5 @yrashk A little bit more information in the README.md
yrashk authored
228
229 Versions
230 --------
231
232 Agner has two kinds of versions:
233
be9362f @jlouis Add more description to the README file.
jlouis authored
234 * Release versions, normally something like <code>1.2.0</code>,
235 represented using tags in `.agner` repos.
236 * Flavour versions, normally something like <code>@release</code>,
237 represented using branches in `.agner` repos. Note the prefix of "@".
238
239 The intention is that a *release* version marks a given point in time
240 where a given version of the code base was released to the general
241 public. When Erlang/OTP is released as OTP-R14B01 for instance, it
242 signifies a *release* in Agner-terminology. On the other hand, a
243 *flavour* signifies a moving target. Continuing the OTP-R14B01
244 example from before, it would be natural to have a *@dev* flavour
245 which tracks the Erlang/OTP branch called `dev`. The other important
246 flavour is *@release* which will track the latest release.
247
44c0d1e @yrashk Added atleast:VERSION syntax to README.md
yrashk authored
248 Also, command line utility and agner-enabled rebar will recognize
5a47092 @yrashk Markdown syntax update in README.md
yrashk authored
249 `atleast:VERSION` format (for example, `atleast:1.5.0`) and will use
44c0d1e @yrashk Added atleast:VERSION syntax to README.md
yrashk authored
250 the latest version after 'VERSION' (so, if some package already has a
5a47092 @yrashk Markdown syntax update in README.md
yrashk authored
251 version of `1.6`, `atleast:1.5.0` will select `1.6`. This is mostly
252 for scenarios when `@release` flavour is absent or broken.
44c0d1e @yrashk Added atleast:VERSION syntax to README.md
yrashk authored
253
be9362f @jlouis Add more description to the README file.
jlouis authored
254 ### How to create relases and flavours
255
256 As hinted, a release version is a *tag* in a `.agner` repository. So
257 to create a release, you alter the `.agner` repository to match your
258 liking and then you tag it (with a standard `git tag` command
259 invocation). Agner will now pick up the change.
260
261 Likewise, for a flavour version, you *branch* the `.agner` repository
262 and alter the branch so it does what your flavour intended to
263 do. Flavours can be made for anything you would like to track over
264 time. By default, the advice is to create two flavours, *@master* and
265 *@release* tracking, respectively, the current development of a
266 project and the latest stable release of that project.
267
268 Keeping everything up-to-date is now outsourced to git and you can use
269 usual git-commands to manipulate the `.agner` repository.
270
271 ### The contents of an .agner package
272
273 The `.agner` package repository contains a file of Erlang-terms, called
274 `agner.config`. This file looks like this:
275
276 {name, "etorrent"}.
277 {authors, ["Jesper Louis Andersen <jesper.louis.andersen@gmail.com>"]}.
278 {description, "Etorrent is a bittorrent client implementation in Erlang focusing on fault-tolerance"}.
279 {homepage, "http://github.com/jlouis/etorrent"}.
280 {rebar_compatible, true}.
281 {license, "BSD2", "COPYING"}.
282 {erlang_versions, [otp_r14b, otp_r14b01, otp_r13b04]}.
283 {url, {git, "https://github.com/jlouis/etorrent.git", {branch, "master"}}}.
284
285 Or in a more generic way:
286
287 {name, ProjectName}.
288 {authors, [Author]}.
289 {description, ProjectDescription}.
290 {homepage, ProjectHomepage}.
291 {rebar_compatible, IsRebarCompatible}.
b2cf7aa @yrashk Minor update on optionality of LicenseFile in the spec (README.md)
yrashk authored
292 {license, LicenseType [, LicenseFile]}.
be9362f @jlouis Add more description to the README file.
jlouis authored
293 {erlang_versions, [OTPAtom]}.
294 {url, UrlSpec}.
295
296 * `ProjectName :: string()` - is the project name. This is usually
297 named the same as the `.agner` package to minimize confusion.
298 * `[Author] :: [string()]` - Can really be any string, but it is
299 usually the names of the project authors in a list including their
300 email-addresses for easy contact.
301 * `ProjectDescription :: string()` - A description of the
302 project. Used for searching through projects.
303 * `ProjectHomepage :: string()` - The URL of the homepage of the
304 project.
305 * `IsRebarCompatible :: boolean()` - Set to `true` if this project
2569b0a @yrashk Minor update on rebar_compatible in README.md
yrashk authored
306 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
307 * `LicenseType :: string(), LicenseFile :: string()` - Two
308 strings. The first one specifies the general license type of the
309 project and the second string explains where the license is to be
310 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
311 `COPYING` or `LICENSE` are used for this). Please note that `LicenseFile` is optional.
be9362f @jlouis Add more description to the README file.
jlouis authored
312 * `[OTPAtom] :: [otp_rXXb | otp_rXXbYY]` - A list of what OTP versions
313 the project can be used with. the `XX` is a major release number in
314 Erlang/OTP (12,13,14,...) and `YY` is a minor release number (01,
315 02, ...).
316 * `UrlSpec :: {git, URL, GitSpec}` - Specifies where to fetch the
8c1d1cb @yrashk Minor update for 'git' URL format in README.md
yrashk authored
317 project. `GitSpec` has type `sha1() | {tag, string()} | {branch, string()}`
318 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
319 respectively. Notice that you can't specify more than one target in
320 this file. To handle multiple versions, you use *releases* and
321 *flavours* by altering the `.agner` repository wherein this
322 configuration file lies.
1341a02 @yrashk Added mentioning of {hg, URL, Rev} URL format in README.md
yrashk authored
323 * `UrlSpec :: {hg, URL, HgRev}` - Specifies where to fetch the
324 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
325
b4b1965 @yrashk Fixed broken link in README.md
yrashk authored
326 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
327
260c851 @yrashk Added another note about 'agner verify' in README.md
yrashk authored
328 It is **highly recommended** that `.agner` repo maintainers use `agner verify` command before
329 committing and pushing their updated specifications.
330
331
2f3d20a @yrashk Added README.md
yrashk authored
332 Rebar
333 -----
334
be9362f @jlouis Add more description to the README file.
jlouis authored
335 Agner-compatible rebar is available at
336 [agner branch](https://github.com/agner/rebar/tree/agner) of
337 [agner/rebar](https://github.com/agner/rebar). Or you can download
338 ready-made rebar from
339 [agner itself](https://github.com/agner/agner/raw/master/rebar). We
340 hope to get rebar integration in the upstream with time.
2f3d20a @yrashk Added README.md
yrashk authored
341
342 Using it with rebar is fairly simple, it uses rebar's deps feature:
343
a26465d @yrashk Markup update in README.md
yrashk authored
344 {deps, [
345 {typespecs, "0.1", {agner, "typespecs"}},
346 {getopt, "0.3.0", {agner, "getopt"}}
347 ]}.
2f3d20a @yrashk Added README.md
yrashk authored
348
fec3baa @yrashk Typo fix
yrashk authored
349 You can also specify your own indices:
2f3d20a @yrashk Added README.md
yrashk authored
350
a26465d @yrashk Markup update in README.md
yrashk authored
351 {agner_indices, [{github, "yourgithubusername"},{github,"agner"}].
2f3d20a @yrashk Added README.md
yrashk authored
352
ca3ad6d @yrashk Added Contributing article link to README.md
yrashk authored
353 Contributing
354 ------------
355
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
356 Please read at [CONTRIBUTING](agner/tree/master/CONTRIBUTING.md).
Something went wrong with that request. Please try again.