home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / os2tk20 / debug / dbuginst.doc < prev    next >
Encoding:
Text File  |  1992-09-24  |  11.9 KB  |  304 lines
  1.  
  2.  
  3. [dbuginst]                                                    [v 0.103]
  4.  
  5.              Debug Kernel / PM Install / Restore Procedure
  6.              ═════════════════════════════════════════════
  7.  
  8. Introduction
  9. ────────────
  10.  
  11. This installation procedure for the debug utility and symbol files, the
  12. debug  kernel,  and the debug version of Presentation Manager  has been
  13. designed to avoid having to boot from the OS/2 installation diskette.
  14.  
  15. This is achieved by leaving the  retail PM dynamic link libraries where
  16. they are (in \os2\dll), untouched, and installing the debug versions to
  17. a separate directory (\os2\DEBUG\dll). The debug versions are then made
  18. the active versions  by simply editing  the 'config.sys' file  and then
  19. rebooting.
  20.  
  21. The installation may now be done from a CD ROM or LAN disk, as well as
  22. the diskettes previously used.
  23.  
  24. Quick Start Guide
  25. ─────────────────
  26.  
  27.   Installing from Diskettes:
  28.   ──────────────────────────
  29.  
  30.   1. Insert "Toolkit Debug Diskette 1" in drive A.  (see below if using
  31.      CD ROM or remote disk).
  32.  
  33.   2. At any OS/2 prompt (windowed or full-screen),  from any directory,
  34.      type the following command:
  35.  
  36.         a:\install   x        [where x is the letter of your  OS/2  2.x
  37.                                        drive WITHOUT a trailing colon.]
  38.  
  39.   3. When prompted to enter a debug install option,  choose the options
  40.      in this order:
  41.  
  42.         Option 1 - install utilities / symbols
  43.         Option 2 - install debug kernel
  44.         Option 3 - install debug PM             [this is optional]
  45.  
  46.   4. Make the necessary config.sys changes as described below.
  47.  
  48.   5. Connect a debug terminal, and reboot
  49.  
  50.  
  51.   Installing from CD ROM or Remote Disk:
  52.   ──────────────────────────────────────
  53.  
  54.   1. If using a CD ROM, insert it in the drive.  If using a remote disk,
  55.      be sure it's connected before starting the install process.
  56.  
  57.   2. At any OS/2 prompt (windowed or full-screen),  from any directory,
  58.      type the following command:
  59.  
  60.         d:\OS2TK20\DEBUG\DBUGINST /Sd:\OS2TK20\DEBUG x
  61.  
  62.      where 'd' is the letter of the CD ROM or remote drive
  63.        and 'x' is the letter of your  OS/2  2.x drive WITHOUT a trailing colon.
  64.  
  65.   3. See steps 3 - 5 above.
  66.  
  67.  
  68.  
  69. Necessary "config.sys" file changes
  70. ───────────────────────────────────
  71.  
  72. 1. Debug Kernel only
  73.  
  74.    If you have only installed the debug kernel (i.e. not debug PM or the
  75.    PM Shell APIs) you still need to make sure that the PMDD.SYS line has
  76.    the /C switch on it (although you DO NOT have to change the directory
  77.    itself).
  78.  
  79.                 device=x:\os2\pmdd.sys /Cn
  80.  
  81.          where    n  is the com port for debug output
  82.  
  83. 2. Debug PM Install
  84.  
  85.    If you install the debug version of PM and/or the PM Shell APIs, you
  86.    will need to make the following changes to your  "config.sys"  file,
  87.    prior to rebooting.
  88.  
  89.      a. Invoke the debug version of "pmdd.sys" (from the \os2\debug\dll
  90.         directory instead of the retail version in \os2)
  91.  
  92.                 device=x:\os2\debug\dll\pmdd.sys /Cn
  93.  
  94.          where    x  is your installation drive
  95.                   n  is the com port for debug output
  96.  
  97.      b. Add the debug DLL directory to the BEGINNING of your LIBPATH
  98.  
  99.                 LIBPATH=x:\os2\debug\dll; .... etc .....
  100.  
  101.          where    x  is your installation drive
  102.  
  103.    These changes are documented during the installation procedure,  and
  104.    are recorded in the  "dbinst.log"  file which is created in the root
  105.    directory of the installation drive.
  106.  
  107. 3. Restoring the retail PM
  108.  
  109.    Remove "x:\os2\debug\dll" from the beginning of the LIBPATH, because
  110.    it is not possible to remove the debug versions of the DLLs from the
  111.    debug DLL directory while they are active.
  112.  
  113.    Optionally, you may want to restore the PMDD.SYS line to the form as
  114.    described in 1, above.
  115.  
  116. 4. Restoring the retail kernel
  117.  
  118.    Restore the PMDD.SYS line to the form as described in 1, above.
  119.  
  120.  
  121. Subsequent Debug Installs / Restores
  122. ────────────────────────────────────
  123.  
  124.   The debug installation  command file and  executable are copied to the
  125.   the root directory of your OS/2 system partition as part of the inital
  126.   debug install process.
  127.  
  128.   This means that you can do further installs or restore retail versions
  129.   in the following way:
  130.  
  131.   1. If using diskettes, at any OS/2 (windowed or fullscreen) prompt, type :
  132.  
  133.         x:
  134.         cd \
  135.         dbinst   x             [where this x is the letter of the drive
  136.                                              to which to install files,
  137.                                              WITHOUT a trailing colon.]
  138.      or if using a CD ROM, type:
  139.  
  140.         d:\OS2TK20\DEBUG\DBUGINST /Sd:\OS2TK20\DEBUG x
  141.  
  142.      where 'd' is the letter of the CD ROM or remote drive
  143.        and 'x' is the letter of your  OS/2  2.x drive WITHOUT a trailing colon.
  144.  
  145.   2. Select options when prompted to do so.
  146.  
  147.   3. Make config.sys changes if necessary, as described above.
  148.  
  149.  
  150.  
  151.  
  152.                         Technical Description
  153.                         ═════════════════════
  154.  
  155. During installation, two files are copied to the root directory of your
  156. specified installation drive (in addition to this document).  The files
  157. are:
  158.  
  159.     1.  dbinst.cmd      - the basic command file, which can be executed
  160.                           separately, and which calls dbuginst.exe with
  161.                           the requested install drive as a command line
  162.                           argument.
  163.  
  164.     2.  dbuginst.exe    - this executable acts as the interface with to
  165.                           the user,  allows him or her  to choose which
  166.                           parts of the debug system to install, or even
  167.                           which parts to restore to the retail version.
  168.                           This program now supports remote installation
  169.                           from a CD ROM or LAN drive.
  170.  
  171. The User Interface
  172. ──────────────────
  173.  
  174. The user interface consists of a menu selection in a tabular format. It
  175. provides installation in  3 optional parts,  and the ability to restore
  176. two of those parts back to their corresponding retail versions.
  177.  
  178.   ┌──────────────────────────────────────────────────────────────────┐
  179.   │                                                                  │
  180.   │  ╔════════╤═══════════════════════════════╤═══════╤═══════════╗  │
  181.   │  ║ Option │           Description         │ Drive │  Status   ║  │
  182.   │  ╠════════╪═══════════════════════════════╪═══════╪═══════════╣  │
  183.   │  ║    1   │ Install utilities / symbols   │  d:   │           ║  │
  184.   │  ║    2   │ Install debug  kernel         │  d:   │           ║  │
  185.   │  ║    3   │ Install debug  PM             │  d:   │           ║  │
  186.   │  ╟────────┼───────────────────────────────┼───────┼───────────╢  │
  187.   │  ║    4   │ Restore retail kernel         │  d:   │           ║  │
  188.   │  ║    5   │ Restore retail PM             │  d:   │           ║  │
  189.   │  ╟────────┼───────────────────────────────┴───────┴───────────╢  │
  190.   │  ║    E   │  Exit                                             ║  │
  191.   │  ╚════════╧═══════════════════════════════════════════════════╝  │
  192.   │                                                                  │
  193.   │ Please input your selection:                                     │
  194.   │                                                                  │
  195.   └──────────────────────────────────────────────────────────────────┘
  196.  
  197.  
  198.  
  199. Installation Options
  200. ────────────────────
  201.  
  202. The install options make up options 1, 2, and 3. On the first occasion,
  203. it is suggested that  you install in  numerical order  (the presence of
  204. the debug version of "pmdd.sys" in "\os2\debug\dll"  from option 1,  is
  205. actually a pre-requisite for option 3).
  206.  
  207. The following describes just what each of the 3 options does:
  208.  
  209.    1. Installing the utilities / symbols:  copies all the symbol (.sym)
  210.       files that correspond to DLLs located in the "\os2\dll" directory
  211.       on the installation partition, to that directory.  It then copies
  212.       debug versions of vga.dll and 8514.dll to a new subdirectory, the
  213.       "os2\debug\dll", together with their symbol files.
  214.  
  215.       Finally, the symbol file creation utility ("mapsym.exe"), and the
  216.       supplied terminal emulator ("t.exe")  are copied to the \os2\apps
  217.       subdirectory. Move "t.exe" to your debug terminal machine, or use
  218.       any other terminal emulator you have available.
  219.  
  220.       The tree structure is as follows:
  221.  
  222.         root ─── os2 ─┬───  dll
  223.                       │        ┌──────────────┐
  224.                       │        │ doscall1.sym │
  225.                       │        │ helpmgr.sym  │
  226.                       │        │ os2char.sym  │
  227.                       │        │ pmctls.sym   │
  228.                       │        │ pmdrag.sym   │
  229.                       │        │ pmgpi.sym    │
  230.                       │        │ pmmle.sym    │
  231.                       │        │ pmshapi.sym  │
  232.                       │        │ pmspl.sym    │
  233.                       │        │ pmwp.sym     │
  234.                       │        │ som.sym      │
  235.                       │        └──────────────┘
  236.                       │
  237.                       ├───  debug  ──────   dll
  238.                       │                        ┌──────────────┐
  239.                       │                        │ pmdd.sys     │
  240.                       │                        │ pmdd.sym     │
  241.                       │                        │ 8514.dll     │
  242.                       │                        │ 8514.sym     │
  243.                       │                        │ vga.dll      │
  244.                       │                        │ vga.sym      │
  245.                       │                        └──────────────┘
  246.                       └───  apps
  247.                                ┌──────────────┐
  248.                                │ mapsym.exe   │
  249.                                │ t.exe        │
  250.                                └──────────────┘
  251.  
  252.    2. Installing the kernel:  unhides "os2krnl"  in the root directory;
  253.       renames it to  "os2krnl.RTL";  replaces it with the debug version
  254.       from the "Toolkit Debug Diskette 1"; and copies the kernel symbol
  255.       file to the root directory (from "Toolkit Debug Diskette 2"):
  256.  
  257.         root
  258.        ┌──────────────┐
  259.        │ os2krnl      │
  260.        │ os2krnl.sym  │
  261.        ├──────────────┤
  262.        │ os2krnl.rtl  │
  263.        └──────────────┘
  264.  
  265.    3. Installing the debug version of PM: unpacks debug versions of the
  266.       PM Window Manager and Graphics Engine DLL and symbol files to the
  267.       "\os2\debug\dll" directory (from "Toolkit Debug Diskette 3"):
  268.  
  269.         root ────  os2  ────  debug  ──── dll
  270.                                             ┌──────────────┐
  271.                                             │ pmgre.dll    │
  272.                                             │ pmgre.sym    │
  273.                                             │ pmwin.dll    │
  274.                                             │ pmwin.sym    │
  275.                                             └──────────────┘
  276.  
  277.  
  278.  
  279. Restore Options
  280. ───────────────
  281.  
  282. The restore options (4 and 5)  reverse the install procedure of options
  283. 2 and 3, respectively.  Note that there is no restore for the utilities
  284. and symbols (option 1),  because those files will simply not be used by
  285. the retail kernel. The mechanisms of the various restore operations are
  286. as follows :
  287.  
  288.    4. Restoring the kernel: replaces the active debug version of kernel
  289.       ("os2krnl") with the retail version saved as "os2krnl.rtl" in the
  290.       root directory, and then deletes the "os2krnl.rtl" file.
  291.  
  292.       (The kernel symbol file will be left in the root directory.)
  293.  
  294.         root
  295.        ┌──────────────┐
  296.        │ os2krnl      │
  297.        └──────────────┘
  298.  
  299.    5. Restoring the retail version of PM:  reminds the user to edit the
  300.       config.sys file.  It does not delete any of the debug versions of
  301.       the DLLs  or PMDD.SYS from the  \os2\debug\dll directory.  (Trace
  302.       files in the  \os2\system\trace directory are also left alone).
  303.  
  304.