Reorganize platform build instructions #4110

ricab · 2025-05-23T16:13:03Z

Fix #4078. See commit descriptions for more information.

MULTI-1953

ricab · 2025-05-23T16:15:51Z

Note for reviewers: you can preview the readme on GH by going to https://github.com/canonical/multipass/tree/platform-build-instructions?tab=readme-ov-file#contributing and you can click on the individual build files for their own renderings.

Copilot

Pull Request Overview

This PR refactors and clarifies the project’s build instructions by moving platform-specific steps into dedicated documents and reflowing the README.

Reformats README introduction, project status table, and usage pointers
Introduces separate BUILD.linux.md, BUILD.macOS.md, and BUILD.windows.md for platform-specific build steps
Updates Windows and macOS build guides with improved wrapping and notes

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
README.md	Reflowed intro text, reformatted table, and updated build section to reference platform docs
BUILD.windows.md	Wrapped long lines, clarified Chocolatey and Defender steps, and reorganized dependency install
BUILD.macOS.md	Wrapped sections, separated Qt install options, and clarified Homebrew/CMake steps
BUILD.linux.md	Added a new Linux build guide with Environment Setup, build, and run instructions

Comments suppressed due to low confidence (3)

BUILD.windows.md:11

The executable name casing is incorrect. It should be PowerShell.exe (capital ‘S’).

Press Windows Key+X and Run Windows PowerShell(Admin) then follow the chocolatey instructions to "Install with Powershell.exe"

BUILD.windows.md:19

There's a typo: "thread protection settings" should be "threat protection settings".

Windows Defender Security Center, go to Virus & threat protection, then Virus and thread protection settings, disable Real-time protection.

BUILD.macOS.md:76

The command opem config env appears to be a typo or unclear; please confirm and correct the intended command.

Then add the entries to the $PATH as above, and add the variables reported by `opem config env`.

codecov · 2025-05-23T16:44:09Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.31%. Comparing base (e58ebff) to head (35f7e43).
Report is 19 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4110   +/-   ##
=======================================
  Coverage   89.31%   89.31%           
=======================================
  Files         259      259           
  Lines       15715    15715           
=======================================
  Hits        14036    14036           
  Misses       1679     1679

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

sharder996

Just some small updates to the build instructions. Let me know how important you think they are.

BUILD.linux.md

sharder996 · 2025-05-24T15:43:07Z

BUILD.osx.md

 Install the latest stable version of Qt6 LTS (6.2.4 at the moment): <http://www.qt.io/download-open-source/>.

-If it tells you that XCode 5.0.0 needs to be installed, go to XCode > Preferences > Locations and make a selection in the _Command Line Tools_ box.
+If it tells you that XCode 5.0.0 needs to be installed, go to XCode > Preferences > Locations and make a selection in
+the _Command Line Tools_ box.

 Add Qt6 to your PATH environment variable, adding to your `.bash_profile` file the following line:

    export PATH=$PATH:~/Qt/6.2.4/clang_64/bin


This might be different based on architecture. On my ARM Mac, it's at ~/Qt/6.2.4/macos/bin

sharder996 · 2025-05-24T15:45:15Z

BUILD.osx.md

@@ -45,7 +56,8 @@ Alternatively if using Qt6 from Homebrew, do

    cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=/usr/local/opt/qt6


I think this should be symmetrical with the previous statement on setting Qt environment variables.

sharder996 · 2025-05-24T15:46:06Z

BUILD.osx.md

@@ -45,7 +56,8 @@ Alternatively if using Qt6 from Homebrew, do

    cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=/usr/local/opt/qt6

-or, if on Apple silicon, brew will store the Qt binaries in a different location. Additionally, OpenSSL will be in a similar location; `/opt/homebrew/Cellar/openssl@3`, which can be set in the project level `CMakeLists.txt` file.
+or, if on Apple silicon, brew will store the Qt binaries in a different location. Additionally, OpenSSL will be in a


Can remove mentions of installing Qt via brew, since brew does not carry the correct version.

sharder996 · 2025-05-24T15:47:00Z

BUILD.osx.md

@@ -54,11 +66,15 @@ Then start the build with:
    cd build/
    ninja

-Take care to adjust the `CMAKE_PREFIX_PATH` to the location you installed Qt above, or else cmake will complain about missing Qt6.
+Take care to adjust the `CMAKE_PREFIX_PATH` to the location you installed Qt above, or else cmake will complain about
+missing Qt6.

 Building in QtCreator


Do we want to "maintain" building Multipass in QtCreator?

sharder996 · 2025-05-24T15:48:59Z

BUILD.windows.md


 ### Qt6
+
 Install the latest stable version of Qt6 (6.2.4 at the moment): <https://www.qt.io/download-thank-you?os=windows/>.


6.2.4 is no longer the "latest" stable version.

IMO, we can just get rid of the version information, unless we want to pin QT to a specific stable version.

Either that or "latest stable version". But this is kind of outside scope here, I just want to have all platforms linked from the Readme... I'll open an issue for improvements specifically.

6.2.4 is a specific version that we align with. It's just that there newer LTS versions, so it's not exactly the "latest" anymore.

sharder996 · 2025-05-24T15:50:18Z

BUILD.windows.md

@@ -94,24 +105,28 @@ Running multipass
 ---------------------------------------

 ### Enable Hyper-V


Not strictly required 🤷

README.md

ricab · 2025-05-26T11:16:54Z

Hey @sharder996, I agree the instructions need fixing in a bunch of places, but that was not the intention of this PR. I guess the title is confusing, I'll update it.

This was only meant to fix #4078 (to complete the merger essentially). Apart from that, I just reformatted the markdown (to be consistent with the new file) and renamed a file.

sharder996

Approving based on the assumption that currently outlined issues in the build instructions will be fixed in a later PR.

ricab · 2025-05-26T16:35:09Z

Approving based on the assumption that currently outlined issues in the build instructions will be fixed in a later PR.

For full disclosure, I am not planning to give that huge priority myself

xmkg · 2025-05-28T07:41:01Z

BUILD.linux.md

+this case, you need to manually fetch the tags from the upstream by running
+`git fetch --tags https://github.com/canonical/multipass.git` in the `<multipass>` source code directory.
+
+### Automatic linker selection


FWIW, this applies to all platforms, not just Linux.

Good catch!

Alright, I moved this section to the central readme and adjusted a little. Let me know what you think.

xmkg

LGTM, except ### Automatic linker selection

Reorganize build instructions, to consistently cover all platforms that are now targeted by the single repository. To that end, link to platform-specific build instructions for each platform from the root README.md, extracting Linux instructions into its own file.

ricab · 2025-05-28T18:12:27Z

:/

@sharder996, sorry if I sounded dismissive. I understand and share your concerns regarding the contents of these build files, it's just that I would rather not get attached to fixing them myself at this point. Doing so properly requires verifying in clean environments and needs a little bit of time (note that the only reason that stuff figures in this PR at all is that I hit Ctrl+Alt+L in CLion to reformat, then tweaked a few newlines). I am perfectly open to scheduling this for an upcoming pulse though.

sharder996 · 2025-05-28T19:03:47Z

@ricab Yup, no problem. I was thinking the same thing when reviewing and it was just an opportunity to note all the problems with the instructions. 😄

xmkg

LGTM.

Reorganize platform build instructions

ricab requested a review from Copilot May 23, 2025 16:15

Copilot AI reviewed May 23, 2025

View reviewed changes

sharder996 requested changes May 24, 2025

View reviewed changes

ricab changed the title ~~Fix platform build instructions~~ Reorganize platform build instructions May 26, 2025

ricab mentioned this pull request May 26, 2025

Revise build instructions #4113

Open

sharder996 previously approved these changes May 26, 2025

View reviewed changes

xmkg reviewed May 28, 2025

View reviewed changes

ricab added 10 commits May 28, 2025 18:19

[docs] Detail Linux build instructions a little

5d97e81

[docs] Reformat Linux build instructions

71d1e58

[docs] Reformat macOS build instructions

9c7d3a5

[docs] rename build-instructions file for macOS

d755c4f

[docs] Reformat Windows build instructions

68acc22

[docs] Reformat readme

44e6855

[docs] Add Coverage build type to Linux examples

c6a19ad

[docs] Move linker section to root readme

113ffce

[docs] Point to policy earlier in README

35f7e43

ricab dismissed sharder996’s stale review via 35f7e43 May 28, 2025 18:02

ricab force-pushed the platform-build-instructions branch from 2392a60 to 35f7e43 Compare May 28, 2025 18:02

xmkg approved these changes May 28, 2025

View reviewed changes

sharder996 approved these changes May 28, 2025

View reviewed changes

sharder996 enabled auto-merge May 28, 2025 19:11

sharder996 added this pull request to the merge queue May 29, 2025

Any commits made after this event will not be merged.

github-merge-queue bot removed this pull request from the merge queue due to failed status checks May 29, 2025

xmkg added this pull request to the merge queue May 29, 2025

Any commits made after this event will not be merged.

github-merge-queue bot pushed a commit that referenced this pull request May 29, 2025

Merge pull request #4110 from canonical/platform-build-instructions

c0aa7c4

Reorganize platform build instructions

github-merge-queue bot removed this pull request from the merge queue due to failed status checks May 30, 2025

sharder996 added this pull request to the merge queue May 30, 2025

Any commits made after this event will not be merged.

		@@ -45,7 +56,8 @@ Alternatively if using Qt6 from Homebrew, do

		cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=/usr/local/opt/qt6


		### Qt6

		Install the latest stable version of Qt6 (6.2.4 at the moment): <https://www.qt.io/download-thank-you?os=windows/>.

		@@ -94,24 +105,28 @@ Running multipass
		---------------------------------------

		### Enable Hyper-V

Reorganize platform build instructions #4110

Reorganize platform build instructions #4110

Conversation

ricab commented May 23, 2025 • edited by sharder996 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ricab commented May 23, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

codecov bot commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sharder996 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ricab commented May 26, 2025

Uh oh!

sharder996 left a comment

Choose a reason for hiding this comment

Uh oh!

ricab commented May 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xmkg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ricab commented May 28, 2025

Uh oh!

sharder996 commented May 28, 2025

Uh oh!

xmkg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ricab commented May 23, 2025 •

edited by sharder996

Loading

codecov bot commented May 23, 2025 •

edited

Loading

xmkg left a comment •

edited

Loading