Agner is a rebar-friendly Erlang package index inspired by Clojars andHomebrew.

Essentially, Agner is an index of Erlang packages with some extracapabilities such as versioning, downloads, installation and so on.

Agner is a shorthand forA Giant Nebula of Erlang Repositories. Italso pays homage to the Danish statistician Agner Krarup Erlang.

It is just a matter of a simple oneliner to get Agner installed:

 curl https://raw.github.com/agner/agner/master/scripts/oneliner | sh

If you want to install latest release instead of HEAD, use this one:

 curl https://raw.github.com/agner/agner/master/scripts/oneliner.release | sh

By now, there is a large set of Erlang tools and libraries available,all of them highly useful. The problem, however, is to provide an indexof these packages, so other people

• Know of their existence
• Can easily use a package in their own projects
• Can search for a particular package

Agner aims to provide such an index, by focusing on a number ofpoints:

• The index is loose in the sense that anyone can overlay the indexand add their own packages to the repository
• The tool is as simple as possible, utilizing git as a backend (for the timebeing) to maintain the indices
• Recognize the ideas of simplicity Joe Armstrong had in mind onthe erlang-questions@ mailing list on the22th of July 2010

This section introduces the terminology of Agner:

• index/indices: Where Agner finds its index of available ofavailable packages. Usually this is a github user with one or moreAgner-packages among the users git repositories. You can enablemultiple indices at the same time if you want.
• package: A separate library or program indentified by theindex. It is an.agner repository underneath the index githubuser, so one example would beagner/gproc.agner specifying apackage for thegproc library undernath theagner-user. Apackage may be overridden by an index; a very important feature thatallows installing packages not hosted in a central index.
• project: A software project, program or library, containingthe actual source code for the program or library. In the running example,this isesl/gproc on github.
• release: A release of a package signifying a point in timewhere the package was deemed to be in a certain (stable) state. Is usuallyused when a new version of the software is released to thegeneral public so you can refer to package X version Y
• flavour: A moving target of a package with some specifiedbehaviour. It is used for tracking the development of a packageover time. Common flavours include the@master flavour, used totrack the development branch of a package and the@releaseflavour, used to track the latest release of the package.

agner help [COMMAND]

Print a command overview on the command line. If the optionalCOMMAND is given, show help for the given command.

agner list [-d/--descriptions] [-p/--properties PROPERTY1[,PROPERTY2]...]           [-s/--search SEARCH_TERM]

Will list all Agner packages. It is used for quick overviews of thepackages that are available in the enabled indices for installation oruse in a program. This command, like most commands, accepts commandline flags:

• -d or--descriptions: With this option enabled, Agner will alsoprint out the descriptions of the packages, for easy grepping to findrelevant packages. It accepts the following flags:

• -p or--properties: A comma, separated list of properties to beincluded in the listing (when present).

• -s or--search: The packages name, description and keyword aresearched, matched againstSEARCH_TERM. Only matching items are shown.

Since searching for packages is so common, a convenience command hasbeen defined:

agner search SEARCH_TERM [-d/--description] [-p/--properties PROPERTY1,PROPERTY2]

This is an alias foragner list -s

agner spec PACKAGE [-v/--version VERSION] [-b/--browser]                   [-h/--homepage] [-p/--property PROPERTY]                   [-s/--spec-file SPECFILE]

Will print a specification of a given package on stdout. The specification is the information Agner uses to determine the location of the package as well as the relevant meta-data for the package. Flags:

• -v or--version: If this version constraint option is given,Agner will print out the specification for that given VERSION (forexampleagner spec gproc -v @release). The version can be either arelease or aflavour. By default, the@master flavour is chosen.

• -b or--browser: Open a browser with the specification file inits respective.agner repository at github.

• -h or--homepage: Open a browser with the package's homepage.

• -p or--property: Agner will only render a particular PROPERTY valueinstead of a full specification (example:agner spec -p rebar_compatible yaws).

• -s or--spec-file: A flag primarily intended for packagemaintainers. This way they can specify their localagner.configfiles to test their package.

agner fetch PACKAGE [DESTDIR] [-v/--version VERSION] [-b/--build]                              [-a/--add-path] [-i/--install]                              [-s/--spec-file SPECFILE] [--package-path PACKAGEPATH]                              [-q/--quiet]

Fetch a given PACKAGE to either the current directory or,optionally, to the DESTDIR directory. Flags:

• -v or--version: The version constraint is as is the case foragner spec. You can choose to constrain a fetch to a givenVERSION, either arelase or aflavour.

• -b or--build: Agner will try to build fetched package. Onlyrebar-compatible packages or packages withbuild_command can bebuilt. If you also specify-a (or--add-path) Agner will add pathto a newly built package to your$HOME/.erlang

• -i or--install: If the package has theinstall_commandproperty defined, Agner will also install this package. Please notethat in most cases you should also specify-b (or--build) in order forinstallation to make sense.

• -s or--spec-file: A flag primarily intended for packagemaintainers. This way they can specify their localagner.configfiles to test their package. Can be used in conjunction with--package-path to point to a checkout copy of an.agner repo (willbe used to set$AGNER_PACKAGE_REPO variable for shell commands,defaults to.)

• -q or--quiet: A flag that will suppress output ofbuild_command &install_command(if present)

For convenience, the following shortcuts are defined:

agner build PACKAGE [DESTDIR] [-v/--version VERSION] [-s/--spec-file SPECFILE] [-a/--add-path] [-i/--install]

Alias foragner fetch --build PACKAGE.

agner install PACKAGE [-v/--version VERSION] [-s/--spec-file SPECFILE]

Alias foragner fetch --build --install PACKAGE /tmp/<uniq_filename>. A typical example would beagner install rebar oragner install rebar -v @agner to getrebar binary inyourPATH. It is assumed thatinstall_command property will make useofAGNER_INSTALL_PREFIX OS environment variable.

agner uninstall PACKAGE [-v/--version VERSION] [-s/--spec-file SPECFILE]

Uninstall given package (and a particular VERSION of it, if specified

• seeagner spec). Will use local SPECFILE if the-s (or--spec-file)option is passed.

agner versions PACKAGE [--no-flavours] [--no-releases]

List the versions of the given PACKAGE. Specifying--no-flavourswill omit flavour versions; and specifying--no-releases will omitrelease versions respectively.

agner prefix PACKAGE [-v/--version VERSION]

Prints prefix where PACKAGE is installed. If package is not installed,prints nothing.

agner config [VARIABLE]

Shows main environmental variables. If VARIABLE is omitted, then listskey=value for each variable. If not omitted, prints just itsvalue. Currently supported variables are:prefix andbin.

agner create PACKAGE [--github-account ACCOUNT]

Contributor's tool that clones.agner repo template and sets itsorigin to ACCOUNT (by default, equalsagner, so if you don't have apermission to create repos inagner, set --github-account to yourpersonal or organization account.

agner verify [SPECFILE]

Verify SPECFILE as a specification file for correctness; intended tobe used to package maintainers to simplify their workflow. If SPECFILEis not given, it defaults toagner.config. Currently checks whether

1. specification is a valid file that can be parsed, 2) the URL can befetched. In the future it will also offer a deeper analysis ofspecification correctness.

When Agner is invoked, it will scan itsindices for packagelists. The default index is "agner", which is located athttps://github.com/agner/. The index isscanned by looking forAgner repositories which are normal (github)repositories suffixed with.agner. An example is the repositoryhttps://github.com/agner/getopt.agnerwhich contains the package details of thegetopt package.

It is important to nail down that there are three balls in the air:

• The index user, who has a list of
• .agner repositories, which points to
• Erlang software projects

By making a split between the repository containing the project andthe repository containing the package, we make it easy to identify.agner repositories, and we enable a simple way to make the projectlive in another source control system, for instance Mercurial (hg). Itis also way easier to keep the (small).agner repositories in anindex and in the long run, it provisions for local caching.

Further indices can be added to Agner through the environment (TODO:flesh out how that is done). Indices are searchedin the order of specification, allowing for overriding of a givenindex. This allows you to create local indices or special indices foryour own use, or try something out on top of other indices.

The multiple indices approach solves authorization questions "the gitway": you put trust in the indices you add to Agner, so if you don'ttrust an index, you can simply refrain from adding it. The main"agner" index is intended to be the official source, but we recognizethat individuals might have reasons to overlay another index ontop. By having a loose index-construction, we hope to alleviate someof the problems with access rights.

Packages are named in one of two ways. Either as the a direct name,mochiweb, or as a form with a prefix of the packageindex,account/package. For exampleyrashk/misultin). We use package names to identify agiven package in Agner - but versions of the package is naturally notpart of its name. This allows for packages to exist in multipleversions at the same time.

Agner has two kinds of versions:

• Release versions, normally something like1.2.0,represented using tags in.agner repos.
• Flavour versions, normally something like@release,represented using branches in.agner repos. Note the prefix of "@"which is present on flavours only.

The intention is that arelease version marks a given point in timewhere a given version of the code base was released to the generalpublic. When Erlang/OTP is released as OTP-R14B01 for instance, itsignifies arelease in Agner-terminology. On the other hand, aflavour signifies a moving target. Continuing the OTP-R14B01example from before, it would be natural to have a@dev flavourwhich tracks the Erlang/OTP branch calleddev. The other importantflavour is@release which will track the latest release.

Also, the command line utility and Agner-enabled rebar will recognizeatleast:VERSION format (for example,atleast:1.5.0) and will usethe latest version after VERSION (so, if some package already has aversion of1.6,atleast:1.5.0 will select1.6. This is mostlyfor scenarios when@release flavour is absent or broken.

As hinted, a release version is atag in a.agner repository. Soto create a release, you alter the.agner repository to match yourliking and then you tag it (with a standardgit tag commandinvocation). Agner will now pick up the change.

Likewise, for a flavour version, youbranch the.agner repositoryand alter the branch so it does what your flavour intended todo. Flavours can be made for anything you would like to track overtime. By default, the advice is to create two flavours,@master and@release. These tracks, respectively, the current development of aproject and the latest stable release of that project.

Keeping everything up-to-date is outsourced to git and you can useusual git-commands to manipulate the.agner repository.

The.agner package repository contains a file of Erlang-terms, calledagner.config. This file looks like this:

{name, "etorrent"}.{authors, ["Jesper Louis Andersen <jesper.louis.andersen@gmail.com>"]}.{description, "Etorrent is a bittorrent client implementation in Erlang focusing on fault-tolerance"}.{homepage, "http://github.com/jlouis/etorrent"}.{rebar_compatible, true}.{license, "BSD2", "COPYING"}.{erlang_versions, [otp_r14b, otp_r14b01, otp_r13b04]}.{url, {git, "https://github.com/jlouis/etorrent.git", {branch, "master"}}}.

Or in a more generic way:

{name, ProjectName}.{authors, [Author]}.{description, ProjectDescription}.{homepage, ProjectHomepage}.{rebar_compatible, IsRebarCompatible}.{license, LicenseType [, LicenseFile]}.{erlang_versions, [OTPAtom]}.{url, UrlSpec}.

The meaning of the individual fields are as in the following:

• ProjectName :: string() - is the project name. This is usuallynamed the same as the.agner package to minimize confusion.

• [Author] :: [string()] - Can really be any string, but it isusually the names of the project authors in a list including theiremail-addresses for easy contact.

• ProjectDescription :: string() - A description of theproject. Used for searching through projects.

• ProjectHomepage :: string() - The URL of the homepage of theproject.

• IsRebarCompatible :: boolean() - Set totrue if this projectusesrebar or is compilable by rebar even if it wasn't originally designed for that.

• LicenseType :: string(), LicenseFile :: string() - Twostrings. The first one specifies the general license type of theproject and the second string explains where the license is to befound from the top level directory (usually file-names likeCOPYING orLICENSE are used for this). Please note thatLicenseFile is optional.

• [OTPAtom] :: [otp_rXXb | otp_rXXbYY] - A list of what OTP versionsthe project can be used with. theXX is a major release number inErlang/OTP (12,13,14,...) andYY is a minor release number (01,02, ...).

• UrlSpec :: {git, URL, GitSpec} - Specifies where to fetch theproject.GitSpec has typesha1() | {tag, string()} | {branch, string()}and points to either string-based sha1 representation, a gittag or agit branchrespectively. Notice that you can't specify more than one target inthis file. To handle multiple versions, you usereleases andflavours by altering the.agner repository wherein thisconfiguration file lies.

• UrlSpec :: {hg, URL, HgRev} - Specifies where to fetch theproject.HgSpec has typestring() and points to either string-based revision representation

The very latest specification typespecs are available inagner_spec.hrl

It ishighly recommended that.agner repo maintainers useagner verify command beforecommitting and pushing their updated specifications.

Agner-compatible rebar can be installed byagner install rebar -v @agner. We hope to get rebar integration in the upstream with time.

Using it with rebar is fairly simple, it makes use of rebar's plugin system.Just include our plugin in your rebar.config and reference defaultdeps directory:

{rebar_plugins, [agner_rebar_plugin]}.{lib_dirs, ["deps"]}.

then, in your .app or .app.src file, add something like this as one of yourapplication keys:

 ... {agner, [       {requires, ["typespecs","getopt","gproc","plists","gen_fsm2","jsx","rebar"]}      ]} ...

An example can be found inagner itself

Also, you can also specify your own indices in rebar.config

{agner_indices, [{github, "yourgithubusername"},{github,"agner"}].

If you want to contrinute to Agner, please read the document atCONTRIBUTING.