

gEDA Project Folder Structure
=============================

The scripts assume a very specific folder structure for gEDA projects, including a
set of minimally required files. It is strongly recommended that the project folders be
laid out exactly as defined here to ensure comaptibilty with present and future functionality.

gEDA Tools
**********

The minimal set of tools which the user should expect to interact with are :

    - ``gschem``, operating on schematics.
    - ``refdes_renum``, operating on schematics.
    - ``gsch2pcb``, operating on schematics to create / update the pcb.
    - ``pcb``, operating on pcb.

The ``gedaif`` package of tendril contains scripts that use these and other ``gEDA`` tools to perform
various functions, and assume a specific file and folder layout. Any deviation from the specified
layout is likely to result in anything from runtime errors to silent omissions from the resultant
data.

Some of the files documented in this section are standard ``gEDA`` files, while others are ``tendril``
specific files.

A gEDA Project
**************

A ``gEDA Project`` consists of exactly one PCB designed using ``gEDA`` tools. Note that this is different
from a ``product``, which can contain one or more ``projects`` (of the gEDA variety or other).

Nomenclature
~~~~~~~~~~~~

gEDA projects use three levels of naming:

    :projname: Project Name is the base name of the PCB, not including hardware revision and configuration information.
    :pcbname: PCB Name is the actual name of the PCB for external fabrication, and therefore includes revision information but not configuration information.
    :confname: Conf Name or Card Name includes full hardware revision as well as configuration information.

The rationale for separation of PCBs by project, pcb, and configuration is inherently ambiguous, and the
developer / maintainer of a project and / or product line must use his / her discretion to make sure that
the basis used is reasonable. Some suggested guidelines are listed here for reference :

    - The ``Project Name`` can, in principle, exist for the entire duration of relevance of the Project itself.
      However, for the sake of simplicity, it is probably easier to change the project name at points where
      there is a significant change from the previous versions. Minimally, the ``Project Name`` should be
      sufficient to fully define the location of the project in the svn tree, which it does by specifying the
      folder name.
    - The ``PCB Name`` must change, without exception, at every change requiring update of ``gerber`` data,
      however minor the change may be. The ``PCB Name`` must be suffcient information to fully define the data set
      to be sent to a bare PCB fabricator as well as handle inventory checks, etc. This should be the name printed
      on the PCB Silk as well as used in Purchase Orders, Indents, etc.
    - The ``Conf Name`` must change along with ``PCB Name``. Besides this, ``conf names`` are expected to change
      asynchronously with general PCB development in the form of configurations added or removed. The ``Conf Name``
      should be suffcient to fully define the assembled PCB when read with information contained in the ``configs.yaml``
      file and other standard gEDA files.

General Structure of Names::

    [PROJECT-NAME-WITH-EMBEDDED-VARIABLES]-[HARDWARE-REVISION]-[SPECIAL-CONFIGURATION-FLAGS]

where:

        * ``PROJECT-NAME-WITH-EMBEDDED-VARIABLES``
                is a name including lower-case letters as placeholders for variable elements
                within the name. The variables may not be explicitly marked out, in which
                case the highest allowed value is the suggested representation.

                In the "Conf Name", the variables should all be completely resolved to
                the correct values.

                The ``PROJECT-NAME`` itself could generally be of the form::

                    [PRODUCT LINE]-[PRIMARY PCB FUNCTION]-[ADDITIONAL INFORMATION]

                Examples:
                 - ``X-TCON-L1`` for Xplore, Temperature Controller, Linear Design 1
                 - ``QASC-iSTRAIN`` for QDA, Active Signal Conditioner, Interactive Strain
                 - ``QDAL41xB`` for QDA, Low-end Data Acquisition Unit, 10^4 * 1Hz, x Channels, Type B

        * ``HARDWARE-REVISION``
                is a representation of the specific Hardware Revision of
                the PCB, generally represented as ``Rn``, where ``n`` is a number. Further
                information in the hardware revision is probably not a good idea. Hardware
                revisions would probably be tracked as branches and not tags since they
                are mutable, in the sense that configurations may be tweaked after
                fabrication of the base PCB. This is upto the project maintainer as well.

        * ``SPECIAL-CONFIGURATION-FLAGS``
                is a list of configuration flags to specify parameters
                that aren't represented in the embedded variables (ex. ``-GR``). In the case
                of core circuit elements that are usually populated except in rare cases,
                the configuration flag can be a negation (ex. ``-NOHV``).

Project Folder Structure
~~~~~~~~~~~~~~~~~~~~~~~~
::

    [projname]
    `-- hardware
        |-- branches
        |   |-- hR1
        |   ..    `-- [full copy of trunk at a specific hardware revision]
        |-- tags
        `-- trunk
            |-- ChangeLog
            |-- gerber                          (all-generated-tendril)
            |   |-- [projname].[layer].gbr or cnc
            |   ..
            |-- [projname]-gerber.zip           (generated-tendril)
            |-- pcb
            |   |-- [projname].cmd              (generated-gsch2pcb)
            |   |-- [projname].dxf              (generated-tendril)
            |   |-- [projname].net              (generated-gsch2pcb)
            |   |-- [projname].pcb
            |   `-- sourcing.yaml               (generated-tendril-manual)
            |-- schematic
                |-- [schname-1].sch
                ..
                |-- [schname-n].sch
                |-- attribs                     (project-template)
                |-- [projname].proj             (project-template-manual)
                |-- readme.txt                  (project-template-manual)
                `-- configs.yaml                (project-template-manual)

The corresponding folder structure that will be generated in the ``refdocs``
filesystem is :
::

    [projname]
    `-- hardware
        |-- branches
        |-- hR1
        |   |   `-- [full copy of trunk at a specific hardware revision]
        |   ..
        |-- tags
        `-- trunk
            `-- doc                             (all-generated-tendril)
                |-- [projname]-masterdoc.pdf
                |-- [projname]-configs.pdf
                |-- [projname]-schematic.pdf
                |-- [projname]-pcb.pdf
                `-- confboms
                    |-- [confname-1]-bom.pdf
                    ..
                    |-- [confname-m]-bom.pdf
                    `-- conf-boms.csv

