Distributing Library Packages: Percent (%) classes vs %ALL namespace
Hi, Community!
Someday you find yourself having a wonderful class package which can be helpful in several projects. So it is a library package.
How to make the classes available for different namespaces in Caché? There are two ways (at least two ways familiar to me):
1. Start the name of the package with %, like %FantasticLib.SuperClass. Wrong way.
If you do that the class would be placed in %SYS and would be available in other namespaces.
This is wrong because of the two reasons:
1. The class will be wiped out with the next Caché update (as all the %SYS Namespace).
2. InterSystems can introduce its own %FantasticLib package.
3. You need to turn off 'read-only' flag on CACHELIB database to install the % class in it which reduces the security level of the system and makes the installation more complicated.
2. Name it without leading '%' like UsefulLibrary.Class and map it to %All namespace. Right way!
All the packages mapped to %ALL are visible in all the Namespaces (with one exception of "SAMPLES"). Documentation.
Yes, it needs one extra step in installation but you can import the library class in any "garbage" namespace like "USER" or to a separate DATABASE/NAMESPACE if the library is large and map the package in %ALL.
And yes, it's a pretty "Сap's" post, but I still meet examples of the %Lib approach, so hope it can be helpful.
Comments
Naming classes and routines with '%z' or '%Z' recommended way, because in this case, such code will be stored in writable database and safe with updating Cache.
Thanks, Dmitry. And when you save this '%z' class say in USER namespace, where is it actually stored? In CACHELIB?
CACHELIB as you already mentioned read-only by default and will be replaced during update.
But %z classes routines and globals will be stored in CACHESYS
Well, the %Z* names were safe from overwrite by InterSystems, until they came out with the %ZEN package 
This naming "mistake" of %ZEN caused a lot of extra checks and workarounds that we may have to carry around forever. 
My personal proposal "CSP#" written as CSPXX (CSPX was already used by Ensemble) didn't win the internal naming contest. 
Guess why. 
See also my post here which documents how to set up %ALL, and how it doesn't actually apply to 100% of your namespaces.
Thanks, John! You mean two exceptions SAMPLES and DOCBOOK?
Yes, that's what I mean.