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