diff options
| -rw-r--r-- | README.rst | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..2b6003f --- /dev/null +++ b/README.rst @@ -0,0 +1,124 @@ +----------------------------------------------------------------------- + Context Mirror Bot +----------------------------------------------------------------------- + +Program for creating and maintaining a mirror for Context_, intended to +be run as a cron job but also handy when checking for updates to +Context manually. + +----------------------------------------------------------------------- + Background +----------------------------------------------------------------------- + +With each release of the *current* and *beta* branches, a new zipball +containing the latest code is uploaded to the Pragma ADE servers and +announced on the `official website`_. Since the tree is no under SCM +nor browsable online, different workarounds have been put into place by +the community. The `first mirror`_ provided a reliable git repository +with the most recent code for many years. It was discontinued_ in early +2014. By that time, a similar mirror was installed on the +`Context Garden`_, but apparently it prevents cloning the repository. +Also, it’s a good thing in general to have some redundancy in case the +alternatives go down. + +----------------------------------------------------------------------- + How It Works +----------------------------------------------------------------------- + +The *Context Mirror Bot* scrapes abovementioned download pages for +timestamps of the most recent zips and matches them against the state +of a repository. When it detects a new zipball, the bot downloads and +extracts it into the local repo, committing the new state along with +its timestamp. Contrary to previous mirrors, this one keeps the *beta* +and *current* in separate branches, producing higher quality diffs. + +----------------------------------------------------------------------- + How-to +----------------------------------------------------------------------- +Install +******* + +To build the executable you need Ocaml_ (tested with version 4.01) as +well as Omake_. *Context Mirror Bot* requires the ``ocurl``, ``uri``, +and ``xmlm`` libraries. I recommend installing them through Opam_. + +If the dependencies are in place, simply issue ``omake`` in the +repository directory and the executable ``context_mirror_bot`` is +created. + +Run +*** + +To familiarize yourself with the options, run :: + + context_mirror_bot --help + +Currently this presents you with this list of options: + +--check check source timestamps +--status print status of local repo +--update update from sources +--prepare prepare local repository +--download download source packages +--clean remove leftover files +--push push to mirror +--files install config and wrapper files +--verbose enable verbose output + +To simply retrieve the current state of Context, choose ``--download``. +The destination directory is currently hardcoded in the variable +``repo_root`` in the program header -- adapt it to your needs. As long +as the target location is writable, the *Mirror Bot* will not leave it. +Run ``context_mirror_bot --clean`` to remove unnecessary temporary +files from the directory. + +In order to set up a mirror you need an SSH key. Store the private key +in the file ``context_mirror_bot_id_rsa`` inside the current working +directory and the *Mirror Bot*. The public key must be registered with +an online repository on a source code hoster like Bitbucket or Github.. + +Now edit the ``gitconfig`` variable in the program header to include +the name of the user you intend the *Mirror Bot* to run under. Also, +edit the variable ``mirror_repo`` to point to the destination +repository at the code hoster. Now recompile with ``omake`` and run +``context_mirror_bot --update`` -- the bot will retrieve the latest +sources and commit them on top of the latest state of the earlier +repository on Gitorious. The result is then pushed to the remote +server. + +----------------------------------------------------------------------- + Locations +----------------------------------------------------------------------- + +The author’s mirror resides in its own `repo at BitBucket`_ and is +committed to by a `dedicated user`_. + +----------------------------------------------------------------------- + About +----------------------------------------------------------------------- + +Written by `Philipp Gesang`_. Inspired by the `original script` by +Marius, the long-term maintainer of the third-party mirror. + +The *Context Mirror Bot* is released under the terms of the GNU General +Public License, version 3 (no later or earlier). See the file +``COPYING`` for the full license text. + +Context_ is supplied under the terms of the GNU General Public License, +version 2 (no later or earlier). See the file ``context-license`` for +details. This file will also be located in the mirror repository tree +under the name ``COPYING``. + +.. _Context: http://www.pragma-ade.com/ +.. _official website: http://www.pragma-ade.com/download-1.htm +.. _first mirror: https://gitorious.org/context +.. _discontinued: http://www.ntg.nl/pipermail/ntg-context/2014/077380.html +.. _Context Garden: http://git.contextgarden.net/context/context +.. _repo at Bitbucket: https://bitbucket.org/phg/context-mirror +.. _dedicated user: https://bitbucket.org/context-mirror-bot +.. _Ocaml: http://ocaml.org/ +.. _Opam: http://opam.ocamlpro.com/ +.. _Omake: http://omake.metaprl.org/index.html +.. _Philipp Gesang: mailto:philipp.gesang@alumni.uni-heidelberg.de +.. _original script: https://gitorious.org/context/context/source/d493b9c93ad826044bd17889da2ee099c8ed72d5:context_git_update.pl + |