[or-cvs] r17415: {updater} oops; add some documentation for that. (in updater/trunk: . doc specs)
nickm at seul.org
nickm at seul.org
Sun Nov 30 06:19:37 UTC 2008
Author: nickm
Date: 2008-11-30 01:19:36 -0500 (Sun, 30 Nov 2008)
New Revision: 17415
Modified:
updater/trunk/TODO
updater/trunk/doc/interface.txt
updater/trunk/specs/thandy-spec.txt
Log:
oops; add some documentation for that.
Modified: updater/trunk/TODO
===================================================================
--- updater/trunk/TODO 2008-11-30 06:19:04 UTC (rev 17414)
+++ updater/trunk/TODO 2008-11-30 06:19:36 UTC (rev 17415)
@@ -1,6 +1,9 @@
-- get messaging sorted
+o get messaging sorted
o try to write up a registry-based exe version checker.,
-- Decouple install from check: they are not necessarily related.
+o Decouple install from check: they are not necessarily related.
+ o Generate newer, better objects internally.
+ - Generate new, better formats for existing 'exe' items
+ - Generate command items properly.
. Download improvements.
o Back off on download failure.
Modified: updater/trunk/doc/interface.txt
===================================================================
--- updater/trunk/doc/interface.txt 2008-11-30 06:19:04 UTC (rev 17414)
+++ updater/trunk/doc/interface.txt 2008-11-30 06:19:36 UTC (rev 17415)
@@ -69,6 +69,11 @@
an installable item (exe, rpm, msi, etc); the PKG is the json package
descriptor it belongs to.
+ NO_INSTALL PKG="a relative path in the repository" ITEM="another one"
+ As CAN_INSTALL, but Thandy has gotten something that it doesn't
+ have a way to install. Can you help?
+
+
THANDY'S JSON2XML FORMAT:
Some people use libraries whose XML parsers are way better than their JSON
Modified: updater/trunk/specs/thandy-spec.txt
===================================================================
--- updater/trunk/specs/thandy-spec.txt 2008-11-30 06:19:04 UTC (rev 17414)
+++ updater/trunk/specs/thandy-spec.txt 2008-11-30 06:19:36 UTC (rev 17415)
@@ -454,14 +454,13 @@
"version" : VERSION,
"format" : FMT,
"ts" : TIME,
- "files" : [ [ PATH, HASH ], ... ],
+ "files" : [ [ PATH, HASH, INFO ], ... ],
"shortdesc" : { LANG : DESC, ... },
"longdesc" : { LANG : DESC, ... },
}
- Most elements are self-explanatory. The "FMT" element describes the
- file format of the package, which should give enough information
- about how to install it.
+ Most elements are self-explanatory. To interpret the 'INFO' entry
+ for each installable file, see section 6.
No two package files in the same repository should have the same
name and version. If a package needs to be changed, the version
@@ -596,8 +595,116 @@
keylist. Note that a new package or bundle key must re-sign and
issue new versions of all packages or bundles it has generated.
+6. Installing files from packages.
+ Any single package file in Thandy can refer to one or more installable
+ files in its 'files' list. These files are called "installable items"
+ below to distinguish them from Thandy's package files as described
+ in 3.7. Note that these installable items may in turn be called
+ "package files" by other package systems. Try not to get confused.
+6.1. Thandy's demands
+
+ Thandy needs at minimum two things to fully support a kind of
+ installable item.
+
+ - Thandy needs to be able to see whether it has already been
+ installed, _before_ downloading the item. We call this
+ operation "checking" the item.
+
+ - Thandy needs to be able to install it. We call this operation
+ "installing" the item, for obscure reasons.
+
+ Methods for checking and installing an item are sometimes linked,
+ but can be orthogonal. For example, an RPM item is checked and
+ installed with the RPM utility. An EXE-based installer, on the
+ other hand, might be checked either by looking for a registry entry,
+ by looking to see if a given installed file has a hash as expected,
+ or by looking in Thandy's internal package database.
+
+ To see how to check or install an item, look at the third element of
+ that item's [ PATH, HASH, INFO, ... ] tuple. We'll call this the
+ item's "INFO" below.
+
+6.2. Checking installable items
+
+ Thandy checks installable items in a package to see whether they're
+ already installed before it tries to download them to the cache.
+ This saves bandwidth.
+
+ To check an item, see whether the check_type field in its INFO is a
+ recognized value. Recognized values are:
+ "registry"
+ "rpm"
+ "db"
+
+ If the field's value is "registry", the INFO must also have these fields:
+ "registry_ent" : [ KEY, VAL ]
+ The installable item is installed if the win32 registry is present,
+ and it has an entry KEY whose value is VAL.
+
+ If the field's value is "rpm", the INFO must also have these fields:
+ "rpm_version" : VERSION_STRING
+ The installable item is installed if the version listed as installed
+ in the RPM database is exactly VERSION_STRING.
+
+ If the field's value is "db", the INFO must also have these fields:
+ "item_name" : KEY,
+ "item_version" : VAL
+ KEY must be unique across the thandy repository. It identifies
+ this kind of installable item uniquely. VAL is the version of this
+ item. When Thandy installs the item, it writes a persistent mapping
+ from KEY to VAL to a local database. The item is instaleld if such
+ a mapping is found to exist.
+
+
+ When Thandy decides to update an installable item that has a missing
+ check_type field, or a check_type field with an unrecognized value,
+ Thandy must download the item whether it is installed or not.
+
+6.3. Installing installable items
+
+ To install an item, see whether the install_type field in its INFO is a
+ recognized value. Recognized values are:
+ "rpm"
+ "command"
+
+ If the field's value is "rpm", the installable item is an RPM
+ package. It gets installed and removed as normal for an RPM.
+
+ If the field's value is "command", the following field must be
+ present:
+ "cmd_install" : COMMAND
+ The following field is optional:
+ "cmd_remove" : COMMAND
+ Each command is a list of strings executed to install or remove the
+ installable item. Strings and substrings of the form ${xyz} are
+ special: they trigger variable expansion. Recognized variables are:
+ ${FILE} : The absolute path to the file to install.
+
+
+ When Thandy decides to install an installable item that has a missing
+ install_type field, or a install_type field with an unrecognized value,
+ Thandy alerts the user to the presence of the file, but can't
+ install it itself.
+
+
+6.99 The obsolete way to install files from packages.
+
+ If an item has no checkType and its package's "format" field is
+ present and set to 'exe', there is an obsolete way to check and
+ install items. This will no longer be supported once packages of
+ this type are no longer generated, and no longer latest in any
+ bundle.
+
+ If an item in such a package has a registry_ent field in its INFO,
+ its presence is detected in the registry as with
+ check_type=registry_ent. Otherwise, checking is done with an entry
+ based on the package's name and version in Thandy's internal DB.
+
+ To install such an item, the item itself is executed, with arguments
+ taken from an exe_args list in its INFO.
+
F. Future directions and open questions
F.1. Package decomposition
More information about the tor-commits
mailing list