Adding the package to its workspaces

General Usage
,
1

I am looking into the workspaces feature, but have trouble understanding what is the correct way to add the package to its workspace einvironment: dev or add.

For example, in the Pkg.jl manual, it is suggested to add the package to the test environment using ] dev ..

On the other hand, Documenter.jl guide suggests adding the package as ] add PkgName to the docs environment.

Since the package may not be even registered yet, using dev seems like the more robust way to add it to workspaces. But then, is there a specific reason to add the package and not dev it in the case of docs? Or is it just a mistake in the Documenter.jl manual?

2

You can add it with a path. I can not find the command directly but you can add the package with add (or dev for unregistered ones) and then add

(here for the Manopt package)

to load the package from the parent folder. Maybe the documenter docs are just slightly outdated?

3

Even for registered ones, dev results in the {path=".."} entry, which seems to be what we want.

But then, I guess, there is really a mistake in Documenter.jl docs.

4

I suspect that part of the Documenter manual was written before [sources] were a thing. Dev should be the way to do things now if it leaves a sources entry.

5

Not totally sure because I think the sources came together with the workspaces and those are mentioned – but maybe it was not fully updated back then.

Ah dev does that already – for the path I was lazy and for a while just copied it over when moving to workspaces, so I did not remember.

6

I’m confused. Why would you need [sources] to refer to the package if you are in one of its workspaces?

As far as I can tell, both add and dev can be used in this scenario, but dev makes more sense to me.

7

As far as I understand the intention, if you want to run, for example, the tests, the environment in the test directory is automatically activated. So, in order to use the package, it needs to be explicitly added to the said environment.

8

I am not 100% sure where I have that from, but the docs environment has to have its main package included / installed / listed (whatever you want to call it) and it should load the one from the parent folder, generating docs for the last registered version does not make much sense.

So hence docs would refer to the parent folders package to document that one?

Maybe also I am confusing something here :smiley: , but I used that scheme on all my packages I updated to workspaces and it works perfectly fine.

9

Yes, the test/docs environment must have the main package as a dependency but since all environments in the workspace share a common Manifest, there is enough information to find the main package without a [sources] entry.

10

Oh! Interesting!

Is that the same for all other direct and weak dependencies?
I.e. I do not have to “repeat” them in the “sub-Project.toml”s?

If so – that’s neat to have less redundancy, then I will adapt then next time I change something on the packages :slight_smile:

11

I haven’t explored anything more than the main package but you can extend this example to test it.

julia> mkdir("TestPackage")
"TestPackage"

julia> mkdir("TestPackage/test")
"TestPackage/test"

julia> write("TestPackage/Project.toml", """
       name = "TestPackage"
       uuid = "fcf858a6-5829-40ba-9e22-8c0850d8ff79"
       version = "1.0.0"

       [workspace]
       projects = ["test"]
       """)
118

julia> write("TestPackage/test/Project.toml", """
       [deps]
       TestPackage = "fcf858a6-5829-40ba-9e22-8c0850d8ff79"
       """)
60

julia> using Pkg

julia> Pkg.activate("TestPackage/test")
  Activating project at `/tmp/TestPackage/test`

julia> Pkg.resolve()
    Updating `/tmp/TestPackage/test/Project.toml`
  [fcf858a6] + TestPackage v1.0.0 `.`
    Updating `/tmp/TestPackage/Manifest.toml`
  [fcf858a6] + TestPackage v1.0.0 `.`

julia> print(read("TestPackage/Manifest.toml", String))
# This file is machine-generated - editing it directly is not advised

julia_version = "1.12.7"
manifest_format = "2.0"
project_hash = "da0c113f9671a260296eba155d4f530891f3b71a"

[[deps.TestPackage]]
path = "."
uuid = "fcf858a6-5829-40ba-9e22-8c0850d8ff79"
version = "1.0.0"
12

The main reason to have redundant sources entries is to support users on julia 1.11 where workspaces are not supported.

13

I have tried to experiment with it.
Apparently, it does not matter whether you add or dev the package.
In either case,

[sources]
PkgName = {path=".."}

is added to the Project.toml of the workspace environment.
Bear in mind, that I checked it only on an already registered package.

14

Did more testing.

  • add PkgName does not work if the package is not registered.
  • add . does not work if there is no git repository created.

Conclusion: one should really use dev . (assuming Julia is run in the package’s directory).