This file provides installation instructions and related information useful for setting up a `local' version of: * Lovelace, an Ada 95 tutor * mklesson, a tutor generator * Small, a sample Ada 95 Object-Oriented program. This file is divided into the following sections: 1. LEGAL NOTES 2. WHERE TO FIND CURRENT VERSIONS 3. INSTALLATION INSTRUCTIONS 4. IF YOU'RE CRAMPED FOR DISK SPACE ============================================================= 1. LEGAL NOTES The Lovelace Ada tutorial & mklesson (tutorial generator) are covered by the GNU General Public License and/or Library General Public License, with a limitation on the amount of material from it that you can print; see the file "tutorial/legal.htm" for more information. Unless otherwise noted, this material is Copyright (C) 1994-1999 David A. Wheeler. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. Small is, in essence, public domain; see the legal notes in file "legal.htm" for a more exact description of Small's legal status. This tutorial is not an endorsement. This tutorial was developed on my own time (off-hours). This tutorial does not represent any kind of endorsement by my employer, the U.S. Department of Defense (DoD), or the U.S. Government. ============================================================= 2. WHERE TO FIND CURRENT VERSIONS If you've already downloaded current versions of the files you need (the Lovelace files, an uncompressing program like pkunzip, and a Web browser), you can skip to section 3 below. Lovelace is distributed on the World Wide Web, with the current home page URL of: http://www.adahome.com/Tutorials/Lovelace/lovelace.htm Use a World Wide Web browser and go to that URL to see the latest version of Lovelace. If you can use "ftp" but aren't set up to use the Web, you can use ftp to download Lovelace. Here's a typical text session: ftp open ftp.adahome.com user anonymous YOUR_EMAIL_ADDRESS {use username "anonymous", and your email address as your password} cd /pub/Ada/HTML binary Then you get the file by running (for the zip format): get lovelace.zip or (for the tar/gunzip format): get lovelace.tar.gz If you don't have a program to uncompress the zip file format, you can obtain an index of programs to do this for you from URL: ftp://ftp.uu.net/pub/archiving/zip/Index To retrieve this file using ftp, type: ftp open ftp.uu.net user anonymous YOUR_EMAIL_ADDRESS {use username "anonymous", and your email address as your password} cd /pub/archiving/zip ascii get Index Then read the index file you receive. When you've decided which file you need, do the same as above, but instead of typing ascii, type: binary get NAME_OF_FILE_YOU_WANT If you don't even have an ftp connection, but you have a working email connection, you can still get the files, though it's not nearly as easy or quick. What you need to do is send an email message to a service that will execute ftp requests for you and send you the results by email. Here are some such services, as noted by IEEE Institute, November 1995: bitftp@pucc.princeton.edu ftpmail@decwrl.dec.com archive-server@Germany.eu.net ftpmail@ftp.uni-stuttgart.de mail-server@cs.tu-berlin.de archive-server@ibr.cs.tu-bs.de mailserver@Leo.org Send an email message to one of the above sites (or another one you identify) with no subject line and a single message line saying "help". You will get a reply stating how to use the service. In general, you'll need to mimic an ftp session in the message body sent to these services. The text commands listed above for ftp commands will be very useful to you. Binary files can't be reliably sent over normal email without packing it up as some sort of text format; one of the most common such formats is "uuencoding". You'll need to specify this packing format when you talk to such services, and once you get the data via email to your machine, you can then unpack it (say using uudecode) to turn it back into a normal file. Unfortunately, many email systems don't do this binary unpacking automatically. If you're doing this by email, good luck to you. If you get stuck, consult a local "guru" on the intricacies of obtaining binary files with ftp and email. ============================================================= 3. INSTALLATION INSTRUCTIONS You should have received a compressed file containing the Lovelace files. The file may be in one of several different compressed formats. If this file is stored in `tar plus gzip' format (a common Unix format), it will probably have a filename like lovelace.tar.gz (or a related filename; MS-DOS systems will have shorter filenames like lovelace.tgz). `tar' is a format that allows multiple files to be stored in a single file. `gzip' is a compression format supported by the FSF GNU `gzip' and `gunzip' programs; it is NOT the same format as the MS-DOS `zip' format. If the file is stored in `zip' format (a common PC format), it will have a filename like `lovelace.zip'. A. Change your current directory to the directory JUST ABOVE the where you want the files to go. So, if you want your files to go into /usr/doc/lovelace, change your current directory to /usr/doc. In Unix and MS-DOS, this is done with the "cd" command, e.g.: cd /usr/doc cd C:\documents On Windows, you'll need to start up an "MS-DOS Command Prompt" to do this, or specify a directory as part of the next step. B. Uncompress the file. For the tar+gzip file, on Unix and MS-DOS systems, do: gunzip lovelace.tar.gz tar xvf lovelace.tar Some MS-DOS machines don't have these programs already; consult your "local expert" on how to get programs to uncompress and untar these files. For the zip file, on MS-DOS systems, do: unzip lovelace.zip (or whatever your unzipping program name is, such as pkunzip or dezip). On Macintoshes, use programs such as stuffit or suntar. Again, if you don't have programs to uncompress and untar, consult your "local expert". On Windows machines, you'll probably use a GUI-based uncompressor; that program should let you specify where you want the files to go. If you want to support the Java applets, you need to expand those as well. Unzip the "adaclass.zip" or "tar xvf" the "adaclass.tar" file; this will expand into a set of directories and subdirectories needed to support the Java applets. If only a few users will use this system, you could alternatively have the users set their "CLASSPATH" variable to include the "adaclass.zip" file in this directory. C. On multiuser systems you _may_ need to reset file access permissions. For Unix systems, do: chmod a=r * D. Read the file "readme", which points out the key files here. On Unix and MS-DOS machines, this can be done using: more < readme E. If you don't already have a "web browser" such as Mosaic, Netscape, Lynx, Cello, etc., install one. You do NOT need Internet access to use Lovelace this way, though Internet access will increase your capabilities. Some old versions of Lovelace are available that have the Cello browser already integrated into them. If you have such a version, you can simply run Cello by running the program "cello.exe" in the lovelace directory (Cello will automatically start at the Lovelace local home page). If you don't have Internet access, make sure your web browser is configured so it will NOT attempt Internet access and make sure that the Web browser "home page" is a local file (say, the initial Lovelace file). For example, to set up Cello so you don't need an Internet connection, edit the "CELLO.INI" file (in Cello's directory) to contain the following settings: LocalOnly=Yes HomePage=c:\lovelace\local.htm The "LocalOnly" line indicates that the web browser (Cello in this case) should not attempt network connections, and the "Homepage" line gives the filename that will be the first filename viewed (change the C:\LOVELACE to wherever you've installed Lovelace). Other web browsers work similarly. G. Start up your web browser (Mosaic, Netscape, etc). Then point your browser to the directory you saved Lovelace into, with the file named "index.html". In most browsers this is simply a "File/Open File" command with the filename "C:\lovelace\index.htm" for MS-DOS machines and "index.html" for other machines. At this point it should all work! If you're using the version of Lovelace integrated with Cello, start up Microsoft Windows and then run the program "cello.exe" in the directory you put lovelace in. For example, if you use Windows 3.1 and you installed Lovelace in c:\lovelace, from the program manager select File/Run and enter "c:\lovelace\cello.exe" (don't enter the quotes). The "local.htm" file contains a warning saying that this version of Lovelace is a local version. If you don't want that warning, you can open the normal home page "lovelace.htm" inside the "tutorials/" subdirectory instead of "local.htm". Most browsers permit you to provide a starting URL when you start them up. You can use that capability to move directly to Lovelace on startup. H. When everything seems to work correctly, remove the tar or zip file. In Unix systems, this is done with: rm lovelace.tar In MS-DOS systems, this is done with: delete lovelace.tar -or- delete lovelace.zip I. From now on, you can simply start up the browser (step G) to use Lovelace! ============================================================= 4. IF YOU'RE CRAMPED FOR DISK SPACE If all you want to do is run the Lovelace tutorial and you're cramped for disk space, delete the following files: *.les (lesson source) *.tim (timestamps) makefile mklesson template default userg.htm If you're not using the Ada source code, you can also delete these files: *.adb (Ada bodies) *.ads (Ada specifications) If you have an old version integrated with Cello (a web browser) and you're not using Cello, remove the following files: 1024-768.sty 640-480.sty 800-600.sty cello.bmk cello.exe cello.ini cello.ino cello.sig cello.sto cello.sty clohelp.hlp default.htm readme.1st Note that the latest version of Lovelace is not normally integrated with Cello, since web browsers are now routinely available. MS-DOS-derived systems should note that Lovelace is implemented as a large number of small text files. In some sense this is a "worst case" for MS-DOS and similar systems; when not using a compressed drive such files use a lot of extra space. If you're really hurting for disk space, using a compressed drive will provide significant space savings. Enjoy! --- David A. Wheeler dwheeler@dwheeler.com