home *** CD-ROM | disk | FTP | other *** search
/ ftp.lokigames.com / ftp.lokigames.com.zip / ftp.lokigames.com / open-source / loki_update / loki_update-full-1.0.13-ppc.run.txt < prev    next >
Text File  |  2001-07-06  |  9KB  |  204 lines
  1.  
  2. Loki Update Tool 1.0
  3.  
  4.  
  5. Introduction
  6. ============
  7. This is a tool written by Loki Software, Inc., designed to be used in
  8. conjunction with their setup and patchkit tools to automatically update
  9. installed products.
  10.  
  11.  
  12. Licensing
  13. =========
  14. This update tool is available for use under the GNU General Public License.
  15.  
  16.  
  17. Basic Operation
  18. ===============
  19. First the update tool looks for updates for itself, and if any are available,
  20. automatically downloads and applies them and restarts.  If an application
  21. name is given on the command line, the update tool looks for all updates
  22. that apply to the existing application, automatically applies them, and
  23. then quits.
  24.  
  25. If the update tool is not given any command line arguments, then it enters
  26. an interactive mode in which the user can select available updates for any
  27. installed products.  It then downloads the README for the patch and makes
  28. it available to the user while the rest of the patch is downloaded.  If a
  29. GPG signature is available, it will be downloaded and used to verify the
  30. update.  If the GPG signature isn't available, or cannot be verified for
  31. some reason, then an MD5 checksum is downloaded and used for verification.
  32. When the user chooses to continue, the update is executed, and passed the
  33. "--nox11" and "--noreadme" options, telling it to run in quiet mode and
  34. print out percentage progress information.  When the patch completes, the
  35. user can continue applying updates until an error occurs or all updates
  36. are complete.
  37.  
  38. Loki's games have a special feature built into them which allow you to
  39. run the game with the '--update' option to automatically update them and
  40. then restart for normal play.
  41.  
  42.  
  43. Update Creation
  44. ===============
  45. The update tool assumes that your patches have been created using the
  46. Loki patchkit tools, and packed using the makeself.sh script written
  47. by Stephane Peter.
  48.  
  49. The patchkit tools are available from Loki Software, Inc.
  50.  
  51. The makeself.sh script is available from:
  52. http://www.lokigames.com/~megastep/makeself/
  53.  
  54. When the product is installed with Loki's setup tool, it is provided
  55. with an product update URL, a place where a list of updates for this
  56. product are listed.  The listing can be text or HTML, and must contain
  57. a set of entries in the form:
  58.  
  59. Product:
  60. Version:
  61. Architecture:
  62. Libc:
  63. Applies:
  64. File:
  65.  
  66. The product is the keyword name of the product, as specified by the
  67. "product" tag in the product installation description file.  The name
  68. of the product actually shown the user is the product description, as
  69. specified by the "desc" tag in the product installation description file.
  70.  
  71. The version is the version of the patch, i.e. what the final version of the
  72. product will be after the patch is applied.  The patch is responsible for
  73. updating the installation database, which is done automatically by Loki's
  74. patchkit tools.
  75.  
  76. The architecture is an optional comma separated list of architectures for
  77. which the patch is valid.  The default is to match any architecture.
  78. Recognized keywords are: x86, ppc, alpha, sparc64, arm, any
  79. New keywords may be added by modifying arch.c in the setupdb distribution.
  80.  
  81. The libc is an optional comma separated list of versions of libc for
  82. which the patch is valid.  The default is to match any version of libc.
  83. Recognized keywords are: libc5, glibc-2.0, glibc-2.1
  84. New keywords may be added by modifying arch.c in the setupdb distribution.
  85.  
  86. The applies field is a comma separated list of product versions to which
  87. the patch may be applied.  If the installed version of the product doesn't
  88. match one of these strings, then the patch is discarded.
  89.  
  90. The file field is the archive file used to upgrade this product.
  91.  
  92. You can also add an optional "Note: blah blah" field which is listed in
  93. parenthesis after the update version when shown to the user.  These notes
  94. apply to versions, not patches, so if you want a note about a version, you
  95. only need to add it to one of the update listings for that version.
  96.  
  97. The update tool supports patches that linearly increase an application
  98. version, convert to a different "flavor" of the product, or add extra
  99. functionality to the application.
  100.  
  101.  
  102. Components
  103. ==========
  104. Patches that add extra functionality to an application, in the form of
  105. an "add-on" or expansion pack are considered special in several ways:
  106.  
  107.  * They are considered separate components and may be patched separately
  108.    from the main application.
  109.  
  110.  * They require a separate "Component" keyword that comes before the
  111.    "Version" keyword in the patch description indicating the verbose
  112.    name of the component.
  113.  
  114.  * The applies field of the patch description contains only a single
  115.    version, and represents the minimum version of the product which
  116.    must be installed for this component to show up as an update option.
  117.  
  118.  * Patches to this component must have a matching "Component" keyword.
  119.  
  120.  * The component installation update must be specified in the same file
  121.    as the patches to this component.  Since the description syntax for a
  122.    new component update and patches to that component are the same, the
  123.    entry with the lowest version number is considered the base update.
  124.  
  125.  * The component update must not modify any files in the base install,
  126.    it should just add new files.
  127.  
  128. Examples of good candidates for "components" might be game level editors,
  129. mission packs, development kits, etc.
  130.  
  131.  
  132. Flavors
  133. =======
  134. An application flavor is designated by an extension to the application
  135. version, using any character except alphanumeric characters, the period,
  136. or a comma, followed by any amount of non-whitespace characters.  An
  137. example of an application flavor might be "1.0 Spanish", or "1.1-demo"
  138.  
  139. The patch tools support patches that convert from one flavor to another
  140. or upgrade the version of a particular flavor, but keep in mind that 
  141. this is equivalent to a separate product in that only updates for your
  142. particular product flavor will be visible on the update selection list.
  143.  
  144. The product as installed usually has no "flavor", this is the default.
  145.  
  146.  
  147. GNU Privacy Guard
  148. =================
  149. While the update tool does not ship with GPG for legal reasons, it will
  150. take advantage of GPG for update checksum and verification if it is
  151. installed on the user's system.  They do not need to know how to use
  152. GPG, the appropriate public keys are automatically downloaded from a
  153. public key server for update verification.
  154.  
  155. More information about GNU Privacy Guard can be found at:
  156. http://www.gnupg.org/
  157.  
  158.  
  159. Advanced Operation
  160. ==================
  161. If you give the update tool the command line argument "--verbose", it will
  162. be verbose about file transfers and patch application.
  163.  
  164. If you give the update tool the command line argument "--debug", it will
  165. give full debug information about file transfers and internal parsing.
  166.  
  167. If you give the update tool the command line argument "--noselfcheck", it
  168. will skip the normal check for updates for itself before going into normal
  169. operation.
  170.  
  171. If you give the update tool the command line argument '--tmppath" followed
  172. by a directory name, it will use that directory as the temporary download
  173. path for updates and signatures.  This defaults to ~/.loki/loki_update/tmp
  174.  
  175. If you give the update tool the command line argument "--meta_url URL",
  176. it will parse the given URL for "product: URL" key/value pairs, and use
  177. those as the update URLs for the listed products.  URL's may be relative
  178. filenames as well as normal internet style URLs.  This makes it easy to
  179. create patch update disks.
  180.  
  181. On the final download screen, you have three buttons that give you control
  182. over the update download sites.  Each update download site is called a
  183. "mirror", and you can choose which site gives you the best download speed.
  184. The first button, "Choose Mirror", brings up a list of download sites for
  185. the current update, and let's you choose which one you want to use.
  186. The second button, "Next Mirror", automatically connects to the next
  187. available download site, continuing the download where it left off,
  188. if possible.
  189. The third button, "Save Mirror", saves the current download site to the
  190. file ~/.loki/loki_update/preferred_mirror.txt, and will use that site
  191. first for future downloads.
  192.  
  193. If you download an update that has a GPG signature, the update tool will
  194. automatically try to download the public key for that signature from a
  195. public key server.  The list of keyservers that are contacted for public
  196. keys is stored in ~/.loki/loki_update/keyservers.txt.  You can add new
  197. servers to this file, one per line.
  198.  
  199.  
  200. Author
  201. ======
  202. The Loki update tool was written by Sam Lantinga at Loki Software, Inc.
  203.  
  204.