Pkg.jl: Document Manifest.toml / Project.toml properly

[fingolfin]

We tried to figure out what constitutes valid entries for Project.toml and Manifest.toml, and what not, and what they are supposed to mean. The existing documentation says little about this. Based on examples and looking at the code, it seems the following keys might be valid (though their exact meaning and allowed / expected content is not clear in all cases).

In Project.toml:

compat ?
deps ?
desc
keywords
license
name
uuid
version

[deps]
[extras]
[targets]

In Manifest.toml entries also (but perhaps also allowed in Project.toml):

path
pinned
repo-url
repo-rev

[fingolfin]

CC @sebasguts

[fredrikekre]

Yes, should definitely be documented. Some breadcrumbs;

• name, uuid and version are the only ones required for packages
• desc, keywords, license are optional, and AFAIK completely unused by Pkg.
• [compat] is explained in https://julialang.github.io/Pkg.jl/v1/compatibility/
• [deps] just list the dependencies (this is where added packages end up).
• [extras] and [targets] are currently explained in https://julialang.github.io/Pkg.jl/v1/creating-packages/#Test-specific-dependencies-1

Also note that Manifest.toml is completely controlled by Pkg, and you should never have to touch that file. Would of course be good to document and explain the content of it.

[timholy]

Also note that Manifest.toml is completely controlled by Pkg, and you should never have to touch that file.

Not quite true, see #492 (comes up for me a lot in #698 where I might have a whole flock of unregistered packages that I'm developing as a group).

[fredrikekre]

Are you manually updating your Manifest.toml to workaround the location issues?

[timholy]

Sometimes, yes.

[KristofferC]

Well, let's put it like this then

Also note that the intention is for Manifest.toml to be completely controlled by Pkg, and you should never have to touch that file.

[kkmann]

Just wanted to bump this - current state of Pkg(3) is a bit confusing to non-experts like me. All the bits and pieces seem to be out there but just putting together a PR for a package on GitHub after properly testing locally in Atom/Juno is quite non-trivial at the moment. I'd greatly appreciate a consitent documentation for the entire workflow!

[cossio]

• [extras] and [targets] are currently explained in https://julialang.github.io/Pkg.jl/latest/creating-packages.html#Test-specific-dependencies-1

I get a not found error on this link.

[fredrikekre]

https://julialang.github.io/Pkg.jl/dev/creating-packages/#Test-specific-dependencies-1

[jonas-schulze]

I manually changed my Project.toml to include the [extras] and [targets] sections. To test whether it was working as intended I deleted my Manifest.toml, but I wasn't able to have it generated again through Pkg (I tried ]activate ., ]instantiate). So I restored that file and ran a ]add CSV (which had already been present in [extras]) and a ]rm CSV, which also removed the whole [targets] section.

1. What should I do to have the Manifest.toml regenerated?
2. Is there a way to add dependencies to [extras] (or to a specific target) using Pkg in a single step? I could do ]add Foo and manually add/move that from [deps] to [extras] and add it to the test target, but this doesn't feel right.
3. Was it my mistake or might this be a bug that removed the [targets] section?

Update: just found out about #480.

[fredrikekre]

Was it my mistake or might this be a bug that removed the [targets] section?

See https://github.com/JuliaLang/Pkg.jl/issues/876. Should be fixed in the next Julia release.

[jonas-schulze]

In https://github.com/JuliaLang/Pkg.jl/pull/1033 and BasicSandbox it sounds like you are heading towards a test/Project.toml similar to described here. Will deps stated in test/Project.toml augment or replace the ones from /Project.toml? Is this to replace [extras]? Is there some further documentation I can read along? 🙂

[fredrikekre]

In #1033 and BasicSandbox it sounds like you are heading towards a test/Project.toml similar to described here.

Yes, this is in fact already implemented on Pkg master (#989) but not documented yet (#1031). See #1008 and specifically https://github.com/JuliaLang/Pkg.jl/issues/1008#issuecomment-461766909 and below for some more discussion)

Will deps stated in test/Project.toml augment or replace the ones from /Project.toml?

The test env will be test/Project.toml with dev package on top.

Is this to replace [extras]?

Yes, although the old setup will also work.

[fredrikekre]

1059, see https://julialang.github.io/Pkg.jl/dev/toml-files/ for the result.

[Wikunia]

Can you change the link regarding [compat] it is also not working

[fredrikekre]

https://julialang.github.io/Pkg.jl/v1/compatibility/

[Wikunia]

@fredrikekre would be nice if you can change the link of your previous comment so that others can find it easier