CvPcb

The global footprint library table contains the list of libraries that are always available regardless of the currently loaded project file. The table is saved in the file fp-lib-table in the user’s home folder. The location of this folder is dependent upon the operating system being used.

The project specific footprint library table contains the list of libraries that are available specifically for the currently loaded project file. The project specific footprint library table can only be edited when it is loaded along with the project netlist file. If no project file is loaded or there is no footprint library table file in the project path, an empty table is created which can be edited and later saved along with the footprint assignment file.

The first time Pcbnew or CvPcb is run and the global footprint table file fp-lib-table is not found in the user’s home folder, Pcbnew or CvPcb will attempt to copy the default footprint table file fp-lib-table stored in the system’s KiCad template folder to the file fp-lib-table in the user’s home folder.

If fp-lib-table cannot be found, an empty footprint library table will be created in the user’s home folder. If this happens, the user can either copy fp-lib-table manually or configure the table by hand.

The default footprint library table includes many of the standard footprint libraries that are installed as part of KiCad.

Obviously, the first thing to do is to modify this table (add/remove entries) according to your work and the libraries you need for all your projects.

(Too many libraries to load is time consuming)

In order to use a footprint library, it must first be added to either the global table or the project specific table. The project specific table is only applicable when you have a net list file open.

Each library entry must have a unique nickname.

This does not have to be related in any way to the actual library file name or path. The colon : character cannot be used anywhere in the nickname. Each library entry must have a valid path and/or file name depending on the type of library. Paths can be defined as absolute, relative, or by environment variable substitution (see section below).

The appropriate plug in type must be selected in order for the library to be properly read. KiCad currently supports reading KiCad legacy, KiCad Pretty, Eagle, and GEDA footprint libraries.

There is also a description field to add a description of the library entry. The option field is not used at this time so adding options will have no effect when loading libraries.

One of the most powerful features of the footprint library table is environment variable substitution. This allows you to define custom paths to where your libraries are stored in environment variables. Environment variable substitution is supported by using the syntax ${ENV_VAR_NAME} in the footprint library path.

By default, at run time KiCad defines two environment variables:

You can override KISYSMOD by defining it yourself in preferences/Configure Path which allows you to substitute your own libraries in place of the default KiCad footprint libraries.

When a project netlist file is loaded, CvPcb defines the KIPRJMOD using the file path (the project path).

Pcbnew also defines this environment variable when loading a board file.

This allows you to store libraries in the project path without having to define the absolute path (which is not always known) to the library in the project specific footprint library table.

The GitHub is a special plugin that provides an interface for read only access to a remote Git Hub repository consisting of pretty (Pretty is name of the KiCad footprint file format) footprints and optionally provides “Copy On Write” (COW) support for editing footprints read from the GitHub repo and saving them locally. Therefore the “Git Hub” plugin is for read only accessing remote pretty footprint libraries at https://github.com. To add a GitHub entry to the footprint library table the “Library Path” in the footprint library table row must be set to a valid GitHub URL.

For example:

https://github.com/liftoff-sr/pretty_footprints

or

https://github.com/KiCad

Typically GitHub URLs take the form:

https://github.com/user_name/repo_name

The “Plugin Type” must be set to “Github”. To enable the “Copy On Write” feature the option allow_pretty_writing_to_this_dir must be added to the “Options” setting of the footprint library table entry. This option is the “Library Path” for local storage of modified copies of footprints read from the GitHub repo. The footprints saved to this path are combined with the read only part of the Git Hub repository to create the footprint library. If this option is missing, then the Git Hub library is read only. If the option is present for a Git Hub library, then any writes to this hybrid library will go to the local *.pretty directory. Note that the github.com resident portion of this hybrid COW library is always read only, meaning you cannot delete anything or modify any footprint in the specified Git Hub repository directly. The aggregate library type remains “Github” in all further discussions, but it consists of both the local read/write portion and the remote read only portion.

The table below shows a footprint library table entry without the option allow_pretty_writing_to_this_dir:

The table below shows a footprint library table entry with the COW option given. Note the use of the environment variable ${HOME} as an example only. The github.pretty directory is located in ${HOME}/pretty/ path. Anytime you use the option allow_pretty_writing_to_this_dir, you will need to create that directory manually in advance and it must end with the extension .pretty.

Footprint loads will always give precedence to the local footprints found in the path given by the option allow_pretty_writing_to_this_dir. Once you have saved a footprint to the COW library’s local directory by doing a footprint save in the footprint editor, no Git Hub updates will be seen when loading a footprint with the same name as one for which you’ve saved locally.

Always keep a separate local *.pretty directory for each Git Hub library, never combine them by referring to the same directory more than once.

Also, do not use the same COW (*.pretty) directory in a footprint library table entry. This would likely create a mess.

The value of the option allow_pretty_writing_to_this_dir will expand any environment variable using the ${} notation to create the path in the same way as the “Library Path” setting.

What is the point of COW? It is to turbo-charge the sharing of footprints.

If you periodically email your COW pretty footprint modifications to the GitHub repository maintainer, you can help update the Git Hub copy. Simply email the individual *.kicad_mod files you find in your COW directories to the maintainer of the GitHub repository. After you have received confirmation that your changes have been committed, you can safely delete your COW file(s) and the updated footprint from the read only part of Git Hub library will flow down. Your goal should be to keep the COW file set as small as possible by contributing frequently to the shared master copies at https://github.com.

Footprint libraries can be defined either globally or specifically to the currently loaded project. Footprint libraries defined in the user’s global table are always available and are stored in the fp-lib-table file in the user’s home folder.

Global footprint libraries can always be accessed even when there is no project net list file opened.

The project specific footprint table is active only for the currently open net list file.

The project specific footprint library table is saved in the file fp-lib-table in the path of the currently open net list . You are free to define libraries in either table.

There are advantages and disadvantages to each method. You can define all of your libraries in the global table which means they will always be available when you need them. The disadvantage of this is that you may have to search through a lot of libraries to find the footprint you are looking for. You can define all your libraries on a project specific basis.

The advantage of this is that you only need to define the libraries you actually need for the project which cuts down on searching.

The disadvantage is that you always have to remember to add each footprint library that you need for every project. You can also define footprint libraries both globally and project specifically.

One usage pattern would be to define your most commonly used libraries globally and the library only required for the project in the project specific library table. There is no restriction on how you define your libraries.

The status bar is located at the bottom of the CvPcb new main window and provides useful information to the user. The following table defines the contents of each pane in the status bar.

Displayed by right-clicking the mouse: