From 64ea90a2519fdb044968fcd6d252cc016818aaac Mon Sep 17 00:00:00 2001 From: Vitor Silveira Date: Mon, 23 Jun 2025 21:46:11 -0300 Subject: [PATCH 1/4] #194: Improve README --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 90fcf7f460..dfc36ad581 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ To dive right in with SwiftCrossUI, check out [the SwiftCrossUI quick start guid ## Overview +- [Overview](#overview) - [Community](#community) - [Supporting SwiftCrossUI](#supporting-swiftcrossui) - [Documentation](#documentation) @@ -89,6 +90,16 @@ cd swift-cross-ui/Examples swift run CounterExample ``` +The examples are written as Swift packages, which means you can't run them on iOS directly without creating an Xcode project. By using tools like [`mint`](https://github.com/yonaskolb/Mint) and [`swift-bundler`](https://github.com/stackotter/swift-bundler), running these apps on the iOS Simulator becomes much easier. + +```sh +brew install mint +mint install stackotter/swift-bundler@main +git clone https://github.com/stackotter/swift-cross-ui +cd swift-cross-ui/Examples +swift bundler run CounterExample --simulator "iPhone" +``` + The documentation contains [a detailed list of all examples](https://stackotter.github.io/swift-cross-ui/documentation/swiftcrossui/examples) ## Backends From 497597f6eaddcab650ccdbfc88fcc84db6be811a Mon Sep 17 00:00:00 2001 From: Vitor Silveira Date: Mon, 23 Jun 2025 21:48:06 -0300 Subject: [PATCH 2/4] #194: Remove overview --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index dfc36ad581..a5f14a770c 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,6 @@ To dive right in with SwiftCrossUI, check out [the SwiftCrossUI quick start guid ## Overview -- [Overview](#overview) - [Community](#community) - [Supporting SwiftCrossUI](#supporting-swiftcrossui) - [Documentation](#documentation) From 80a42a4080016852e801cfbf22566a3eeee1fe46 Mon Sep 17 00:00:00 2001 From: Vitor Silveira Date: Tue, 24 Jun 2025 16:51:47 -0300 Subject: [PATCH 3/4] #194: Clarify example execution steps and recommend Swift Bundler --- README.md | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a5f14a770c..3cef27ae2d 100644 --- a/README.md +++ b/README.md @@ -81,24 +81,48 @@ struct CounterApp: App { } ``` -Clone the SwiftCrossUI repository to test out this example, and many more; +Clone the SwiftCrossUI repository to test out this example and others. Running the examples requires an installation of [Swift Bundler](https://github.com/stackotter/swift-bundler), which provides consistent behavior across platforms and enables running on iOS and tvOS simulators and devices. + +To install Swift Bundler, you can follow [its official installation instructions](https://github.com/stackotter/swift-bundler?tab=readme-ov-file#installation-). Swift Bundler is typically installed using [Mint](https://github.com/yonaskolb/Mint?tab=readme-ov-file#installing), a Swift package manager that lets you easily install and run CLI tools distributed as Swift packages. + +If you don't have Mint installed, you can install it with [Homebrew](https://brew.sh/): ```sh -git clone https://github.com/stackotter/swift-cross-ui -cd swift-cross-ui/Examples -swift run CounterExample +brew install mint ``` -The examples are written as Swift packages, which means you can't run them on iOS directly without creating an Xcode project. By using tools like [`mint`](https://github.com/yonaskolb/Mint) and [`swift-bundler`](https://github.com/stackotter/swift-bundler), running these apps on the iOS Simulator becomes much easier. +Then use Mint to install Swift Bundler: ```sh -brew install mint mint install stackotter/swift-bundler@main +``` + +Once installed, clone the project and run the example: + +```sh git clone https://github.com/stackotter/swift-cross-ui cd swift-cross-ui/Examples -swift bundler run CounterExample --simulator "iPhone" +swift bundler run CounterExample ``` +You can also run on iOS and tvOS: + +```sh +# On a connected device with "iPhone" in its name (macOS only) +swift bundler run CounterExample device iPhone + +# On a simulator with "iPhone 16" in its name (macOS only) +swift bundler run CounterExample simulator "iPhone 16" +``` + +These examples may also be run on your host machine without Swift Bundler by using SwiftPM: + +```sh +swift run CounterExample +``` + +However, resources may not be loaded as expected, and features like deep linking may not work. This method also does not support running on iOS or tvOS. + The documentation contains [a detailed list of all examples](https://stackotter.github.io/swift-cross-ui/documentation/swiftcrossui/examples) ## Backends From d62a56a6647a1411981bb13b9553b42df7ae54e0 Mon Sep 17 00:00:00 2001 From: stackotter Date: Wed, 25 Jun 2025 11:33:50 +1000 Subject: [PATCH 4/4] Update example running instructions in readme and docs (recommend sbun) --- README.md | 46 ++++++------------- .../SwiftCrossUI.docc/Examples.md | 35 +++++++++++--- 2 files changed, 44 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 3cef27ae2d..1fd42419ee 100644 --- a/README.md +++ b/README.md @@ -66,11 +66,11 @@ import SwiftCrossUI import DefaultBackend @main -struct CounterApp: App { +struct YourApp: App { @State var count = 0 var body: some Scene { - WindowGroup("CounterApp") { + WindowGroup("YourApp") { HStack { Button("-") { count -= 1 } Text("Count: \(count)") @@ -80,51 +80,35 @@ struct CounterApp: App { } } ``` +Figure 2: *Sources/YourApp/YourApp.swift* -Clone the SwiftCrossUI repository to test out this example and others. Running the examples requires an installation of [Swift Bundler](https://github.com/stackotter/swift-bundler), which provides consistent behavior across platforms and enables running on iOS and tvOS simulators and devices. +## More examples -To install Swift Bundler, you can follow [its official installation instructions](https://github.com/stackotter/swift-bundler?tab=readme-ov-file#installation-). Swift Bundler is typically installed using [Mint](https://github.com/yonaskolb/Mint?tab=readme-ov-file#installing), a Swift package manager that lets you easily install and run CLI tools distributed as Swift packages. +The SwiftCrossUI repository contains the above example and many more. The documentation hosts [a detailed list of all examples](https://stackotter.github.io/swift-cross-ui/documentation/swiftcrossui/examples). -If you don't have Mint installed, you can install it with [Homebrew](https://brew.sh/): +Running the examples requires [Swift Bundler](https://github.com/stackotter/swift-bundler), which provides consistent behavior across platforms and enables running on iOS/tvOS devices and simulators. -```sh -brew install mint -``` - -Then use Mint to install Swift Bundler: - -```sh -mint install stackotter/swift-bundler@main -``` - -Once installed, clone the project and run the example: +To install Swift Bundler, follow [its official installation instructions](https://github.com/stackotter/swift-bundler?tab=readme-ov-file#installation-). ```sh git clone https://github.com/stackotter/swift-cross-ui cd swift-cross-ui/Examples -swift bundler run CounterExample -``` - -You can also run on iOS and tvOS: - -```sh -# On a connected device with "iPhone" in its name (macOS only) -swift bundler run CounterExample device iPhone -# On a simulator with "iPhone 16" in its name (macOS only) -swift bundler run CounterExample simulator "iPhone 16" +# Run on host machine +swift-bundler run CounterExample +# Run on a connected device with "iPhone" in its name (macOS only) +swift-bundler run CounterExample --device iPhone +# Run on a simulator with "iPhone 16" in its name (macOS only) +swift-bundler run CounterExample --simulator "iPhone 16" ``` -These examples may also be run on your host machine without Swift Bundler by using SwiftPM: +These examples may also be run using SwiftPM. However, resources may not be loaded as expected, and features such as deep linking may not work. You also won't be able to run the examples on iOS or tvOS using this method. ```sh +# Non-recommended method swift run CounterExample ``` -However, resources may not be loaded as expected, and features like deep linking may not work. This method also does not support running on iOS or tvOS. - -The documentation contains [a detailed list of all examples](https://stackotter.github.io/swift-cross-ui/documentation/swiftcrossui/examples) - ## Backends SwiftCrossUI has a variety of backends tailored to different operating systems. The beauty of SwiftCrossUI is that you can write your app once and have it look native everywhere. For this reason I recommend using [DefaultBackend](https://stackotter.github.io/swift-cross-ui/documentation/swiftcrossui/defaultbackend) unless you've got particular constraints. diff --git a/Sources/SwiftCrossUI/SwiftCrossUI.docc/Examples.md b/Sources/SwiftCrossUI/SwiftCrossUI.docc/Examples.md index 7e293d6eb3..ab54ea10e2 100644 --- a/Sources/SwiftCrossUI/SwiftCrossUI.docc/Examples.md +++ b/Sources/SwiftCrossUI/SwiftCrossUI.docc/Examples.md @@ -9,22 +9,45 @@ A few examples are included with SwiftCrossUI to demonstrate some of its basic f - `CounterExample`, a simple app with buttons to increase and decrease a count. - `RandomNumberGeneratorExample`, a simple app to generate random numbers between a minimum and maximum. - `WindowingExample`, a simple app showcasing how ``WindowGroup`` is used to make multi-window apps and - control the properties of each window. + control the properties of each window. It also demonstrates the use of modals + such as alerts and file pickers. - `GreetingGeneratorExample`, a simple app demonstrating dynamic state and the ``ForEach`` view. - `NavigationExample`, an app showcasing ``NavigationStack`` and related concepts. -- `SplitExample`, an app showcasing sidebar-based navigation with multiple levels. +- `SplitExample`, an app showcasing ``NavigationSplitView``-based hierarchical navigation. - `StressTestExample`, an app used to test view update performance. - `SpreadsheetExample`, an app showcasing tables. - `ControlsExample`, an app showcasing the various types of controls available. +- `NotesExample`, an app showcasing multi-line text editing and a more realistic usage of SwiftCrossUI. +- `PathsExample`, an app showcasing the use of ``Path`` to draw various shapes. +- `WebViewExample`, an app showcasing the use of ``WebView`` to display websites. Only works on Apple platforms so far. -To run an example, either select the example under schemes at the top of the window (in Xcode), or run it from the command line like so: +## Running examples -``` -swift run ExampleToRun +Running the examples requires [Swift Bundler](https://github.com/stackotter/swift-bundler), which provides consistent behavior across platforms and enables running SwiftPM-based apps on iOS/tvOS devices and simulators. + +To install Swift Bundler, follow [its official installation instructions](https://github.com/stackotter/swift-bundler?tab=readme-ov-file#installation-). + +```sh +git clone https://github.com/stackotter/swift-cross-ui +cd swift-cross-ui/Examples + +# Run on host machine +swift-bundler run CounterExample +# Run on a connected device with "iPhone" in its name (macOS only) +swift-bundler run CounterExample --device iPhone +# Run on a simulator with "iPhone 16" in its name (macOS only) +swift-bundler run CounterExample --simulator "iPhone 16" ``` If you want to try out an example with a backend other than the default, you can do that too; +```sh +SCUI_DEFAULT_BACKEND=Gtk3Backend swift-bundler run ExampleToRun ``` -SCUI_DEFAULT_BACKEND=QtBackend swift run ExampleToRun + +These examples may also be run using SwiftPM. However, resources may not be loaded as expected, and features such as deep linking may not work. You also won't be able to run the examples on iOS or tvOS using this method. + +```sh +# Non-recommended method +swift run CounterExample ```