pcb-rnd knowledge pool

Advanced library path configuration

lib_path_conf by Tibor 'Igor2' Palinkas on 2018-03-08	Tags: howto, library, search, path, directory, config, prepend, append, overwrite, insert, list
node source

Abstract: For the simplest setup it is enough to configure all library paths as a static list. However, advanced use need advanced configuration capabilities, which pcb-rnd fully supports: extending existing list of paths with local additions.

pcb-rnd comes with a sophisticated configuration system that allows the user to maintain modular configuration files. A detailed description of the conf system is available in the official documentation. This article demonstrates how to use the conf system to set up the library search path.

Simplest case

In the simplest case the list of library paths, configured at conf node rc/library_search_paths, is a static list typically configured on system level. In the default installation, for example it includes the optional "user's home" library in "~/pcblib/" and the default minimal library installed with pcb-rnd at "$(rc.path.share)/pcblib" (which is something like /usr/share/pcb-rnd/pcblib).

The user may decide to have an user level configuration (in ~/.pcb-rnd/pcb-conf.lht) that simply overwrites this list with a new list. This is common for users maintaining their own libraries. It is also possible that a project file or even a board file overwrites the full list, with local configuration.

These can be done by adding the following subtree in the config section of any of the above mentioned files:


ha:overwrite {
 ha:rc {
   li:library_search_paths {
     my_lib_path1
     my_lib_path2
     my_lib_path3
   }
 }
}

Each config source ( role ) has a priority , which controls in which order one config source would overwrite (or extend) the data created by another source. The default priorities are set up as common sense suggests: user config overrides system config, project config override user config, board level config overrides project config, command line arguments override everything.

This helps the user to set up local deviations from the standard config at some levels (e.g. for a specific project) without having to use local config in everywhere (e.g. having to specify local configuration for all other projects which would be fine with the standard config otherwise).

Advanced use: extend existing lists

Example setup

It is not always practical to simply overwrite an existing list of library paths. For example Alice and Bob are working on the same project, but they have different systems and thus different installation of pcb-rnd. A typical example is:

they should keep the paths set up by the system config file - the installation process knew where the standard lib got installed, and this path may differ on different systems
the user level configuration (the config file in the user's $HOME dir) should append a few more paths to this list. These are extra footprint libraries both Alice and Bob downloaded from various sources, but they prefer to keep them in different directories (e.g. in Alice keeps them in /opt/footprints while Bob keeps them in /usr/local/share/fp)
the project they share comes with a local, project-specific footprint lib, placed in a local dir relative to the project's config file. The path of this footprint lib should be inserted in front of the final list so project-local footprints are preferred over other sources. (This operation is called "prepend" in the conf system).

Example setup - the config files

The central, system installed config will still contain this subtree ("..." means other settings/subtrees may be there):


li:pcb-rnd-conf-v1 {
  ha:overwrite {
   ...
   ha:rc {
     li:library_search_paths {
      ?../pcblib
      ?~/pcblib/
      $(rc.path.share)/pcblib
     }
   }
   ...
  }
}

On Alice's system, /home/alice/.pcb-rnd/pcb-conf.lht contains:


li:pcb-rnd-conf-v1 {
 ha:append {
  ha:rc {
    li:library_search_paths {
      /opt/footprints
    }
  }
 }
}

Bob's user config file is similar.

The project file, called project.lht, in next to the board files in their common project, contains:


li:pcb-rnd-conf-v1 {
 ha:prepend {
  ha:rc {
    li:library_search_paths {
      ./local_fps
    }
  }
 }
}

When all the config sources are merged on Alice's system, the following happens when one of the board files of the project is loaded:

the library search path list is reset to empty when the merge starts
the lowest priority source, system config is applied: it overwrites the empty list with {?../pcblib; ?~/pcblib/ $(rc.path.share)/pcblib}
the user level config is applied; it appends /opt/footprints, so the resulting list is: {?../pcblib; ?~/pcblib/ $(rc.path.share)/pcblib; /opt/footprints}
the next, higher priority source is the project file, which prepends ./local_fps, so the new list is: {./local_fps; ?../pcblib; ?~/pcblib/ $(rc.path.share)/pcblib; /opt/footprints}

Summary of the mechanism

config sources are processed in order of their priority
each config source may overwrite the path list, prepend entries or append entries

using the CLI

The config nodes injected from the CLI, using the -c argument, are placed in their own config source with the highest priority (by default). It is possible to control each -c to overwrite, prepend or append using different operators:

syntax meaning
-c rc/library_search_paths=foo overwrite the list with value 'foo' (the new list is 1 item long)
-c rc/library_search_paths+=foo append 'foo' at the end of the list
-c rc/library_search_paths^=foo prepend 'foo' at the beginning of the list

syntax	meaning
-c rc/library_search_paths=foo	overwrite the list with value 'foo' (the new list is 1 item long)
-c rc/library_search_paths+=foo	append 'foo' at the end of the list
-c rc/library_search_paths^=foo	prepend 'foo' at the beginning of the list

It is not possible to specify multiple list items for a single -c, but it is possible to use -c multiple times. For example -c rc/library_search_paths=foo -c rc/library_search_paths+=bar -c rc/library_search_paths^=baz will result in a list {baz;foo;bar}.