--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ueda/doc/prelayout.txt	Mon Jul 20 00:24:37 2015 +0000
@@ -0,0 +1,110 @@
+Pre-layout in uEDA
+
+If one implements the common division of labor in which the conceptual/schematic
+hardware design and the PCB layout are done by different people, in what form
+is the design passed from the original designer to the PCB layout contractor?
+
+The common input to the PCB layout step is the netlist.  However, the netlist is
+actually not enough.  The netlist specifies all interconnections among
+components in the design, but what about the components themselves?  In what
+form is the list of components passed from design to layout?  The answer depends
+on exactly how the division of labor is implemented.
+
+In some organisations the designer may specify standard components by value or
+device nomenclature and let the PCB layout person pick the footprints.  Or the
+designer may specify the footprints verbally ("this resistor is an 0805, this
+tantalum cap is size C, this logic IC is SMT, that one is a DIP..."), but still
+leave it to the layout person to actually draw the footprints in the PCB layout
+package of his/her choice.
+
+However, if the hardware design is being done by a non-profit organisation like
+the International Free Computing Task Force (the application scenario for which
+uEDA is designed), it is often the case that the conceptual/schematic hardware
+designer is a volunteer whereas the PCB layout labor has to be hired for money.
+In this scenario it is advantageous to save cost by having the designer do as
+much pre-layout work as possible, including the scripted generation of all PCB
+land patterns, leaving only the actual layout (the placement of the supplied
+footprints on the PCB and trace routing) to the costly hired labor.
+
+An additional consideration is that in order to keep our designs strictly free
+and open source from start to finish, we don't want the layout to be done in
+some proprietary package and we insist instead that it be done with the free
+and open source PCB program (http://pcb.sourceforge.net/).  Or more precisely,
+we insist on the PCB layout file format.
+
+These two considerations combine to suggest that we generate the PCB footprints
+for all components in the design in the PCB format and hand them to whoever we
+hire to do the layout.  This is what is called pre-layout in uEDA.
+
+Whereas PCB layout is inherently a graphical/visual task and thus seriously
+incompatible with the world view of the uEDA author, the footprint generation
+for PCB happens to be very compatible with the UNIX culture-based text-based
+scripted flow embraced by uEDA.  The PCB project's original footprint library
+is actually M4 code that generates footprints algorithmically on the fly!
+
+The pre-layout function of uEDA requires the use of the IFCTF part library.
+Among other things it contains a version of the M4 footprint library from PCB
+ported from GNU M4 to the original UNIX M4.  The IFCTF part library is
+maintained in the IFCTF CVS repository and may be checked out with:
+
+$ cvs -d :pserver:anoncvs@ifctfvax.Harhan.ORG:/fs1/IFCTF-cvs co ifctf-part-lib
+
+uEDA expects it to be installed in /usr/local/eda/ifctf-part-lib
+
+The pre-layout function of uEDA works as follows:
+
+1. Each component needs to have a footprint= attribute defined in the MCL.
+   It works exactly like the footprint= attribute in gEDA with the gsch2pcb
+   flow.
+
+2. To generate the PCB footprints for your design, run the following pipeline:
+
+ueda-getfps | ueda-runm4 > elements.pcb
+
+ueda-getfps(1) reads the MCL and emits a set of M4 macro calls to generate all
+of the footprints, and ueda-runm4(1) runs m4(1) on the IFCTF part library.
+The output of the pipeline is a concatenated set of footprints for the board
+with the name field (refdes) filled in correctly in each.  If the -h option is
+given to ueda-getfps, the concatenated set of footprints will be preceded by a
+blank PCB template (the same one provided by PCB itself when starting a new
+layout) and the resulting elements.pcb will be a valid layout PCB that can be
+loaded into PCB to start the layout job.
+
+Alternatively, ueda-cutelements(1) may be used to cut the concatenated output
+from ueda-getfps | ueda-runm4 into one file per element.  It should be run in
+an empty directory and the files thus produced are named after the component
+reference designators.
+
+The uEDA footprint generation mechanism is designed so that the generation of
+all footprints at once concatenated into a single PCB file is native whereas
+producing single elements is secondary because the way PCB's M4 library is
+designed makes this approach much more efficient, especially when using the
+original UNIX M4 rather than GNU M4.
+
+File elements
+
+In addition to the M4-based original PCB footprint library which has been
+incorporated into the IFCTF part library, there are other popular footprint
+libraries which are simple collections of pregenerated elements, one per file.
+They are called file element libraries, and there is a very popular and very
+useful one maintained by John Luciani.
+
+uEDA supports file element libraries in addition to the main M4-based IFCTF
+part library, but the process always goes through M4.
+
+ueda-getfps(1) normally generates a make_footprint() M4 macro call for every
+component.  This macro looks for the requested footprint in the M4 library and
+if none is found, invokes the ueda-instfileelem(1) utility to try to find it in
+the file element libraries and instantiate it from there.
+See the ueda-instfileelem(1) man page for how to locate the file element
+libraries.
+
+Some file element libraries (particularly John Luciani's) use footprint names
+which would confuse M4.  To get around this problem, the footprint= attribute
+in the MCL may be specified as follows:
+
+ footprint=file:Long-weird_footprint-name
+
+This syntax tells ueda-getfps(1) to generate a make_footprint_file() M4 macro
+call instead of make_footprint().  The former invokes ueda-instfileelem(1)
+immediately without trying to look in the M4 library first.