BFOIT - Introduction to Computer Programming

Appendix H (Installation of TG)




*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

This program is free software; you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

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.

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
                        

My Experience

If a site or someone would like to use these lessons as part of an introduction to programming class you will need to install stuff on the computer(s) you will be using.  For the Logo lessons you will need to install the TG programming environment.  For the Java lessons, you will need the turtle graphics library source code.

I have installed/used both in a few environments and I've helped others install and run it on a few others.  I develop and test new versions of TG on two Microsoft Windows systems and an Apple notebook running OS X.  Although I do not currently have a Linux system, I've exchanged email with users and have found that if it runs on Apple OS X, it runs on Linux.

You Need Java

If your computer does not have Java on it, you can download the standard Java Runtime Environment from a few places on the Internet.  I just Googled "download java runtime" and found many. Here are the top few links:

I release TG built on a Microsoft Windows XP system with Java version 1.4.2 (the first version of Java that supports audio/sound).  I am not aware of any problems with more recent versions of the Java Runtime Environment.  I run version 1.5 on my Macbook and version 1.6 on a Windows 7 system.  If you have a slow Internet connection, the older the version of Java, the smaller the size of the download.

The runtime environment allows you to work through all of the Logo-based lessons.  If you want to continue on with the introduction to Java lessons, you will need the full Java SDK (Software Development Kit).  I recommend going to Java SE Previous Releases Downloads page.  Follow one of the links (Java SE 6, Java SE 5, or Java SE 1.4) to get to a Downloads page.

Theoretically, the program is platform independent.  My experience is more like "Write once, debug everywhere."

Obtaining the TG Programming Environment (TG.jar)

Using A Browser

The easiest way to run the TG application is to simply grab the TG.jar file from the BFOIT website.  And the easiest way to do this is by taking advantage of your browser's built-in ability to perform an FTP (File Transfer Protocol) GET function. You do this by typing:

        ftp://TGDownloads@guyhaas.com:TGDownloads@guyhaas.com/ 

into the browser's search bar. Figure H.1 shows doing this with the Chrome browser.

Figure H.1

And once you've entered it, Figure H.2 shows what you'll get.

Figure H.2

You can then download TG.jar simply by clicking on its name.

Another file that may be of interest to you is TG_VersionHistory.txt. As the name indicates, it is a list of what has changed in TG. If you are interested in what has changed in some version, simply click on its name and read through it.

Using A Command Prompt, Terminal, or Shell Window

Another way to FTP TG.jar is via a Command Prompt (Windows), Terminal (OS X), or shell (Unix/Linux) window. If you are using Windows and are unfamiliar with a Command Prompt window, here is Gizmo's description.

Here is an example session.

    C:\Users\guy> ftp ftp.guyhaas.com
    Connected to guyhaas.com.
    220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------
    220-You are user number 1 of 500 allowed.
    220-Local time is now 13:54. Server port: 21.
    220-This is a private system - No anonymous login
    220 You will be disconnected after 15 minutes of inactivity.
    User (guyhaas.COm:(none)): TGDownloads@guyhaas.com
    331 User TGDownloads@guyhaas.com OK. Password required
    Password: TGDownloads
    230-OK. Current restricted directory is /
    230 0 Kbytes used (0%) - authorized: 1024 Kb
    ftp> bin
    200 TYPE is now 8-bit binary
    ftp> get TG.jar
    200 PORT command successful
    150-Connecting to port 28325
    226-File Successfully transferred
    226 0.259 seconds (measured here), 1.34 Mbytes per second
    ftp: 362290 bytes received in 0.34Seconds 1065.56Kbytes/sec.
    ftp> bye
    221 Logout.

    C:\Users\guy>
                        

What I typed is in green.  Numbers that will vary are in blue. The email address you type in at the "Password:" prompt is not displayed.

Starting with TG v.9.36.1, new versions will available as *beta* software.  Once I have a version of TG in what I believe to be release quality, I will put it on the net for access using ftp.  As always, it will not become the standard TG.jar until I have put it through a lot of testing.

There is a file I maintain on the ftp server that may be of interest to you - TG_VersionHistory.txt.  As the name indicates, it is a list of most of what has changed in the different versions of TG.  This documentation is often provided before I update the ItP lessons website, sometimes even before I update the help file.  If you are interested in what has changed in some version, simply get the file with ftp and read through it.  Here is an example snippet of the file:



    Version 0.9.38.2
    ----------------
    Added commands NOROUNDING and SETROUNDING.

    Added operators LABELHEIGHT, LINECAP, and
    PENPATTERN.

    Fixed bug where missing closing bracket or
    parenthesis was not reported.

    Improved an error message for missing input in
    a procedure invocation.  When error message was
    "XXX doesn't output value" and it now has
    "; YYY expects more inputs" appended onto it.

                        

How To Start TG

There are a couple of ways to run TG. 

Some users like to place the TG.jar file on their desktop and double-click on the displayed icon to start it.

I prefer creating a folder (subdirectory) in a user's home directory for TG.jar, named ItP on my computers.  It can be started by double-clicking on it's name in the system's directory display program.  But, I prefer to:

  1. open a shell or terminal emulator (e.g., a Command Prompt window on a Windows system),
  2. change the current directory to the one containing TG.jar, and
  3. start TG with the java command:
        java -jar TG.jar
    			

I do this for a few reasons.  The first is that there are a bunch of options that can be appended to the command.  As an example, you can have TG start with an Editor subwindow of a specified height running in Emacs mode.  If I'm using a notebook attached to a projector in a classroom, I can specify a large sized font.  For a list of supported options, enter the command:

    java -jar TG.jar help
			

A second reason is that starting TG this way sets the current working directory to be wherever you are when the command is entered.  As an example, if I'm using my Windows 7 system with TG.jar in the ItP subdirectory, I open a CommandPrompt window, cd to ItP, and start TG with a java command; this makes TG's current working directory C:\Users\guy\ItP

Figure H.3

resulting in the following TG window appearing.  I typed in the pwd (print working directory) directive to show the current working directory.

Figure H.4

A third reason is that this introduction to computer programming is targeted to follow an introduction with a drag-n-drop environment, Scratch in particular.  It is targeted to precede an advanced placement computer science (AP CS) class since it has a much simpler syntax than either the Python or Java programming language.  I want the student to start to explore what's under the covers on their computer, to be exposed to interacting with the system at the command line level.  If you need to learn more about working at the command line level on your system, use Google search with the words "command" and "line" along with the name of your system, e.g., Windows.

One last reason is that TG prints "this should not happen" error messages in the window it was started in.  If you see any of these messages, I'd like to know about them - email me please.

Media Files

Picture Files

Throughout the lessons there are references to picture files and audio files.  As you are playing with TG running as an applet (included in most of the lessons), when you access a media file, it is downloaded from the network.  But if you are using TG on your computer and want to use media files, you are going to have to install the media files on your computer.

So, how do you get them?

Here are links to all of the picture files available to the TG running as an applet:

The way you save (download) one of these picture files onto your computer for use with TG depends on your computer system and browser.  On a Windows system with the Chrome browser, to save (download) one of these picture files onto your computer, left-button-click the mouse on the link above.  This will bring up the picture in your browser.  You can then right-button-click the mouse on the image and choose "Save image as..." from the pop-up menu. 

On an Apple system with the Chrome browser, click the mouse on a link above.  This will bring up the picture in your browser.  You can then hold the [control] key down and click the mouse on the image; this will open a pop-up menu from which you can choose "Save image as..."

Figure H.3 shows the pop-up menu on my system.

Figure H.5

You system will pop-up a window that helps you save the picture file.  At this point you should select the directory where you want to access the file from.  This is probably the directory that contains your Logo programs.  If you are unsure, please read the next section (Current Working Directory).

This same method of saving picture files works with most pictures you can find on the net.  And don't forget to search your computer for files with the most common picture file suffixes, e.g., *.jpg, *.png, ...

Sound Clip Files

TG.jar has eight sound clip files included in it.  This is similar to support for the built-in shapes for the turtle.  There are some additional sound clip files on the BFOIT website.  Here are links to them; they can be saved onto a computer similarly to the way you save picture files.  As I improve lessons, incorporating more audio into the programs, I will provide links to more.

Current Working Directory

When you start to work with media files or have a program subroutine library, you need to become familiar with the file system on your computer.  When you start to use loadclip, loadpicture, and/or loadshape commands, they take an input which is a file specification.  loadcode can be used to include bits of source code into new programs; and its input is a file specification.

What is a file specification?

In its simplest form, a file specification is just the name of a file, e.g., Cat.wav, clouds.jpg, colors.jlogo, etc...  For this to work, the files must exist in TG's current working directory.  As mentioned above, the current working directory starts out at the folder you are in when you type in the java command to start TG.  At any point, the current working directory can be printed with TG's pwd command.  If, again as described above, you have a directory dedicated to programming with TG (where you have placed the TG.jar file) you can put all of the files you want to load in this directory.  If you do this, you can use the commands audiofiles, pictfiles, and jlogofiles to see the names of files you have in the current working directory.

So, what if the current working directory is not where the files you want to load are?

One way is to use a relative path instead of just the file's name.  As an example, to better organize my stuff, I maintain subdirectories in my ItP directory for the different kinds of files I load.  Specifically, I have an audio subdirectory, an images subdirectory, and a jLogo subdirectory.  If I start TG as described above, I can load files with a relative path, e.g.,

    loadpicture "images\\Underwater.jpg
			

Notice that the backslash ('\') separator in the path has been doubled up.  The escape character for Logo is a backslash, meaning that the character following it should be taken literally.

An identical path can be prefixed to the name of a picture file you want to load as a new shape for the turtle.

    loadshape "images\\Fish_Rt.png 32
			

The following image shows these commands in action.

Figure H.6

As of version .9.35.1 of TG, there is another way.  TG now has a cd directive.  Once you've started TG, you can change the current working directory with cd, giving it an input in the form of either an absolute or relative path.

All of the examples I've given are for a Microsoft Windows system.  For Apple and Linux systems, the paths are slightly different.  On these systems, elements of the path are separated by forward slash ('/') characters so they do not have to be doubled up.  Also, Apple and Linux systems, being Unix-based, do not have a drive specification ("C:" in the above examples), their absolute paths simply start with a forward slash.

Java Turtle Graphics Source Code

You can also do turtle graphics stuff in Java.  I have packaged together support for the graphics-oriented Logo commands and operators from TG, making them available in Java programs you can write.  To access them, you simply instantiate a TurtleGraphicsWindow class, and invoke it methods.

To use TurtleGraphicsWindow, you will need its Java source code and the TG source code files that it accesses.  You must copy these source code files onto your computer and compile them.  I've put all of the source code you need into a .jar file and placed it on the website's TGDownloads ftp directory.  Here is an example session of getting the files on a Microsoft Windows system.

    C:\Users\guy> ftp ftp.guyhaas.com
    Connected to guyhaas.com.
    220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------
    220-You are user number 1 of 500 allowed.
    220-Local time is now 13:54. Server port: 21.
    220-This is a private system - No anonymous login
    220 You will be disconnected after 15 minutes of inactivity.
    User (guyhaas.COm:(none)): TGDownloads@guyhaas.com
    331 User TGDownloads@guyhaas.com OK. Password required
    Password: TGDownloads
    230-OK. Current restricted directory is /
    230 0 Kbytes used (0%) - authorized: 1024 Kb
    ftp> bin
    200 TYPE is now 8-bit binary
    ftp> get TGW_Src.jar
    200 PORT command successful
    150-Connecting to port 29470
    226-File Successfully transferred
    226 0.180 seconds (measured here), 1.48 Mbytes per second
    ftp: 280495 bytes received in 0.31Seconds 901.91Kbytes/sec.
    ftp> bye
    221 Logout.


    C:\Users\guy> jar xvf TGW_Src.jar
     created: META-INF/
     inflated: META-INF/MANIFEST.MF
     inflated: AbortException.java
     inflated: ArrowTurtle.java
     inflated: BallTurtle.java
     inflated: BoxTurtle.java
     inflated: CrossTurtle.java
     inflated: DiamondTurtle.java
     inflated: Params.java
     inflated: PixelRectangle.java
     inflated: Sprite.java
     inflated: SpritePixels.java
     inflated: TGCanvas.java
     inflated: TGFileIO.java
     inflated: TGArcOp.java
     inflated: TGFillOp.java
     inflated: TGGraphicsOp.java
     inflated: TGKeyHandler.java
     inflated: TGLabelOp.java
     inflated: TGLineOp.java
     inflated: TGMouseHandler.java
     inflated: TGPoint.java
     inflated: TGSetPixelsOp.java
     inflated: TGWexample1.java
     inflated: TGWexample2.java
     inflated: TGWexample3.java
     inflated: TGWexample4.java
     inflated: TGWexample5.java
     inflated: TGWexample6.java
     inflated: TGWexample7.java
     inflated: TriangleTurtle.java
     inflated: TurtleGraphicsWindow.java
     inflated: TurtleTurtle.java
     inflated: Clouds.jpg
     inflated: Parrot.png
     inflated: compile_tgw.bat

    C:\Users\guy>
                        

What I typed is in green.  Numbers that will vary are in blue. The email address you type in at the "Password:" prompt is not displayed.

If you would prefer to access the files in .zip format, I've provided a file, TurtleGraphics.zip, in the ftp directory.  Make sure to use ftp's bin command to transfer the file in binary/image mode.

Public Domain Mark
This work (BFOIT: Introduction to Computer Programming, by Guy M. Haas),
identified by Berkeley Foundation for Opportunities in IT (BFOIT),
is free of known copyright restrictions.