support 'west init --topdir'

[thorsten-klein]

Fixes #774 (Successor of #775)

This PR introduces a new --topdir option for west init, allowing users to explicitly specify the west workspace directory (topdir) during initialization.

This is particularly useful when using --local, as the current behavior always sets the parent of the given directory as the topdir. In addition, west is currently unable to determine both manifest.path and manifest.file from a single directory argument as the path can be interpreted in multiple ways (e.g. it can be split at various places).

With the new --topdir argument, users can now directly control where the west workspace is created.

Parameterized tests for west init --topdir are added as well.

Moreover, the help texts and descriptions are (hopefully) simplified.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.43%. Comparing base (a3af732) to head (67306db).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #854      +/-   ##
==========================================
- Coverage   84.52%   84.43%   -0.09%     
==========================================
  Files          11       11              
  Lines        3366     3379      +13     
==========================================
+ Hits         2845     2853       +8     
- Misses        521      526       +5     

Files with missing lines	Coverage Δ
src/west/app/project.py	80.61% <100.00%> (+0.25%)	⬆️

... and 2 files with indirect coverage changes

[mbolivar]

Seems reasonable to me

[pdgendt]

Looks good!

[pdgendt]

@marc-hb I'm not sure if @fouge is very active? I think we can move forward with this?

[marc-hb]

I really want to review this one because I spent a lot of time on #774 and #775 but @thorsten-klein is just submitting way too much code, I can't keep up.

west did not use to be like this, help! :-D

Can you give me a few more days?

[thorsten-klein]

@thorsten-klein is just submitting way too much code, I can't keep up.

Sorry 🤞

Can you give me a few more days?

Yes, sure 👍🏻 Thank you in advance for your time and input!

[carlescufi]

@thorsten-klein is just submitting way too much code, I can't keep up.

Seconded, and I'll take this opportunity to thank you for all your contributions @thorsten-klein.

[carlescufi]

Even though I'd prefer —topdir was only compatible with -l, this is not a blocking issue for me. Thanks!

[pdgendt]

Let's wait for feedback from @marc-hb, as he requested some more time.

[marc-hb]

This is particularly useful when using --local

I downloaded this PR and tested the other, --manifest-url option and it does not seem to work for me. I ran out of time and did not try --local yet. I didn't look at the code either.

Describing directory nesting clearly and accurately is not easy - it is basically a "specification" except it has to be user-friendly too. So I will look at the code only when that "specification" is complete and unambiguous.

This help looks like the two last ones can be both used at the same time:

west init [-m URL] [--mr REVISION] [--mf FILE] [-o=GIT_CLONE_OPTION] [-t WORKSPACE_DIR] [directory]

But it's not actually possible:

FATAL ERROR: --topdir cannot be combined with positional argument [directory]

When using either separately, each one seems to have the same effect. So, there does not seem to be any new feature in the remote case, which means it's still not possible to west init a manifest two levels down or more in the remote case? Is this an oversight? The help does not seem to say. I don't see why --local would be more flexible than --manifest-url. I would hope the --manifest-url and --local options work the same immediately after the git clone operation.

[marc-hb]

This is particularly useful when using --local

I downloaded this PR and tested the other, --manifest-url option and it does not seem to work for me. I ran out of time and did not try --local yet. I didn't look at the code either.

Describing directory nesting clearly and accurately is not easy - it is basically a "specification" except it has to be user-friendly too. So I will look at the code only when that "specification" is complete and unambiguous (EDIT and of course: working for me).

This help looks like the two last ones can be both used at the same time:

west init [-m URL] [--mr REVISION] [--mf FILE] [-o=GIT_CLONE_OPTION] [-t WORKSPACE_DIR] [directory]

But it's not actually possible:

FATAL ERROR: --topdir cannot be combined with positional argument [directory]

When using either separately, each one seems to have the same effect. So, there does not seem to be any new feature in the remote case, which means it's still not possible to west init a manifest two levels down or more in the remote case? Is this an oversight? The help does not seem to say. I don't see why --local would be more flexible than --manifest-url. I would hope the --manifest-url and --local options work the same immediately after the git clone operation.

[thorsten-klein]

Thank you for the review 🙏

When using either separately, each one seems to have the same effect. So, there does not seem to be any new feature in the remote case, which means it's still not possible to west init a manifest two levels down or more in the remote case? Is this an oversight? The help does not seem to say. I don't see why --local would be more flexible than --manifest-url. I would hope the --manifest-url and --local options work the same immediately after the git clone operation.

Yes, exactly. --topdir and positional argument directory do exactly the same in remote case.
I have proposed to get rid of this positional argument at all, but it will not be accepted for now because it is a breaking change (what I fully understand).

Nevertheless, in remote case those arguments that do the same are mutually exclusive (see error message you got).
I have applied your suggested change, which totally make sense to point out in the help that they both cannot be combined ([--topdir DIR | directory]) 👍🏻

it's still not possible to west init a manifest two levels down or more in the remote case?

This has already worked before in remote case, since the positional argument [directory] already exists and it does exactly the same as --topdir (see above). The main value in this change lays in the local case (and is the pre-work to potentially remove the positional argument [directory] in future)

Thank you 👍🏻

[thorsten-klein]

I think I have resolved all review comments in the code👍🏻

[marc-hb]

it's still not possible to west init a manifest two levels down or more in the remote case?

This has already worked before in remote case, ...

Has it? Please share one example of a west init --manifest-url ... command that can produce this:

workspace
├── extra
│   └── level
│       └── manifest_clone
│           └── .git
└── .west

[thorsten-klein]

it's still not possible to west init a manifest two levels down

Yes, you are right. I will push my changes where I have added support for this and also some test.