Pkg.add and package development best practices?

Tooling Package Management
,
1

Quick question:

Is it better to use

# In a Julia script
using Pkg
Pkg.add("MyPackageName")

or

julia> ]  # enters the pkg interface
pkg> add MyPackageName

when advising people to use a package? 

Context

I ask because I’m still trying to figure out what the “best practices” are regarding making packages and making good documentation for people to easily plug-n-play.  It’s worth noting that I have a couple different target audiences in mind:

  • People in research who just want to use Julia to compute their problem of interest.

  • Software developers who would like to either
    1. contribute to the package
    2. make their own package
    3. or make applications outside of the standard scientific computing domain.

Of couse, the advice will depend on which of these audiences I’m targeting, but I’d figure I’d ask for all the variations since good documentation is important for wider Julia adoption.

2

They’re exactly the same in functionality. In general, I would recommend the documenting with the second. The first mainly exists for scripts that need to interact with packages.

3

I mostly use the repl, so I don’t know whether that advice is more or less likely to help someone who for instance uses VSCode or some future development environment.

To me the ] version is still better because if it doesn’t apply it’s at least a bit more discrete. In Pluto, for instance, you generally don’t interact with Pkg at all. But you only have to learn that ]add Whatever can be ignored once, while using Pkg; Pkg.add("Whatever") looks like something you might need to do parts of or whatever.

4

The problem with the second is that you cannot copy/paste it to the REPL. It was for me a headache when teaching once, the very first thing the students tried to do resulted in a syntax error. Since then I suggest the first one (in tutorials or user guides).

1 Like
5

I would always do the first so it can be copy pasted and you don’t have to introduce anything about REPL modes in the test.

2 Likes
6

I’m surprised pasting doesn’t work. Shouldn’t be too difficult to implement, but one would need to look out for multiline arrays.

7

I would just add that I really like that the pkg mode always informs you of what environment you are in.

(environment) pkg>

If you’re working with package development, or simply building a Project/Manifest for version management, etc., it’s always really helpful to know which environment your actually adding the new package to! I’ve been burned by doing ‘Pkg.add()’ many times before I realized this.

8

I also always go with the first when explaining to people with little knowledge of Julia because:

  1. The person can past that in the REPL and it will work.
  2. The person can put it in a script and it will work.
  3. I do not need to explain REPL modes or even get them to understand what kinda of bracket I am talking about, no, the square bracket, yes, just the closing bracket, yes it goes against your programmer instincts to start with a closing bracket, yes, the bracket is not just to indicate it that you are in the REPL, you really need to type it, yes, the bracket is supposed to disappear, did the REPL change color? great, now type “add PackageName”, no, parenthesis are not needed, great now we can go back and, ah to go back you need to press backspace all the way back, did it change color, no? one more time, yes, you need to delete the closing square bracket that disappeared as it was there yet, yes aham, I agree with you that it is a bit weird.

The story, all names, characters, and incidents portrayed in this comment are fictitious. No identification with actual persons (living or deceased, especially my advisor, co-advisor, and lab colleagues), places, buildings, and products is intended or should be inferred.

2 Likes
9

Wow, appreciate all these responses. 🙏 From the looks of it, seems like

# In a Julia script
using Pkg
Pkg.add("MyPackageName")

is probably better for copy-pasta purposes (and avoiding overcoming intuitions of software devs).

However, the point that @Brad_Carman made about knowing which environment you’re actually adding the package to is also very helpful, so I’ll keep the benefits of

julia> ]  # enters the pkg interface
pkg> add MyPackageName

in mind depending on who I’m talking to. Thanks again everyone!

1 Like