Library Management

The README on the main page describes a simple way of managing this KiCad Library. For Freetronics' KiCad-based projects we use a more complex approach incorporating git submodules. We recommend this approach for any non-trivial project that is already using git for version control.

This page describes how to use this approach. It assumes that you are already using git to manage your KiCad project, and that you are reasonably familiar with git.

Why use this approach?

The reason for using the "powerful way" is it allows you to version control the libraries in lock-step with your project, so any given revision of your project is always associated with a matching revision of the library.

• Changes to the library (additions, edits, deletions) can't possibly effect your project, as nothing gets updated until you go into the submodule directory and git pull.

• Anyone who wants to look at a historical revision of your project can see the exact library that was used to create it, no confusion about why a footprint on a board and a footprint in the PCB might be different. This is particularly useful in the schematic editor, which currently reloads schematic symbols as soon as it detects they've changed in the library.

• Unlike the KiCad "github integration" outlined in the "Easy Way", this approach works 100% offline and allows you to even edit the library locally without an internet connection.

Using Freetronics Kicad repositories

Whenever you git clone a Freetronics design repository that's based on KiCad, you need to run git submodule init in order to update the submodule that contains the library details. Otherwise, attempts to access the library will fail.

Adding the library to your project

These steps explain how to include the Freetronics Kicad library git repository as a "sub-module" of your KiCad project. To do this you must have already started a new git repository for your project.

Using the command line, navigate to your project repository's top-level directory then execute a command like this:

git submodule add https://github.com/freetronics/freetronics_kicad_library.git library

This tells git to check out the Freetronics KiCad library repository as a "submodule" of your current repository, in the directory library. If you want a more specific name then you could call this ftlibrary or any other name.

Configuring schematic editor

In the KiCad schematic editor (eeschema), choose Preferences -> Set Active Libraries and add the path to library/freetronics_schematic.lib. Relative paths such as that shown seme to work.

The KiCad schematic symbols replace quite a few of the common symbols (R for Resistor, C for Capacitor, INDUCTOR, etc). For this reason we recommend moving freetronics_schematic to the top of the list of libraries. Eeschema always uses the first matching name it comes across, starting from the top of the list of libraries. Not doing this may have unexpected results as eeschema mysteriously replaces a Freetronics symbol with one from the built-in libraries.

Configuring footprint tables

Here is a sample fp-lib-table file that references the footprint library located inside the submodule directory:

(fp_lib_table
  (lib
   (name FT)
   (type KiCad)
   (uri ${KIPRJMOD}/library/freetronics_footprints.pretty)
   (options "")
   (descr "Freetronics Kicad Library")
   )
)

You should copy this file into your repository directory and use git add fp-lib-table to add it to source control. You can also edit the table inside pcbnew by choosing Preferences -> Library Tables.

Tracking the submodule in git

So far these steps create the submodule and allow you to access it from inside KiCad. The next step is properly adding it to your git repository, so it can be revision tracked.

If you type git status, you will see some output like the following:

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

	new file:   .gitmodules
   	new file:   library
    new file:   fp-lib-table

If you run git commit at this point, the commit you create will associate the directory library with the remote copy of the Freetronics KiCad Library repository.

If you change directories into the library directory that holds the library submodule, you'll find that you are able to pull, push and commit against this repository as if it was any other git repository. However when you come back out into the main project directory, you'll notice a new line of output in git status:

On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   library (new commits)

You need to git add library and git commit library in order for the updated library revision to be associated with the new commit in your project repository. The actual contents of the library aren't added to your repository, just metadata that says "I am using revision xyz of this submodule".

If you haven't been exposed to git submodules before then you're probably feeling a bit confused at this point. This short chapter in the git-scm book gives a good overview of them.