docs: Create development environment setup instructions (including virtual)

Author: stackotter

Sources/SwiftCrossUI/SwiftCrossUI.docc/Quick start.md

@@ -6,6 +6,8 @@ Creating a cross-platform SwiftCrossUI app with Swift Bundler.
 
 This quick start guide uses [Swift Bundler](https://github.com/stackotter/swift-bundler). Although not strictly required, it simplifies many aspects of cross-platform distribution and provides a platform-agnostic configuration format for specifying things such as app icons and custom URL schemes.
 
+> Note: If you're new to Swift, we recommend starting with <doc:Setting-up-a-development-environment>.
+
 ## Installing Swift Bundler
 
 Follow [the installation instructions in Swift Bundler's readme](https://github.com/stackotter/swift-bundler?tab=readme-ov-file#installation-). `mint` is the preferred installation method on macOS and Linux as of the last update to this quick start guide.

Sources/SwiftCrossUI/SwiftCrossUI.docc/Setting up a development environment.md

@@ -0,0 +1,139 @@
+# Setting up a development environment
+
+Detailed set up instructions for macOS, Linux, and Windows based development environments.
+
+## Overview
+
+Building a cross-platform app requires testing your app in a variety of environments. Setting up development environments can come with many platform-specific challenges. This article attempts to give an overview of the steps involved and touch on the most common pain-points for each platform.
+
+In this article we'll focus on developing SwiftCrossUI apps with Swift Bundler, but much of the information should still apply if you choose to use a different build system.
+
+> Note: This article covers setting up development environments on pre-existing machines. To develop in a virtual machine, first follow <doc:Setting-up-virtual-development-environments> then return to complete the set up process.
+
+## Apple platforms
+
+As you might expect, setting up a development environment for Apple platforms comes with the least challenges; as long as you have a Mac.
+
+This article doesn't cover Apple development from Linux or Windows machines. However, Swift Bundler will likely support cross-compilation in the future. And in the mean time [xtool](https://xtool.sh) is a great option for targeting iOS from Linux and Windows; as long as you're ok with mixing and matching build systems to target various platforms.
+
+We'll install the following tools:
+
+- [Xcode](https://developer.apple.com/xcode/); even if you aren't using the editor, you'll still need the SDKs that come with it
+- [Swift Bundler](https://swiftbundler.dev); this unifies your cross platform development experience with a consistent CLI interface and configuration format
+
+### Installing Xcode
+
+You have two main options:
+
+- Install Xcode from the macOS App Store
+- Install Xcode manually
+
+Installing from the App Store is simple:
+
+1. Just visit [Xcode's App Store page](https://apps.apple.com/us/app/xcode/id497799835?mt=12/)
+2. Click GET
+
+Installing manually gives you more flexibility. It also lets you install directly to an external storage device, which comes in handy if you're running low on storage. It goes like so:
+
+1. Locate your desired Xcode release on [https://xcodereleases.com]
+2. Click Download; this is take you to the requested Xcode release download in the Apple Developer portal, and requires an Apple Developer login
+3. Unzip the `.xip` file. I recommend using [unxip](https://github.com/saagarjha/unxip); it's faster and it doesn't use temporary storage on your internal drive, which causes issue when low on storage and installing to an external drive.
+4. Move `Xcode.app` to wherever you want it, whether that be `/Applications` or some external location.
+5. Open Xcode and select the SDKs you need when it prompts you to install optional components.
+6. Run `xcode-select --switch /path/to/Xcode.app` in terminal if installing Xcode at a non-standard location or alongside an existing version of Xcode.
+
+### Installing Swift Bundler
+
+Swift Bundler's [documentation](https://swiftbundler.dev/documentation/swift-bundler/installation) lists a wide variety of installation methods, but if you have Mint installed it's as easy as running `mint install stackotter/swift-bundler@main`.
+
+Once installed, run `swift bundler` in terminal as a quick sanity check.
+
+### Further steps
+
+If you're only using <doc:AppKitBackend> and <doc:UIKitBackend> when targeting Apple platforms, then you're good to go.
+
+If you'd like to test your app with <doc:GtkBackend> or <doc:Gtk3Backend> without leaving your Mac, visit the backends' respective documentation pages for detailed dependency installation instructions.
+
+## Linux
+
+We'll install the following:
+
+- The latest stable [Swift toolchain](https://www.swift.org/install/linux/)
+- [Swift Bundler](https://swiftbundler.dev)
+- [Gtk](https://www.gtk.org/) (3 or 4 depending on which is available)
+
+### Installing a Swift toolchain
+
+With the release of [swiftly](https://github.com/swiftlang/swiftly), the official Swift toolchain manager, installing Swift toolchains on Linux has become much easier. That said, there are still a few things to watch out for when using less mainstream Linux distributions. If Swiftly doesn't work for you, feel free to use an alternative installation method as found on the [Swift installation instructions page](https://www.swift.org/install/linux).
+
+1. Follow the [Swiftly-based installation instructions](https://www.swift.org/install/linux).
+2. Make sure that `swift` is not only installed but also on your path by opening a new terminal window and running `swift --version`.
+
+> Tip: If your Linux distribution isn't officially supported, check out [`xtremekforever`'s post on the Swift Forums](https://forums.swift.org/t/running-swift-on-unsupported-distributions/71741). It contains a table that tells you which distribution to select in Swiftly, or in the swfit.org downloads section, in order to maximise the chance of things working on your chosen distribution. The best distribution to download for isn't always the most intuitive.
+
+### Installing Swift Bundler
+
+Swift Bundler's [documentation](https://swiftbundler.dev/documentation/swift-bundler/installation) lists a wide variety of installation methods. If you have Mint installed, then installing Swift Bundler is as easy as running `mint install stackotter/swift-bundler@main`. A good alternative method is the manual installation method.
+
+Once installed, run `swift-bundler` in terminal as a quick sanity check.
+
+> Warning: If you're coming from macOS, you'll have to adjust your habits because `swift bundler` with a space instead of a hyphen doesn't work on Linux.
+
+### Installing Gtk (3 or 4)
+
+You're almost ready to go. The final step is to install the dependencies for the backend you'll be using. On Linux you're limited to <doc:GtkBackend> and <doc:Gtk3Backend>. We recommend using <doc:GtkBackend> unless you have a really good reason not to. <doc:Gtk3Backend> purely exists to support older Linux distributions, and doesn't support as many features.
+
+> Tip: some distributions such as Ubuntu 22.04 allow you to install both Gtk 3 and Gtk 4. This can come in handy when you have to target both <doc:GtkBackend> and <doc:Gtk3Backend>.
+
+Click through to your chosen backend for detailed dependency installation instructions:
+
+- <doc:GtkBackend>
+- <doc:Gtk3Backend>
+
+## Windows
+
+We'll install the following:
+
+- The latest stable [Swift toolchain](https://www.swift.org/install/windows/)
+- [Swift Bundler](https://swiftbundler.dev)
+- <doc:WinUIBackend> related dependencies
+
+### Installing a Swift toolchain
+
+The [Swift installation instructions page](https://www.swift.org/install/windows/) lists various installation methods. The easiest is the WinGet-based method:
+
+1. Visit the [Swift installation instructions page](https://www.swift.org/install/windows/).
+2. Click the Instructions button in the WinGet installation method card.
+3. Follow the installation instructions.
+4. Run `swift --version` as a quick sanity check.
+
+We don't include the instructions here because the Visual Studio version they depend on may change in the future.
+
+### Installing Swift Bundler
+
+Swift Bundler's [documentation](https://swiftbundler.dev/documentation/swift-bundler/installation) lists a wide variety of installation methods. The only one applicable to Windows at the moment is the manual installation method.
+
+First we'll clone and build Swift Bundler locally. Make sure to do this in a location that you're ok with keeping around.
+
+```sh
+git clone https://github.com/stackotter/swift-bundler
+cd swift-bundler
+swift build -c release
+```
+
+Next we'll add Swift Bundler to the system Path so that you can run it from any directory. These instructions have been adapted from [a eukhost article](https://www.eukhost.com/kb/how-to-add-to-the-path-on-windows-10-and-windows-11/) which includes additional images that some may find useful.
+
+1. Search for 'Edit the system environment variables' in the start menu. Select the matching option.
+2. Click the `Environment Variables...` button.
+3. Navigate to the `System Variables` tab.
+4. Select the row corresponding to the `Path` variable and click `Edit...`.
+5. Click `New`, and enter `absolute\path\to\swift-bundler\.build\release` (replacing with the appropriate path).
+6. Save your changes by selecting `OK` a bunch of times.
+
+Open a new command prompt window and run `swift bundler` as a quick sanity check.
+
+### Installing WinUIBackend related dependencies
+
+You're almost ready to start developing. That final step is to install the dependencies required by <doc:WinUIBackend>. Click through to <doc:WinUIBackend>'s documentation page for detailed installation instructions.
+
+> Warning: You may run into strange Swift issues if you use Command Prompt for Swift development. We recommend always using the Native Tools Command Prompt for VS 2022, which you can find in the start menu.

Sources/SwiftCrossUI/SwiftCrossUI.docc/Setting up a virtual development environment.md

@@ -0,0 +1,127 @@
+# Setting up a virtual development environment
+
+Detailed set up instructions for virtual Linux and Windows development environments.
+
+## Overview
+
+Most developers only have access to one or two of the major operating systems for development. Setting up virtual machines is an important part of developing and testing cross-platform apps, especially for smaller less-specialized teams.
+
+This article covers VM creation, leaving set up to the more general <doc:Setting-up-development-environments> article which applies to both physical and virtual machines.
+
+So far this article only covers macOS hosts but will be expanded to cover other host OSes in future.
+
+## Creating VMs on macOS hosts (UTM)
+
+Before continuing, make sure that you've installed [UTM](https://mac.getutm.app/). A download link is available on their website.
+
+These instructions have been adapted from [UTM's VM creation guides](https://docs.getutm.app/guides/guides/).
+
+### Windows guests
+
+These instructions apply to both Windows 10 and Windows 11. Choose which you want to install before you get started. We recommend Windows 11 because it's better supported by UTM, especially on Apple Silicon.
+
+Here are links to the relevant ISO download pages:
+
+- [Windows 11 x64 ISO](https://www.microsoft.com/en-us/software-download/windows11)
+- [Windows 11 arm64 ISO](https://www.microsoft.com/en-us/software-download/windows11arm64)
+- [Windows 10 x64 ISO](https://www.microsoft.com/en-au/software-download/windows10iso)
+- Unfortunately Windows 10 arm64 doesn't support VM hypervisors. Microsoft also doesn't provide any downloads for it.
+
+Once you've decided on a Windows version, you can begin the VM creation process.
+
+1. Download the installer ISO for your chosen Windows version. Make sure it matches the architecture of your host machine (arm64 for Apple Silicon).
+2. Click the `+` button in UTM.
+3. Select `Virtualize`.
+4. Select `Windows`.
+5. Click `Browse...` and select the ISO you downloaded.
+6. Ensure that `Install Windows 10 or higher` and `Install drivers and SPICE tools` are both checked. Click `Continue`.
+7. Configure the amount of RAM and number of CPU cores to allocate. Then click `Next`.
+   - Linking `swift-winui` and `swift-uwp` can be pretty RAM intensive. We recommend allocating as much RAM as you can without compromising your macOS experience.
+8. Configure the amount of storage to allocate. Click `Next`.
+9. Press `Save` to create the VM. Then press `Run` to start the VM.
+10. Follow any instructions the Windows installer gives you.
+11. Once the installation process has completed, navigate to the `D:` drive in file explorer and run the Spice Guest Tools installer. This enables clipboard sharing and automatic display resizing.
+
+The next few steps are optional, and walk through setting up a shared directory between the host and guest machines.
+
+1. Shutdown the VM.
+2. Click the edit button (the icon with 3 sliders) in the top right of UTM and navigate to the `Sharing` tab.
+3. Set `Path` to the directory you want to share (probably your top-level projects directory).
+4. Ensure that `Directory Share Mode` is set to `SPICE WebDAV`.
+5. Boot the VM.
+
+You should now find the shared directory mounted as a drive inside your Windows VM.
+
+You're now ready to begin setting up a SwiftCrossUI development environment inside your Windows VM. Head over to <doc:Setting-up-development-environments> to continue.
+
+### Linux guests
+
+You must choose a Linux distribution before starting VM creation. We recommend Ubuntu 24.04 because it has the best Swift support. Fedora is also great, but the latest version that Swift officially supports is a year and a half old.
+
+Here's a list of ISO download pages for the most common Linux distribution choices:
+
+- [Ubuntu Desktop 24.04 x64](https://ubuntu.com/download/desktop)
+- [Ubuntu Server 24.04 arm64](https://ubuntu.com/download/server/arm); Ubuntu doesn't provide stable arm64 desktop iso downloads, but it only takes one extra step to convert to install the Ubuntu desktop environment
+- [Ubuntu Desktop 24.04 arm64 (daily build)](https://cdimage.ubuntu.com/daily-live/20240421/); unstable, mileage may vary
+
+Once you've decided on a Linux distribution, you can begin the VM creation process.
+
+1. Download the install ISO for your chosen Linux distribution. Make sure it matches the architecture of your host machine (arm64 for Apple Silicon).
+2. Click the `+` button in UTM.
+3. Select `Virtualize`.
+4. Select `Linux`.
+5. Click `Browse...` and select the ISO you downloaded.
+6. Click `Continue`.
+7. Configure the amount of RAM and number of CPU cores to allocate. Then click `Next`.
+8. Configure the amount of storage to allocate. Click `Continue`.
+9. [Optional]: Select a directory to share with the VM. Do this if you want to use your preferred code editor on your host machine to edit code as you test it in the VM (recommended). You will have to perform some additional steps post-installation to configure directory sharing in the guest.
+10. Click `Continue`.
+11. Click `Save` to create the VM. Then press `Run` to start the VM.
+12. Follow the Ubuntu installer.
+
+You should now have a working VM. If you used an Ubuntu Server installer, run the following commands to install a graphical environment:
+
+```sh
+sudo apt update
+sudo apt install ubuntu-desktop
+sudo reboot
+```
+
+Run the following command to enable clipboard sharing and dynamic display resizing:
+
+```sh
+# Ubuntu, Debian, apt-based
+sudo apt install spice-vdagent
+# Fedora, CentOS, RPM-based
+sudo yum install spice-vdagent
+```
+
+If you selected a directory to share with the VM, set up your VM to automatically mount the shared directory on boot. To do so, follow these steps, replacing `USER` with your VM username.
+
+1. Edit `/etc/fstab` to add the following two lines:
+
+```
+share /mnt/utm 9p trans=virtio,version=9p2000.L,rw,_netdev,nofail,auto 0 0
+/mnt/utm /home/USER/utm fuse.bindfs map=501/1000:@20/@1000,x-systemd.requires=/mnt/utm,_netdev,nofail,auto 0 0
+```
+
+2. Now run the following commands to install required dependencies, create your mount destinations, and reboot so that your changes take effect:
+
+```sh
+sudo apt install bindfs
+sudo mkdir /mnt/utm
+mkdir /home/USER/utm
+sudo reboot -h now
+```
+
+3. You'll find your directory mounted at `~/utm`. If you run into file ownership related issues, check your macOS user id (with the `id -u` command). If it isn't `501`, update the `bindfs` fstab rule accordingly and reboot again.
+
+You're now ready to begin setting up a SwiftCrossUI development environment inside your Linux VM. Head over to <doc:Setting-up-development-environments> to continue.
+
+<!-- ## Creating VMs on Linux hosts (Gnome Boxes) -->
+
+<!-- ### Windows guests -->
+
+<!-- ### Linux guests -->
+
+<!-- Linux virtual machines can be useful when you need to test on multiple Linux distributions. -->

Sources/SwiftCrossUI/SwiftCrossUI.docc/SwiftCrossUI.md

@@ -11,6 +11,8 @@ SwiftCrossUI takes inspiration from SwiftUI, allowing you to use the basic conce
 ### Getting Started
 
 - <doc:Quick-start>
+- <doc:Setting-up-a-development-environment>
+- <doc:Setting-up-a-virtual-development-environment>
 - <doc:Examples>
 - <doc:Hot-reloading>