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

Reorganize platform build instructions

Author: ricab

BUILD.linux.md

@@ -0,0 +1,84 @@
+# Build instructions for Linux
+
+## Environment Setup
+
+### Build dependencies
+
+```
+cd <multipass>
+sudo apt install devscripts equivs
+mk-build-deps -s sudo -i
+```
+
+## Building
+
+First, go into the repository root and get all the submodules:
+
+```
+cd <multipass>
+git submodule update --init --recursive
+```
+
+If building on arm, s390x, ppc64le, or riscv, you will need to set the `VCPKG_FORCE_SYSTEM_BINARIES`  environment
+variable:
+
+```
+export VCPKG_FORCE_SYSTEM_BINARIES=1
+```
+
+Then create a build directory and run CMake.
+
+```
+mkdir build
+cd build
+cmake ../
+```
+
+This will fetch all necessary content, build vcpkg dependencies, and initialize the build system. You can also specify
+the `-DCMAKE_BUILD_TYPE` option to set the build type (e.g., `Debug`, `Release`, `Coverage`, etc.).
+
+Finally, to build the project, run:
+
+```
+cmake --build . --parallel
+```
+
+Please note that if you're working on a forked repository that you created using the "Copy the main branch only" option,
+the repository will not include the necessary git tags to determine the Multipass version during CMake configuration. In
+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.
+
+## Run the Multipass daemon and client
+
+First, install Multipass's runtime dependencies. On AMD64 architecture, you can do this with:
+
+```
+sudo apt update
+sudo apt install libgl1 libpng16-16 libqt6core6 libqt6gui6 \
+    libqt6network6 libqt6widgets6 libxml2 libvirt0 dnsmasq-base \
+    dnsmasq-utils qemu-system-x86 qemu-utils libslang2 iproute2 \
+    iptables iputils-ping libatm1 libxtables12 xterm
+```
+
+Then run the Multipass daemon:
+
+```
+sudo <multipass>/build/bin/multipassd &
+```
+
+Copy the desktop file that Multipass clients expect to find in your home:
+
+```
+mkdir -p ~/.local/share/multipass/
+cp <multipass>/data/multipass.gui.autostart.desktop ~/.local/share/multipass/
+```
+
+Optionally, enable auto-complete in Bash:
+
+```
+source <multipass>/completions/bash/multipass
+```
+
+Now you can use the `multipass` command from your terminal (for example
+`<multipass>/build/bin/multipass launch --name foo`) or launch the GUI client with the command
+`<multipass>/build/bin/multipass.gui`.

BUILD.osx.md renamed to BUILD.macOS.md

@@ -3,37 +3,48 @@ Build instructions for Mac OS
 
 Environment Setup
 -----------------
+
 ### XCode
-Can be installed via the App Store. Once this is done, you may need to install the command line tooling too, to do this run:
+
+Can be installed via the App Store. Once this is done, you may need to install the command line tooling too, to do this
+run:
 
     xcode-select --install
 
-Ensure you have development Frameworks for at least OS X 10.8 installed, with the typical compiler toolchain and "git". Avoid the version of cmake supplied, we need a newer one (see later).
+Ensure you have development Frameworks for at least OS X 10.8 installed, with the typical compiler toolchain and "git".
+Avoid the version of cmake supplied, we need a newer one (see later).
 
 ### Qt6
+
 #### Option 1: Using Qt official sources
+
 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
 
 Adjust accordingly if you customized the Qt install directory.
 
-#### Option 2: Using Homebrew
+#### Option 2: Using Homebrew
+
 Install Qt6:
 
     brew install qt6
 
 ### Cmake/OpenSSL
-Building a Multipass package requires cmake 3.9 or greater. OpenSSL is also necessary at build time. The most convenient means to obtain these dependencies is with Homebrew <https://brew.sh/>.
+
+Building a Multipass package requires cmake 3.9 or greater. OpenSSL is also necessary at build time. The most convenient
+means to obtain these dependencies is with Homebrew <https://brew.sh/>.
 
     brew install cmake openssl@3
 
 Building
 ---------------------------------------
+
     cd <multipass>
     git submodule update --init --recursive
 
@@ -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
+similar location; `/opt/homebrew/Cellar/openssl@3`, which can be set in the project level `CMakeLists.txt` file.
 
     cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qt6
 
@@ -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
 ---------------------
-QtCreator will be missing all the environment adjustments made above. To get cmake to successfully configure, open the project and adjust the Build Environment (click the "Projects" icon of the left pane, scroll down). Then add the entries to the $PATH as above, and add the variables reported by `opem config env`. CMake should now succeed, and QtCreator allow you to edit the project files.
+QtCreator will be missing all the environment adjustments made above. To get cmake to successfully configure, open the
+project and adjust the Build Environment (click the "Projects" icon of the left pane, scroll down). Then add the entries
+to the $PATH as above, and add the variables reported by `opem config env`. CMake should now succeed, and QtCreator
+allow you to edit the project files.
 
 
 Creating a Package

BUILD.windows.md

@@ -3,43 +3,54 @@ Build instructions for Windows 10
 
 Environment Setup
 -----------------
+
 ### Chocolatey
+
 Install chocolatey, a package manager, to download the rest of the dependencies: <https://chocolatey.org/>
 
-Press Windows Key+X and Run Windows PowerShell(Admin) then follow the chocolatey instructions to "Install with Powershell.exe"
+Press Windows Key+X and Run Windows PowerShell(Admin) then follow the chocolatey instructions to "Install with
+Powershell.exe"
 
 After chocolatey is installed you can now install the rest of the dependencies:
 
     choco install visualstudio2019buildtools visualstudio2019-workload-vctools cmake ninja cmder qemu-img openssl -yfd
 
-You may have to disable Windows Defender Real-time protection if you want the packages to install quicker.
-Search for Windows Defender Security Center, go to Virus & threat protection, then Virus and thread protection settings, disable Real-time protection.
+You may have to disable Windows Defender Real-time protection if you want the packages to install quicker. Search for
+Windows Defender Security Center, go to Virus & threat protection, then Virus and thread protection settings, disable
+Real-time protection.
 
-NOTE: visualcpp-build-tools is only the installer package. For this reason, choco cannot detect any new compiler tool updates so choco upgrade
-will report no new updates available. To update the compiler and related tooling, you will need to search for "Add or remove programs",
-find "Microsoft Visual Studio Installer" and click "Modify".
+NOTE: visualcpp-build-tools is only the installer package. For this reason, choco cannot detect any new compiler tool
+updates so choco upgrade will report no new updates available. To update the compiler and related tooling, you will need
+to search for "Add or remove programs", find "Microsoft Visual Studio Installer" and click "Modify".
 
 ### Git
-You need to enable symlinks in Windows Git, have a look at [the git-for-windows docs](https://github.com/git-for-windows/git/wiki/Symbolic-Links).
+
+You need to enable symlinks in Windows Git, have a look at
+[the git-for-windows docs](https://github.com/git-for-windows/git/wiki/Symbolic-Links).
 
 ### Qt6
+
 Install the latest stable version of Qt6 (6.2.4 at the moment): <https://www.qt.io/download-thank-you?os=windows/>.
 
 In the online installer, under Qt, select MSVC 2019 64-bit.
 
 If you already have Qt installed, run the MaintenanceTool included in the Qt directory to update to the latest version.
 
-Alternatively, download the [qtbase archive](https://download.qt.io/online/qtsdkrepository/windows_x86/desktop/qt6_624/qt.qt6.624.win64_msvc2019_64/6.2.4-0-202203140926qtbase-Windows-Windows_10_21H2-MSVC2019-Windows-Windows_10_21H2-X86_64.7z) and extract it to `C:\Qt` (so it ends up in `C:\Qt\6.2.4`).
+Alternatively, download the
+[qtbase archive](https://download.qt.io/online/qtsdkrepository/windows_x86/desktop/qt6_624/qt.qt6.624.win64_msvc2019_64/6.2.4-0-202203140926qtbase-Windows-Windows_10_21H2-MSVC2019-Windows-Windows_10_21H2-X86_64.7z)
+and extract it to `C:\Qt` (so it ends up in `C:\Qt\6.2.4`).
 
 ### Path setup
+
 You'll have to manually add CMake and Qt to your account's PATH variable.
 
-Search for "Edit environment variables for your account" then edit your Path variable.
-Add the following:
-     `C:\Program Files\CMake\bin`
-     `C:\Qt\6.2.4\msvc2019_64\bin`
+Search for "Edit environment variables for your account" then edit your Path variable. Add the following:
+
+- `C:\Program Files\CMake\bin`
+- `C:\Qt\6.2.4\msvc2019_64\bin`
 
 ### Cmder setup
+
 Cmder is a sane terminal emulator for windows, which includes git and SSH support among other things.
 
 The following will setup a task that you can use to build things with the VS2019 compiler toolchain.
@@ -48,10 +59,10 @@ Run cmder which should be installed by default on C:\tools\cmder\Cmder.exe
 Click on the green "+" sign on the right lower corner of cmder
 Select "Setup tasks..."
 Click the "+" button to add a new task
-In the  task parameters box add (basically copying from cmd:Cmder task):
-    ``/icon "%CMDER_ROOT%\icons\cmder.ico"``
+In the task parameters box add (basically copying from cmd:Cmder task):
+``/icon "%CMDER_ROOT%\icons\cmder.ico"``
 In the commands box, add:
-    ``cmd /k ""%ConEmuDir%\..\init.bat" && "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64" -new_console:d:%USERPROFILE%``
+``cmd /k ""%ConEmuDir%\..\init.bat" && "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64" -new_console:d:%USERPROFILE%``
 
 Give the task a name (first box), such as vs2019 and click Save Settings.
 
@@ -94,24 +105,28 @@ Running multipass
 ---------------------------------------
 
 ### Enable Hyper-V
+
 Before starting multipassd, you'll have to enable the Hyper-V functionality in Windows 10 Pro.
 See: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
 
     Press Windows Key + X, Select Windows PowerShell (Admin)
     Run "Enable-WindowsOptionalFeature -Online -FeatureName:Microsoft-Hyper-V -All"
 
 ### Start the daemon (multipassd)
+
     Press Windows Key + X, Select Windows PowerShell (Admin)
     Run multipassd (for example: multipassd --logger=stderr)
     Alternatively, you can install multipassd as a Windows Service (Run "multipassd /install")
     To stop and uninstall the Windows service, Run "multipassd /uninstall"
 
 ### Run multipass
+
     With the multipassd daemon now running on another shell (or as a windows service) you can now run multipass.
     Press Windows Key + X, Select Windows PowerShell, or alternatively run cmd.exe on the search bar
     Try "multipass help"
 
 ### Permissions/privileges for multipassd
+
 multipassd needs Administrator privileges in order to create symlinks when using mounts and to manage Hyper-V instances.
 
 If you don't need symlink support you can run multipassd on a less privileged shell but your user account