Richard Acuff, Stanford KSL, Dec-87 Guide to exporting Explorer software from the KSL This document is a collection of hints to help people trying to export software developed on the TI Explorer at the Stanford KSL to other Explorer installations. The problems encountered when trying to export software include getting all the right files onto the right media, making sure that any patches or environmental tools are included, matching system software versions with the remote site, and making sure that any legal or administrative matters are taken care of. Administrative Issues --------------------- The first thing to check when getting ready to send KSL developed software out is that proper legal notices and attributes are in the files. On the Explorer it is common practice to modify TI's system code in order to provide a hook for some new piece of functionality. When making these "patches," the author should clearly annotate the code from TI (or other sources), as well as any changes made. Then appropriate legal notices should be included in the file with this modified code. In the case of TI, you should include two things; (1) the text of the copyright notice at the top of the file from TI and (2) the following text: "Your rights to use and copy Explorer System Software must be obtained directly by license from Texas Instruments Incorporated. Unauthorized use is prohibited." It is also necessary to attribute funding agencies and authors. To make things easy, there is a template file, SYS:SITE;KSL-FILE-HEADER.LISP. When starting a new file of code the author should insert this file just after the mode line at the top and substitute appropriate info for text in '<>'. Here is what this template looks like: ;;; This software developed by: ;;; ;;; at the Stanford University Knowledge Systems Lab in . ;;; ;;; This work was supported in part by: ;;; ;;;---------------------------------------------------------------------- ;;; Portions of this code indicated by the comment line: ;;; ;;; are derived from code licensed from Texas Instruments Inc. ;;; KSL's changes are noted by comment lines beginning with: ;;; ;;; The following restrictions apply to the TI code: ;;; Your rights to use and copy Explorer System Software must be obtained ;;; directly by license from Texas Instruments Incorporated. Unauthorized ;;; use is prohibited. ;;;---------------------------------------------------------------------- ;;; The items in `<>' should all be replaced as follows (Note that Mouse-Middle can be used to select the '<>' items): This should be replaced by all the names of people who have worked on this file in the KSL, one per line. This should be replaced by the month and year, eg. Dec '87. This should be replaced by the grants that were used to support the work, eg. "NIH Grant 5 P41 RR00785-15" for SSRG work, "DARPA Grant N00039-86- C-0033" for general KSL work, or "DARPA Grant F30602-85-C-0012" for the Architectures Project. See your project administrator to find out what number(s) should be used here. If you used absolutely no TI code in the file by copying it with minor modifications from a file with a TI restricted rights legend, then you should delete this line and the ones below it up to the second line of hyphens. Otherwise you must fill in the rest of the sections. When a piece of code is copied from a TI file it should be annotated with some distinguishing mark. Placing the comment line ";;; TI Code" just above it is suggested. This should be done for each piece of code. Change this line to be that distinguishing mark. When a piece of a copied TI function is changed it should be commented, and the comment should be distinguished somehow, usually by putting the author's initials followed by a ':' at the start of the comment. This line should be replaced by all such distinguishing marks used in the file. Each TI file has a restricted rights legend at the top of it. This must be copied here. Take everything from the line reading "RESTRICTED RIGHTS LEGEND" to the last copyright notice. This is very important. This line should be replaced by a one-liner describing the use of the file. Some people who have other documentation styles might want to just delete this line. Time for an example. Suppose John Foo and Freeda Bar are writing some software in the KSL working on a DARPA-sponsored project, and they have to change a TI function called SYS:FROBULATE while they're at it. Here's what their file might end up looking like: ;;; -*- Mode:Common-Lisp; Package:DISFROB; Base:10 -*- ;;; This software developed by: ;;; John Foo ;;; Freeda Bar ;;; at the Stanford University Knowledge Systems Lab in Dec '87. ;;; ;;; This work was supported in part by: ;;; DARPA Grant AI-98-0982349 ;;; NIH Grant 5 P41 RR00785-15 ;;;---------------------------------------------------------------------- ;;; Portions of this code indicated by the comment line: ;;; TI Code ;;; are derived from code licensed from Texas Instruments Inc. ;;; KSL's changes are noted by comment lines beginning with: ;;; FOO: ;;; BAR: ;;; The following restrictions apply to the TI code: ;;; Your rights to use and copy Explorer System Software must be obtained ;;; directly by license from Texas Instruments Incorporated. Unauthorized ;;; use is prohibited. ;;; RESTRICTED RIGHTS LEGEND ;;;Use, duplication, or disclosure by the Government is subject to ;;;restrictions as set forth in subdivision (b)(3)(ii) of the Rights in ;;;Technical Data and Computer Software clause at 52.227-7013. ;;; ;;; TEXAS INSTRUMENTS INCORPORATED. ;;; P.O. BOX 2909 ;;; AUSTIN, TEXAS 78769 ;;; MS 2151 ;;; ;;; Copyright (C) 1985, Texas Instruments Incorporated. All rights reserved. ; Copyright (C) 1980, Massachusetts Institute of Technology ; Copyright (C) 1984, Texas Instruments Incorporated. All rights reserved. ;;;---------------------------------------------------------------------- ;;; File of support functions for the DISFROB package (defvar ...) (... more code ...] ;;; TI Code sys: (defun frobulate (frober) (... ;;FOO: Changed to allow a NIL FROBER (... Code John Foo changed ...) ) ) (... and so on ...) If you have any questions about what you should put into a file, send mail to Bug-LispM@sumex-aim. Media ----- The easiest way to send something to another Explorer user is probably via 1/4 inch cartridge tapes written on the Explorer. You can also try to make file available via a network, or use tar tapes, Symbolics Carry tapes, or move files to other systems to write tapes. To write a tape on the Explorer you can use the Backup Utility, accessed via B, or the MT: package functions describe in the Tools and Utilities manual. Always be sure to include hardcopy instructions with any media explaining how to load it. System Bug Fixes ---------------- As everyone should know, there is a system in the KSL called KSL-Patches that contains bug fixes that haven't yet made it into TI's released software. These patches should go out with all software. Take the files KSLx:SYS-PATCHES;*.*#*, SYS:SITE;KSL-PATCHES.SYSTEM#>, and SYS:SITE;KSL-PATCHES.TRANSLATIONS#>. The last two files should be edited at the remote site to set up the logical host KSLx and to control which patches are loaded. The KSL-Patches system consists of four modules: MAIN, IP, NFS, and LOCAL- CUSTOMIZATIONS. MAIN includes patches to standard system software, and should always be loaded. IP and NFS contain patches to the optional packages from TI with those names. The line in the DEFSYSTEM that loads these should be commented out if a site doesn't use those packages. LOCAL-CUSTOMIZATIONS is all the local modifications that aren't really bug fixes. It's here for historical reasons. Almost all sites will want to comment this one out, though they may want to create their own based on it. KSL Tools --------- There are a number of tools and utilities that have been developed or are used in the KSL to make working with the Explorer easier. If any of these are used by a system being exported the TOOLS:TOOLS; directory should be included in the export. Each tool is a system (in the DEFSYSTEM sense), but most of the DEFSYSTEM forms are in TOOLS:TOOLS;DEFSYSTEMS.LISP, with the exception of 36XX-EXPLORER and KSL-PATCHES. Almost all the tools are self contained but the remote user might have to make some changes to the environment to get everything to work. In particular the remote user should be told the following: - The TOOLS:TOOLS; logical directory must be defined in SYS:SITE;TOOLS.TRANSLATIONS#>. - The TOOLS system must be loaded via (MAKE-SYSTEM :TOOLS :NOCONFIRM :NOWARN :SILENT) and then (LOAD-TOOLS) or m-X Document Tool can be used to get documentation about the tools. - To use the Window-System-Additions tool the IMAGES:IMAGES; logical directory must be defined, usually in the namespace.