I have noticed that KiCad 6.0 has a few new directories for libraries,
Specifically "KICAD6_3RD_PARTY C:\Users\billy\Documents\KiCad\6.0\3rdparty "
What I am wondering is what would be the best way to setup a git repository for developing libraries for this folder?
I was able to find this KiCad Addons | Developer Documentation | KiCad which helps me with the folder structure, but doesn’t give me a good way to integrate git in my development of the library.
Sort of the same question. Should I use these new directories for my stuff or are they special? What are the pros and cons?
Specifically:
/Users/me/Documents/KiCad/6.0/footprints
/Users/me/Documents/KiCad/6.0/symbols
/Users/me/Documents/KiCad/6.0/3dmodels
Why do only a few have Environment variable set for them?
thanks, oh I’m on MacOS 10.15.7
This also confuses me.
Some of the environment variables are peppered throughout this document…
https://docs.kicad.org/6.0/en/kicad/kicad.html
But I have yet to find a definitive and complete table of all active environment variables for 6.0.
Here’s what I’ve dug out from that file…
KICAD6_SYMBOL_DIR
KICAD6_FOOTPRINT_DIR
KICAD6_3DMODEL_DIR
KICAD6_TEMPLATE_DIR
KICAD6_SCRIPTING_DIR
KICAD6_USER_SCRIPTING_DIR
KICAD_CONFIG_HOME
KICAD_DOCUMENTS_HOME
KICAD_USER_TEMPLATE_DIR
KICAD_TEMPLATE_DIR
KIPRJMOD (not user-definable)
So now there’s some that are prefixed “KICAD6”, some are still “KICAD” as before, and some are “KI”, hard to know which from the older “KICAD” and “KI” eras still do anything at all.
KICAD6_3RD_PARTY is for things installed by the Plugin and Content Manager (PCM)
KICAD6_*_DIR variables are for the official KiCad libraries and templates shipped with KiCad 6 – these are supposed to be read-only, and it’s not a good idea to place your own libraries in these folders as they can be overwritten when installing new versions of KiCad.
There is no default environment variable set up for you to put your own user libraries in. Using environment variables as part of library paths is not required. You can do this if you choose, and you can call the variable whatever you’d like. You can also just put a direct path to your user libraries.
/Users/me/Documents/KiCad/6.0/footprints
/Users/me/Documents/KiCad/6.0/symbols
/Users/me/Documents/KiCad/6.0/3dmodels
These paths (and the equivalents on Windows or Linux in the user Documents folder) are provided as an suggested location for your user libraries. You can put your user libraries here, or anywhere else that you have write access to. The KICAD_DOCUMENTS_HOME variable (not defined by default) can be used to change where KiCad looks for this default Documents path.
KICAD_CONFIG_HOME can be used to change the location KiCad looks for configuration files. This is an advanced thing that most people should not do. If you aren’t sure what this means, just ignore it.
KICAD_USER_TEMPLATE_DIR controls where KiCad looks for project templates defined by you (the user).
Thank you Jon, your explanation is the clearest I’ve seen anywhere so far.
I’ve spent some time today trying to configure the environment variables to customize my folder structure: without the “6.0” parent folder and with subfolder names of my choosing. Unfortunately, after looking through the source code, this seems impossible.
The “6.0” folder and the exact names of the subfolders are more than a “suggested location for your user libraries” as you mentioned. It appears to be impossible to circumvent KiCad’s hardcoded folder structure that is created in my home folder.
From poking around a bit, it seems at startup the SETTINGS_MANAGER constructor calls PATHS::EnsureUserPathsExist, which calls EnsurePathExists on each user folder, with names that are hard coded as string literals in paths.cpp … and this line in paths.cpp forces the “6.0” folder … aPath.AppendDir(SETTINGS_MANAGER::GetSettingsVersion()); … I cannot find any way, using environment variables or otherwise, to customize the names/paths of these folders.
So it appears we must have that folder structure with those exact names.
We don’t have to use them, as you said in your post, but they must exist.
I expected that I could use KICAD_USER_*_DIR environment variables to override the default folder paths. If a corresponding environment variable is set for a particular folder, then the code would call EnsurePathExists on the path in that environment variable, and fall back on the hardcoded default folder path if the environment variable does not exist.
Anyway, I’ll start migrating my 5.0 libraries to the the 6.0 folder structure as-is and move on with life.
Smaller observations I made during this inquiry…
• I found a variable KICAD6_USER_SCRIPTING_DIR mentioned in the official documentation…
But the only occurrence of it in the source code is a help tip/description (in the function ‘initialiseEnvVarHelp’). So I can only assume KICAD6_USER_SCRIPTING_DIR does nothing.
• Since the default path of KICAD6_3RD_PARTY points to a folder in the user’s folder, it is different than the other KICAD6_* variables, which all point to official folders outside the user’s folder. Also, it is strange that it doesn’t end with “_DIR” as the others do. Perhaps most importantly, the name “3rd Party” does not connote any relationship to the Plugin and Content Manager “PCM”. With this logic, perhaps it should be called KICAD_USER_PCM_DIR, or similar.
• To make it more clear what environment variables exist, it would be nice if all environment variables were visible in the “Configure Paths” dialog. As it is now, to understand what paths are configurable, it is necessary to refer to the manual or dig through source code.
• Since the other folder names are plural, shouldn’t “scripting” be “scripts”, and “template” be “templates”?
What I meant by “suggested location” is that you are suggested to put your files here, not that it is possible to reconfigure this location. As you’ve found, you can’t change where these folders are created, but you can choose to put your libraries elsewhere.
Correct, it’s a leftover that needs to be removed from the documentation.
Maybe, but the USER part would be redundant: all content in this dir is user-managed; there isn’t and won’t be some equivalent “system” dir.
Maybe, but these are maintained mostly for legacy reasons and there isn’t a very strong reason to change them that I can see.
Some of these environment variables do not exist by default though. The Configure Paths dialog only shows environment variables that exist. Also, the Configure Paths dialog cannot override actual environment variables that are set in the system environment.
This statement is very helpful.
I was probably causing unnecessary confusion earlier in the thread by using the term “environment variables” to refer to the variables in the Configure Paths dialog, since the variables in the Configure Paths dialog are not system environment variables. However, it does say “Environment Variables” in small text under the window title bar though, perhaps that text should be removed?
I understand why KICAD_CONFIG_HOME must be an actual system environment variable: the documentation explains it very clearly “naturally you can’t store the location of the configuration into the configuration”. But I didn’t realize KICAD_DOCUMENTS_HOME also must be a system environment variable. As an aside, it does seem to work for only a few folders if it is defined in the Configure Paths dialog, strange.
Regardless, this pointed me down a path to an acceptable workaround for the stubborn “6.0” folder…
Using those environment variables, I relocated both the preferences and the canonical documents-home to ~/Documents/KiCad/Data using the following commands (MacOS Monterey) …
launchctl setenv KICAD_DOCUMENTS_HOME /Users/me/Documents/KiCad/Data
launchctl setenv KICAD_CONFIG_HOME /Users/me/Documents/KiCad/Data/KiCad
For a permanent method of setting these environment variables, a LaunchAgent setenv plist can be used.
With this, the “6.0” folder and all the subfolders (including those that do nothing and are only suggestions and cannot be renamed or removed) are buried under ~/Documents/KiCad/Data
The two user path variables that do exist can be used to assign the KICAD_USER_TEMPLATE_DIR and KICAD6_3RD_PARTY folders to ~/Documents/KiCad/Templates and ~/Documents/KiCad/Managed.
Worst-case scenario, aliases can be used, for example “~/Documents/KiCad/Data/KiCad/6.0/plugins” to “~Documents/KiCad/Plug-Ins”
I think it would be cleaner to support path overrides in each of the PATHS::GetUser*Path() functions (exposed in the Configure Paths dialog), but this seems like a workable solution for now.
On my Linux Mint box, KiCad only uses two “real” environment variables:
I am even a bit surprised that the KIGITHUB environment variable exists.
As far as I know that has been deprecated for quite some time, and I bougt a new PC and installed everything from scratch just before christmas. I think I used KiCad V5.1.12 for about a week before it upgraded to V6.0.0.
Just to rant my 2cents. I think the library paths, naming, aliasing, environment variables, whatever you want to call it is the worst thing about KiCad. I’m sure I’ve spent more time with library issues than designing over the years. V6 has started the issues all over again. I wouldn’t mind that if it was an improvement. Unfortunately it’s more complex, less flexible and by the looks of it will require more changes in the future.
IMO anything legacy regarding library locating is trash. Its been poorly documented and interpreted differently by all users for years. So forget about supporting legacy methods.
Come up with a simple, clean, even inflexible, least common denominator way to support what needs to be done. I don’t think users need infinite flexibility in the way they store libraries and less is better. The current V6 implementation can’t even be explained by crafyjon. (Although thanks for trying, its not your fault). A picture would be worth 10,000 words and also expose the absurdity of the current situation.
I agree with you that it’s one of the most opaque parts of KiCad, and v6 did not improve it, so it will likely require changes in the future. But with the current release cycle of 4 years or so, I don’t find it unreasonable to spend some hours re-organizing my assets when upgrading considering how much nicer v6 is overall. I’ve made a set of regex scripts to speed this up, and the new harmonized file formats with s-expressions has improved that as well.
In the future, I hope something like an installation wizard would be added to guide us through configuring user-paths (for our symbols, footprints, 3d models, projects, templates, etc). One thing that I find irritating about v6 is that it’s so forceful/prescriptive about creating folders with hard-coded names (“3dmodels” “6.0” gah!). I really don’t like that it forces such things on me, and in my own home folder no less.
I’ll share the way I’ve found to work around this, also I tried to capture it all in the screenshot below.
• I set KICAD_DOCUMENTS_HOME and KICAD_CONFIG_HOME to point to the same folder (as craftyjon said earlier, these have to be set outside of KiCad). That folder is buried in a “Data” folder, so KiCad can make whatever mess it wants in there, it doesn’t bother me. A nice part of this setup, is that the Data folder is at the same level as my personal library folders, so when I do a backup, I simply archive the entire parent ~/Documents/KiCad folder and all is safe.
• Then in the KiCad GUI, I created KICAD_USER_*DIR variables that point to my folders with the names and locations I want. These variables are used in the symbol and footprint library paths. My personal library names are surrounded with parentheses so they sort above the built-in libraries; I don’t know why the list order I set in this path window (using the up and down arrows) isn’t used for the order they appear in the symbol and footprint lists, those list-reordering arrows seem to have no useful function, alas. Better yet, if KiCad’s symbol and footprint library lists would have some sort of UI separation of system libraries from the user libraries, then I wouldn’t need to use the parenthesis hack. I’ve read somewhere else on this forum that some people use "00" or similar prefixes on their libraries to control sorting, yuck. In the past, I used "+ " as a prefix since it looked a bit nicer, but I am afraid to use spaces in my library names, perhaps irrationally.
• I made a KICAD_USER_MODEL_DIR variable that I use in the footprint editor properties panel to point to the appropriate 3D model. I have no idea what “3D Search Paths” is intended for, but I have never needed to set those anyway. Generally, I don’t like the concept of search paths, since it encourages sloppiness and I’m never 100% certain what the search will find, I’d rather just resolve link errors instead and be certain the correct models are used.
• The new plugin manager seems pretty nice. I need to figure out how to get the plugins I wrote for v5 to be installable in there. It seems happy to use the folder where I pointed it to in KICAD6_3RD_PARTY. As I said earlier, I don’t know why that variable name doesn’t end with "DIR" like the others, and I don’t care for the term “3rd party”, I’d rather it be called something having to do with “plugins” even if the PCM does more than just plugins, but that’s a matter of preference. I called my folder “Managed” so I know not to fool around in there. I might change it to “Plug-Ins” though. I still think the PCM path variable should be 'KICAD_USER’ instead of ‘KICAD6_’ since they are plug-ins that i’ve installed as a user and the files live in my user directory, as opposed to the other ‘KICAD6_’ variables which point to the official/system content. Nuanced distinction, but important since we are talking about making the environment variables easier to understand.
I’m tempted to try to modify the source of paths.cpp to hack in path overrides for the user folders (it’s in the ~/Documents/KiCad/Source folder in the screenshot), but I’m not sure it’s worth the time since I’m happy with my setup as it is now with these workarounds. The KiCad team has done a remarkable job with v6, so I’m sure they’ll find a way to solve the difficulties with environment setup when they get to that dusty/messy part of the code in a future release.
Anyway, here’s my setup. Perhaps it’s helpful for others, or perhaps people could tell me what I could do better, or can tell me I did something stupid.
hello, I created an image there, it shows the Windows structure of Kicad6, could you see if I created everything correctly?
Hello, I have adjusted the folder structure again. The KiCad variables are capitalized and written in red. The Windows environment variables are blue.
I would capitalize the environment variables uniformly.
I also want to color the four gray folders green so that you can see that the user can only make changes in these folders.
Incidentally, the image is from my created HTML file.
https://gabischatz.github.io/KiCad6_WIN_DIR/
So ich habe es endlich geschafft die Seite online zu stellen.
Ich finde es nur schade, dass ich keinerlei Rückmeldung dazu bekomme.
So I finally managed to put the site online.It’s just a shame that I haven’t received any feedback on this.
Hi Lutz, If I’m understanding the behavior of KICAD_DOCUMENTS_HOME correctly, I suppose that KiCad would create a “KiCad/6.0” folder hierarchy inside of your “Data” folder if it is indeed set to point there as your image indicates. This seems strange to me that your “6.0” folder is a sibling of “Data”, it makes me wonder if the environment variable is not set up correctly.
Maybe it’s helpful to look here to understand how KICAD_DOCUMENTS_HOME determines where your 6.0 folder resides…
As far as I know, all your _USER_ variables should begin with KICAD_ and not KICAD6_, I believe the latter is reserved for official use and should not be changed.
Also, I’m fairly certain that KiCad is not expecting any of your _USER_ variables, they are only a suggested way to simplify the setup of your personal libraries, footprints, and other paths. You could just type the complete path to the libraries if you wish, you don’t need to use variables, but they are certainly helpful.
Confusingly, the only _USER_ variable that does anything seems to be KICAD_USER_TEMPLATE_DIR, which does have some built-in functionality as you can see here…
Please don’t take any of this as gospel, it’s just what I learned from this thread, trial and error, and looking a little at the source.
Hello,
You would probably find most people using Kicad have adapted to the supplied folder structure and are more interested in creating Schematics and PCBs than altering that structure.
you are most certainly correct that most people would rather adapt to how things are, rather than try to improve their environment and how it is organized.
Thanks to everyone for their input, I knew I needed to overhaul the way I handled Libraries for KiCad.
I chose to setup 4 repositories in the “Documents/KiCAD/6.0” folders and set the appropriate path variables in KiCad.
The repositories are downloaded to the Following Folder:
I got tired of finding broken datasheet links so I ended up setting up a datasheets library, because I got tired of broken datasheet links. Be sure to watch out for companies that require a confidentiality agreement or don’t want people reposting datasheets.
So I added a path variable to KiCad for the datasheets library so I can use ${KICAD_USER_DATASHEET}/path to the datasheet/readme.md
The readme.md is helpful for the companies that split application data and Data Sheets into separate files.
This is a genius tip! I will do the same from now on.
Whenever I draw a new component, I have always created a subfolder in my own “Datasheets” folder, with a name that matches the symbol name. I place the datasheet, application notes, etc in there. But I never thought to link to that local PDF using the symbol metadata field for the datasheet. I’ve always used URLs for the datasheet field and have also been frustrated by broken links and the extra browser tab bloat.
Thank you for sharing this great idea.
Looking more into this, I found this thread from 2019 that mentions exactly this use of a _DATASHEET environment variable… $(KICAD_DATASHEET_DIR) proposal - #11 by paulvdh
I just tried this in the project that I am working on now, and I set up my symbol like this …
Now pressing ‘d’ on this symbol in the schematic editor immediately opens my local copy of the datasheet. This is wonderful!
However, I tried setting the symbol datasheet field like this, and strangely, it did not work…
${KICAD_USER_DATASHEET_DIR}/${VALUE}/${VALUE}.pdf
I would expect it would have expanded to this…
${KICAD_USER_DATASHEET_DIR}/TI-BQ25171/TI-BQ25171.pdf
The ${VALUE} replacement token is mentioned here…
This would have been nice so I could simply regex my symbol library files and never have to set the datasheet field ever again.
For posterity, this was found to be a bug with the “Show Datasheet” function and has been fixed by the development team (slated for 6.0.3). More details here…
