[CI-NO-BUILD] [build] Introduce menu wrapper for build operations

[benyamin-codez]

1. Menuing system providing:
   a) Management of environment variables:
   EWDK11_DIR
   EWDK11_24H2_DIR
   VIRTIO_WIN_NO_ARM
   _BUILD_DISABLE_SDV
   VIRTIO_WIN_SDV_2022
   SKIP_SDV_ACTUAL
   CODEQL_OFFLINE_ONLY
   CODEQL_RUN_BLIND
   b) Launcher for build environments:
   UNINITIALIZED (dynamic)
   Cobalt EWDK
   Germanium EWDK
   c) Build launcher with options for targets, platforms (archs), analysis builds and environments
   d) Syntactically correct buildAll.bat parameter hints
   e) Launcher for signer (VirtIO Test Cert)
   f) Launcher for cleaners (includes quiet and debug options)

2. Launcher for Windows 11 to ensure the script runs in conhost.

[benyamin-codez]

A pretty pic:

[YanVugenfirer]

@benyamin-codez Thanks! Looks cool!

I have two comments:

1. Let's choose a name that is more user-facing :) Something like "build_menu.bat" or even menuconfig.bat
2. Can we improve the convoluted menus with some "functions" to improve readability? (not must)

[YanVugenfirer]

I also suggest not to use the exact name for the "last" EWDK used for the build. It will change at some point.
Then, instead of changing paths in one place, we will have to search and replace in many places in the projects.

[benyamin-codez]

@YanVugenfirer

Thanks for the feedback..!

Let's choose a name that is more user-facing :) Something like "build_menu.bat" or even menuconfig.bat

Whatever do you mean...?!? 8^D
I think build_menu.bat and build_menu_win11.cmd would suit well.

This raises the issue of the two titles. Presently they are:

• Rapid Prototyping Build Wrapper for the window title; and
• Rapid Prototyping Build Wrapper - for Windows KVM Guest Drivers for the menu heading.

Perhaps just replace the words Rapid Prototyping Build Wrapper with...
... Build Script Menu Wrapper...
... or even just Build Script Menu...?

Please advise.

Can we improve the convoluted menus with some "functions" to improve readability? (not must)

Can you point me towards which part(s) you are finding convoluted? ( Please don't say the whole thing...!! 8^d )
Can you provide an example of how a function might help?
Do you mean like pop-up dialogue boxes that contain more info?
There's quite a lot of information to fit in ~80 columns x ~62 (max for 1080p) lines...
I had considered a wider format, but it becomes difficult to write...
...especially when printing colour over one line with more than 4 parts.
I had considered a multi-page menuing system but was trying to retain at least a little bit of KISS...

I also suggest not to use the exact name for the "last" EWDK used for the build. It will change at some point.
Then, instead of changing paths in one place, we will have to search and replace in many places in the projects.

I considered this at great length and tried various other labels.
The problem I found is that it became very ambiguous, e.g. what exactly does "latest" mean?

There were three factors that ultimately led me to use the named EWDKs.
First, the build environment is explicitly set per the wiki.
Second, was my impression of what a novice builder might find helpful and easiest to navigate.
It was my impression that this would be largely informed by the wiki.
That is, provided this wrapper and the wiki are in agreement, a novice would have confidence to continue.
Finally, we use the environment variables EWDK11_DIR and EWDK11_24H2_DIR...
...the latter being a direct reference to Germanium, i.e. 24H2.
These variables would most likely also need to be updated upon moving to a new EWDK, e.g. EWDK11_25Hx_DIR.

So the files needing updates would be this wrapper, build\SetVsEnv.bat and the wiki.
At least these are all "build" related, and would/should be considered together.
There may also be some driver-specific changes needed per any upgrade to a new EWDK.

If PR #1212 was to merge (which I'm very much hoping it will),...
...there most likely would also be some required changes to build\build.bat.
These changes would likely relate to WHCP and EWDK-specific CodeQL suites and packages.
PR #1212 more tightly binds the build scripting to the environment described in the wiki...
...and replaces wiki content by automating environment preparation of CodeQL.
So changes to the environment, e.g. the EWDK version, should be reflected in the wiki...
...and thus also build\build.bat, build\SetVsEnv.bat and this wrapper.

Given the above, I'm minded to leave this part of the wrapper as-is, but remain open to specific suggestions.

FWIW, here are a couple of pics showing changes I'm about to add to PR #1212 as a result of the PR #1210 review:

You will observe that the Win10 EWDK (legacy) references are very specific...
...but I have left the Win11 reference quite generic.

Best regards,
Ben

[benyamin-codez]

Renamed.

[kostyanf14]

@benyamin-codez

In general, I agree with this tool but all our usage is a CI or other automation tools. We can review and merge this menu tool but it will not be maintained. Do you agree to support this in the future, update the menu for any new MS requirements like build tools, code analysis tools, etc?

[benyamin-codez]

@kostyanf14

In general, I agree with this tool but all our usage is a CI or other automation tools.

That's certainly appropriate for your workflows, especially those geared towards WHCP requirements. I would say this tool is more suited to the workflows of bespoke and externally contributing developers and that of the casual or novice builder.

It exposes all of the current build options and displays hints for buildAll.bat parameters so the casual or novice builder can easily choose the desired options and [B]uild the whole repo, or alternatively open an environment and build for a particular driver using the hinted parameters. This is a great advantage for anyone who isn't familiar with the build syntax and limitations. Running up the wrapper and toggling the various options will soon show what I mean, e.g. try doing a Win10_SDV build or choose Win10 and Win11 and see that you are also enabling Win10_SDV and Win11_SDV. The rules around building for different architectures/platforms are similarly implemented.

For developers, multiple environments are exposed to facilitate refactoring the source for compilation in more recent EWDKs and various code analysis options have been made available, both established and new. This allows for rapid prototyping without requiring a Visual Studio IDE or the developer to repeatedly issue CLI commands.

We can review and merge this menu tool but it will not be maintained. Do you agree to support this in the future, update the menu for any new MS requirements like build tools, code analysis tools, etc?

To avoid any furtherance of doubt, my submission is provided on an entirely as-is basis without any warranty or guarantee whatsoever and according to the terms of the LICENSE at the time it was submitted. Furthermore, the terms of said LICENSE and the explicit and implied disclaimers, bars and indemnities expressed therein, shall extend severally and collectively also to my agents, representatives, heirs or substitutes, successors, and assigns.

Having said that, I'll most likely assist with maintaining it, especially if I keep dropping PRs here. 8^d

Anyone can, of course, submit a PR for any necessary or desired changes, including to the wrapper.
I do expect there will be some "by design" responses to raised issues, and when SDV leaves for good with Win10 and Server2016/2019/2022, there will likely be a consolidation of the various code analysis components and the deletion of the _BUILD_DISABLE_SDV and SKIP_SDV_ACTUAL (if PR #1212 or its derivatives are merged) environment variables.

I expect updates to this tool will track changes to the build environment and the wiki. As mentioned above, coincident changes to the build environment would notably be in build\build.bat and build\SetVsEnv.bat. It is noteworthy, that whilst the reverse is true, the build environment is in no way functionally dependent on this wrapper.

[benyamin-codez]

@kostyanf14

Should I add CI-NO-BUILD to this one...?

[YanVugenfirer]

@kostyanf14

Should I add CI-NO-BUILD to this one...?

Yes, please

[kostyanf14]

@benyamin-codez

Should I add CI-NO-BUILD to this one...?

Yes

[YanVugenfirer]

@kostyanf14

In general, I agree with this tool but all our usage is a CI or other automation tools.

That's certainly appropriate for your workflows, especially those geared towards WHCP requirements. I would say this tool is more suited to the workflows of bespoke and externally contributing developers and that of the casual or novice builder.

It exposes all of the current build options and displays hints for buildAll.bat parameters so the casual or novice builder can easily choose the desired options and [B]uild the whole repo, or alternatively open an environment and build for a particular driver using the hinted parameters. This is a great advantage for anyone who isn't familiar with the build syntax and limitations. Running up the wrapper and toggling the various options will soon show what I mean, e.g. try doing a Win10_SDV build or choose Win10 and Win11 and see that you are also enabling Win10_SDV and Win11_SDV. The rules around building for different architectures/platforms are similarly implemented.

I'm afraid I have to disagree with the above statement on the deep philosophical level :)

Here is how the development flow works:

1. You work in the VS on the platform that is interesting to you (let's say x64 Win11 or Win10 ARM64). While you actively develop, you build only for this specific platform.
2. Then, I want you to test that compilation passes on EVERYTHING. And I don't want to provide an easy method to avoid it :)

For developers, multiple environments are exposed to facilitate refactoring the source for compilation in more recent EWDKs and various code analysis options have been made available, both established and new. This allows for rapid prototyping without requiring a Visual Studio IDE or the developer to repeatedly issue CLI commands.

Again, very similar way of thinking here. In most cases, we want to support two eWDK environments. Maybe 3 (in a separate branch) when there is a vNext Windows versions. We specifically avoid compiling each Windows version with own eWDK. We don't want to have 5 packages for Windows 10 and 3 packages for Windows 11 (for now, and more going forward). We want to (as long as it will be possible), to have one package for Windows 10, one package for Windows 11.
That's why I also suggest not to name eWDKs. BTW: even if we name them, please don't use MS code names. We never did, it adds additional confusion. Please use build numbers or MS designated convention like Win11 24H2.

We can review and merge this menu tool but it will not be maintained. Do you agree to support this in the future, update the menu for any new MS requirements like build tools, code analysis tools, etc?

To avoid any furtherance of doubt, my submission is provided on an entirely as-is basis without any warranty or guarantee whatsoever and according to the terms of the LICENSE at the time it was submitted. Furthermore, the terms of said LICENSE and the explicit and implied disclaimers, bars and indemnities expressed therein, shall extend severally and collectively also to my agents, representatives, heirs or substitutes, successors, and assigns.

Having said that, I'll most likely assist with maintaining it, especially if I keep dropping PRs here. 8^d

Anyone can, of course, submit a PR for any necessary or desired changes, including to the wrapper. I do expect there will be some "by design" responses to raised issues, and when SDV leaves for good with Win10 and Server2016/2019/2022, there will likely be a consolidation of the various code analysis components and the deletion of the _BUILD_DISABLE_SDV and SKIP_SDV_ACTUAL (if PR #1212 or its derivatives are merged) environment variables.

That's an important part, otherwise this script will become unusable very fast. Again - our workflow is different. We already have all the platforms set in the VS.

I expect updates to this tool will track changes to the build environment and the wiki. As mentioned above, coincident changes to the build environment would notably be in build\build.bat and build\SetVsEnv.bat. It is noteworthy, that whilst the reverse is true, the build environment is in no way functionally dependent on this wrapper.

[benyamin-codez]

@YanVugenfirer

Thanks for the further feedback...!

That's certainly appropriate for your workflows, especially those geared towards WHCP requirements. I would say this tool is more suited to the workflows of bespoke and externally contributing developers and that of the casual or novice builder.

It exposes all of the current build options and displays hints for buildAll.bat parameters so the casual or novice builder can easily choose the desired options and [B]uild the whole repo, or alternatively open an environment and build for a particular driver using the hinted parameters. This is a great advantage for anyone who isn't familiar with the build syntax and limitations. Running up the wrapper and toggling the various options will soon show what I mean, e.g. try doing a Win10_SDV build or choose Win10 and Win11 and see that you are also enabling Win10_SDV and Win11_SDV. The rules around building for different architectures/platforms are similarly implemented.

I'm afraid I have to disagree with the above statement on the deep philosophical level :)

Here is how the development flow works:

1. You work in the VS on the platform that is interesting to you (let's say x64 Win11 or Win10 ARM64). While you actively develop, you build only for this specific platform.
2. Then, I want you to test that compilation passes on EVERYTHING. And I don't want to provide an easy method to avoid it :)

I'm not sure how we disagree... 8^d
That's how I do it - except not in VS - if I can help it - maybe that's the "deep philosophical level" disagreement..? 8^D
Perhaps all I can say is "different strokes for different folks" and "there are many paths to the same goal"...
I think we are actually on the same page...??

By way of explanation, note my emphasis above, i.e. re "...so the casual or novice builder...". The point I was raising here, might be best served by an example of a novice builder wanting the latest vioscsi driver for their particular platform and target of interest. Perhaps they have no concern whatsoever for any other driver and certainly no concern for the WHCP process. They're not cutting code for PRs and just want the binaries for their particular needs. The point I was trying to make here is that after choosing their desired options they can use the buildAll.bat hint when building in an environment prepared by the options they have chosen, e.g. VIRTIO_WIN_NO_ARM and preferred EWDK location.

Regarding your point:

And I don't want to provide an easy method to avoid it :)

I note that the build script I propose in #1212 will clearly show warnings and errors at the end of the build if one builds without SDV options. If skipping targets or architectures is also a concern, I could add warnings for this too (targets partially done already via DVL outcome logging)... I do note however, that most of these build options already exist, and there's nothing to stop developers employing them to skip elements and then rely on the checks when submitting PRs. I guess this wrapper does - by design - make it easier for devs to do that. For this reason, I'm happy to add those warnings and I could also add a summary warning about whether the build is suitably configured to produce artefacts for WHCP submission, if you think that would be helpful.

For developers, multiple environments are exposed to facilitate refactoring the source for compilation in more recent EWDKs and various code analysis options have been made available, both established and new. This allows for rapid prototyping without requiring a Visual Studio IDE or the developer to repeatedly issue CLI commands.

Again, very similar way of thinking here. In most cases, we want to support two eWDK environments. Maybe 3 (in a separate branch) when there is a vNext Windows versions. We specifically avoid compiling each Windows version with own eWDK. We don't want to have 5 packages for Windows 10 and 3 packages for Windows 11 (for now, and more going forward). We want to (as long as it will be possible), to have one package for Windows 10, one package for Windows 11.

Again, I'm not sure how we disagree. I'm not proposing to have additional packages.

In the wrapper, we recommend [A] Dynamic environment by build script... which picks the EWDK dynamically, depending on the target. This is the current behaviour, which I'm not proposing to change. All I was saying here was if you had a driver you know works with Cobalt EWDK, you can test it with Germanium EWDK to see what compilation errors you might need to address. These alternate environments aren't meant to be used to build out drivers for WHCP submission, but rather to develop drivers and test them for compilation compatibility with the next EWDK release. This is not necessarily to develop a driver for a vNext Windows version; it could be just to move to a new EWDK. Once proven, the driver would then be built as normal using the dynamic build environment prior to submission, so only one package per target, as you are expecting.

That's why I also suggest not to name eWDKs. BTW: even if we name them, please don't use MS code names. We never did, it adds additional confusion. Please use build numbers or MS designated convention like Win11 24H2.

The MS codenames here are actually MS internal development codenames that track with the semester-based engineering milestones. These milestones are NOT necessarily equivalent to the Windows version. Some examples of this would include Titanium EWDK which is semester 19H1 but is for Windows version 1903, or Nickel EWDK which is semester 22H2 but covers Windows versions 22H2 and 22H3. So these development codenames track one-to-one with the relevant development semester and NOT the Windows version. I think it is important to not confuse development semesters with Windows versions and an effective way of doing this is to use the development codename instead of the semester. This is one reason MS use them internally.

Furthermore, the Build Lab determines the maximum available NTDDI_VERSION or ABRACADABRA value for that EWDK. The development code names also now track well with the Build Lab names (less the Release and Build tags), e.g. following the Titanium (19H1) EWDK, MS uses the two letter codes from the periodic table of elements, e.g. Germanium is ge_release_svc_prod3.[build].[rev], where "ge" refers to Germanium and this maps to the *.iso filename very tightly, e.g. EWDK_ge_release_svc_prod3_[build]_[builddate-time].iso.

I also avoided using build numbers because, again, these relate more to Windows versions than development semesters.

Given the above explanations, how do you think we should proceed?

That's an important part, otherwise this script will become unusable very fast. Again - our workflow is different. We already have all the platforms set in the VS.

Please accept my apologies - I'm unsure as to what "important part" you are referring to here... 8^d

If I presume you mean maintaining this wrapper script, I can only undertake to use my best endeavours to do so under the aforementioned provisos. I hope and trust this would be sufficient.

I also previously raised the following:

... raises the issue of the two titles. Presently they are:

• Rapid Prototyping Build Wrapper for the window title; and
• Rapid Prototyping Build Wrapper - for Windows KVM Guest Drivers for the menu heading.

Perhaps just replace the words Rapid Prototyping Build Wrapper with...
... Build Script Menu Wrapper...
... or even just Build Script Menu...?

Please advise.

Happy to leave it otherwise... 8^d

Let me know what you think about this and the above and we can go from there.

Best regards,
Ben