From 8f31d69f4be0cbb2b1b24416a9e3cd376cf9418a Mon Sep 17 00:00:00 2001 From: dskuza Date: Wed, 4 Sep 2024 12:43:19 +0000 Subject: [PATCH] Update iOS contributing guide See title. Additionally, this removes the skia build scripts and updates the major version dependency rule to v6.0.0 in the Preview app. Diffs= 8773f56fc Update iOS contributing guide (#8018) Co-authored-by: David Skuza --- .rive_head | 2 +- CONTRIBUTING.md | 63 ++++++++++++------- .../RiveExample.xcodeproj/project.pbxproj | 2 +- scripts/build.skia.macos.sh | 47 -------------- scripts/build.skia.sh | 50 --------------- 5 files changed, 44 insertions(+), 120 deletions(-) delete mode 100755 scripts/build.skia.macos.sh delete mode 100755 scripts/build.skia.sh diff --git a/.rive_head b/.rive_head index fb2a1242..a46872f8 100644 --- a/.rive_head +++ b/.rive_head @@ -1 +1 @@ -d63786feecc4a5ad8325109b4dfadb7f5c05e86c +8773f56fce235f4bc9364e59aa7b3bf9a2c8cbc8 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd4362df..29e07142 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,26 +2,50 @@ We want this community to be friendly and respectful to each other. Please follow it in all your interactions with the project. -## Development workflow +## Getting started -To get started with the project, please install a few pre-requisites: [ninja](https://formulae.brew.sh/formula/ninja) & [premake5](https://premake.github.io/). [Homebrew](https://formulae.brew.sh/) will install both [git-lfs](https://formulae.brew.sh/formula/git-lfs) and ninja, for premake5 you will need to download the binary, and make sure its available on your path. Moving the executable to `/usr/local/bin/` will work. +To get started with building this runtime, you must install a few prerequisites: +- [Xcode](https://developer.apple.com/xcode/) +- [premake5](https://premake.github.io/) + - For premake5, you may download the binary, making sure it's available in your `$PATH`. Moving the executable to `/usr/local/bin/` will work. + - [Homebrew](https://brew.sh) may be used to install premake5: `$ brew install premake` +- [ply](https://pypi.org/project/ply/) + - Installed with Python. On macOS, this can be installed using the default Python 3 installation: `$ pip3 install ply` -Check out this repository, making sure to include the submodules. It is important to use ssh to checkout this repo, as the submodules are linked via ssh. +Check that your Xcode active developer directory is set to one that includes the iOS and macOS toolchains. + - You can check your currect directory by running `$ xcode-select -p` in the command line. + - Using your Xcode installation is a working option: `$ sudo xcode-select -s /Applications/Xcode.app` -`git clone --recurse-submodules git@github.com:rive-app/rive-ios.git` +Rive is constantly making use of the latest clang features, so please ensure your Xcode and Xcode Command Line Tools are up-to-date with the latest versions. -The package relies on [Skia](https://skia.org/), as well as [rive-runtime](https://github.com/rive-app/rive-runtime) in order to be built. To shorten the build cycle, we rely on compiled libraries for skia, rive & rive-skia-renderer. -The `./scripts/build.sh all` script will download or build appropriate libraries, be sure to run configure when making changes to our rive-runtime submodule. +Next, check out this repository, making sure to use ssh, and making sure to include its submodules. It is important to use ssh to checkout this repository, rather than https, as the submodules are linked via ssh. -Rive is constantly making use of the latest clang features, so please ensure your Xcode and Xcode Command Line Tools are up to date with the latest versions. +```bash +git clone --recurse-submodules git@github.com:rive-app/rive-ios.git +``` -## Targets / Schemes +This runtime relies on our open-source [Rive runtime](https://github.com/rive-app/rive-runtime) in order to be built. This dependency will automatically be included if you clone this repository with `--recurse-submobules`. If you have already cloned the directory without submodules, you can update the submodules by performing the following from the **root** of your cloned repository: -The example app has different targets/schemes. The `example` targets make use of the local Rive dependency and the `preview` targets make use of a hosted version of Rive - to make it easy to run without needing to do all of the local development setup. If you're making changes to the underlying Rive package and need to test the example app, be sure to set the target/scheme to `example`. See [Customizing the build schemes for a project](https://developer.apple.com/documentation/xcode/customizing-the-build-schemes-for-a-project) for more information. +```bash +cd submodules +git submodule update --init --recursive +``` + +Once you have cloned the repository, the prerequisites are installed, and your Xcode active developer directory is properly set, you can build this runtime by running the following from the **root** of your cloned repository: + +```bash +$ ./scripts/build.sh all +``` + +If the script completes successfully, then all necessary frameworks are built, and you can continue on to running the Example apps. + +## Example and Preview targets / schemes + +The Example app has different targets and schemes, currently for both iOS and macOS. The `Example` targets make use of the local Rive dependency (built above) and the `Preview` targets make use of a hosted version of Rive, added via Swift Package Manager, to make it easy to run without needing to do all of the local development setup above. If you're making changes to the underlying runtime and need to test the Example app, be sure to set the scheme to either `Example (iOS)` or `Example (macOS)`, depending on your platform. See [Customizing the build schemes for a project](https://developer.apple.com/documentation/xcode/customizing-the-build-schemes-for-a-project) for more information. ## Releasing -After releasing a new Rive runtime version you'll need to manually update the Rive dependency for the `preview` targets. This is to ensure that anyone evaluating Rive is using the latest hosted version. Right click the `RiveRuntime` dependency in the inspector and select `Update Package`. If there is a major version bump it will need to be configured in the project settings, by updating the minimum version in the `Package Dependencies` section for the `RiveExample` project. +After releasing a new runtime version you'll need to manually update the `rive-ios` dependency for the `Preview` targets. This is to ensure that anyone evaluating Rive is using the latest hosted version. Right click the `RiveRuntime` dependency in the inspector and select `Update Package`. If there is a major version bump, it will need to be configured in the project settings, by updating the `Up to Next Major Version` dependency rule with the new major version, in the `Package Dependencies` section for the `RiveExample` project. ### Uploading caches @@ -32,30 +56,27 @@ Note: on a Mac with brew, you can simply run 'brew install awscli' Note: the 'dependencies' directory is just a cache of what the configure.sh script downloads. It can be removed if you suspect it is out of date, and then just rerun the script (./scripts/configure.sh) -### Changing rive-runtime/skia +### Changing the `rive-cpp` submodule + +Changes within the `RiveRuntime` target should be reflected when you make builds. -Changes within the rive-ios should just be reflected when you make builds. -If you make changes within the `rive-runtime` submodule you will need to compile the prebuilt libraries, this can take a reasonably long time, but as long as you are working on rive-runtime with no uncommitted changes, it will fall back to using the cache, so you will only need to build once. +If you make changes within the `rive-cpp` submodule, you will need to compile the prebuilt libraries. This can take a reasonably long time, but as long as you are working on `rive-cpp` with no uncommitted changes, it will fall back to using the cache, so you will only need to build once. ### Testing changes -In addition to tests in the project, you may want to visually test out any changes by running the `Example-iOS` app at the top-level. Open the `RiveExample.xcodeproj` project in XCode. Make sure you have the local build of iOS run before testing out this application. Feel free to bring in additional Rives to the `assets/` folder. Ensure you add the Rive to the targets by checking the checkbox "Add to targets: RiveExample" when dragging assets into the folder so it can be properly included in the assets bundle and referenced accordingly in the example app. +In addition to tests in the project, you may want to visually test out any changes by running the `Example (iOS)` app at the top-level. Open the `RiveExample` project in Xcode. Make sure you have built the RiveRuntime scheme at least once before testing out this application. Feel free to bring in additional Rive files into the `assets/` folder. Ensure you add the Rive files to the correct targets by checking "Add to targets: RiveExample" when dragging assets into the folder, so it can be properly included in the assets bundle and referenced accordingly in the Example app(s). ### Linting and tests - We currently do not have any automatic linting set up. -- Tests are run on pull request, and you should be able to run tests via xcode in the `RiveRuntime` project. +- Tests are run on pull request, and you should be able to run tests via Xcode in the `RiveRuntime` project. ## Scripts -The `scripts` folder contains a few scripts to manage dependencies and perform builds. +The `scripts` folder contains a few scripts to manage dependencies and perform builds. The main script used to build this runtime is `build.sh`. For more information on usage, you can run the script with no arguments to print some additional information. However, the most common usage will be what's referenced above: `$ build.sh all`. ## FAQ ### `Rive.h` file not found -This is probably because of missing submodules. Make sure you check out rive with [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). - -### `rive/renderer.hpp` file not found - -This is likely because the `script/configure.py` has not been run yet. +This is probably because of missing submodules. Make sure you check out this repository with [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). See above for more information. diff --git a/Example-iOS/RiveExample.xcodeproj/project.pbxproj b/Example-iOS/RiveExample.xcodeproj/project.pbxproj index f8ae0922..76157f45 100644 --- a/Example-iOS/RiveExample.xcodeproj/project.pbxproj +++ b/Example-iOS/RiveExample.xcodeproj/project.pbxproj @@ -1620,7 +1620,7 @@ repositoryURL = "https://github.com/rive-app/rive-ios/"; requirement = { kind = upToNextMajorVersion; - minimumVersion = 5.11.0; + minimumVersion = 6.0.0; }; }; /* End XCRemoteSwiftPackageReference section */ diff --git a/scripts/build.skia.macos.sh b/scripts/build.skia.macos.sh deleted file mode 100755 index 52e0a079..00000000 --- a/scripts/build.skia.macos.sh +++ /dev/null @@ -1,47 +0,0 @@ -#!/bin/bash -set -ex - -ARCH_X64=x64 -ARCH_ARM64=arm64 - -usage() { - printf "Usage: %s -a arch\n" "$0" - printf "\t-a Specify an architecture (i.e. '%s', '%s')\n" $ARCH_X64 $ARCH_ARM64 - exit 1 # Exit script after printing help -} - -while getopts "a:cd" opt; do - case "$opt" in - a) ARCH_NAME="$OPTARG" ;; - \?) usage ;; # Print usage in case parameter is non-existent - esac -done - -if [ -z "$ARCH_NAME" ]; then - echo "No architecture specified" - usage -fi - -path=`readlink -f "${BASH_SOURCE:-$0}"` -DEV_SCRIPT_DIR=`dirname $path` - -export SKIA_REPO="https://github.com/rive-app/skia" -export SKIA_BRANCH="rive" -export COMPILE_TARGET="macos_$EXPECTED_NDK_VERSION_$ARCH_NAME" -export CACHE_NAME="rive_skia_macos" -export MAKE_SKIA_FILE="make_skia_macos.sh" -export SKIA_DIR_NAME="skia" -# we can have multiple at the same time... -export ARCHIVE_CONTENTS_NAME="archive_contents_macos_$ARCH_NAME" - -if [ -d "$DEV_SCRIPT_DIR/../submodules/rive-runtime" ]; -then - export RIVE_RUNTIME_DIR="$DEV_SCRIPT_DIR/../submodules/rive-runtime" -else - export RIVE_RUNTIME_DIR="$DEV_SCRIPT_DIR/../../runtime" -fi - -# Build skia -pushd "$RIVE_RUNTIME_DIR"/skia/dependencies -./make_skia_macos.sh $ARCH_NAME -popd diff --git a/scripts/build.skia.sh b/scripts/build.skia.sh deleted file mode 100755 index f76d0f28..00000000 --- a/scripts/build.skia.sh +++ /dev/null @@ -1,50 +0,0 @@ -#!/bin/bash -set -ex - -ARCH_X86=x86 -ARCH_X64=x64 -ARCH_ARM=arm -ARCH_ARM64=arm64 -ARCH_SIM_ARM64=iossim_arm64 - -usage() { - printf "Usage: %s -a arch\n" "$0" - printf "\t-a Specify an architecture (i.e. '%s', '%s', '%s', '%s', '%s')\n" $ARCH_X86 $ARCH_X64 $ARCH_ARM $ARCH_ARM64 $ARCH_SIM_ARM64 - exit 1 # Exit script after printing help -} - -while getopts "a:cd" opt; do - case "$opt" in - a) ARCH_NAME="$OPTARG" ;; - \?) usage ;; # Print usage in case parameter is non-existent - esac -done - -if [ -z "$ARCH_NAME" ]; then - echo "No architecture specified" - usage -fi - -path=`readlink -f "${BASH_SOURCE:-$0}"` -DEV_SCRIPT_DIR=`dirname $path` - -export SKIA_REPO="https://github.com/rive-app/skia" -export SKIA_BRANCH="rive" -export COMPILE_TARGET="ios_$EXPECTED_NDK_VERSION_$ARCH_NAME" -export CACHE_NAME="rive_skia_ios" -export MAKE_SKIA_FILE="make_skia_ios.sh" -export SKIA_DIR_NAME="skia" -# we can have multiple at the same time... -export ARCHIVE_CONTENTS_NAME="archive_contents_ios_$ARCH_NAME" - -if [ -d "$DEV_SCRIPT_DIR/../submodules/rive-runtime" ]; -then - export RIVE_RUNTIME_DIR="$DEV_SCRIPT_DIR/../submodules/rive-runtime" -else - export RIVE_RUNTIME_DIR="$DEV_SCRIPT_DIR/../../runtime" -fi - -# Build skia -pushd "$RIVE_RUNTIME_DIR"/skia/dependencies -./make_skia_ios.sh $ARCH_NAME -popd