README.txt

= Overview

---

The GDSII Ruby Library provides an easy-to-use interface using Ruby for reading
and writing GDSII files.

Details in HTML form of the package's API may be generated by running:
    % rake doc

Contributors:

* Jim Freeze
* Ben Hoefer
* James Masters
* Matt Welland
* Dan White

Project webspace:

http://rubyforge.org/projects/gdsii/

This library is released under the MIT License (see LICENSE.txt)

---

== Installation

The "installation" is easy - simply add the contents in the "lib" directory
in this package to a directory where Ruby is installed or set the $RUBYLIB
environment variable to include the "lib" directory.

Alternatively, install it as a Ruby Gem and do something like this
in your Ruby files:
    require 'gdsii'
    class MyClass
        include Gdsii
        ...
    end

See the <i>samples</i> directory for an example.

---

== Unit Testing

The GDSII library has been tested on Windows XP, SuSE Linux, SunOS, and HP-UX.
To test the library on your own platform and configuration, a number of test
suites are located in the <i>test</i> directory of this installation package.
Those tests with file names beginning with <i>test_</i> can be run at once
by running:
    % rake test

== Test Coverage

Test coverage may be analyzed by running:
    % rake coverage

If your environment has the gem <i>Launchy</i> installed a page will be
opened in your browser showing the coverage report.

== Test Descriptions

test_gds_group.rb::  A unit test of the high-level GDSII methods.
test_gds_record.rb:: A unit test of the low-level GDSII methods.
test_h_pthru.rb::    Uses the GDSII high-level methods to read in a GDSII
                     file and then write out the same GDSII file.  The file
                     should be identical - or at least just have just EOF
                     null-padding differences.
h_pthru.rb::         Stand-alone version of the above - accepts command line
                     args.
test_l_pthru.rb::    Uses the GDSII low-level methods to read in a GDSII
                     file and then write out the same GDSII file.  The file
                     should be identical - or at least just have just EOF
                     null-padding differences.
l_pthru.rb::         Stand-alone version of the above - accepts command line
                     args.
test_h_write.rb::    Uses high-level GDSII methods to write out a number of
                     GDSII records using many of the available method calls.
                     This can be useful to verify that the GDSII library is
                     working and the output file can be compared against the
                     file found in ./test/baseline/h_write.gds to ensure that
                     the platform is reading and writing GDSII properly.
h_write.rb::         Stand-alone version of the above - accepts command line
                     args.
test_hs_pthru.rb::   Uses the GDSII high-level *streamlined* methods to read
                     in a GDSII file and write out the contents in one pass.
                     The resulting GDSII file should be identical - or at
                     least just have just EOF null-padding differences.
hs_pthru.rb::        Stand-alone version of the above - accepts command line
                     args.

---

== Utility Scripts

A few utility scripts have been included in the "bin" directory for general
purpose use and/or for reference in using the Ruby GDSII library:

gds2rb::      Translates a GDSII file into a Ruby script containing commands
              to recreate the GDSII file. This might make custom edits to a
              GDSII file easy by post- processing the script through
              automation or by hand before running the script to produce
              an output GDSII file.
gdsdebug::    A detailed GDSII "dump" program that can be used to debug issues
              with a GDSII file that may be somehow corrupt or may be causing
              the GDSII Ruby file read methods to fail.
gdsdump::     A conversion of GDSII data to the "L" file format (ASCII). This
              can make quickly reviewing GDSII file contents through text very
              easy.
gdslayers::   Lists all layer and data types in the GDSII file.
gdssremove::  Removes the specified structure(s) from the GDSII file.
gdsssplit::   Extracts the specified structure(s) from the GDSII file and
              creates separate files for each of the extracted structures.
gdsstats::    Reads a GDSII file and produces a statistical summary of the
              contents of each structure in the file.
gdsstructs::  Lists all structure names found in the GDSII file.
gdstree::     Prints a hierarchical tree of structures in a GDSII file.