I just merged the new symbol library table code into the KiCad development branch. This represents a significant change over the way symbol libraries have been managed. If you use development builds either from source or nightly builds, please see the [blog post on the KiCad website]. It contains the necessary user information for a successful transition to the symbol library table. If you find any unexpected issues, please file a bug report and include the original project files and symbol libraries that caused the issues if possible. This should be the last major change except for the new symbol library manager before the feature freeze of the stable 5 version. Thank you for your patience during this transition and enjoy.
Another change broke the nightly build (documentation now goes to a different directory, and the winbuilder fails to find it there), so there is no nightly today.
There was an issue loading the project specific symbol library table in release builds that I just fixed in commit 9f0b2e4bb. This would only effect users that use project specific libraries in release builds so many users may not have even noticed it. The nightly package builders should be have packages built soon. Sorry about the inconvenience.
@stambaughw
Could you explain how library cache and rescue symbols functionality work now? It looks like there are some considerable changes here.
If I recall correctly the rescue window used to appear when there were differences between cache and external library. Now it appears only when required library is not found, otherwise symbols from the external library is used without any warnings and original cached symbols are overwritten with next save.
If no external libraries were lined to project then cache used to be used. Now in this case rescue window appears, rescue library is created from cache and added to local library table. Is looks like after using these rescued symbols library and saving the file there is no way back to using external library. I mean that you cannot easily synchronize schematic with external library because you’ve lost library names (which are now required).
Am I correct? Is it expected to work this way? It seems to be more dangerous for projects (as it was before introducing rescue functionality).
The symbol rescuer had a potentially fatal flaw. It only rescued symbols that were different than the symbol in the original library. It did not rescue symbols could no longer be found in any library. This meant that you were always using the cached symbols in this case. This was a serious flaw. If the cache library ever got corrupted or deleted, all of the links to the symbols that no longer existed in any library would be broken. This is not the purpose of the cache library. It only should have ever been used as a temporary backup in case the user accidentally deleted a symbol in the schematic while editing. Unfortunately, it has been used a crutch since the beginning of the project albeit a crutch that was hidden from the user for the most part.
To answer your question, it makes perfect sense to rescue symbols that cannot found in the library list or now in the library table to prevent the situation describe above. This way if the cache ever gets corrupted or deleted, there should not be any broke symbol links (unless of course you delete symbol libraries that have links in the schematic) because they are always rescued to the rescue library. So your assumption about it being more dangerous is incorrect. It is now far less likely to have a broken symbol links.
The risk that I’m afraid of is mainly that symbols that are loaded to schematic may differ from those that were used while drawing and now I won’t get warning that they may not match.
I use my own libraries and sometimes I change them (names, paths, pin positions…) so when I open old project I can’t rely on links to my libraries and I usually rely on cache. Now probably I should rely on *-rescue.lib created from cache after removing sym-lib-table entries.
You are far better off with the changes I made than you were without them. We should have never relied on the cache and should have displayed a warning to users that there where symbols in the cache that no longer existed in any library. If you changed a symbol in a library and it doesn’t match the one in the cache (which should be a copy of the last symbol pulled from said library when you save the schematic), then you want to use the rescued symbol. If the library symbol was used, the schematic would be broken by the changes to the symbol. This is how the rescuer always worked. All I did was include rescuing symbols found in the cache that could no longer be found in any library. The rescue library is far safer than the cache.
While waiting for the windows nightly to be updated I am looking for some clarification: In the blog post on the KiCad web site under point 3:
Make sure your default KiCad template project file (kicad.pro) has no entries in the [eeschema/libraries] section or get a copy from the KiCad source repo. If you build from source or are using a nightly build, the update project template file has already been installed. It is imperative that you do not have any symbol libraries in your project files. Otherwise, you could possible be effect by this bug which the symbol library table is designed to resolve.
(Emphasis by me).
What does “have any symbol libraries in your project files” actually mean? Does it refer to the settings managed under Settings- Component libraries that is stored in the project .pro file? So should the list of component library files be cleared out before remapping?
Also under point 5:
For the most accurate remapping you should 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.
If one has made sure that there are not any symbols that only resides in the cache as instructed under point 1 of the blog post, will step 5 add any additional information, or is it just a safeguard in case something has been forgotten? (It just seems that this could contribute to a messy sym-lib-table file.)
One manual way to migrate (using the own internal language of the Eeschema files):
Backup your project first, just for safety.
Copy your “-cache.lib" as "-rescue.lib” (as example);
Open the *.sch in a text editor;
Replace strings in all the text "\nL " to “\nL Project:” (\n in the indication of new line, so “L” is in the begin of the line);
Open the schematic in the new Eeschema but cancel all the automatic migration;
In the symbol table import your “*-rescue.lib” as “Project” in the local (project libraries);
Restart Eeschema / KiCad;
Re-open the schematic (probably you be not asked you to synchronize the library).
I used this method tho migrate a 9 files (hierarchical) project and had almost no issue (the only founded is related to one new version of a MCP4922 in the internal library that use “/” in the name and create some problem in the cache interpretation). With my old projects with just 1 schematic file I had no error at all.
I had to do manually, because the automatic procedure couldn’t deal with this big project. And this procedure as inspired in the step 5 of https://kicad.org/post/symbol-lib-table/.
Is slash ("/") allowed in part names now? The most recent KLC prohibits slash, but there are many parts in the official libs that do use slash (notably Microchip parts). (See https://github.com/KiCad/kicad-library/issues/1799)
The slash has been allowed in the past. We disallowed it only in the latest reincarnation of the KLC in preparation for the new file format. (In the hope that no symbols with this char in their name will be left at the time the new file format comes along.)
