0. What is a local lib This is a concept that does not exist in gschem/lepton. Topic is how we reference/store symbols within a sheet. It has _nothing_ to do with how you build symbol libraries. This pool node lists all different ways symbols can be referenced: http://repo.hu/cgi-bin/pool.cgi?project=sch-rnd-aux&cmd=show&node=loclib_embed Please read it, without this info you won't understand any of the blow. This other pool node explains the reasons why I don't implement external references, which is the default behaviour in gschem/lepton: http://repo.hu/cgi-bin/pool.cgi?project=sch-rnd-aux&cmd=show&node=loclib_noext Now that you know the theory, let's try it in practice! 1. Default embed, opt-in local lib By default, sch-rnd works in embed mode (each symbol you place is fully copied into the sheet; place 10 times, it is copied there 10 times; much like pcb-rnd's subcircuits). You can change this by setting config node editor/paste_to_local_lib ; a menu item is provided in "mode/Symbols and libraries" with hotkey {m s p}. When enabled, symbols pasted from the library go into the local library tree and a grp_ref is placed on the sheet. You can turn it on or off any time, and as you'll see in a later, you can convert between embed and local lib on a per symbol instance basis. When you place a symbol with the local lib enabled, the symbol will appear in your library window's subtree. This subtree shows the "in-sheet local library". Only one master copy of each unique symbol is placed in the local lib, and only when the feature is enabled or when you explicitly move an already placed symbol into the local lib. You can do all three possible setups: - never enable local lib, so all symbols are embedded on per instance basis in your sheet - always enable local lib, so symbols are always copied only once into your sheet's local lib and your actual placed symbols are just group refs ("symlibs") to the local lib symbol - mixed: some symbols are embedded, others are from the local lib Since we have no external reference, the only one thing you can't do is produce a non-portable sheet that refers to an external symbol by file name. Yes, this also means your sheet will open correctly on another system, whether you used local lib or full embed, independently of what libs are on that other system. 2. direct, manual move between embed and local lib If you right click over a symbol's empty space, you see two new context menus at the bottom: - move symbol to local lib ref. - convert local lib ref. to embedded The first one will take an embedded symbol and put it in the local lib (if it's not already there) and convert the instance group to a group ref. Or in short, converts from embedded to local lib referenced on a per instance basis. The second is the reverse transformation: if you have a group ref to a local lib symbol, you can convert that instance into a real group (an instance copied out from the local lib). This is useful if you want to make some drastic edits on this one instance that will make it different from the other, unfirom local lib refs. Note: with local lib refs you can still have a few deviations from the local lib master version on per symbol instance basis: - you can create and change attributes - you can move, rotate, mirror and delete floaters But you can't create new floaters or edit the graphics per instance, because these are really stored only once, in the local lib. 3. Example usage One aspect of using local lib is that you save some disk space, which is not really a big deal these days. Another aspect is less VCS noise when you have to place/remove many instances of the same boring bypass caps or resistors. But the real good thing is uniformity. It's much easier to guarantee that you get the same resistor, same capacitor, same diode, same Vcc, same gnd if you: - enable local lib first - place the first instance of your resistor/capacitor/diode from the lib - once done, place any more copies from the tree of the library window (always look there first if you already have it) So this is sort of a QA tool mainly. Thus I expect it will be popular among pro users while hobbyists will probably more often go with full embedding. 4. Backgroud: moving floaters I had to extend the original design doc a bit so that floaters on a group_ref (which is how a symbol instance from the local lib is placed). The new part is http://repo.hu/projects/cschem/design/03_drawing.html#des3:83 to des3:86 5. Copy-paste corner cases Copy-paste becomes funny when you use local libs: you select and copy group refs pointing in your own sheet's local lib. Now imagine you copy only the reference in your buffer, the close the original sheet and open a differnet one and try to paste: the reference is invalid! Of course we could automatically embed on copy, but then if you copy a group ref within a sheet you'd end up with embedded symbols instead, so copy would have side effects, which is bad. Instead the buffer also has the same local lib concept - in fact the buffer is pretty much a sheet, just without local config. So copy and paste always remembers if you have local lib instances on it and keeps them as local lib refs, and paste places local lib refs (adding the symbol in the local lib, if needed, e.g. when you paste on a different sheet), even if you have the local lib paste off. Rationale: the local lib paste setting controls what to do when you import symbosl from the external lib. On buffer operations, we try to keep everything as is, so if you copy a local lib group ref, that will end up as a local lib group ref on paste and won't accidentally embed. For more details on all the solutions I considered and how it is implemented finally, you can read this short summary: http://repo.hu/projects/cschem/developer/symbol_loclib_paste.txt