Let's say you've been reading the eggs tutorial and you are almost done writing your first egg. You've tested that it works locally, and now you probably want to make it available to others. If you would like people to be able to install your egg using chicken-install YOUR-EGG, there are a few steps you need to take.

Creating a release-info file

First, you must create a so-called "release-info" file and make it available on a well-known location via HTTP (discussed below). This is a file which describes where the released versions of your egg can be found. It looks something like this:

This example describes where to find the canonical repository and an URI pattern which describes how to find release tarballs. It then goes on to declare three official releases; 0.1, 0.2 and 1.0.

The patterns in the URI enclosed in curly braces are seen as substitution patterns to be replaced by values. egg-name expands to the current egg's name (which is already known when the release-info file is being fetched) and egg-release is replaced by the string in each release declaration.

The supported types for uri are currently targz, tarbz, zip and meta-file. The first three are all archives expected to extract to a directory with the egg sources in it (zip files are allowed to expand directly into the files, but this is not recommended). The final one is special and deserves some more explanation; see the next section for that.

Currently repo is not used by automated tools, but is intended to make it easy for users to find the repository. In preparation for when it will be used in the future, it's a good idea to use consistent names, so please use the short name of the tool. Generally this is how it is invoked on the commandline: svn, mtn, git, bzr, hg, darcs, fossil etc.

Meta-file distribution

Sometimes it is impractical to create archives containing your egg's file contents. The egg releasing system has been designed to require as few manual steps as possible, so it is easy for people to release early and often.

A core ideal of the release system is to make it possible to release simply by tagging your code in a VCS. Some code hosting sites automatically make archives available for each tagged version, thereby making the release available immediately when the code is pushed to the server. For those that don't, the meta-file distribution file type is a way to release by tagging without having to manually make a tarball, as long as there is a way to directly obtain the raw sources of a specific release version via HTTP.

The idea is that each released egg always must have a meta-file to describe its dependencies, its author and license and so on. This meta-file can be used to provide a listing of all the files that are part of an egg. The system that manages egg releases automatically will download all these files and put them in a directory. When someone requests your egg with chicken-install, these files are all served up. Just add a files entry to your meta-file, which lists the files (these are resolved relatively to the meta-file itself).

This is a real-world example of the uri-common egg. It lists all the files which it consists of, and these will be downloaded by chicken-install. The disadvantage of this approach is that if you forget a file, your egg is uninstallable, so if you can please use the archive distribution types instead. Another disadvantage is that every time you add, remove or rename a file you need to remember to change the meta-file.

Because this egg uses subversion and each release has a corresponding tag, it can simply point to the metafile in the right subdirectory under tags and it will simply work. For other version systems this may require some more messing around.

Publishing your egg

After creating the release-info file, you need to make it known to the chicken-install infrastructure that an egg with the given name has a release info file at the location where you published it. This step finally makes it possible for people to say chicken-install YOUR-EGG and have it install your egg, or use (depends YOUR-EGG) in meta-files of their eggs.

Currently this is done by adding a line to the egg-locations file in Subversion, which can be found at https://code.call-cc.org/svn/chicken-eggs/egg-locations. If you don't have a Subversion account, just ask on the chicken-users mailinglist for somebody to do it for you or to request an account. To keep maintenance to a minimum, it's best to add a release-info location which will never change; only the release-info file itself should be changed when you make a new release. This can most easily be accomplished by pointing to the "raw file" view of your trunk/tip/head/master branch in your canonical repository's web interface. That way, this file is kept under version control alongside all the other files in your egg.

If you prefer, you can just publish the file separately via HTTP somewhere and keep overwriting it. If your code hoster doesn't provide an easy way to point to a raw view on a moving "latest version" pointer via HTTP, you could instead opt to store just the release-info files of your eggs in the centralised Chicken eggs subversion repository. Just contact one of the project maintainers or write to the chicken-users mailinglist.

Instructions for popular code hosting methods and VCSes

Now we've explained the basic idea, here's an overview of how to figure out the correct URIs and how to automate some steps away.

Chicken subversion eggs repository

The traditional way to distribute eggs has not changed much. We hope to get rid of the manual steps by writing post-commit hooks but for now it is necessary to maintain a meta-file listing all the files in your egg and to create a release-info file containing all your tags and the following repo and uri entries:

You can copy these verbatim. For existing eggs we've already done the work for you.

Bitbucket (mercurial)

Location of release-info file

You can use the code browser to figure out the path to your release-info file. First, copy the link that says "raw". This URI is almost correct but will contain a revision ID hash, so it is pinned to whatever revision is currently the tip. However, you can replace it with the string "tip" and it will still work, and when you visit it again after making changes it will have picked up those changes. Example:

Making releases

The bitbucket code browser also offers a "get source" link that allows you to fetch the files in that revision as a tarball. The same trick as with the raw files works here; just replace the link's revision ID hash with a symbolic name. You can use tags and bookmarks as symbolic names.

So to make a new release, just tag your release with a well-defined name. If you tag your eggs with the version as tag or bookmark name, you can use the following release-info file. Just don't forget to substitute your bitbucket username!

Making releases

Gitorious makes tags available for download as tarballs. To find the location, go to the source tree browser and switch to a tag in the right-hand panel. You should now get a button in the same panel that says "Download TAG-NAME as tar.gz".

So to make a new release, just tag your release with a well-defined name. If you tag your eggs with the version as tag name, you can use the following release-info file. Just don't forget to substitute your Gitorious project name!

Note that there is a Chicken Eggs project on Gitorious already. If you want you can ask its owner to add your egg's repository to it.

Github (git)

Location of release-info file

Use the code browser ("source" tab) to browse to your release-info file and copy the "raw" link. This link should work as-is, as long as you do this while looking at the latest revision of the file in the master branch. For example, for the Kalaha egg it would look like:

Making releases

Github makes tags available for download as tarballs. To find the location, click the big "Downloads" button/link in the code browser. It will pop up a selection dialog where you can choose between tarball and "zipball". It will also offer downloads for each tag, but those are zipballs only. However, you can copy the link and replace "zipball" in the URL by "tarball", or you can first click "switch tags" and then open the "Downloads" dialog and it will offer you download links for both tar and zip for that specific tag.

So to make a new release, just tag your release with a well-defined name. If you tag your eggs with the version as tag name, you can use the following release-info file. Just don't forget to substitute your Github username!

Making releases

Google Code currently does not have a way to automatically serve up tagged revisions as tarballs. You can, however, manually upload the tarballs so they appear on the "Downloads" section of your project. If you do this, you can access the files as http://my-egg.googlecode.com/files/my-egg-0.1.tar.gz

If you prefer, you can also opt to use the automatic "meta-file" way of serving files. First see the meta-file section at the start of this wiki page to figure out how to set up a files section in your meta-file.

For Mercurial, you can base your release-info file off the following snippet:

Making releases

Since this interface doesn't have a way to serve up tarballs, you must either create your own tarballs and publish them elsewhere or use the manual "meta-file" way.

See the meta-file section at the start of this wiki page to figure out how to set up a files section in your meta-file. The URI to your meta file is similar to the release-info file, except this time you can replace "tip" with the release's tagname. If you use tagnames that are identical to the release version, you can base the release-info file on the following example:

This assumes hgwebdir is running on the domain's root URI and the egg is available in a repo which has the same name as your egg.

Fossil's default web UI

This is the web UI you get when running "fossil serve".

There is one tricky part: by default, this interface disallows almost all outside access; you must log in, even if you just want to browse anonymously.

To get this stuff to work, you must first create an account which is granted access to download zipfiles (the "z" permission). Then you need to enable "Allow REMOTE_USER authentication" (which can be found under "admin" => "access control settings") and set the REMOTE_USER environment variable to this user before starting the server.

TODO: It would be great if someone actively using Fossil could take a look at this and see if these things can be done in a simpler way. For example, the wiki allows accessing files by name (like /doc/trunk/eggname.release-info), but that adds some HTML around it which we don't want.

Location of release-info file

Unfortunately, Fossil's web UI does not make it possible to link to the downloadable raw trunk version of a file, so for now you will need to maintain the release-info separately. It could be stored on a webserver or in the chicken-eggs svn repo.

You could use the raw file view but then you would need to update your egg's entry in egg-locations every time you push a new release so it points to the new version of the release-info file.

It doesn't appear to be possible to construct an URI based on symbolic tag names with Fossil's web UI, so unfortunately you can't use URI patterns. Here's an example of a release-info file with a few release entries for a hypothetical egg, which is available from a directory directly under the root of the domain, which is named after the egg: