
= Upgrading from Version 4 to Version 5

Changes were made to the behavior to KiCad during the version 5
development that can impact projects created with older versions
of KiCad.  This section serves as a guide to ensure the smoothest
possible path when upgrading to version 5 of KiCad.

== Schematic Symbol Libraries

Schematic symbol libraries are no longer accessed using a symbol
(referred to as components in version 4) look up list.  Symbol
libraries are now managed by a symbol library table that behaves
similarly to the footprint library table.  This change is a significant
improvement, but some schematics may need manual intervention when being
converted to version 5.

In previous versions, KiCad used a list of library files to search when
locating symbols in the Eeschema file. When locating a symbol, each path
would be searched and the first library that held the symbol name
would be used.

From v5, KiCad symbol names are prefixed with a nickname, and a
https://github.com/KiCad/kicad-doc/blob/master/src/kicad/kicad_upgrading_from_v4_to_v5.adoc[lookup table matching
nicknames to library paths] is used to locate the library which holds the
symbol. The table is called the 'symbol library table' and built from
configuration files stored in the user's KiCad configuration directory
and the currently loaded project directory.

To upgrade a KiCad project from v4 to v5, nicknames for all of the library
files need to be created and then schematic symbol names need to be prefixed
with the correct nickname.


=== Global Symbol Library Table.
Eeschema v5 will automatically create a global symbol table when
first started. You will be given a chance to skip this and create
your own global symbol table by hand. You only need to do this if
don't use KiCad symbol libraries at all. Otherwise it is easier to
modify the automatically generated global symbol table.

[NOTE]
If you track the
https://github.com/KiCad/kicad-symbols[symbol library repository],
changes made to the default global symbol library table are not
tracked by KiCad.  You will have to manually keep the global symbol
library table up to date.

=== Symbol Library Table Mapping

Automatic remapping of symbols will be executed whenever a
schematic is opened that has not been remapped.
There are a few steps you should take ahead of time in order for the
remapping to be the most effective.

[NOTE]
If you have been using a development build of KiCad, copy the full
default global symbol library table file (sym-lib-table) from the
template folder installed with the KiCad libraries or from the
https://github.com/KiCad/kicad-library/blob/master/template/sym-lib-table[KiCad library repo]
to your KiCad user configuration folder.  This will replace the
empty one (most likely) created by Eeschema.  If you do not do
this, you will most likely end up with a bunch of broken symbol
links.

[WARNING]
Remapped schematics will not be compatible with older versions of
KiCad.  The Remap Symbols dialog will make a backup of your schematic
files and you should do the same if you remap manually. +

1. If possible, keep version 4 of KiCad installed on your system unless
   you have never used any of the symbol libraries distributed with KiCad.

2. If you get warning about missing libraries when you start version 4
   of Eeschema, make sure to fix the missing libraries if they contain
   symbols that are in the schematic before you attempt to remap your
   schematic.  Otherwise, the correct symbol will not be found and you
   will end up with broken symbol links in your schematic.  You can test
   this by left clicking on a symbol in the schematic and verifying
   that the symbol is not being loaded from the cache library.  If a
   symbol is being loaded from the cache library, Eeschema cannot find
   your part in the system or project symbol libraries. If you need a
   cached part to be available to other projects on your system, you will
   need to integrate it into a system or project library manually.

3. If symbol recovery is required during the remapping process, do not
   dismiss it.  Failure to recover symbols will result in broken symbol
   links or the wrong symbol being linked in the schematic.

4. During the remapping process, symbol libraries not found in the global
   symbol library table will be used to create a project specific symbol
   library table.  You can move them manually to the global symbol
   library table if that is your preference.

5. For the most accurate remapping, create a project library by copying
   the project cache file (project-name-cache.lib) to a different file
   and add it to the top of the symbol library list.  You must use a
   version of KiCad prior to the symbol library table implementation in
   order to do this.

[NOTE]
.** Fixing broken remapping: **
A tool has been provided to attempt to fix remapping issues.  If there
are missing symbol library links in a schematic, they can be fixed by
opening the "Tools->Edit Symbol Library References..." menu entry and
clicking on the "Map Orphans" button.

=== Remapping Search Order

When remapping symbols, KiCad proceeds in the following order to assign
the library to a symbol:

1. Global Symbol Library Table: Symbols are preferentially mapped to the global symbol
   library table, if one exists.

2. Project specific libraries: Libraries listed in the project library list that are not
   in the global symbol library table are searched next.

3. Project cache file:  If a symbol doesn't exist in the listed libraries above,
   it is first rescued -- a copy is made from the cache and placed in the __proj__-rescue.lib --
   before the symbol is mapped to this new, rescue library.

=== Symbol Names and Symbol Library Nickname Limitations

Symbol names may not contain `<SPACE>, ':', '/'`.

Library nicknames may not contain `<SPACE>, ':'`.

Existing symbol names with these characters must be renamed by manually editing the
relevant schematic and library files.

== Symbol Cache Library Availability

The cache library is no longer shown in either the symbol library viewer or
the symbol library editor.  The cache should never be edited because
any changes are overwritten by the next schematic save.

== Board File Format Changes

Several new features have been added to Pcbnew which impact the board file
format.  Using these new features in board designs will prevent them from
being opened with previous versions of Pcbnew.

- Rounded rectangle footprint pads.
- Custom shape footprint pads.
- Footprint pad names longer than four characters.
- Keep out zones on more than a single layer.
- 3D models offset saved as millimeters instead of inches.
- Footprint text locking.

=== Global Footprint Library Table.

If you track the
https://github.com/KiCad/kicad-footprints[footprint library repository],
changes made to the default global footprint library table are not tracked
by KiCad.  You will have to manually keep the global footprint library table
up to date.
