Skip to content

Resource libraries

Jump to bottom
drforbin edited this page Mar 20, 2020 · 1 revision

Objectives

  1. Allow the user to simultaneously edit and/or view schematics that use different and conflicting libraries.
  2. Monitor library status and notify the user when resources are modified.
  3. Support resources beyond schematics and symbols (e.g. pictures).
  4. Provide support for future library creation, modification and selection features in the gschem UI.
  5. Allow libraries to be configured via the new configuration system and without requiring gafrc files.
  6. Provide internationalized translations of the titles and descriptions of the standard libraries shipped with geda-gaf.
  7. Properly support the XDG Base Directory Specification.

User interface

Note that this section does not describe the implementation, but the desired behaviour.

Library search path

A library search path is a path in the filesystem that geda-gaf should search for libraries. Library paths should be used to describe the system-specific filesystem layout of resource libraries rather than to group resources logically or semantically.

There are three, independently configurable sets of library search paths used by geda-gaf:

  1. The system search path describe where to search for system libraries. It defaults to, in order:

    • the geda-gaf/resources subdirectory of each entry in ${XDG_DATA_DIRS}
    • the ${pkgdatadir}/resources directory configured at build time.

    You could set the system library paths using gaf config library system-search-path.

  2. The user search path describes where to search for user-specific libraries. It defaults to ${XDG_DATA_HOME}/geda-gaf/resources.

    You could set the user library paths using gaf config library user-search-path.

  3. The project search path describes where to search for project-specific libraries. It defaults to .. Since all relative elements in a search path are resolved from the current project's root directory, this means that by default geda-gaf searches each project for libraries and makes them available for use.

    You could set the project library paths using gaf config library search-path.

So, with the default configuration, gschem would search the following directories for resource libraries on most systems:

  1. The current project's root directory (project)
  2. ${HOME}/.local/share/geda-gaf/resources/ (user)
  3. /usr/local/share/geda-gaf/resources/ (system)
  4. /usr/share/geda-gaf/resources/ (system)
  5. /usr/share/gEDA/resources/ (system)

Suppose that, for a particular project, you are sure that you have provided all of the necessary symbols in the project's libraries. You can explicitly disable all user and system libraries by running:

gaf config -p library system-search-path ""
gaf config -p library user-search-path ""

Libraries

Libraries are sets of related resources. They should be used to group resources logically, independently of where the library is located on the filesystem.

A library is a leaf directory in the filesystem (it shouldn't normally have subdirectories). Usually, it will be in one of the directories listed in the library search paths. It must contain a library.conf file and its basename must not start with a ..

The library.conf file tells the library system that the directory is a library, what sort of resources the directory provides, and some additional metadata. A library.conf file for a passives library should look something like this:

[library]
title=Passives
description=Symbols for passive components (resistors, capacitors, inductors, etc.)
mimetypes=application/x-geda-symbol

The mimetypes here tells the system that the library contains only geda-gaf symbol files, and that it shouldn't bother looking there for other types of resource (such as pictures). If you had a library that contained only subcircuit schematic files, you would use a value of application/x-geda-schematic. An empty value means that the library should be searched for all types of resources.

Each library is uniquely identified by the basename of its path. For example, the /usr/share/geda-gaf/resources/passives library would be identified as the passives library.

When looking for a library with a particular name, the system searches through the library search paths until it finds a match. For example, if a user library ${HOME}/.local/share/geda-gaf/resources/passives exists, then the system will ignore a system library in /usr/share/geda-gaf/resources/passives.

Each project has a list of enabled libraries. For example, to enable the passives library and another library called transistors in a project, you can run gaf config library libraries passives;transistors.

Resources

Resources are files. Like libraries, resources are uniquely identified by their basename. For example, the /usr/share/geda-gaf/resources/passives/resistor.sym resource would be identified as resistor.sym.

When looking for a resource with a particular name, the system searches through the enabled libraries until it finds a file that matches. So, if you had set the list of enabled libraries to passives;transistors and (for some reason) the transistors library also contained a resistor.sym, it would be ignored in favour of the version from the passives library.

Migration from old system

gafrc entry Configuration setting
(component-library "/path/to/dir") system-search-path=/path/to;... + libraries=dir;...
(component-library-search "/path/to/dir") system-search-path=/path/to/dir;...
(component-library-reset) system-search-path= + user-search-path= + search-path= + libraries=

Examples

Many projects use a per-project symbol directory named ./symbols. To set this up, touch ./symbols/library.conf and run gaf config library libraries symbols to enable the library.

If you don't want to use any system symbol libraries at all in any of your designs, run gaf config -u library system-search-path "".

Clone this wiki locally