                               FIELD guide

Before doing this demo the student should have a basic knowledge of the X window system - 
   a. how to create windows 
   b. how to use the mouse and keyboard as input devices in X 
   c. user should be familiar with various user-interface objects - 
      pull-down menus, dialog boxes, scroll bars, icons
 
Part I - Preparing for the Tutorial

   1. make a directory called field - mkdir field
   2. enter this directory by typing - cd field
   3. copy files in directory <tutorial directory> to the current dir - cp <>*.c  .
   4. add the directory /cs/bin/field to the path variable of your .cshrc file
      /* elaborate here */

Getting into the FIELD environment

   1. start X window system 
   2. move the mouse to any window and type -  field   
      The Control Panel window will be placed on the screen. 
      Fig. 1  - Diagram of control panel.

   
The Control Panel and Help Feature

   /* short description of control panel */
   /*   1. what is on the control panel - what the buttons stand for */
   /*   2. features about the windows */
   /*       a. moving  */
   /*       b. changing size */
   /*       c. removing vs. iconizing */
   /*          clicking on the remove button of the control panel doesn't do anything */
   /*          shift-clicking on the remove button of control panel doesn't do anything */
   /*          clicking or shift-clicking the remove button of shell makes it go away - no icon */
   /*       d. pushing and popping */
   /*       e. pull-down menu bar */
   /*       f. bar at bottom of screen to display info about file */
   /*       g. name of the window */

   1. Choose the Shell button from the UNIX menu.  This should bring up a 
      UNIX shell from which you can do any commands. You will be in your home 
      directory.  From this shell you can execute any of the normal shell commands.
      For instance, type the pwd command and this will tell you that the current 
      directory is your home directory. 
      Fig. 2 - Picture of the FIELD UNIX shell.
      
   2. Choose the Help from the Commands menu.  
      Fig. 3 - Picture of Help Information window.  
      /* stress heirarchical help information */
      /* might want to leave this open so that you can refer to it later. */
      The HELP Information tool of FIELD provides online documentation for the user.
      The two paneled windows beneath the title HELP Information contain a list of 
      the topics which online help documentation is available for.  The small window 
      below the topics displays the name of the help information that is being currently
      displayed.  

   3. Choose control from the topics list.
      Fig. 4 - Help information on control
      The help information for the control panel is divided into topics.  Each of 
      these help topics represents an icon on the control panel.  For other,
      help information windows, the topics describe the menu buttons that are available.

   4. Choose dbg from the topics list to see a description of what the dbg tool 
      does.  
   
   5. Choose ^^control from the topics list to get back to the control panel help window. 
 
   6. Choose ^^ field to return to the field help window.

   7. Choose Mouse Help from the Commands menu.
      There is also a help facility to provide information about the mouse buttons.
      Fig. 5 - Mouse Help information

      This help window displays the function of each of the left, middle, and right
      mouse buttons in that particular window.  For example, move the mouse into the 
      help information window.  Information describing the action of the mouse 
      buttons should appear in the MOUSE HELP Information window. 
      
  
Editing a File with the aedit Tool

    1. Starting aedit from control panel
       To start aedit click on the E icon labeled aedit.   You will be prompted 
       for the position of the new window.  Move the mouse where you would like the
       upper left hand corner of the window to be and click the left mouse button.
       A new window with a dialog box called Annotation Window will appear.  Move the
       cursor into the dialog box and type <filename> in the rectangular box to the right
       of the word name.  Next, click on the accept button and the current contents of the 
       file are displayed.   Since <filename> is a new file, the window should be empty.

       There are several features of the edit window noted in Figure XX.

    2. Adding text (formatting feature)
       Adding text in the field editor is simple.  Just type the letters from the 
       keyboard.  When you want to go to a new line just type a return.
       Type in the following C routine:
         /* main routine for list program */
       Notice that when you hit return after typeing main(), the cursor is indented on the 
       new line.  This is the indenting feature of the field editor.  It allows the user to 
       format program code quickly and easily.  You can turn off the indentation feature 
       by choosing the SetMode button from the Edit menu and deselecting the auto_indent
       radio button.


    3. Moving throughout a file
       a. scrolling (menu and scroll bars)
       b. using the move menu command 

    4. Searching for a string in a file

    5. Positioning a line in the window

    6. Cutting Text
 
    7. Copying Text 

    8. Pasting Text 

    9. Saving a File
        a. Savefile
        b. Saveas

    10. Closing a File (Quitting the editor)
        a. Closefile 
        b. Closeabort 

Building an Executable with the Build Tool

    1. Click on the M(build) icon and the M(transcript) icons.    
       The two windows shown in figure XX should appear.  The Build window is 
       for the build window while the transcript window echos any messages that 
       would appear in the shell.

    2. Setting the project 
       /* say something about what a project is */
       Choose Set Project from the Project menu.  A dialog box 
       like the one in Figure XXX should appear.  Click on the 
       accept button.   Since you started field in the directory that 
       your tutorial code is in your project should be in the
       current working directory.

    3. Declaring File Dependencies  

       a. Choosing the file to set dependancies for

       Choose setfile from the File menu.  A dialog box similar to
       the one pictured in Figure XX should appear.  Click on the file
       list.c and then choose accept.  

       b. Setting the Dependancies
       
       Click on the middle mouse button to the right of the word 
       Dependencies.  The dialog in Figure XX
       should appear.  The file list.c includes the header file list.h
       and therefore list.h is a dependant file, i.e. if list.h changes
       then list.c will have to be recompiled.  Choose list.h from 
       the list of files by clicking on it and then choose accept.
       The file list.h should now appear under the word dependancies.
       Choose sorter.c from the list of files.  
     
       c. Setting Dependencies for sorter.c

       Declare that sorter.c is dependent on list.h by following 
       steps 3a and 3b. for the file sorter.c.

       d. Creating the link command 

       Set the file to sorter.  Make it dependent on list.o and 
       sorter.o. In the bottom window type the link command 
       $(CC) -o sorter list.o sorter.o telling the make command
       to link the files list.o and sorter.o together to make an 
       executable.

       e. Saving the File Relationships

       Choose Save from the Project menu to save the dependencies
       that you have just set.  The project is saved so that the 
       next time you start field, you will not have to reset all
       the file dependencies.

    4. Graphical Views of File Dependencies 

       File dependencies can be represented as a directed graph with 
       each node representing a graph and each arc representing that 
       the source node is dependent on the destination node.  
       To view the dependency graph for a file, first choose Graph from 
       the Windows menu and then set the file using the Set File
       button from the File menu.  The dependency graph for sorter 
       is shown in figure XX.  

    5. Compiling Files

       a. Open Sorter.c with the annotedit Tool

       The annotedit tool has an editor like aedit tool, but 
       uses graphical symbols for compiling and debugging. To 
       open sorter.c, click on the annotedit icon in the control 
       panel.  A dialog box should appear asking for the name to the 
       file to edit.  Type sorter.c in the name field of the 
       dialog box and click on the accept button.  A window like 
       the one shown in Figure XX should appear.

       b. Set the Build Display Window to Transcript

       Choose Transcript from the Windows menu of the Build tool.
       The resulting Build view should look like Figure XX.

       b. Compiling a File 
       
       Choose compile from the Commands menu.  A thin message bar
       should appear saying that it is compiling your file.  After
       the compilation is done, a dialog should appear with the 
       message displayed in Figure XX if there were no compilation
       errors or a dialog box similar to Figure XX displaying 
       the error messages.  Click accept on the dialog box.   If 
       there were any compilation errors or warnings, an E or W 
       enclosed in a box will appear to the left of the line 
       containing the error.  

       c. Displaying Compilation Errors

       To display the error message for a line, click the middle 
       mouse button on the E or W annotation.  A dialog box similar
       to Figure XX should appear telling what the error message 
       is.   Choose accept in the error dialog box.

       d. Correcting Compilation Errors
 
       To correct the compilation errors use the the editor as aedit
       explained in the section YY.

       e. Removing an Error or Warning Annotation

       After you have corrected a compilation error or warning, 
       remove the annotation to the left of the line by clicking 
       the middle mouse button on the annotation, clicking on the
       box to the left of the word remove, and then choosing accept.
       This is useful for keeping track of which compilation errors 
       have been fixed and which have not.

       f. Producing a Valid .o File  
    
       Keep on doing the above steps until you get no more compilation
       error messages.  

      
   6. Making the Final Running Version  

      To link all the of the files together, choose make from the
      Command menu of the Build tool.  A message similar to the one
      shown in Figure XX should appear.


      
Debugging with the dbg tool

  The field debugger is very similar to the dbx debugger on the suns.
  It has a window where commands can be entered by the keyboard, 
  buttons that can be clicked on for controlling the debugger, and 
  breakpoints can be set in the annotation editor.  

   1. Click on the dbg icon on the control panel.  A dialog box 
      and window should appear asking for the name of the program to 
      debug.  Type sorter in the debug field and click on the accept
      button.  The debugger should start up and look like  
      in Figure XX.

   2. Break points

      A break point represents a line in the source file where the 
      debugger will stop executing.  They can be used to stop the 
      program periodically and check the status of the program and 
      hopefully islolate the problem area and find the bug.

     a. Open annotedit sessions on sorter.c and list.c, if you do  
        not already have one open.

     b. Check the annotation type selector to the right of the program
        text to make sure that it is set to BREAK.     

     c. Go to line 20 of sorter.c and press the right mouse button down 
        in the annotation column to the left of the source file.
        A stop sign annotation should be placed in the annotation 
        column.  See Figure XX.

   3. Executing Programs in the debugger.
      The debugger has several different modes that you can 
      execute programs in.  It can step through the program one
      line at a time or run the program continuously until it hits a 
      breakpoint or the program exits. 

      a. Running the program con
         
       
      


Using Graphical Views of Programs

1. Displaying Program Structure with flow

   The flow tool will automatically produce directed a directed graph representing the 
   procedure calls in the program.  A node in the graph represents
   a function and an arc represents that the source function calls 
   the destination function.

   a. While you have a debugger session open for sorter, click on 
      the flow icon.  A flow graph for the sorter program should 
      appear and look like Figure XX.


2. Displaying Program Stack with viewstack

   The program stack represents the function calls that a program
   has made.   As the program runs the stack display will automatically
   update itself.   

   a. Open a debugger session on the file sorter.  
  
   b. Open an annotedit on sorter.c if you have not already.
   c. Click on the viewstack icon from the Control Panel.  A window 
      similar to the one shown in Figure XX should appear.  
   d. Set a breakpoint at the first line of the function main.
   e. Choose run from the debugger buttons to execute until the first 
      breakpoint.   
    
   f. The stack viewer should have been updated and the new view should
      look like figure XX.  Each function call entry on the stack 
      is offset by a number representing the stack level.  The highest
      number appears at the top of the screen and represents the current
      procedure that is executing.   Each stack entry also includes
      the parameters to the function in parenthesis, the line number
      and source file that the function is defined in, and a list
      of the values of any local variables.

   g. Choose step from the debugger buttons and an entry in the 
      stack should be produced for the function call to 
      create_new_item.  The stack will continue to be updated as 
      the program runs.    
      

3. Analysis of Program Efficiency with fprof

After you have run your program through once.  You can use the 
profile command to evaluate program efficiency.


4. Displaying Data Structures with typeedit and display


 

        


               
     

     
