summaryrefslogtreecommitdiff
path: root/README.rst
blob: 2b6003f1398470d4d40b0859ba4ed796d9962e96 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
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