Alpha_1 Developer's Handbook Alpha_1 Developer's Handbook
Copyright (C) 1994-2000 University of Utah.
All rights reserved.
This is the Alpha_1 Developer's Handbook. This handbook is intended to be used by graduate students, staff, and visitors who are supported directly (as research assistants) or indirectly (by providing access to the graphics lab machines) by the Alpha_1 project. It describes various aspects and items of policy and procedure which have been established by the faculty and staff of Alpha_1. The handbook is provided as a quick reference so graphics researchers can be aware of the procedures and know what is expected. If you are still not clear on an issue after reading the handbook, please feel free to contact an Alpha_1 staff member.
The Alpha_1 User's Manual and Alpha_1 Programmer's Manual are the primary reference works for users and developers, respectively, of Alpha_1 software. This handbook is reference that records information about group organization, general graphics lab policies, and the basics of Alpha_1 development for staff and research assistants.
There have been, and continue to be, many sponsors of the research which is directed by Rich Riesenfeld and Elaine Cohen at the University of Utah. Active areas of research emphasize topics in the areas of Computer Aided Geometric Design, Computer Aided Manufacturing, Computer Graphics, and Scientific Visualization.
Over a period of several years ARPA has sponsored a sustained program of research here in the area of integrated mechanical design and manufacture, and related activities.
Utah is the administrative home for the National Science Foundation Science and Technology Center (STC) in "Computer Graphics and Scientific Visualization." The Center consists of five separate sites located at five universities: Brown University, California Institute of Technology (CalTech), Cornell University, University of North Carolina at Chapel Hill (UNC), and University of Utah.
The goal of this consortium is to forge a collaborative effort that joins together the strengths of each institution to advance the subject area in a fundamental way. It is hoped that an atmosphere of considerable interaction and exchange within the Center will come about.
The STC receives generous vendor support which contributes heavily to the facilities which the project enjoys.
We have also been designated a State Center of Excellence in Computer Graphics and Scientific Visualization. This provides recognition of the activities of the Center from the State of Utah, especially with regard to work that is likely to advance the economic and employment opportunities for Utah.
The "GDC group" consists of faculty members, full-time professional staff, and students who work on a wide range of projects which fall in the categories of CAGD, CAD/CAM, scientific visualization, and graphics. "GDC" stands for "Graphics, Geometry, and Computation".
The main body of software produced by the GDC group is called "Alpha_1", after the discrete-spline alpha functions. (We used to call the group and the software project by the same name, but that got confusing.)
The faculty members heading the project (with their e-mail addresses, campus extensions and office numbers) are:
Rich Riesenfeld rfr@cs.utah.edu, 1-7026, MEB 3408Elaine Cohen cohen@cs.utah.edu, 1-8235, MEB 3404
Sam Drake drake@cs.utah.edu, 1-7933, MEB 3334
The faculty members are the primary contact for students as they are developing thesis topics and performing their thesis research, although the staff members help informally in these areas as well.
Most day-to-day procedural issues, software issues, and direction of Research Assistants' activities are handled by the staff members. The staff members are:
Russ Fish fish@cs.utah.edu, 1-5884, MEB 3336David Johnson dejohnso@cs.utah.edu, 5-1726, MEB 3330
Tom Thompson tthompso@cs.utah.edu, 1-5642, MEB 3349
David serves as the point of contact for the staff. If you have questions about how to handle a certain problem, or who to see about a particular issue, check with David.
The Alpha_1 staff is responsible for many of the ongoing aspects of the project. A partial listing of staff activities includes:
- Short, medium, and long-range project planning
- Software design and architecture
- Software development, maintenance, and portability
- Software releases
- Consulting with students on research and development issues
- Performing research
- Tours, demos, and lectures
- Documentation
- Modeling projects
- Facilities planning and development
All staff and student members of the Alpha_1 project take some responsibility for all these areas. The staff members have special expertise and long-term experience in particular areas, and students are encouraged to ask questions and learn from the staff. The Alpha_1 staff is funded specifically to advance the research agenda. Providing student assistance is not their primary responsibility. Staff and students together have a mutual interest in maintaining such an environment. Therefore, students will get much more positive responses from staff members if they come requesting information about fixing a bug than if they hand in a bug report with an implicit expectation that it should be fixed for them.
Some useful mailing lists for reaching the GDC faculty, staff, and students are:
- gdc-all@cs.utah.edu or gdc@cs.utah.edu
- GDC faculty, staff, students, and users. This is a large list which should be used whenever the information is specific to Alpha_1 and not of general interest to the graphics community at Utah.
- gdc-execs@cs.utah.edu
- The faculty associated with the GDC project.
- gdc-staff@cs.utah.edu
- GDC Technical and administrative staff.
- gdc-grads@cs.utah.edu
- GDC grad (and undergrad) student research assistants.
- a1-soft@cs.utah.edu
- GDC technical staff and research assistants involved with the Alpha_1 software.
- a1-bugs@cs.utah.edu
- Mailing list for Alpha_1 bug reports. (This is usually just the staff.) No promise is made that bugs will get fixed in any reasonable amount of time, but this provides a place to send them and we'll do our best to advise you in fixing the bug yourself or finding a work-around.
All distribution of Alpha_1 is under license from our tech-transfer company named Engineering Geometry Systems (EGS), which has offices downtown. Their main focus is developing commercial CAD/CAM products based on the Alpha_1 code base, with their own proprietary additions. The Alpha_1 research software system is available to other universities and educational institutions for a nominal distribution fee, but a license from EGS is required. Inquires about how to get a copy of the system should be directed to:
Glenn McMinn
Engineering Geometry Systems
275 E. South Temple
Salt Lake City, Utah 84111-1247
(801) 575-6021
mcminn@cs.utah.edu
General purpose group meetings for GDC staff and students are arranged on a quarterly basis and annouced via mailing lists. Alpha_1 working groups are subsets of the larger group (usually 5-10 people) which meet periodically, depending on interest, to discuss specific issues focused on particular target areas. Working groups in the past have dealt with areas such as ray-tracing, trimmed surfaces and booleans, constraints, dependencies, NC and process planning, animation, and user interfaces.
Each working group (and the larger GDC group) maintains a separate mailing list, all of which are on ~alpha1/a1mail. GDC group members can add or remove your own name from any working group mailing list if you wish, or send mail to dejohnso@cs.utah.edu.
GDC meetings are generally held in the graphics lab conference room (MEB 3349).
Demos and tours come up regularly for various reasons. Our lab is a very popular one for general University activities because computer graphics is attractive. Demos range from tours for high-school students who have no computer literacy to site visits for representatives of our funding agencies.
We do a number of tours as a service for the larger University and state community of which we are a part. Most students who have worked a summer with GDC should be able to conduct one of these demos. All tours and demos (except informal personal ones) must be cleared through the faculty and/or staff. We cannot respond to every request, so we have to strike a balance between showing people our work and getting the work done. Please be willing to take your turn to do these tours ocassionally.
The tours and demos for research sponsors (which come up less often) are extremely critical. If you are asked to participate in those demos, you will be told exactly what we want to show. If you are not participating, then you will be asked to stay out of the way. This generally means helping to clean up the lab and then staying out during the demos, as well as staying off of any machines that are being used for the demos.
Here are some possible demos to use if you are doing tours:
- Alpha_1 Videotapes
- Run about 12 minutes, VHS and 3/4" format tapes should be in the lab at all times. There are several versions, all should be labeled. You should view them ahead of time to make sure they talk about what you want to cover. This is the most boring form of demo, however. Do not remove the videotapes from the lab, and do not make copies without permission.
- Slide Show
- There is a slide carousel in the graphics lab conference room with a good a sample of Alpha_1 images.
- viewa1
- Always a nice demo, especially on a device with some real graphics hardware (i.e., an SGI, not a Sun). Show your own models or some of the "standards" (teapot, helicopter, marine propeller, scissors).
- SGI Demos
- Most are fairly self-explanatory.
- shape_edit
- Prepare these carefully. It is very, very hard to do a nice demo of shape_edit for someone who is not very familiar and very interested in what we do here.
For a patient, interested, computer-oriented visitor, almost any scl file can be stepped through for a demo if it is reasonably well organized and clean.
GDC supports a number of students as Research Assistants (RAs) during the summer and through the academic year.
It is important that students who are RAs for GDC have taken the full graduate course sequences in computer graphics (CS651-2-3) and computer aided geometric design (CS667-8-9). This is necessary because it is a specialty of our research emphasis, and students need to be familiar with these concepts. Our research funding is based on making advances in both areas and in applications of these areas. Moreover, outsiders expect students who have worked with us to have acquired this knowledge. We feel that the time to learn the material is in classes, not during the summer when knowledge and familiarity with the subject matter should be assumed. Hence, performance in CS651, 652, 653 (the graphics sequence) and CS667, 668, 669 (the CAGD sequence), or equivalent (i.e., you had such courses elsewhere) is a significant factor in determining qualifications of new (and some old) students to be summer RAs on our projects. Further, knowledge gained from other special topics courses and seminar courses in these and related areas help prepare a student to make research contributions more rapidly. Obviously, overall graduate performance is a general indicator used by many projects.
RA funding is not a fellowship. It is an employment relationship that furthers the interests of all associated parties. Our project is funded to perform directed research and we must account for, present, and defend our decisions and efforts routinely. This includes our choices of students, the projects on which they work, and their progress. Many of the workstations and other graphics and visualization equipment which graduate students use have been obtained as the results of such efforts and we must report to those sponsors also. Students who are hired as RAs are responsible for helping advance research goals that we are funded to pursue. We also want students to quickly become familiar with research areas and problems in which they might work for their theses, and to start experimenting and making contributions early. So, a candidate RA, after initial discussions with faculty and staff, will be requested to make a proposal stating the particular subproject area(s) in which they want to work and what they plan to accomplish, both for themself and for advancing the project goals. These proposals are usually developed collaboratively by the faculty, staff, and student. We strive to have students work on projects in which they are interested and which advance their research as much as possible, although there are usually "service" components involved in the employment.
In summary, we view research assistantships as bilateral arrangements which should be mutually beneficial provided that a good match is present between project objectives and student preparation and interest. The RA relationship serves best when there is a good understanding of the needs of all parties to the agreement.
Students who want to receive summer RA support from GDC go through the following procedure:
Summer projects are usually arranged as much as possible to lie in your area of potential thesis research. If you have defended a proposal, then a portion (but not all) of your summer work is normally directly related to your thesis research. New students get a larger proportion of low-level system maintenance chores, while students with more experience with the project are allowed a larger component of their thesis area to be supported work. Students who are pursuing a thesis topic which is not related to GDC's research goals are rarely given summer support.
Most new students are required to model a part of their choice during their first 2-3 weeks of work. This establishes some familiarity with the purposes of the Alpha_1 system, and illustrates that modeling is not as easy as one would like to think. Parts with sculptured surfaces, and simple assemblies and mechanical linkages are particularly appropriate for such a project.
Support levels for summer vary from half-time to full-time. New students are often supported only at half-time for the first summer, while more experienced students usually receive full-time summer support. All of this, of course, depends on how well the proposed projects line up with the research for which the funding is provided and how much funding is available.
The nominal working period for the summer is June 15 through September 15, and there are two weeks of vacation time (usually 1 week on either end). There is flexibility on when you take your vacation, but we would like to know when you can be expected to be around. As you finalize your plans, please mark them in two places: The $a/.calendar file (which loads into your emacs if you have the alpha1 setup), and $a$ploc/year/vacations. Follow the existing format in each file.
When there are many new students for the summer, each will be assigned a "mentor" (another student or staff member who has worked on the project before). These people can help you with questions like "Why doesn't this makefile do the right thing?" and "Where do I look for a function that does this".
Each summer student is expected to make a weekly appointment with a staff member to check progress, to attend whatever working group meetings are appropriate, to attend the weekly GDC group meeting, and to write monthly progress reports, in addition to completing the projects outlined in their summer proposal.
GDC supports several students as RAs during the academic year. Since there is more competition for those positions, the selection criteria are more rigorous than for summer RA funding. Students who receive academic year support will be required to have displayed work which is well above average on their summer projects. A specific set of project goals, mutually agreed on by staff, and the student and approved by the faculty, is required for each quarter of funding.
Before you leave the project with your degree, please check the following list so that your work is available to other members of the GDC group in the future:
- Include a funding acknowledgement in the acknowledgements section of your thesis. This is very important. Even if you were not an RA, your computing time was paid for by these agencies. Most fellowships for graduate students on the project are supplemented by GDC to achieve parity with departmental standards. If you have questions, check with Elaine.
- Add an entry for your thesis and any papers or technical reports that you wrote to $a$ploc/papers/Papers.bib so that we can list them as publications to the sponsoring agencies.
- E-mail a copy of your thesis.bib file to dejohnso@cs.utah.edu for inclusion into the GDC bibliography file.
- Provide a single-sided, unbound copy of your thesis for the GDC archives.
- Provide copies of any papers you used in your research that came from difficult sources (e.g., inter-library loans), so that the next person in the group who needs the paper does not have to dig it up the same way.
- Clean up your home directory and any working directories on the Alpha_1 tree. Leave your software in the best possible shape you can. If it is not installed, make sure a staff member knows where it is. If it needs to be installed, do it. Leave some documentation so someone besides you could run it. Meet with staff to discuss the status of your software before you leave.
- Put any images that will be of general use for demos, or historical documentation on an appropriate subdirectory of $img. Discuss this with staff if you are not sure what is appropriate.
- Turn in your Alpha_1 manuals, so they can be reused by another student.
- Recruit a good student to take your place.
- Carry on with good work that reflects the superior opportunities you have been afforded. Stay in touch with us by keeping your e-mail and post office address up to date.
Printed Alpha_1 manuals are currently provided free of charge to serious users related to the project at the University of Utah who have a legitimate need for them. The following is a list of the manuals:
- Alpha_1 User's Manual
- Alpha_1 Programmer's Manual
- Alpha_1 Developer's Handbook
Most people who are not working for GDC, but are just using the system, will need only the User's Manual. Students who are hired by GDC for work as research assistants during the summer or the academic year will need all the manuals.
In addition, all the manuals are available in the graphics lab for reading, although they must stay in the lab.
Manuals may be obtained from the staff. No attempt is made to keep them in stock all the time, so most of the time you will just have to leave your name to get in line for the next printing.
These manuals and the binders are quite expensive to reproduce and distribute (more than 25 dollars for a single copy of the User's Manual). When you no longer need the manuals, please return them.
All staff and students who receive any support from the GDC project are required to file an informal report of their activities each month. This includes people who use GDC computer accounts, even if they do not receive salaries. For example, a student with an external fellowship who is developing a thesis topic which is integrated with the Alpha_1 software must file monthly reports.
The GDC staff and faculty members use the monthly reports mostly as an aid in reporting research results to funding agencies. They are used in a small way to monitor progress of students, but this is not the primary purpose. These reports are very important! Summarizing a year's progress on a large project is not easy under any circumstances, but it is a great help to have good descriptions of results already on file in small chunks that can be pulled together into a larger document.
A reminder will be sent out at the beginning of each month, requesting that you file your report for the previous month. The sooner you write the report, the easier it is -- because that way you can remember what you did. Reports should generally be submitted by the end of the first week of the month, and certainly no later than the 15th. You will receive delinquency notices periodically until you get it done. Many people find it helpful to keep a rough log of how they spend their time or to make notes regarding ongoing activity, because they can just glance back over them and write their report in a few minutes. This is the easiest approach.
The reports are stored in a separate directory for each month of the year (this facilitates generating reports to our sponsors, who request them to cover specific time periods). The main directory can be accessed, if you have your directory variables set up properly, by cd $a$reports.
The individual monthly directories are named by the first three characters of the month and the last two digits of the current year, as in "jun91".
A template file will have been generated with your name as the suffix, and "a1-" as the prefix. An example might be "a1-smith.tex". You should write your report into this file.
This is a LaTeX format file. If you wish to use LaTeX formatting commands, you may. But also feel free just to type in raw text in any way that looks reasonable.
Initially the file contains the following three lines:
\keyword{ Not Active }
\section{ ... [John Smith, jun91] }
\% time{ 0 }
You should replace the ellipsis ("...") with a title of your work ("Fixing Ray-tracer Bugs", for example). Then look at the file $a$reports/keywords and select a keyword from that list which most appropriately fits the topic. Be sure to exactly copy the keyword, including capitalization. See $a$reports/README for more details.
If you have had more than one active project during the month, copy these three header lines and make new entries for the other projects. Please do not run a whole bunch of unrelated stuff together in the same section, because we usually sort these reports by topics when we are compiling project reports.
Occasionally, when you are beginning a large project, it may be useful to put in a longer description. When you have defended your thesis proposal and begun doing your research, go ahead and put in the abstract or a short version of the introduction to your thesis in the monthly report. Then future reports do not have to give the background information each time, but we have some solid text to use in the project reports.
If you have any questions about your reports, please see Carolyn.
Students are encouraged to write papers for publication in journals and conference proceedings. All papers discussing research related to GDC, or supported by any of the projects headed by Rich and Elaine must be reviewed by Rich and/or Elaine before they are sent out. It is preferable to have early discussions at the time that a paper topic is being considered.
Most importantly, if you were supported by GDC in any way during preparation of the results or the paper itself (and this includes using computer time on any graphics lab machines), then you must include an appropriate acknowledgment of our funding agencies. Please send e-mail to Elaine to get the appropriate text for your paper, video, or other publication.
Once any paper is sent in for publication, you must add a citation to the file
$a$ploc/papers/Papers.biband mention the publication in your monthly report. At various stages when the paper is reviewed, accepted, and published, the citation must be updated. This file, like the monthly reports, is also used for generation of reports to funding agencies.
While the formalities here may not seem important, they are a critical part of sustaining the kind of support that GDC has enjoyed for more than a decade.
A GDC bibliography of sorts is visible on the GDC group page under publications, and is maintained on the directory
/res/gdc/bibs/
It would be very helpful to us if you would send a copy of the (LaTeX) bibliography which you use in any publications to dejohnso@cs.utah.edu. It will be merged with the full GDC bibliography file. Please feel free to copy any entries from the GDC bibliography file when you need the references for your own thesis or other publications.
We are beginning a GDC archive of theses, tech reports and other documents published by members of the group. You are expected to give copies of all publications in final form (especially your thesis) to staff so that it can be added to the archive. Single-sided, unbound copies are prefered, because we want to be able to easily make more copies from the archive materials.
Currently, if you are trying to locate a particular document, Elaine has the most extensive personal library and will sign out books and papers to students.
The Design, Visualization, and Graphics Lab (usually called the "graphics lab") is one of the department's specialized facilities. Through access to the lab, many people are potential users of the workstations and other devices it contains. GDC and graphics users always have priority over people who are not doing graphical work. As on all department machines, playing games has zero priority, even for games that can only be run on the high-end graphics machines (e.g., "flight").
Once you have been set up with an account on the graphics lab machines, and are physically using the lab itself, there are certain civic responsibilities which are expected to be carried out by all users. The faculty and staff normally do not use the lab for day-to-day work, but may drop in at any time with visitors. It is embarrassing to bring a visitor into a sloppy public area filled with very expensive equipment. The following guidelines should not impose a major hardship on anyone.
Note first that no matter how many hours you spend in the lab every day, it is not your office. When you log out and leave for the day, you should take your books, papers, and coffee cups with you.
The custodial staff for the building and the department will take care of emptying wastebaskets. They occasionally vacuum and even wipe fingerprints off the screens. However, it is the responsibility of everyone who uses the lab to:
- pick up trash left lying on the tables;
- put manuals and reference books back on the shelves;
- straighten up the monitors and chairs,
- replace burned out light bulbs,
- clean the white boards, and
- replenish supplies such as markers, kim-wipes, and tissues.
You should do all these things for your own working area, and as needed for the lab as a whole.
Eating is allowed in the lab, but in order to keep this privilege, please be very careful to keep food and liquids off the equipment. This is especially important in the graphics lab since it contains expensive, one-of-a-kind machines.
The conference room adjoining the graphics lab (often called the "annex") is reserved for use by GDC working groups and other graphics group meetings. Scheduling of the room is currently handled by JoAnn (jarich@line) and recorded on the GDC calendar (`~alpha1/.calendar'). Please apply the same housekeeping rules to this room as to the workstation area in the graphics lab.
All the hardware in the graphics lab (and throughout the department) is maintained by the DSL (Digital Systems Lab). If there are hardware problems of any kind, send mail to dsl@cs describing the problem. This includes monitors that need adjustment, broken keyboards and mice, faulty cables, etc. If there are problems with the lab itself (e.g, broken floor tiles, leaks in the roof), then tell the DSL about those as well.
In more serious cases (e.g., roof leaks, a machine that will be down for an extended period), you should also send a copy of the message to a GDC staff or faculty member, so that we are aware of the problem.
Serious software problems (e.g., machine reboots, system crashes) should be reported to unixsys@cs. Minor software problems and maintenance issues (e.g., restoring files from backup tapes, resetting the printer spooler, replacing printer cartridges) should be reported to opers@cs.
Do not report problems with Alpha_1 software to unixsys@cs or opers@cs. See the section below on reporting bugs.
The Graphics Lab contains a number of reference books and manuals. Normally, all of these should remain in the graphics lab at all times. Occasionally, it may be very helpful to take a volume home for an evening or a weekend (e.g., LaTeX, Motif, and C++ reference books). We hope that an honor system will work for this. A signout sheet is posted on the end of the bookshelf by the north door of the lab. If you wish to borrow a book for a short time (e.g. overnight or over the weekend), sign it out and then cross your name out when you return the book. We must all strictly subscribe to this system if it is to work.
The machines in the graphics lab are all supported by the central C.S. Department servers for network file system, passwords, and so on. There are currently SGI, SUN, and HP workstations and some PC's in the lab.
Other specialized facilities in the lab include:
- A "Phantom" haptic (force-feedback) interface device.
- Apple IMAC, G4, and Cannon digital camera for animation/video editing.
- Tele-conferencing facilities to the other STC schools.
Accounts on the graphics machines must be approved by professor Elaine Cohen. Alpha_1 execution-only use requires no special group access. Staff, students, and visitors who need other Alpha_1 access will be placed in one or both of the following login groups:
- reada1
- For people who will read but not change the Alpha_1 sources and need access to other project information.
- alpha1
- For people who are developers of Alpha_1 and will be modifying the sources. You must also have group reada1 for alpha1 access to work properly. This is the most "privileged" group, (in the sense of access to Alpha_1 files and programs). Even this group cannot actually write the source files directly, but is allowed to run source code control programs which can modify the sources.
You should be sensitive to the fact that some of the public machines in the graphics lab are prized resources, and other people working in the lab may not be able to get their work done if you do not pay attention to how much of the resources you are using. (In the past, all workstations in the Graphics Lab were shared resources, but now there are personal cubical areas in the lab as well.)
These rules govern public graphics lab workstation usage, and are expected courtesies:
- Logout.
- You must logout if you will be gone more than 15 minutes. This is particularly important when you are going to lunch or walking next door for a meeting.
- Batch Jobs.
- Long running background jobs should always be niced +10.
- Other Workstations.
- Use your own workstation. People sitting at the console of a workstation have priority over remote users. Do not login remotely to another machine which is in use if your machine can do the job. Exceptions to this rule are multiprocessor machines.
Disk space is provided through file servers and various local disks. All
disks are automounted under the name `/res/gdc/*'. The physical
location of each disk should be irrelevant to the user. A single home
directory for each account is currently provided for all C.S. machines under
the automounter path `/home/
GDC group members normally do not do Alpha_1 development on home directories, but rather on a standard working directory. There are several reasons for this. One is that you will use a lot of disk space doing Alpha_1 development, and this allows us to track usage and retrieve space more easily when necessary. Another is that other members of the group know where to look to share software and ideas currently under development. That is, the a1pub directories provide a rough group workspace. Finally, when you leave, the Alpha_1 code you have developed is readily available for staff members to install and maintain, if necessary.
Non-GDC users of the graphics lab machines should consult with the GDC staff if they need large amounts of disk space for projects. The staff can probably locate a large public area for you to use.
All users of the graphics lab machines should keep careful track of how much disk space they are using on the various file systems. You should check your usage at least every couple of weeks. Clean off anything that is not active or that can be easily regenerated. Compress large files that you need to keep around. Archive image sequences from animations to some sort of off-line storage once you are done making the video. Various lab machines have exabyte tape drives for archiving.
Detailed disk space policies, physical locations and capacites, and usage information can be found online in the `$a$ploc/disk' directory and in the `README' file in particular.
This section contains some pointers for people getting started on the development effort in Alpha_1.
Alpha_1 currently is implemented in the C++ programming language. It runs under the Unix operating system. Some familiarity with Unix is necessary before any of the Alpha_1 programs can be run. There is a document which gives a beginner's introduction to Unix in Volume 2 of the Unix user's manual.
In addition, a screen-oriented editor, GNU emacs, is used exclusively for Alpha_1 software development. Anyone who will be doing more than trivial work on Alpha_1 software at Utah will need to be proficient in the use of emacs. Emacs contains a tutorial for new users.
Before beginning to experiment with Alpha_1, new users must set some environment variables used by Alpha_1 programs. To do this automatically you must modify your `~/.cshrc' file. The user ~alpha1 has an example of this in `~alpha1/.cshrc'. At the very top of your file place the commands:
source /res/gdc/projects/general/cmds/set-envars setenv A1_QUIET yes setenv A1WRK $gWRK/alpha1 source $gPRJ/alpha1/cmds/set-envars set path = ($bin $gBIN $sbin $path)
The important line in this example is the last one containing the directive "source." This reads and executes the file "set-envars." The first four lines set environment variables which are used as flags to control what variables "set-envars" defines and their value.
set path = ( $bin $path )
Next you will want to configure your emacs to load Alpha_1 key bindings and functions. Do this by editing your ".emacs" file and adding this to the top:
(condition-case ()
(load (substitute-in-file-name "gPRJ/emacs/gdc_general"))
(error (message "Can't load gdc_general.el")))
(condition-case ()
(load (substitute-in-file-name "$A1SRC/emacs/alpha1"))
(error (message "Can't load alpha1.el")))
Finally, you should define the USERNAME variable to your name by editing your ".login" file and adding:
setenv USERNAME "You R. Name"
Once you have the Alpha_1 environment set up and are familiar with the basics of Unix and emacs, you will want to get information relating specifically to Alpha_1. The best way to get online information about Alpha_1 is to learn to use info in emacs. At any time (while running emacs) you can invoke info with "C-h i". Info is self-documenting (i.e., there is a tutorial you can request when info starts up). There are three Alpha_1 menu items in the directory. One is the User's Manual, another is the Programmer's Manual, and the third is this document. If you are reading a paper copy, the information in it is derived from the same text as the info database. The online info databases will always be the most current written documentation on the Alpha_1 system at the development sites.
If you are going to be participating in the development of Alpha_1, you must read the chapter on programming standards. This chapter describes in detail the conventions and practices which the Alpha_1 group has adopted and is required reading for all members of the group. Software which does not meet these standards will not be incorporated into the system.
If you cannot find enough information for a programming task from the info tree, the actual C++ code which makes up Alpha_1 is generally very well commented and can be accessed easily with the tags database.
The tags functions in emacs provide methods for accessing portions of the Alpha_1 code directly via keywords. The keywords are currently any function or routine name, any defined constant name, and most of the names of major data structures. The command "M-." will show you the location of the first occurrence of a specified tag, and "<arg> M-." will go to the next occurrence of the tag. The first time that you invoke "M-." you will be asked to provide the name of the tags file to be used. The Alpha_1 C++ code tags are in file "$a/.ctags". If you set the environment variable TAGS, emacs will read that file as the tags table without asking.
setenv TAGS $a/.ctagsThe visit-function command (bound to "C-c C-v" in emacs) works from the same tag table, interpreting the word under the cursor in the buffer as the tag to be visited.
Whenever additions to the Alpha_1 system are made, the author should provide as much documentation as possible. It is absolutely required that all code (including C++ and shell scripts) be generously commented and tagged. If a new program or utility has been provided, a document should be prepared describing its use. The document may then be given to a GDC staff member who maintains the manuals for editing and including into the manual. Generally, only one or two people will be maintaining the documents and will have responsibility for installing new documentation. Note that this does not exempt you from writing the documentation for utilities you create in Alpha_1.
This section is for Computer Science majors working with GDC. If you are not a Computer Science major, we encourage you to report bugs as described below, but we do not expect you to be as able to fix the bugs yourself.
A summary of the procedures described in the remainder of this section is:
- Always try to fix bugs yourself first. Alpha_1 is a cooperative effort, and we depend on you as much as you depend on us.
- If you can not fix it, look for a work around. This provides the staff with more information and takes the pressure off.
- Send clear and concise reports including all the useful information from your debugging efforts and short sample input.
- Send reports to a1-bugs@cs.utah.edu, not to individuals. You will get a faster response that way.
Rule #1: Always do everything you can to fix a bug yourself.
The primary responsibility of the GDC staff is research, not maintenance. For a research system, Alpha_1 is remarkably bug-free. One reason for this is that the graduate students on the project have been very capable and have fixed bugs themselves as they use the software rather than always relying on the staff. Of course, if you are new and do not have much experience working with Alpha_1, this can be daunting, but is an excellent way to gain experience. Make a sincere effort!
When you encounter something you think is a bug, first make sure it is a bug. Obviously core dumps are bugs. For other more subtle effects, ask others and read the manual. Once you are convinced you have a bug, do the following:
- Create a working directory version of the offending program. You can do this by going to the corresponding directory in your working tree (e.g., $rendd) and typing:
cd $w$rendd a1makeThe program name is usually what you type to invoke the program with the suffix "pgm". On some directories more than one program can be made and a bare "a1make" will make them all, so you should use the following in that case:
a1make <program>pgm
- Now run your program under the debugger to generate the error. Remember that you need an uncompressed a1 file as standard input for most Alpha_1 programs. You can uncompress an a1 file using:
zcat <file.a1 | into file.a1The preferred debugger is gdb on everything that runs it (HPBSD, Sun, SGI). The gdb documentation is online under emacs. To get it type: "C-h i" and select "gdb" from the menu. Gdb also has a help command built-in. On systems without gdb, use dbx. Dbx should have a man page.
- Sometimes the bug is so simple you can see it immediately. If you do, fix the bug by copying the file and editing it. Then recompile the program and test it. If it now runs with your input try some other stuff (some a1 files are on $a$data). If it still works go to a staff member and have them review your change.
- If the fix is approved check it in.
What happens if you can not fix the problem? Look for a work around. If you can cause the bug to "disappear" with slightly different input this is a big win: you can get work done and (by including this information in a bug report) the staff will have more clues about the problem. Try the same program and input on a different machine type. Make sure your files are readable (use deconv), and have another student take a look for obvious errors, etc. Then send a bug report.
What is a good bug report? A good report is clear and concise. Include all relevant information, but nothing else. For normal C++ programs your bug report should include the following:
- the host name and machine types you have run this on
- the program with all the options you used (including an a1state file)
- a short data sample which generates the error
- all error messages generated by the program
- a stack trace of the program when it fails
- a brief summary of what you think is failing (gleaned from your debugging session)
Note several things in this list: try programs on more than one machine type, and do not forget to give us all the input (including the program options). Make sure your sample input file is as small as you can make it. You should always include the stack trace from your effort to debug the program and a summary of what you think is happening. Remember, clear and concise. It is worth spending an extra 10 minutes to write clearly, otherwise we have to debug your bug report.
Send bug reports to "a1-bugs@cs.utah.edu". Do not send them to individuals. All staff members are on the a1-bugs list, so you have 5 times the chance of a quick fix by sending them there. Also, the person you send it to might not know how to fix it and would simply re-route the message anyway.
Some of the directories which are local to the development group at Utah are listed below, with shell variable names in parentheses where they exist:
- /res/gdc/wrk
- Working directories for development.
- /res/gdc/projects/alpha1
- Alpha_1 master sources ($A1SRC, $a).
- /res/gdc/projects/cvs
- Alpha_1 (and other GDC software projects) master CVS tree ($CVSROOT).
- /res/gdc/projects/alpha1/man
- Alpha_1 manuals.
- /res/gdc/projects/History/diffs
- Location of diff files created during pre-CVS checkins. ($diffs).
- /res/gdc/projects/alpha1/tst/
- Data for running test suites ($A1TSTSRC, $ts).
- /res/gdc/projects/alpha1/sys
- Location of the compiled trees for various architectures. ($A1BIN, $A1DBG).
- /res/gdc/projects/other
- Local administration and projects. ($prj).
- /res/gdc/zzzzz/images
- Alpha_1 online image archives ($img).
- /res/gdc/projects/alpha1/data/textures
- Alpha_1 online texture images.
Alpha_1 consists of a set of file trees each with the identical structure but with different contents. These trees are the source, optimized binary, debug binary, test suite input, and test suite output. Each of these trees is referenced through an environment variable:
- A1SRC
- Contains the source code for all of Alpha_1.
- A1BIN
- Contains the optimized object code, libraries, and executables generated from the source code.
- A1DBG
- Contains the debugging object code and libraries.
- A1TSTSRC
- Contains the source code and reference files for the test suite facility.
- A1TSTOUT
- Contains the results of running the test suites for a particular host.
There is one (and only one) copy of the source tree, and test suite source tree. There are multiple copies of the two binary trees and the test suite output tree, one copy for each machine architecture. For instance, there is one binary tree on the HP700 workstations, and another binary tree for the SGI workstations. The "set-envars" script determines the architecture type for the current host and sets these variables accordingly.
The source tree itself is a singly rooted tree under $A1SRC and contains the entire set of "source" files for Alpha_1. Briefly, this tree is subdivided into
Becoming familiar with this structure is essential for those working on the system. The notations in parentheses are the standard Alpha_1 abbreviations for each directory, which are implemented via shell variables and symlinks in Unix.
- C++ sources (with program and library subdivisions)
- scripts needed to work in the system
- commands, definitions and environment setups
- geometric models (which are considered general data)
- demo geometry files
- include files
- documentation
- special projects
At the top-most level is a directory called alpha1. Its exact path may differ from one installation to another, but all system references are through the environment variable $A1SRC which contains the particular system path. A short form for users is the shell variable $a.
Subdirectories of the $A1SRC directory and their abbreviations are listed and briefly described below. The names in parentheses are directory abbreviations, see section Directory Links.
- a1make
- (amk) Global make scripts.
- a1test
- (atst) Scripts for running the test suites.
- cmds
- (cmds) Variable definitions.
- data
- (data) Miscellaneous geometry data files.
- databases
- (db) Info and checkout databases.
- demo
- (demo) Canned geometry for shape_edit demos.
- docs
- (docs) Documentation.
- emacs
- (aem) Emacs tags, documents, editor customizations.
- include
- (ai) Alpha_1 include files.
- projects
- (prj) Project development directories, one per project.
- src
- (src) All sources.
- structs
- (astr) Object definitions (str files).
- utah
- (autah) Utah specific unix utilities.
The "src" directory has four major subdirectories: cmd, lib, and views. The cmd directory (srccmd) has all the program directories, the lib directory (srclib) contains directories for libraries, and the views (views) directory contains interactive Motif-based programs.
The subdirectories of srclib are:
- alpha1
- (alib) Basic Alpha_1 library, divided into: boot, support, obj1, and obj2.
- client
- (clientlib) The main user interface library for programming Motif clients.
- display
- (dlib) Low-level display library for drawing splines and surfaces.
- dummy
- (dumlib) Dummy methods for C++ to reduce the size of executables.
- eplastics
- (epllib) Routine for doing "eplastics" (physically based surface deformations).
- geom
- (gmlib) Functions for combining and manipulating spline surfaces, sweeps, shape operations, and mass property calculations.
- iges
- (igeslib) Routines for reading and writing the IGES file format.
- interface
- (milib) The interface code for the client-server protocol.
- madraw
- (malib) The adraw code used by alpine.
- malpine
- (malplib) Library routines for the main alpine window.
- mm
- (mmlib) Low-level Motif interface code used by alpine.
- mot
- (motlib) Low-level Motif interface code used by alpine.
- mslice
- (msllib) The slice code used by alpine.
- msweep
- (mslib) The sweep code used by alpine.
- nc
- (nclib) Numerical control code for controlling the milling machine, lathe, etc.
- object
- (olib) Object headers and virtual function tables for C++ objects.
- prof
- (proflib) Routines which implement the profile constraint editor.
- reduce
- (redlib) Code for reducing polylines to spline curves.
- rsi
- (rsilib) Ray-surface intersection
- scan
- (slib) Polygon scan conversion library.
- slice3d
- (sl3dlib) Routines for computing planar slices through objects.
- spline
- (splib) General Alpha_1 spline library, divided into three sections: bspline, tess, mspl.
- ssi
- (ssilib) Surface-surface intersection library.
- trim
- (trimlib) Trimmed surface manipluation functions.
The subdirectories of srccmd are described by the programs they contain. They are:
- a1defaults
- (a1defd) Set and print program default arguments.
- a1util
- (a1utild) Compare and annotate a1 files.
- calc
- (calcd) Mass property calculation.
- check
- (checkd) Source code control programs: checkin and checkout.
- chidden
- (chidd) Hidden line removal for spline surfaces.
- contour
- (cntrd) Generate contour slices of a geometric model.
- eplastics
- (eplasd) Plastic deformation of spline surfaces.
- hidden
- (hidd) Hidden line removal for polygons.
- lines
- (linesd) Spline surface to isoline generation.
- linkage
- (linkd) Forward and inverse kinematics.
- nc/ncshade
- (ncsdd) Subdivision-based NC code generation scheme.
- obj-parser
- (parsd) Text to binary file conversion.
- prt
- (prtd) Ray tracer.
- render
- (rendd) Scan line renderer.
- shade
- (shaded) Image composition tool.
- slice3d
- (sl3dd) Planar slices through objects.
- ssi
- (ssid) Boolean operations on geometric models.
- structgen
- (sgend) Code generators for system objects.
- surf
- (surfd) Surface manipulation.
- tess
- (tessd) Spline surface tesselation program.
- util
- (utild) Utility scripts.
- view
- (viewd) Geometric model viewing program.
The binary tree contains the object code generated from the source. Each source directory has a corresponding binary directory with the object files. Aside from these duplicated directories, the binary trees also populate library and bin directories left empty on the source tree.
- bin
- ($bin) Executables for the apporpriate host
- lib
- (lib) For library archives.
- a1make
- (amk) Log information written by the global make.
The Alpha_1 file trees are all set up to be fully protected from the public. All Alpha_1 files are proprietary and are not to be accessed by anyone without permission. Nor should students or staff give out copies of any code to anyone without permission. This applies to code that you write while sponsored in any way by GDC, code derived from sponsored code, as well as all existing Alpha_1 code. Make sure that code you write is accessible by GDC group members, but protected against general public access. (The easiest way to do this is to do your development on one of the official $gPRJ working areas rather than on your home directory or some general scratch directory.)
Alpha_1 developers should make sure their umask is 002. This causes files written under alpha1 to be readable by readers, rather than publicly read-protected.
The file protections are maintained by a program (administered by Russ) which runs every day to insure that the protections are set as decided by the policy.
The file system is secured via directory protections, controlled by access groups, rather than public-read protecting everything. There is a gdc group for general access by GDC people. There are also two Alpha_1-specific groups to which a user may belong: alpha1, and reada1. These groups have a nested relationship. People in reada1 may read source files. People in alpha1 may read files and modify files (using CVS checkout and checkin). The alpha1 group are typically people who are developing parts of the system.
The root of the main Alpha_1 tree has protection:
drwxr-xr-x alpha1 alpha1
This provides limited public access for execution only and for mail to be deposited to certain Alpha_1 mailing lists.
Subtrees which are accessible to people with reada1 privileges have the protection:
drwxr-x-- alpha1 reada1
Since all members of the alpha1 group must also have group reada1, anyone with any alpha1 group privileges can get to these directories. But there is no public access beyond this point. All the files under the source tree root have protection which indicates they are publicly readable, but their paths go through the source tree root so "outsiders" without reada1 access are unable to get to them or even know of their existence. One can think of the source tree root as a "gate keeper." Everything else under the source tree root is group alpha1, so readers, with only group reada1, are the ones getting the "public" access on the inside.
Working directories, sources, and other project files are kept on subdirectories which are accessible to members who have reada1 group access. The roots of those trees have protection:
drwxr-x-- alpha1 reada1
Most of the source directories and source files have protection:
drwxr-xr-x alpha1 alpha1 (source directory) -rw-r--r-- alpha1 alpha1 (source file)
These directories and files also appear to have public access, but this is really just reada1 access (because there is always a "gate-keeper" at the root of the tree). Controlled directories (that is, everything "official" in Alpha_1) are owned by alpha1 with both group and public access limited to reading. They are writable only by user "alpha1" (not group alpha1). But all of the Alpha_1 build tools (cvs update, makeall, etc.) run as user alpha1, under the cron command. Only those with group alpha1 access can check files into the Alpha_1 CVS tree.
Since the file structure described previously gets fairly deep and complex in places, there is a set of symlinks for all directories with variable abbreviations. These symlinks allow easy random movement throughout the Alpha_1 file system without having to remember or type long pathnames.
The most common use of these symlinks is "cd abbrev" to move to the subdirectory whose abbreviation is specified. Directory links can also be used to easily examine files on other directories without actually changing to that directory:
more ~/a/abbrev/file
The symbolic links are also available from within emacs.
To set up these links for your own use, link the standard Alpha_1 links directory to your home directory.
ln -s $a/a1_links ~/a
The other part of the process, setting your "cdpath", is done for you by set-envars when you login. The cdpath variable tells the C-shell where to look for a subdirectory in case the subdirectory indicated in a cd command cannot be found. The set-envars script sets the cdpath to
set cdpath = ( ~/a ~ )The first directory is the standard links directory you just linked into your home account. This causes a cd to an abbreviated name to search this list. The second directory is used to access your own working directories. This will be covered in more detail later.
Each directory is also given a variable name (which is the same as the symlink name). These variables can also be used to navigate the file system. For instance, one common use of these is "cd $a$abbrev" to move to the subdirectory whose abbreviation is specified. Directory variables can also be used to examine files on other directories without changing to that directory (e.g., more $a$abbrev/file). These variables are not used very often since they require more typing.
The normal execution of the "set-envars" command will cause these variables to be defined as C-shell variables. These variables will not be inherited by programs you run and will not be available inside an emacs. If you do want them from emacs you can tell "set-envars" to define environment variables instead.
setenv USE_A1_ENVARS yesThis will define all variables as environment variables. You may have problems with this arrangement, however. A shell can only pass a limited amount of information in the environment and you may find that a1make fails if your environment is too big.
Many Alpha_1 programs are written as filters. That is, they simply read their standard input, compute a little, and write to their standard output. More sophisticated services like reading multiple files or uncompressing (or compressing) input (or output) is done by a shell script which wraps every Alpha_1 filter. This script handles some flags (e.g., -help) and passes the rest onto the filter. By convention, the filter program has the suffix "pgm" and the script which wraps it does not. Therefore, the rendering program is called "renderpgm" and the render script is called "render". Normal users only know about and execute the script, but sometimes developers need to know about the program as well.
The script itself is called "a1_exec_script", it knows about and handles these arguments:
a1_exec_script [ -pipe ] [ -state state-file ] [ -workdir dir ] [ -help ]
- state-file
- An a1 state file. The default "a1state" is read automatically.
- dir
- The directory containing a working version of the program.
This script first scans the command line for these arguments and collects the rest for delivery to the program. The script also identifies the input files, and decompresses each one and "cat"s them to the program. Normally, the output of the program is compressed again for compact storage. However, if the output is really going to another program you do not want this compression. You can tell the script this with the -pipe flag. The a1state feature of Alpha_1 programs assumes that if a file named "a1state" exists, it is a state file and should be read. If your state file is named something else (or is located in some other directory) you can indicate this with the -state flag. Eventually the script executes the program by simply executing the name. This means the standard Unix search path is used to find the executable. If you have an executable which is not on your path (or your path would find another version first) you can use the -workdir flag to indicate which directory contains the program. In fact, most people have "$bin" before "." which means that all working directory executables will require this flag. Finally, the -help flag summarizes the common flags available to all programs and suggests documentation on program specific flags. All the above flags may be abbreviated to single letters (e.g., -p, -s, -w, -h).
Whenever a program with the suffix "pgm" is installed in the system (for instance, by the nightly make) a symlink from the "a1_exec_script" file to the program name is created. This has the effect of making the program script known and executable. Therefore, there is no "setup" required to use this script in your programs, simply installing your code is enough.
This section describes some practical issues for working in and on Alpha_1.
As described earlier, the Alpha_1 directory structure consists of several independent (but structurally identical) directory trees. When you are modifying an existing part of the system, you cannot (due to file protections) change the files on the source tree. Instead, each developer is given their own tree on which to do program development. These working trees are placed on either gr or lotus under the directory "a1pub". The name of the tree is the user's account name so that accessing someone else's working tree is easy (working trees are group writable).
To make a working tree for yourself, just create the working directory:
mkdir /res/gdc/wrk/your-login(Replace "your-login" with your account name.)
CVS will make subdirectories of the workdir automatically as you check out files.
Now you can move to, say, your render working directory by typing
cd $w/rendd
It is important that an addition to Alpha_1 be tested before being installed into the main system. The best mechanism for doing this is to execute the test suites for this program (if you are modifying an existing program). If there are no test suites (or if it passes the existing tests) leave the new development on the working tree with easy access for users. Announce its availability to an appropriate subgroup via the mail system and solicit testing. Example data is helpful in getting other users to run your addition, before they pour their test cases into your code.
At all times, the possible negative impact on other users of changes to existing parts of Alpha_1 should be minimized. Try whenever possible to get a global view of what effect your changes will have on the system as a whole. If you have questions, don't hesitate to consult a GDC staff member.
In the current system, Alpha_1 files in the source tree are owned by user alpha1, and are accorded group read access, but not group write access. CVS, the Concurrent Version System, is the source-code control system we use to maintain the source tree and users' working trees from a common RCS repository.
For more detailed information about what these programs do and how they work, see the CVS section of the Programmer's Manual Home Page.
The recommended method for creating totally new directories (involving a new subdirectory of src) is as follows:
- Follow usual practice in deciding when a new directory is needed and put its abbreviation and location in $a$cmds/dir.vars. Discuss it first with a member of the GDC support staff.
- Create a working directory in your tree for the new source directory.
- Create your new files and test it there, or move it from elsewhere.
- Install your new directory and files to the repository with CVS.
Finally, add your new directory to the "srcdirs" files on the amk directory so makeall will run a1make there periodically, keeping it up to date with the rest of the system.
Modifying Header Files
C++ include files are the mechanism we use to describe common structures and types that will be used by many files. Include files for Alpha_1 C++ code are on ai and its subdirectories and end in ".h." Makefile dependencies are generated between the source file and the compiled files. All files which depend on a particular include file are recompiled when the include file is updated.