StarTool Frequently Asked Questions 1. OVERVIEW 1.1 What is StarTool? 1.2 What are star diagrams? 1.3 Why use StarTool? 1.4 What languages does StarTool support? 1.5 Where can I find more information, help, or tips about StarTool? 1.6 Is there a mailing list? 1.7 Is StarTool open source? 1.8 Who is the principal investigator? 2. GETTING STARTOOL 2.1 What are the system requirements for StarTool? 2.2 Can I still run StarTool if I don't run Linux, Solaris, or Windows? 2.3 What software do I need on my computer before I install StarTool? 2.4 Where can I download StarTool? 2.5 My only access to the Internet is email. How do I get StarTool? 3. INSTALLATION 3.1 Where do I unpack the files? 3.2 Is there an installer/configure script? 5. GETTING STARTED 5.1 How do I start StarTool? 5.2 How do I load files into StarTool? 5.3 How do I view the files? 5.4 How do I search for text? 5.5 How do I create a star diagram? 5.6 How can I expand/collapse portions of the diagram? 5.7 What are all of these at-signs (@) on the nodes? 5.8 Can I trim/prune a portion of the diagram? 5.9 Can I save my star diagrams? 6. TROUBLESHOOTING 6.1 StarTool complains that it can't find tcl/tk, but I'm sure it's installed. 6.2 When I try starting StarTool, I just get a blank window. What's wrong? 6.3 StarTool complains that it cannot find a library. For example, ld.so.1: polaris: fatal: libXext.so.0: open failed: No such file or directory 6.4 I keep getting parse errors for a certain file. What's wrong? 6.5 I can't seem to add any files which include system headers such as stdio.h or stdlib.h. StarTool keeps reporting that it can't parse the files due to missing __attribute__ or __const declarations. 6.6 Is there any way I can prevent cstar from expanding the #include's? 6.7 What do I do if I still can't get things to work? 7. FAQ ISSUES 7.1 Where is the official copy of this FAQ? 7.2 How do I add a question and/or answer to this FAQ? 8. CREDITS Copyright and Disclaimer ---------------------------------------------------------------- 1. OVERVIEW 1.1 What is StarTool? StarTool is a software engineering tool designed to aid the understanding and maintenance of software. It is based on graphical visualizations of code called star diagrams. 1.2 What are star diagrams? A star diagram is a tree of all the direct and indirect references to one or more variables in a program. StarTool presents star diagrams in a graphical form that the user can manipulate. 1.3 Why use StarTool? Performing a restructuring to encapsulate a data structure can be difficult since most of the code related to the data structure is distributed over the entire system. Star diagrams provide a low-level representation of source code that can help a programmer focus on the area of the source code most relevant to the restructuring task at hand. StarTool can further help plan a restructuring by recording a list of changes. More specifically, the intent to create an abstraction may be recorded by ``trimming'' a node from the star diagram. A trim can be viewed as an independent star diagram to aid performing the restructuring later. 1.4 What languages does StarTool support? There currently exist tools for analyzing programs written in C (cstar), Ada (adastar), and Tcl/Tk (tclstar). There are also multilanguage tools for analyzing programs written in both C and Tcl/Tk (ctclstar) and C, Tcl/Tk, and Ada (ctcladastar). We forsee providing support for C++ in the near future. 1.5 Where can I find more information, help, or tips about StarTool? Check out the StarTool website: http://www.cs.ucsd.edu/~wgg/Software/StarTool for the latest information on the tool. The website also has copies of the StarTool Users' Manual and a comprehensive list of academic papers and theses on StarTool. 1.6 Is there a mailing list? Not at this time. For now, direct questions to William Griswold (wgg@cs.ucsd.edu). 1.7 Is StarTool open source? The source code for StarTool is not freely available from our website. However, should you desire to compile the code on a platform we're not currently supporting, email William Griswold (wgg@cs.ucsd.edu) for assistance. 1.8 Who is the principal investigator? William Griswold (wgg@cs.ucsd.edu) is the principal investigator. Professor Griswold is a faculty member of UCSD's Computer Science Department. His research interests are in software engineering generally, and software evolution specifically. 2. GETTING STARTOOL 2.1 What are the system requirements for StarTool? Binary configurations of StarTool are available for the following configurations: Platform OS ----------------------------- Sun Sparc Solaris/SunOS Intel x86 Linux Intel x86 Windows 95/NT HP-PA HP-UX Intel x86 BSD/OS The complete version of StarTool, with support for C, Ada, and Tcl, requires approximately 20M of free disk space. 2.2 Can I still run StarTool if I don't run one of the platforms listed above? Source distributions of StarTool are available through William Griswold (wgg@cs.ucsd.edu). 2.3 What software do I need on my computer before I install StarTool? If you intend to use a version of StarTool which supports Ada (adastar or ctcladastar), you must also have the GNU Gnat-Ada compiler installed on your machine (ftp.cs.nyu.edu/pub/gnat/private/old). StarTool requires Gnat version 3.10. Refer to the users' manual for more information on obtaining and installing Gnat. 2.4 Where can I download StarTool? http://www.cs.ucsd.edu/~wgg/Software/StarTool/download.html. 2.5 My only access to the Internet is email. How do I get StarTool? Email William Griswold (wgg@cs.ucsd.edu). Please include some information about your occupation and what how you plan to use the tool. 3. INSTALLATION 3.1 Where do I unpack the files? Create a directory called 'StarTool' and unpack the files into this directory. 3.2 Is there an installer/configure script? Not at this time. We will definitely have one in the near future. 5. GETTING STARTED 5.1 How do I start StarTool? StarTool/bin contains the binaries for the different versions of StarTool. All of the tools have 'star' in their name. For instance, the version of tool for analyzing C programs is called 'cstar' and the tool for analyzing programs written in both C and Ada is called cadastar. 5.2 How do I load files into StarTool? Click on the 'add files' button and select the file(s) you wish to import into StarTool. 5.3 How do I view the files? Select a file from the file browser list box (directly below the caption box). Click on the 'Display File' button. Alternatively, you can double click on a file from the file browser. 5.4 How do I search for text? When viewing a particular file, click on the 'Search for a String' button to perform local searches. Global searches are possible using the 'Search for a String in All Files' button located on the main window. In the grep window, type in a regular expression in the edit box and click the 'OK' button or press return. Case sensitivity is controlled by the checkbox labeled 'Match Case'. 5.5 How do I create a star diagram? To build a new star diagram of a variable, first display the file containing the variable. Navigate to the desired variable and then double-click on the variable. Alternatively, single-click on the variable and click on the 'Add to Star' button. Note that if you continue to double click on variables, they will be added to the existing star diagram. To create a new star diagram, first display the previously created star diagram by clicking on its 'Display' button. 5.6 How can I expand/collapse portions of the diagram? When you first display a star diagram, only the root node is shown. To display the entire star diagram, click on 'clear selections' button on the left side of the display. Then click on 'apply to diagram'. You can selectively remove (elide) certain types of nodes (e.g., all if-statements) by selecting one or more options from the 'nodes to exclude' menu and clicking the 'apply to diagram button'. 5.7 What are all of these at-signs (@) on the nodes? An '@' sign represents the name of the identifier contained in the topmost node of the star diagram. For example, a node labeled '@ []' indicates a C array reference. 5.8 Can I trim/prune a portion of the diagram? Yes. First find the root of the subtree you wish to prune. Select it by clicking on the node once. Then click the 'Add to Arm List' button on the top of the window. This process of trimming nodes is fundamental to creating a restructuring plan. Refer to the Users' Manual for more information. 5.9 Can I save my star diagrams? Yes, click on the 'Save' button on the main window. This will save any star diagrams you've created, along with the list of trimmed nodes for each star diagram, and the list of project files. 5.10 How do I close a project and start a new one? There is currently no support for 'New Project' or 'Close Project'. Exit StarTool and start it again with a blank project. 6. TROUBLESHOOTING 6.1 StarTool complains that it can't find tcl/tk, but I'm sure it's installed. You need to set the TCL_LIBRARY and TK_LIBRARY environment variables to point to the tcl and library files. For example, on Linux, the library files for tcl/tk are usually located in /usr/lib. If you're using csh/tcsh, add the following lines to your .cshrc: setenv TCL_LIBRARY /usr/lib/tcl8.0 setenv TK_LIBRARY /usr/lib/tk8.0 Also make sure that StarTool/bin is in your $PATH variable. 6.2 When I try starting StarTool, I just get a blank window. What's wrong? StarTool needs to know the location of the Tcl/Tk code for its user interface. Try the following command: cstar ../tcl replace 'cstar' with the version of StarTool you trying to run. 6.3 StarTool complains that it cannot find a library. For example, ld.so.1: polaris: fatal: libXext.so.0: open failed: No such file or directory Portions of StarTool system use dynamically linked libraries. Some systems have troubles resolving these links if the installation is not exactly like ours. In this case, you need to find where the missing library is and set your link/load path as follows. For example, the libXext.so.0 library is located in /usr/openwin/lib/ on most Solaris systems. We add the following line to our .cshrc: setenv LD_LIBRARY_PATH /usr/openwin/lib 6.4 I keep getting parse errors for a certain file. What's wrong? Cstar sometimes has difficulty processing files with complex include file dependencies. It's worth it to first run the project files through the C preprocessor to generate *.i files. Refer to the Users' Manual for information on generating proprocessor output. 6.5 I can't seem to add any files which include system headers such as stdio.h or stdlib.h. StarTool keeps reporting that it can't parse the files due to missing __attribute__ or __const declarations. We've experienced some problems using cstar on Linux. Although we are not certain of the cause of the problem we do have a workaround that requires you to insert the following lines before including any system header files: #define __const const #define __attribute__(a) 6.6 Is there any way I can prevent cstar from expanding the #include's? Not at this time. Cstar currently uses the parser from an open-source tool for analyzing C programs called Icaria. We realize that expanding #include's can make the files difficult to manage. In future versions, we may rely on the GNU gcc parser instead. 6.7 What do I do if I still can't get things to work? First consult the StarTool Users' Manual available on our website (http://www.cs.ucsd.edu/~wgg/Software/StarTool). If you still can't find the answer to your question, email Michael Copenhafer (mcopenha@cs.ucsd.edu). Please include with your problem description any configuration details (esp. platform, os, StarTool version) 7. FAQ ISSUES 7.1 Where is the official copy of this FAQ? The official copy is available on the StarTool website http://www.cs.ucsd.edu/~wgg/Software/StarTool 7.2 How do I add a question and/or answer to this FAQ? Email Michael Copenhafer (mcopenha@cs.ucsd.edu). 8. CREDITS This work is copyright 2000 by Michael Copenhafer and William Griswold. You may freely redistribute this document provided the authors' names are not removed. This article is provided as is without any express or implied warranties. While every effort has been taken to ensure the accuracy of the information contained in this article, the authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.