Admin/components/README
author wenzelm
Sun Mar 24 13:48:46 2019 +0100 (3 months ago)
changeset 69962 82e945d472d5
parent 69429 dc5fbcb07c7b
permissions -rw-r--r--
documentation of document markers and re-interpreted command tags;
wenzelm@69429
     1
Notes on maintaining the Isabelle component repository at TUM
wenzelm@69429
     2
=============================================================
wenzelm@50332
     3
wenzelm@50332
     4
Quick reference
wenzelm@50332
     5
---------------
wenzelm@50332
     6
wenzelm@69429
     7
  * ensure that Isabelle/Scala/SSH can connect to the host specified via
wenzelm@69429
     8
    system option "isabelle_components_server"; this may require to install
wenzelm@69429
     9
    an unencrypted ssh host key as follows:
wenzelm@69429
    10
wenzelm@69429
    11
      $ ssh-keyscan -t rsa lxbroy10.informatik.tu-muenchen.de >> ~/.ssh/known_hosts
wenzelm@69429
    12
wenzelm@69429
    13
  * local setup (and test) of component directory, e.g. in
wenzelm@69429
    14
wenzelm@69429
    15
      screwdriver-3.14/
wenzelm@69429
    16
wenzelm@69429
    17
  * packaging (with associated SHA1 digest), e.g.
wenzelm@69429
    18
wenzelm@69429
    19
      $ isabelle build_components screwdriver-3.14
wenzelm@69429
    20
wenzelm@69429
    21
  * publishing, e.g.
wenzelm@69429
    22
wenzelm@69429
    23
      $ isabelle build_components -P screwdriver-3.14.tar.gz
wenzelm@69429
    24
wenzelm@69429
    25
  * manual editing of Admin/components/main: screwdriver-3.14
wenzelm@50332
    26
wenzelm@50332
    27
wenzelm@50332
    28
Unique names
wenzelm@50332
    29
------------
wenzelm@50332
    30
wenzelm@50332
    31
Component names are globally unique over time and space: names of
wenzelm@50332
    32
published components are never re-used.  If some component needs to be
wenzelm@50332
    33
re-packaged, extra indices may be added to the official version number
wenzelm@50332
    34
like this:
wenzelm@50332
    35
wenzelm@50332
    36
  screwdriver-3.14    #default packaging/publishing, no index
wenzelm@50332
    37
  screwdriver-3.14-1  #another refinement of the same
wenzelm@50332
    38
  screwdriver-3.14-2  #yet another refinement of the same
wenzelm@50332
    39
wenzelm@50332
    40
There is no standard format for the structure of component names: they
wenzelm@50332
    41
are compared for equality only, without any guess at an ordering.
wenzelm@50332
    42
wenzelm@50332
    43
Components are registered in Admin/components/main (or similar) for
wenzelm@50332
    44
use of that particular Isabelle repository version, subject to regular
wenzelm@50332
    45
Mercurial history.  This allows to bisect Isabelle versions with full
wenzelm@50332
    46
record of the required components for testing.
wenzelm@50332
    47
wenzelm@50332
    48
wenzelm@50332
    49
Authentic archives
wenzelm@50332
    50
------------------
wenzelm@50332
    51
wenzelm@50332
    52
Isabelle components are managed as authentic .tar.gz archives in
wenzelm@50332
    53
/home/isabelle/components from where they are made publicly available
wenzelm@68649
    54
on https://isabelle.in.tum.de/components/.
wenzelm@50332
    55
wenzelm@50332
    56
Visibility on the HTTP server depends on local Unix file permission:
wenzelm@50332
    57
nonfree components should omit "read" mode for the Unix group/other;
wenzelm@50332
    58
regular components should be world-readable.
wenzelm@50332
    59
wenzelm@50527
    60
The file Admin/components/components.sha1 contains SHA1 identifiers
wenzelm@50527
    61
within the Isabelle repository, for integrity checking of the archives
wenzelm@69429
    62
that are exposed to the public file-system.  The command-line tool
wenzelm@69429
    63
"isabelle build_components" maintains these hash-keys automatically.
wenzelm@50332
    64
wenzelm@50332
    65
wenzelm@50332
    66
Unpacked copy
wenzelm@50332
    67
-------------
wenzelm@50332
    68
wenzelm@69429
    69
A second unpacked copy is provided in /home/isabelle/contrib/. This allows
wenzelm@69429
    70
users and administrative services within the TUM network to activate arbitrary
wenzelm@69429
    71
snapshots of the repository with all standard components being available,
wenzelm@69429
    72
without extra copying or unpacking of the authentic archives. The
wenzelm@69429
    73
isabelle_cronjob does this routinely: it will break if the unpacked version is
wenzelm@69429
    74
omitted.
wenzelm@69429
    75
wenzelm@69429
    76
The command-line tool "isabelle build_components -P" takes care of uploading
wenzelm@69429
    77
the .tar.gz archive and unpacking it, unless it is a special component (e.g.
wenzelm@69429
    78
for multiplatform application bundling).