Use of PERSONAL vs PLUS

[KitBaum]

I have received materials to be posted on SSC recently from a couple of authors who also include a README.md file that they have maintained on Githiub. Those files contain advice such as ""Or manually: download all `.ado` and `.sthlp` files and place them in your personal ado directory (`adopath`)."

As I have told them, this is a Really Bad Idea. There is nothing wrong with manually downloading materials and putting them in the right place, but this is not the right place. Why?

Because if they ever install the routine from SSC (or a version of that package from the Stata Journal archives), the files will be placed in the appropriate subdirectory of PLUS. The ado update command will check to see if there is an up-to-date version in PLUS.

Let's say the user has manually downloaded a version in PERSONAL. Some time later, the author fixes a bug and sends it to me, I update the SSC package, and they now download from SSC into PLUS after reading that a bug has been fixed. But on the adopath, PERSONAL comes before PLUS, so they will never be able to execute the bug-fixed version, as it is occluded by the original version in PERSONAL. This is all perfectly logical behavior on Stata's part, but could be a real hassle for users who are not aware of these distinctions.

I recommend that they download the package using the ssc install command, which will then sync with ado update if they use that command (as they should). But if they download manually, they should use PLUS and create an appropriate subdirectory if necessary.

[Leonardo Guizzetti]

Well said, Kit. This could also be a useful Stata Tip if you were so inclined to write one. (I can't recall such a tip on this topic previously.)

[KitBaum]

Thanks; I have drafted a Stata Tip on the subject, as there are a number of details that should be better understood.

[Sebastian Kripfganz]

While Kit makes a valid point about the pitfalls of placing ado files in the PERSONAL ado path, I am not sure I agree with the recommendation to download files manually and place them in the PLUS ado path. ado update checks the entries in the stata.trk file in the PLUS folder. But when files are manually put in this folder (or the respective subfolder), no such entry is created in stata.trk. I haven't checked what happens when an updated version is later installed through net install or ssc install, but manually placing files in PLUS is certainly not a clean solution.

Files could be downloaded and placed in a totally different folder. Using adopath +, the respective path could then be added to the bottom of the ado path search list. This way, Stata automatically finds the ado files but it would still first look in PLUS in case there is an updated version.

[KitBaum]

Thanks for your comments, Sebastian. I agree that it would not be the best practice to manually place items in PLUS, or for that matter to tweak the adopath. It is likely that any package manually installed will not be picked up by ado update, which makes it more difficult to ensure that you have the latest version of the package. If packages are installed via net install or sec install, there should be no problem -- although there is no guarantee that a non-Stata Journal package accessed by net install has the distribution date that ado update requires. Well-maintained sites for community-contributed software should contain a Distribution-Date: field YYYYMMDD) in the .pkg file. Unfortunately, not all sites follow this convention.