Gattrib: an attribute editor for gEDA

Change log
2.22.2004 -- Initial posting. SDB
3.4.2004 -- Provide link to version of 20040304. SDB
3.6.2004 -- Update to verison 20040306. SDB
3.11.2004 -- Bugfix release 20040311. SDB
3.13.2004 -- Bugfix and implement comp sort. release 20040313. SDB
8.15.2004 -- New release 20040806. Implements pin attrib display and works under GTK2.X. SDB
9.4.2004 -- Added note about latest edition on CVS. SDB
11.20.2004 -- New release 20041120. Allows user to add and delete attrib columns. SDB
11.1.2005 -- Removed links to local copy. Now point user to main gEDA page for downloads.

Gattrib is an attribute editor for gEDA. It reads a set of gschem .sch files (schematic files) and creates a spreadsheet showing all components, nets, and pins in rows, with the associated attributes listed in the columns. A typical screenshot is presented below. Gattrib allows the user to add, modify, or delete attributes outside of gschem, and then save the .sch files back out. When it is completed, it will allow th user to edit attributes attached to components, nets, and pins. (Currently, only component attribute editing and pin attribute viewing is implemented. I am still working on understanding how nets work in gnetlist; when I have figured that out entirely, I will implement net attrib editing. Pin attribute editing requires some architectural changes in gEDA itself, so it might take some time.)

Gattrib is useful in situations where you need to add, modify, or delete a number of attributes all at once. It saves you the pain of clicking on each schematic object and using gschem's attribute editor when you have a large number of changes to make. For example, suppose you create a large design with generic components, and then later want to attach "footprint" attributes to all your components for layout. Using gschem to do this is a real hassle because you must click on each and every component. Gattrib makes this job easy: it shows you all components in your design, and allows you to attach the "footprint" attribte to all components using an easy-to-use spreadsheet.

Starting with release 20041120, gattrib now allows you to insert and delete new attrib columns. For example, if you now want to insert a footprint or a distributor's part number for each part in your design, you can do so from within gattrib by selecting "edit->att new attrib column". When you save out your design, the new attribute will be stored in your .sch file. This makes it easy to create BOMs, and keep track of other attributes attached to your schematics. You can also delete old, unnecessary attributes from within gattrib by selecting "edit->delete attribute column".

Starting with release 20040806, gattrib also allows you to view (but not edit) pin attributes. This is useful to review your "pinnumber" and "pinseq" attributes before going into layout.

In the future, you will also be able to edit attributes attached to nets. This is very useful for attaching routing attributes controlling track impedance, width, diff-pair & bus length tolerance, etc. However, this feature is currently unimplemented.

Garchive is written in C and depends upon functions living in libgeda. It also incorporates significant amounts of code from GTK+Extra (http://gtkextra.sourceforge.net/) -- in particular, the GtkSheet widget which implements the spreadsheet itself. Also, starting with the 20040806 release, gattrib works with both GTK-1.X and GTK-2.X. Choice of the 1.X or 2.X versions is made automatically at configure time; the configure script looks for either GTK-1.X or GTK-2.x on the system, and then chooses either gtkextra-1.X or gtkextra-2.X for compilation.

Further information about gattrib's internal workings are contained in the tarball. In particular, see the files "NOTES" and ProgramArchitecture.gnumeric. Also, I have spread copious comments throughout the code in order to help others come to grips with how gattrib works.

NOTE: Gattrib is currently beta software. It has been tested on several designs, and works. However, please take care to back up your design regularly, just as you would with any design tool.

Gattrib is now distributed with the rest of gEDA/gaf. You may download it from the main gEDA download page. It is a free-standing application, but links to libgeda. Therefore, you are best advised to install it at the same time as installing the rest of gEDA/gaf.

You can invoke gattrib on your design from the command line in the following way:

(This assumes you have a multi-page design with file names "my_design_1.sch", "my_design_2.sch", etc.) Gattrib will then read in your design, and present you with a spreadsheet showing all components and associated attributes. Alternately, you can also just run gattrib without any files on the command line, and specify the input files using the "file->open" dialog box. (Note that you can also read in additional files using "file->open" at any time during your editing session. Pages from the newly opened design will be merged into your spreadsheet. Be careful doing this -- if you merge pages from different designs with common component refdeses, you will lose your component attributes!)

To edit your attributes, just edit the cells in the spreadsheet.

To save your design, just select "file->save" from the command menu. Note that no checks are currently done when you select save. Be careful!

To quit, just select "file->quit" from the command menu. Note that currently no checks thet you have saved your design are done when you quit.

If you want to add an entirely new attribute to your design (i.e. one which doesn't exist on any component), you can do so from within gattrib starting with version 20041120. Just use the pull-down menu item "edit->add new attribute column", and enter a name for the new attribute in the dialog box. A new attribute column will be created on the spreadsheet. The new attribute will be present in your design when you save it out, and you can view the new attribute from within gschem, just as you ordinarily would.

If you want to insert an entirely new attribute into your design using an older version of gattrib, you must first "seed" the attribute. That is, you must attach at least one instance of that attribute to a component using gschem. Then you can use gattrib to attach the attribute to the remaining components.

There is currently no "official" documentation. I may do a man page some time in the future. In any event, gattrib is fairly obvious to use. If you want your hand held a little bit, usage instructions are available above.

Gattrib essentially has three layers:

1. At base, I used the TOPLEVEL data structure from libgeda and the program flow from gnetlist to create a typical gEDA representation of the design. I stole and modified a lot of code from gnetlist and gschem to implement this. A number of libgeda functions are also invoked to massage the TOPLEVEL data.
2. One level up, I created the SHEET_DATA, TABLE, and STRING_LIST data structures to hold information about the design in a format closer to that used in the spreadsheet. I then wrote functions used to take data from the TOPLEVEL structure and transform it into and out of SHEET_DATA, TABLE, and STRING_LIST format.
3. At top level, I used functions and structures out of GtkSheet to create and present the spreadsheet GUI to the user. I expropriated and radically modified "testgtksheet.c" to implement these functions.

If you are interested in working on gattrib, I welcome your contributions! To help you understand how gattrib works, I have included a couple of files in the source tarball which try to document the internal workings of gattrib. These files include:

• NOTES -- This file contains some notes about the internal data structures used in gattrib.
• ProgramArchitecture.gnumeric -- This is a Gnumeric spreadsheet holding the various functions I wrote for gattrib in an organized fashion. This is useful as an API reference when working on gattrib.
• AlesCorrespondance -- This is an e-mail exchange between me and Ales on geda-dev about the data structures used in gEDA. I include it here for historical reference, and because Ales explains some of the mysteries behind how component attributes are supposed to be handled in gEDA. NOTE: The data structures proposed by me in this e-mail are mostly obsolete. Don't rely on this e-mail to understand what is going on in current versions of gattrib!

Moving forward, the following features need to be implemented:

• Throw up "Are you sure" dialog boxes upon selecting "save" and "quit" from menu.
• Printing and export of CSV formats. This will make gattrib a nice way to handle BOMs.
• Alphabetic sort of rows. (Should happen automatically upon read-in of design.)
• Editing of net attributes (important for setting routing attributes).
• Editing of pin attribute (important for going to layout with the proper pinseq). This will require a change in the way gEDA is architected, so it might take some time for this to happen.
• Search/replace of individual attributes.
• Search for component refdeses & netnames. Set/view component & net visibility (through options pull-down menu). Currently, visibility is "invisible", and both name & value are displayed (if you turn on the visibility).

• Maybe re-implement the low-level, net handling stuff using gnetman instead of gnetlist. Gnetman apparently handles hierarchy better than gnetlist. However, using gnetman requires understanding how it works, which will take a while . . . .
• Code clean-up. There is a lot of left-over stuff in gattrib which doesn't need to be in there. In particular, a lot of code is simply not used. This situation holds because large parts of gattrib are a cut-'n-paste job from other programs, and extra cruft from these programs still remains hanging around. Running the C analog of "Covered" (a Verilog tool) on gattrib and cleaning up the stuff which is never executed would be a good idea. (Does anybody know which tool is the analog of "Covered" for C? If so, please e-mail me!)
• Write up a manpage??
• Suggestions from others?

I welcome contributions from interested hackers. If you want to help me finish gattrib, or wish to submit a patch please send me an e-mail!

Please send comments, bug reports, suggestions, complaints, or kudos to Stuart Brorson.