NuGet / Home

Repo for NuGet Client issues

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

NuGet Docs: nuget.config locations on linux

Mikejo5000 opened this issue · comments

NuGet Product Used

Other/NA

Product Version

N/A

Worked before?

No response

Impact

None

Repro Steps & Context

Ported from NuGet Docs, where we are closing issues.
Opener: Rast1234

NuGet Product(s) Involved
dotnet.exe

The Elevator Pitch
From the docs it's unclear where dotnet add, dotnet nuget, etc look for configs:

$XDG_DATA_HOME (typically ~/.local/share or /usr/local/share, depending on OS distribution)

In my case, this variable is not set. I wanted to add a global configuration for my docker image and tried these options:

location: /usr/local/share, /etc/opt, /
filename: NuGet.Config, NuGetDefaults.Config, nuget.config
The only working solution turned out to be /nuget.config.

How docs can be improved in this regard:

describe exact algorithm used by tooling for locating configs
if $XDG_DATA_HOME is unset, what is the fallback? it can't be distro-specific, it's somewhere in nuget source code
clarify use case of NuGetDefaults.Config
clarify if nuget looks for case-sensitive config names or not: NuGet.Config vs nuget.config
describe recommended and legacy locations/filenames. "On Linux, this previous location was /etc/opt" is not clear
Additional Context and Details
No response

COMMENTS
from @Rast1234
Thanks for looking at this ticket. I don't think PR from any external contributor is really possible here: in order to make a PR, one would have to dig into previous, current and upcoming versions of nuget and dotnet nuget cli to figure out developer intentions. Some things are not possible to understand from code, eg. what's going to be depreacted and what is the most recommended mechanism the team is currently betting on...

COMMENTS
from @nkolev92
@Rast1234

@heng-liu recently updated the doc: https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#config-file-locations-and-uses

I went through the questions and spent a minute or 2 where appropriate to help out the person changing the doc and maybe help answer some questions for you in the meantime.

describe exact algorithm used by tooling for locating configs
I think https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#how-settings-are-applied
covers that.

if $XDG_DATA_HOME is unset, what is the fallback? it can't be distro-specific, it's somewhere in nuget source code

The backup is Home, https://github.com/NuGet/NuGet.Client/blob/741f7d55477ebd3e2201a5d9e6a030daa25ec5f2/src/NuGet.Core/NuGet.Common/PathUtil/NuGetEnvironment.cs#L223. https://github.com/NuGet/NuGet.Client/blob/741f7d55477ebd3e2201a5d9e6a030daa25ec5f2/src/NuGet.Core/NuGet.Common/PathUtil/NuGetEnvironment.cs#L284-L305. Basically looks at the HOME variable.

clarify use case of NuGetDefaults.Config

It's to add non-removable sources. I don't think this is something we recommend folks use much, but deeper analysis is needed here.

clarify if nuget looks for case-sensitive config names or not: NuGet.Config vs nuget.config

It matters on case sensitive FS.
nuget.config, NuGet.config and NuGet.Config are all respected in that order.
https://github.com/NuGet/NuGet.Client/blob/741f7d55477ebd3e2201a5d9e6a030daa25ec5f2/src/NuGet.Core/NuGet.Configuration/Settings/Settings.cs#L34-L36

describe recommended and legacy locations/filenames. "On Linux, this previous location was /etc/opt" is not clear

I think /etc/opt is not used anymore, so it's not recommended as a machine wide config location.

COMMENTS
from @Rast1234
i'm not sure what changed in docs but it looks better, great!

NuGetEnvironment.cs is interesting. looks like a approached my task with wrong mindset:

i expected tooling to look in some predefined specific place for a global, user-independent config if no user/project configs exist, like most linux tools place their global settings in /etc/something/nuget.config. i see this is not the case as it tries really hard to use one of env variables. i think even root always has at least $HOME that's why GetValueOrThrowMissingEnvVar doesn't throw, but i'm not sure this assumption is 100% valid. especially in containers...
the config which happens to work for me, /nuget.config, works because tooling looks up the directory tree until it finds anything?
and back to docs:

~/.local/share or /usr/local/share will be used (varies by OS distribution)

why? i only see Path.Combine(_getHome.Value, ".local", "share"); in source code. how can local (without dot) end up in here?

On Linux, this previous location was /etc/opt

i see a fallback to /etc/opt in a branch related to CommonApplicationData enum value. since docs say previous (version?), is branch effectively dead?

COMMENTS
from @nkolev92
why? i only see Path.Combine(_getHome.Value, ".local", "share"); in source code. how can local (without dot) end up in here?

Might be something that true at some point but not now? Not sure, requires deeper analysis.

Yeah, I think the /etc/opt on is probably not reachable anymore.

COMMENTS
from @Rast1234
issue is still relevant. please make sure docs are up to date with actual implementation and without hard to verify statements like "on linux, previous location was ..." with no clear meaning

Verbose Logs

No response

TL;DR summary: please investigate exact actual algorithm on how nuget-related tooling looks for configs, and describe it clearly in the docs. what variables are in play here? what paths on what OS are considered? in what order? what locations/vars are recommended, not recommended/deprecated? what would be best practice to set up, say, in containers or other scenarios?

it's difficult to figure out from source code and not miss something. it really is, i tried. also an outside contributor has no idea what's actually recommended, what's deprecated and kept for compatibility reasons

current docs have phrases like (varies by tooling) and on linux, previous location was ... which are confusing

We added new dotnet commands to understand the NuGet settings applied to a repository/directory. All the new commands are documented in the spec. There should be docs page for every new command mentioned in the spec for example dotnet nuget config paths.

Thanks! This is useful for debugging "where did this come from" but still does not answer questions like "where do i place config to make everything work"