Skip to content

Per project symbol and source libraries

Jump to bottom
peter-b edited this page Dec 12, 2012 · 4 revisions

Overview

This page describes the "per-project-libraries" blueprint on Launchpad.

One big problem with gschem and libgeda is that it is not possible to have two schematics that use different libraries loaded simultaneously. This is because, currently, the symbol and source libraries are singleton and determined by whichever gafrc file was loaded most recently. A new library system is needed to address this, based on the capability of the new config system to provide per-project config values.

Current status

This blueprint blocks the "config-sys-transition" blueprint.

Tasks

Design notes

General notes

  • Get rid of "command" and "Scheme" component libraries, and only support "directory" libraries. There hasn't been any significant uptake of the "virtual" library types.
  • Having separate symbol and source libraries is confusing. Normally, a directory for hierarchical subcircuits will contain both the subcircuit schematics and their corresponding symbols. Forcing the user to tweak the configuration in two different places to tell gEDA how to find the subcircuits is counterintuitive.
  • Support resources other than .sch and .sym files. It's possible that the code (or something based on it) might be useful for other tools (e.g. PCB).
  • Provide a signal-based method to get notified if a library changes. Important to carefully consider the corner cases that occur if two libraries contain a resource with the same name. Also, what about applications that may not provide a main loop (e.g. gaf shell)?
  • Make API as simple & foolproof as possible. Consider referencing an EdaConfig instance, and use config modification signals to automatically update the library if the library-related configuration changes.
  • If caching is used, make sure it's as invisible to the API user as possible. It shouldn't ever be necessary to call a "refresh the cache" function, for example.
  • Use GIO extensively (for example, GFileMonitor will be very useful). Also, if the API uses GFile as much as possible rather than passing filenames around, it'll be easier to (a) make a future upgrade to support libraries that aren't filesystem-backed and (b) make sure to avoid OS-specific filename quirks (e.g. special characters, etc).

Library info

  • There needs to be some way to obtain a translatable, human-friendly name and description for a library.
  • Also, it would be useful to annotate a library with what types of resources it contains.

A library.conf key-value file in each library directory would be a good way to do this (and would also provide a simple way to determine whether a directory's supposed to be a library or not).

Some keys that might be useful (just one library section needed in the file at this stage):

  • name [locale string] "human-friendly", internationalised name for the library.
  • description [locale string] similarly, a more detailed description of the library.
  • resource-types [string list] mimetypes of the resources that the library contains. The default would probably be application/x-geda-schematic;application/x-geda-symbol.

N.b. will need update to desktop-i18n tool to support translating library files for the symbol libraries distributed with gEDA/gaf.

Configuring libraries

How to find libraries:

Use a library section in gEDA config files for library-related config.

  • Need to have system, user and project search paths for library directories. All of the library directories found in the search paths should be used, with the directories found first having higher priority.
  • If library→system-library-path [string-list] isn't set, look for a directory called gEDA/libraries/ in each of ${XDG_DATA_DIRS} and ${datadir}. Use g_get_system_data_dirs() from GLib for this, along with s_path_sys_data()!
  • If library→user-library-path [string-list] isn't set, look for ${XDG_DATA_HOME}/gEDA/libraries/ and ${HOME}/.gEDA/libraries/. Use g_get_user_data_dir(). Might need to add an s_path_user_data() function to libgeda too...
  • If library→library-path [string-list] (project-specific) isn't set, use ./ by default
  • Scan the search paths (recursively?) for directories containing a library.conf file? Or just assume that any directory in the library search paths should be treated as a library? On the one hand, it's less discoverable to require a library.conf file; on the other hand, it would prevent lists of available libraries from getting cluttered with empty and/or non-library directories.

How to select libraries:

  • Treat the actual directory basename of a library as the library's "real" name. In case of a conflict, the less specific is masked (i.e. a "foo" user library masks a "foo" system library). If two libraries at the same level of specificity have the same name (e.g. both ${XDG_DATA_HOME}/gEDA/libraries/bar/ and ${HOME}/.gEDA/libraries/bar exist), then the one found later in the search path is masked.
  • library→libraries [string-list] should be a list of library names to use. We should set a default value that's minimal but still useful. Libraries earlier in the list should get priority if two selected libraries contain a resource with the same name. (Is this info even necessary?)

...and that's it. Probably only 4 config variables required.

Clone this wiki locally