X-Authentication-Warning: delorie.com: mail set sender to geda-user-bounces using -f
X-Recipient: geda-user AT delorie DOT com
Date: Wed, 19 Feb 2020 16:06:45 +0100 (CET)
From: Roland Lutz <rlutz AT hedmen DOT org>
To: geda-user AT delorie DOT com
Subject: [geda-user] Proposal: Library handling
Message-ID: <alpine.DEB.2.20.2002181340190.1436@nimbus>
User-Agent: Alpine 2.20 (DEB 67 2015-01-07)
MIME-Version: 1.0
Content-Type: text/plain; format=flowed; charset=US-ASCII
Reply-To: geda-user AT delorie DOT com

Hi,

I have some ideas about improving library handling in gEDA/gaf which I'd 
like to put up for discussion here.



Proposal 1: Named libraries
===========================

A symbol is currently referenced by its basename, e.g. "resistor-1.sym". 
When gEDA looks for a symbol, it searches all library directories for a 
file with that name, and uses the first one it finds.

I suggest referencing symbols by two strings: the basename, and a library 
identifier.  Using the basename (instead of e.g. a full path) allows 
library authors to revise the internal organization of the library. 
Using a library identifier (instead of e.g. a library path) allows the 
user to reorganize the libraries on their machine and facilitates sharing 
schematic files between users.

When a library is added, a library identifier would be specified, e.g.:

   (add-library "kmk-essentials" "~/geda/kmk-essentials")

Some library identifiers are reserved for special purposes:

   unknown
     This is the internal identifier used whenever a symbol is referenced
     by an old file which doesn't specify a library identifier.  This means
     the old symbol lookup logic is to be used.

   default
     This is the identifier for the historic default library.

   local
     This identifier is reserved for project-local libraries specified in
     the project's configuration file.  The user interface may offer
     dedicated controls to manipulate project-local libraries.



Proposal 2: Library section
===========================

Currently, symbols are referenced from the schematic file like this:

C 5000 2000 1 0 0 resistor-1.sym

For embedded symbols, a section containing the symbol contents follows:

C 5000 2000 1 0 0 EMBEDDEDresistor-1.sym
[
L 5600 2200 5500 2000 3 0 0 0 -1 -1
L 5500 2000 5400 2200 3 0 0 0 -1 -1
...and so on...
]

This is repeated every time the embedded symbol is used.

I propose adding special syntax to the file format which allows embedding 
a symbol once and then referencing it, e.g.:

s resistor-1 1 default resistor-1.sym
[
L 600 200 500 0 3 0 0 0 -1 -1
L 500 0 400 200 3 0 0 0 -1 -1
...and so on...
]

From there on, whenever the symbol "resistor-1" is referenced, this means 
the symbol file "resistor-1.sym" from the default library, whose contents 
are included for convenience.  The distinction between basename and symbol 
identifier is made so multiple symbols with the same basename can be used; 
in that case, gEDA would assign a different identifier to each symbol, 
e.g. "resistor-1<1>".

There are three modes of embedding a symbol:

   omit (0)
     The symbol's contents are omitted, i.e., it isn't embedded at all.
     This is useful for minimizing changes when using an SCM.

   reference (1)
     The symbol's contents are included, but the file in the library is
     authoritative.  This is useful for distributing schematic files to other
     users, and for detecting symbol changes.  The UI would display a
     warning if the library is missing or the symbol in the library differs
     from the one included in the schematic but require a user interaction
     before updating the symbol in the schematic.

   embed (2)
     The symbol embedded in the schematic is authoritative; its basename is
     included for reference but otherwise ignored.  This is useful for
     including custom one-off symbols without having to bother with
     external files.



Any thoughts or comments?

Roland