From 7312152ce3f543c788e395a8519f456ff41ed4fd Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 17:40:33 +0200 Subject: [PATCH 1/8] Experiment with "Tools" menu --- docs/actions/gym.md | 349 +------------------------------------------- docs/tools.md | 45 ++++++ docs/tools/gym.md | 242 ++++++++++++++++++++++++++++++ mkdocs.yml | 3 + 4 files changed, 293 insertions(+), 346 deletions(-) create mode 100644 docs/tools.md create mode 100644 docs/tools/gym.md diff --git a/docs/actions/gym.md b/docs/actions/gym.md index 2ef68e96af..cf541539b7 100644 --- a/docs/actions/gym.md +++ b/docs/actions/gym.md @@ -1,352 +1,9 @@ - - # gym +Deprecated action: -Alias for the `build_ios_app` action - - - - -

- -

- -------- - -

- Features • - Usage • - Tips -

- -------- - -
gym is part of fastlane: The easiest way to automate beta deployments and releases for your iOS and Android apps.
- -# What's gym? - -_gym_ builds and packages iOS apps for you. It takes care of all the heavy lifting and makes it super easy to generate a signed `ipa` or `app` file 💪 - -_gym_ is a replacement for [shenzhen](https://github.com/nomad/shenzhen). - -### Before _gym_ - -```no-highlight -xcodebuild clean archive -archivePath build/MyApp \ - -scheme MyApp -xcodebuild -exportArchive \ - -exportFormat ipa \ - -archivePath "build/MyApp.xcarchive" \ - -exportPath "build/MyApp.ipa" \ - -exportProvisioningProfile "ProvisioningProfileName" -``` - -### With _gym_ - -```no-highlight -fastlane gym -``` - -### Why _gym_? - -_gym_ uses the latest APIs to build and sign your application which results in much faster build times. - -| | Gym Features | -|----------|----------------| -🚀 | _gym_ builds 30% faster than other build tools like [shenzhen](https://github.com/nomad/shenzhen) -🏁 | Beautiful inline build output -📖 | Helps you resolve common build errors like code signing issues -🚠 | Sensible defaults: Automatically detect the project, its schemes and more -🔗 | Works perfectly with [_fastlane_](https://fastlane.tools) and other tools -📦 | Automatically generates an `ipa` and a compressed `dSYM` file -🚅 | Don't remember any complicated build commands, just _gym_ -🔧 | Easy and dynamic configuration using parameters and environment variables -💾 | Store common build settings in a `Gymfile` -📤 | All archives are stored and accessible in the Xcode Organizer -💻 | Supports both iOS and Mac applications - -![/img/actions/gymScreenshot.png](/img/actions/gymScreenshot.png) - ------ - -![/img/actions/gym.gif](/img/actions/gym.gif) - -# Usage - -```no-highlight -fastlane gym -``` - -That's all you need to build your application. If you want more control, here are some available parameters: - -```no-highlight -fastlane gym --workspace "Example.xcworkspace" --scheme "AppName" --clean -``` - -If you need to use a different Xcode installation, use `xcode-select` or define `DEVELOPER_DIR`: - -```no-highlight -DEVELOPER_DIR="/Applications/Xcode6.2.app" fastlane gym -``` - -For a list of all available parameters use - -```no-highlight -fastlane action gym -``` - -If you run into any issues, use the `verbose` mode to get more information - -```no-highlight -fastlane gym --verbose -``` - -Set the right export method if you're not uploading to App Store or TestFlight: - -```no-highlight -fastlane gym --export_method ad-hoc -``` - -To pass boolean parameters make sure to use _gym_ like this: - -```no-highlight -fastlane gym --include_bitcode true --include_symbols false -``` - -To access the raw `xcodebuild` output open `~/Library/Logs/gym` - -# Gymfile - -Since you might want to manually trigger a new build but don't want to specify all the parameters every time, you can store your defaults in a so called `Gymfile`. - -Run `fastlane gym init` to create a new configuration file. Example: - -```ruby-skip-tests -scheme("Example") - -sdk("iphoneos9.0") - -clean(true) - -output_directory("./build") # store the ipa in this folder -output_name("MyApp") # the name of the ipa file -``` - -## Export options - -Since Xcode 7, _gym_ is using new Xcode API which allows us to specify export options using `plist` file. By default _gym_ creates this file for you and you are able to modify some parameters by using `export_method`, `export_team_id`, `include_symbols` or `include_bitcode`. If you want to have more options, like creating manifest file for app thinning, you can provide your own `plist` file: - -```ruby-skip-tests -export_options("./ExportOptions.plist") -``` - -or you can provide hash of values directly in the `Gymfile`: - -```ruby-skip-tests -export_options = { - method: "ad-hoc", - manifest: { - appURL: "https://example.com/My App.ipa", - }, - thinning: "" -} -``` - -Optional: If _gym_ can't automatically detect the provisioning profiles to use, you can pass a mapping of bundle identifiers to provisioning profiles: - -```ruby-skip-tests -export_options: { - method: "app-store", - provisioningProfiles: { - "com.example.bundleid" => "Provisioning Profile Name", - "com.example.bundleid2" => "Provisioning Profile Name 2" - } -} -``` - -**Note**: If you use [_fastlane_](https://fastlane.tools) with [_match_](https://fastlane.tools/match) you don't need to provide those values manually. - -For the list of available options run `xcodebuild -help`. - -## Setup code signing - -- [More information on how to get started with codesigning](https://docs.fastlane.tools/codesigning/getting-started/) -- [Docs on how to set up your Xcode project](https://docs.fastlane.tools/codesigning/xcode-project/) - -## Automating the whole process - -_gym_ works great together with [_fastlane_](https://fastlane.tools), which connects all deployment tools into one streamlined workflow. - -Using _fastlane_ you can define a configuration like - -```ruby -lane :beta do - scan - gym(scheme: "MyApp") - crashlytics -end - -# error block is executed when a error occurs -error do |lane, exception| - slack( - # message with short human friendly message - message: exception.to_s, - success: false, - # Output containing extended log output - payload: { "Output" => exception.error_info.to_s } - ) -end -``` - -When _gym_ raises an error the `error_info` property will contain the process output -in case you want to display the error in 3rd party tools such as Slack. - -You can then easily switch between the beta provider (e.g. `testflight`, `hockey`, `s3` and more). - -# How does it work? - -_gym_ uses the latest APIs to build and sign your application. The 2 main components are - -- `xcodebuild` -- [xcpretty](https://github.com/supermarin/xcpretty) - -When you run _gym_ without the `--silent` mode it will print out every command it executes. - -To build the archive _gym_ uses the following command: - -```no-highlight -set -o pipefail && \ -xcodebuild -scheme 'Example' \ --project './Example.xcodeproj' \ --configuration 'Release' \ --destination 'generic/platform=iOS' \ --archivePath '/Users/felixkrause/Library/Developer/Xcode/Archives/2015-08-11/ExampleProductName 2015-08-11 18.15.30.xcarchive' \ -archive | xcpretty -``` - -After building the archive it is being checked by _gym_. If it's valid, it gets packaged up and signed into an `ipa` file. - -_gym_ automatically chooses a different packaging method depending on the version of Xcode you're using. - -### Xcode 7 and above - -```no-highlight -/usr/bin/xcrun path/to/xcbuild-safe.sh -exportArchive \ --exportOptionsPlist '/tmp/gym_config_1442852529.plist' \ --archivePath '/Users/fkrause/Library/Developer/Xcode/Archives/2015-09-21/App 2015-09-21 09.21.56.xcarchive' \ --exportPath '/tmp/1442852529' -``` - -_gym_ makes use of the new Xcode 7 API which allows us to specify the export options using a `plist` file. You can find more information about the available options by running `xcodebuild --help`. - -Using this method there are no workarounds for WatchKit or Swift required, as it uses the same technique Xcode uses when exporting your binary. - -Note: the [xcbuild-safe.sh script](https://github.com/fastlane/fastlane/blob/master/gym/lib/assets/wrap_xcodebuild/xcbuild-safe.sh) wraps around xcodebuild to workaround some incompatibilities. - -## Use 'ProvisionQL' for advanced Quick Look in Finder - -Install [ProvisionQL](https://github.com/ealeksandrov/ProvisionQL). - -It will show you `ipa` files like this: -![img/actions/QuickLookScreenshot-App.png](/img/actions/QuickLookScreenshot-App.png) - -
- - -gym || ----|--- -Supported platforms | ios, mac -Author | @KrauseFx -Returns | The absolute path to the generated ipa file - - - -## 4 Examples - -```ruby -build_ios_app(scheme: "MyApp", workspace: "MyApp.xcworkspace") -``` - -```ruby -build_ios_app( - workspace: "MyApp.xcworkspace", - configuration: "Debug", - scheme: "MyApp", - silent: true, - clean: true, - output_directory: "path/to/dir", # Destination directory. Defaults to current directory. - output_name: "my-app.ipa", # specify the name of the .ipa file to generate (including file extension) - sdk: "iOS 11.1" # use SDK as the name or path of the base SDK when building the project. -) -``` - -```ruby -gym # alias for "build_ios_app" -``` - -```ruby -build_app # alias for "build_ios_app" -``` - - - - - -## Parameters - -Key | Description | Default -----|-------------|-------- - `workspace` | Path to the workspace file | - `project` | Path to the project file | - `scheme` | The project's scheme. Make sure it's marked as `Shared` | - `clean` | Should the project be cleaned before building it? | `false` - `output_directory` | The directory in which the ipa file should be stored in | `.` - `output_name` | The name of the resulting ipa file | - `configuration` | The configuration to use when building the app. Defaults to 'Release' | [*](#parameters-legend-dynamic) - `silent` | Hide all information that's not necessary while building | `false` - `codesigning_identity` | The name of the code signing identity to use. It has to match the name exactly. e.g. 'iPhone Distribution: SunApps GmbH' | - `skip_package_ipa` | Should we skip packaging the ipa? | `false` - `include_symbols` | Should the ipa file include symbols? | - `include_bitcode` | Should the ipa file include bitcode? | - `export_method` | Method used to export the archive. Valid values are: app-store, ad-hoc, package, enterprise, development, developer-id | - `export_options` | Path to an export options plist or a hash with export options. Use 'xcodebuild -help' to print the full set of available options | - `export_xcargs` | Pass additional arguments to xcodebuild for the package phase. Be sure to quote the setting names and values e.g. OTHER_LDFLAGS="-ObjC -lstdc++" | - `skip_build_archive` | Export ipa from previously built xarchive. Uses archive_path as source | - `skip_archive` | After building, don't archive, effectively not including -archivePath param | - `build_path` | The directory in which the archive should be stored in | - `archive_path` | The path to the created archive | - `derived_data_path` | The directory where built products and other derived data will go | - `result_bundle` | Should an Xcode result bundle be generated in the output directory | `false` - `buildlog_path` | The directory where to store the build log | [*](#parameters-legend-dynamic) - `sdk` | The SDK that should be used for building the application | - `toolchain` | The toolchain that should be used for building the application (e.g. com.apple.dt.toolchain.Swift_2_3, org.swift.30p620160816a) | - `destination` | Use a custom destination for building the app | - `export_team_id` | Optional: Sometimes you need to specify a team id when exporting the ipa file | - `xcargs` | Pass additional arguments to xcodebuild for the build phase. Be sure to quote the setting names and values e.g. OTHER_LDFLAGS="-ObjC -lstdc++" | - `xcconfig` | Use an extra XCCONFIG file to build your app | - `suppress_xcode_output` | Suppress the output of xcodebuild to stdout. Output is still saved in buildlog_path | - `disable_xcpretty` | Disable xcpretty formatting of build output | - `xcpretty_test_format` | Use the test (RSpec style) format for build output | - `xcpretty_formatter` | A custom xcpretty formatter to use | - `xcpretty_report_junit` | Have xcpretty create a JUnit-style XML report at the provided path | - `xcpretty_report_html` | Have xcpretty create a simple HTML report at the provided path | - `xcpretty_report_json` | Have xcpretty create a JSON compilation database at the provided path | - `analyze_build_time` | Analyze the project build time and store the output in 'culprits.txt' file | - `xcpretty_utf` | Have xcpretty use unicode encoding when reporting builds | - `skip_profile_detection` | Do not try to build a profile mapping from the xcodeproj. Match or a manually provided mapping should be used | `false` - -* = default value is dependent on the user's system - - -
-To show the documentation in your terminal, run -```no-highlight -fastlane action gym -``` +- New action name: [`build_ios_app`](build_ios_app.md) +- Underlying tool: [`gym`](../tools/gym.md) View source code diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 0000000000..323a144550 --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,45 @@ +{!docs/setup-fastlane-header.md!} + +# fastlane actions + +TODO document what tools are and how they work + +This page contains a list of all fastlane tools: + +### iOS + +#### App Store +- [`produce`](tools/produce.md): Create new iOS apps on iTunes Connect and Dev Portal using the command line +- [`precheck`](tools/precheck.md): Check your app using a community driven set of App Store review rules to avoid being rejected +- [`deliver`](tools/deliver.md): Upload screenshots, metadata, and your app to the App Store + +#### Screenshots +- [`snapshot`](tools/snapshot.md): Automate taking localized screenshots of your iOS and tvOS apps on every device +- [`frameit`](tools/frameit.md): Quickly put your screenshots into the right device frames + +#### Certificates and Provisioning Profiles +- [`match`](tools/match.md): Easily sync your certificates and profiles across your team using Git +- [`pem`](tools/pem.md): Automatically generate and renew your push notification profiles +- [`sigh`](tools/sigh.md): Because you would rather spend your time building stuff than fighting provisioning +- [`cert`](tools/cert.md): Automatically create and maintain iOS code signing certificates + +#### Testing +- [`scan`](tools/scan.md): The easiest way to run tests for your iOS and Mac apps +- [`pilot`](tools/pilot.md): The best way to manage your TestFlight testers and builds from your terminal +- [`boarding`](https://github.com/fastlane/boarding): The easiest way to invite your TestFlight beta testers + +#### Building +- [`gym`](tools/gym.md): Building your iOS apps has never been easier + +#### Plumbing +- [`spaceship`](tools/spaceship.md): Ruby library to access the Apple Dev Center and iTunes Connect + +### Android + +#### Google Play +- [`supply`](tools/supply.md): Upload your Android app and its metadata to Google Play + +#### Screenshots +- [`screengrab`](tools/screengrab.md): Automate taking localized screenshots of your Android app on every device + +TODO update list or replace with table \ No newline at end of file diff --git a/docs/tools/gym.md b/docs/tools/gym.md new file mode 100644 index 0000000000..b7fdad2b1f --- /dev/null +++ b/docs/tools/gym.md @@ -0,0 +1,242 @@ +

+ +

+ +------- + +

+ Features • + Usage • + Tips +

+ +------- + +
gym is part of fastlane: The easiest way to automate beta deployments and releases for your iOS and Android apps.
+ +# What's gym? + +_gym_ builds and packages iOS apps for you. It takes care of all the heavy lifting and makes it super easy to generate a signed `ipa` or `app` file 💪 + +_gym_ is a replacement for [shenzhen](https://github.com/nomad/shenzhen). + +### Before _gym_ + +```no-highlight +xcodebuild clean archive -archivePath build/MyApp \ + -scheme MyApp +xcodebuild -exportArchive \ + -exportFormat ipa \ + -archivePath "build/MyApp.xcarchive" \ + -exportPath "build/MyApp.ipa" \ + -exportProvisioningProfile "ProvisioningProfileName" +``` + +### With _gym_ + +```no-highlight +fastlane gym +``` + +### Why _gym_? + +_gym_ uses the latest APIs to build and sign your application which results in much faster build times. + +| | Gym Features | +|----------|----------------| +🚀 | _gym_ builds 30% faster than other build tools like [shenzhen](https://github.com/nomad/shenzhen) +🏁 | Beautiful inline build output +📖 | Helps you resolve common build errors like code signing issues +🚠 | Sensible defaults: Automatically detect the project, its schemes and more +🔗 | Works perfectly with [_fastlane_](https://fastlane.tools) and other tools +📦 | Automatically generates an `ipa` and a compressed `dSYM` file +🚅 | Don't remember any complicated build commands, just _gym_ +🔧 | Easy and dynamic configuration using parameters and environment variables +💾 | Store common build settings in a `Gymfile` +📤 | All archives are stored and accessible in the Xcode Organizer +💻 | Supports both iOS and Mac applications + +![/img/actions/gymScreenshot.png](/img/actions/gymScreenshot.png) + +----- + +![/img/actions/gym.gif](/img/actions/gym.gif) + +# Usage + +```no-highlight +fastlane gym +``` + +That's all you need to build your application. If you want more control, here are some available parameters: + +```no-highlight +fastlane gym --workspace "Example.xcworkspace" --scheme "AppName" --clean +``` + +If you need to use a different Xcode installation, use `xcode-select` or define `DEVELOPER_DIR`: + +```no-highlight +DEVELOPER_DIR="/Applications/Xcode6.2.app" fastlane gym +``` + +For a list of all available parameters use + +```no-highlight +fastlane action gym +``` + +If you run into any issues, use the `verbose` mode to get more information + +```no-highlight +fastlane gym --verbose +``` + +Set the right export method if you're not uploading to App Store or TestFlight: + +```no-highlight +fastlane gym --export_method ad-hoc +``` + +To pass boolean parameters make sure to use _gym_ like this: + +```no-highlight +fastlane gym --include_bitcode true --include_symbols false +``` + +To access the raw `xcodebuild` output open `~/Library/Logs/gym` + +# Gymfile + +Since you might want to manually trigger a new build but don't want to specify all the parameters every time, you can store your defaults in a so called `Gymfile`. + +Run `fastlane gym init` to create a new configuration file. Example: + +```ruby-skip-tests +scheme("Example") + +sdk("iphoneos9.0") + +clean(true) + +output_directory("./build") # store the ipa in this folder +output_name("MyApp") # the name of the ipa file +``` + +## Export options + +Since Xcode 7, _gym_ is using new Xcode API which allows us to specify export options using `plist` file. By default _gym_ creates this file for you and you are able to modify some parameters by using `export_method`, `export_team_id`, `include_symbols` or `include_bitcode`. If you want to have more options, like creating manifest file for app thinning, you can provide your own `plist` file: + +```ruby-skip-tests +export_options("./ExportOptions.plist") +``` + +or you can provide hash of values directly in the `Gymfile`: + +```ruby-skip-tests +export_options = { + method: "ad-hoc", + manifest: { + appURL: "https://example.com/My App.ipa", + }, + thinning: "" +} +``` + +Optional: If _gym_ can't automatically detect the provisioning profiles to use, you can pass a mapping of bundle identifiers to provisioning profiles: + +```ruby-skip-tests +export_options: { + method: "app-store", + provisioningProfiles: { + "com.example.bundleid" => "Provisioning Profile Name", + "com.example.bundleid2" => "Provisioning Profile Name 2" + } +} +``` + +**Note**: If you use [_fastlane_](https://fastlane.tools) with [_match_](https://fastlane.tools/match) you don't need to provide those values manually. + +For the list of available options run `xcodebuild -help`. + +## Setup code signing + +- [More information on how to get started with codesigning](https://docs.fastlane.tools/codesigning/getting-started/) +- [Docs on how to set up your Xcode project](https://docs.fastlane.tools/codesigning/xcode-project/) + +## Automating the whole process + +_gym_ works great together with [_fastlane_](https://fastlane.tools), which connects all deployment tools into one streamlined workflow. + +Using _fastlane_ you can define a configuration like + +```ruby +lane :beta do + scan + gym(scheme: "MyApp") + crashlytics +end + +# error block is executed when a error occurs +error do |lane, exception| + slack( + # message with short human friendly message + message: exception.to_s, + success: false, + # Output containing extended log output + payload: { "Output" => exception.error_info.to_s } + ) +end +``` + +When _gym_ raises an error the `error_info` property will contain the process output +in case you want to display the error in 3rd party tools such as Slack. + +You can then easily switch between the beta provider (e.g. `testflight`, `hockey`, `s3` and more). + +# How does it work? + +_gym_ uses the latest APIs to build and sign your application. The 2 main components are + +- `xcodebuild` +- [xcpretty](https://github.com/supermarin/xcpretty) + +When you run _gym_ without the `--silent` mode it will print out every command it executes. + +To build the archive _gym_ uses the following command: + +```no-highlight +set -o pipefail && \ +xcodebuild -scheme 'Example' \ +-project './Example.xcodeproj' \ +-configuration 'Release' \ +-destination 'generic/platform=iOS' \ +-archivePath '/Users/felixkrause/Library/Developer/Xcode/Archives/2015-08-11/ExampleProductName 2015-08-11 18.15.30.xcarchive' \ +archive | xcpretty +``` + +After building the archive it is being checked by _gym_. If it's valid, it gets packaged up and signed into an `ipa` file. + +_gym_ automatically chooses a different packaging method depending on the version of Xcode you're using. + +### Xcode 7 and above + +```no-highlight +/usr/bin/xcrun path/to/xcbuild-safe.sh -exportArchive \ +-exportOptionsPlist '/tmp/gym_config_1442852529.plist' \ +-archivePath '/Users/fkrause/Library/Developer/Xcode/Archives/2015-09-21/App 2015-09-21 09.21.56.xcarchive' \ +-exportPath '/tmp/1442852529' +``` + +_gym_ makes use of the new Xcode 7 API which allows us to specify the export options using a `plist` file. You can find more information about the available options by running `xcodebuild --help`. + +Using this method there are no workarounds for WatchKit or Swift required, as it uses the same technique Xcode uses when exporting your binary. + +Note: the [xcbuild-safe.sh script](https://github.com/fastlane/fastlane/blob/master/gym/lib/assets/wrap_xcodebuild/xcbuild-safe.sh) wraps around xcodebuild to workaround some incompatibilities. + +## Use 'ProvisionQL' for advanced Quick Look in Finder + +Install [ProvisionQL](https://github.com/ealeksandrov/ProvisionQL). + +It will show you `ipa` files like this: +![img/actions/QuickLookScreenshot-App.png](/img/actions/QuickLookScreenshot-App.png) diff --git a/mkdocs.yml b/mkdocs.yml index e148760633..cc8c406c17 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,9 @@ pages: - Screenshots: getting-started/android/screenshots.md - Beta Deployment: getting-started/android/beta-deployment.md - Release Deployment: getting-started/android/release-deployment.md +- Tools: tools.md +- _Tools: + - gym: tools/gym.md - Actions: actions.md - _Actions: - adb: actions/adb.md From 08247fb7a9e70183d3b8264cd402e3a5c537789c Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 17:46:30 +0200 Subject: [PATCH 2/8] remove tool docs from action --- docs/actions/build_ios_app.md | 246 +--------------------------------- 1 file changed, 1 insertion(+), 245 deletions(-) diff --git a/docs/actions/build_ios_app.md b/docs/actions/build_ios_app.md index ecd3bbf077..596d9978cf 100644 --- a/docs/actions/build_ios_app.md +++ b/docs/actions/build_ios_app.md @@ -6,255 +6,11 @@ To modify it, go to its source at https://github.com/fastlane/fastlane/blob/mast # build_ios_app -Easily build and sign your app (via _gym_) +This action uses the [`gym`](../tools/gym.md) tool to build your iOS app. -

- -

- -------- - -

- Features • - Usage • - Tips -

- -------- - -
gym is part of fastlane: The easiest way to automate beta deployments and releases for your iOS and Android apps.
- -# What's gym? - -_gym_ builds and packages iOS apps for you. It takes care of all the heavy lifting and makes it super easy to generate a signed `ipa` or `app` file 💪 - -_gym_ is a replacement for [shenzhen](https://github.com/nomad/shenzhen). - -### Before _gym_ - -```no-highlight -xcodebuild clean archive -archivePath build/MyApp \ - -scheme MyApp -xcodebuild -exportArchive \ - -exportFormat ipa \ - -archivePath "build/MyApp.xcarchive" \ - -exportPath "build/MyApp.ipa" \ - -exportProvisioningProfile "ProvisioningProfileName" -``` - -### With _gym_ - -```no-highlight -fastlane gym -``` - -### Why _gym_? - -_gym_ uses the latest APIs to build and sign your application which results in much faster build times. - -| | Gym Features | -|----------|----------------| -🚀 | _gym_ builds 30% faster than other build tools like [shenzhen](https://github.com/nomad/shenzhen) -🏁 | Beautiful inline build output -📖 | Helps you resolve common build errors like code signing issues -🚠 | Sensible defaults: Automatically detect the project, its schemes and more -🔗 | Works perfectly with [_fastlane_](https://fastlane.tools) and other tools -📦 | Automatically generates an `ipa` and a compressed `dSYM` file -🚅 | Don't remember any complicated build commands, just _gym_ -🔧 | Easy and dynamic configuration using parameters and environment variables -💾 | Store common build settings in a `Gymfile` -📤 | All archives are stored and accessible in the Xcode Organizer -💻 | Supports both iOS and Mac applications - -![/img/actions/gymScreenshot.png](/img/actions/gymScreenshot.png) - ------ - -![/img/actions/gym.gif](/img/actions/gym.gif) - -# Usage - -```no-highlight -fastlane gym -``` - -That's all you need to build your application. If you want more control, here are some available parameters: - -```no-highlight -fastlane gym --workspace "Example.xcworkspace" --scheme "AppName" --clean -``` - -If you need to use a different Xcode installation, use `xcode-select` or define `DEVELOPER_DIR`: - -```no-highlight -DEVELOPER_DIR="/Applications/Xcode6.2.app" fastlane gym -``` - -For a list of all available parameters use - -```no-highlight -fastlane action gym -``` - -If you run into any issues, use the `verbose` mode to get more information - -```no-highlight -fastlane gym --verbose -``` - -Set the right export method if you're not uploading to App Store or TestFlight: - -```no-highlight -fastlane gym --export_method ad-hoc -``` - -To pass boolean parameters make sure to use _gym_ like this: - -```no-highlight -fastlane gym --include_bitcode true --include_symbols false -``` - -To access the raw `xcodebuild` output open `~/Library/Logs/gym` - -# Gymfile - -Since you might want to manually trigger a new build but don't want to specify all the parameters every time, you can store your defaults in a so called `Gymfile`. - -Run `fastlane gym init` to create a new configuration file. Example: - -```ruby-skip-tests -scheme("Example") - -sdk("iphoneos9.0") - -clean(true) - -output_directory("./build") # store the ipa in this folder -output_name("MyApp") # the name of the ipa file -``` - -## Export options - -Since Xcode 7, _gym_ is using new Xcode API which allows us to specify export options using `plist` file. By default _gym_ creates this file for you and you are able to modify some parameters by using `export_method`, `export_team_id`, `include_symbols` or `include_bitcode`. If you want to have more options, like creating manifest file for app thinning, you can provide your own `plist` file: - -```ruby-skip-tests -export_options("./ExportOptions.plist") -``` - -or you can provide hash of values directly in the `Gymfile`: - -```ruby-skip-tests -export_options = { - method: "ad-hoc", - manifest: { - appURL: "https://example.com/My App.ipa", - }, - thinning: "" -} -``` - -Optional: If _gym_ can't automatically detect the provisioning profiles to use, you can pass a mapping of bundle identifiers to provisioning profiles: - -```ruby-skip-tests -export_options: { - method: "app-store", - provisioningProfiles: { - "com.example.bundleid" => "Provisioning Profile Name", - "com.example.bundleid2" => "Provisioning Profile Name 2" - } -} -``` - -**Note**: If you use [_fastlane_](https://fastlane.tools) with [_match_](https://fastlane.tools/match) you don't need to provide those values manually. - -For the list of available options run `xcodebuild -help`. - -## Setup code signing - -- [More information on how to get started with codesigning](https://docs.fastlane.tools/codesigning/getting-started/) -- [Docs on how to set up your Xcode project](https://docs.fastlane.tools/codesigning/xcode-project/) - -## Automating the whole process - -_gym_ works great together with [_fastlane_](https://fastlane.tools), which connects all deployment tools into one streamlined workflow. - -Using _fastlane_ you can define a configuration like - -```ruby -lane :beta do - scan - gym(scheme: "MyApp") - crashlytics -end - -# error block is executed when a error occurs -error do |lane, exception| - slack( - # message with short human friendly message - message: exception.to_s, - success: false, - # Output containing extended log output - payload: { "Output" => exception.error_info.to_s } - ) -end -``` - -When _gym_ raises an error the `error_info` property will contain the process output -in case you want to display the error in 3rd party tools such as Slack. - -You can then easily switch between the beta provider (e.g. `testflight`, `hockey`, `s3` and more). - -# How does it work? - -_gym_ uses the latest APIs to build and sign your application. The 2 main components are - -- `xcodebuild` -- [xcpretty](https://github.com/supermarin/xcpretty) - -When you run _gym_ without the `--silent` mode it will print out every command it executes. - -To build the archive _gym_ uses the following command: - -```no-highlight -set -o pipefail && \ -xcodebuild -scheme 'Example' \ --project './Example.xcodeproj' \ --configuration 'Release' \ --destination 'generic/platform=iOS' \ --archivePath '/Users/felixkrause/Library/Developer/Xcode/Archives/2015-08-11/ExampleProductName 2015-08-11 18.15.30.xcarchive' \ -archive | xcpretty -``` - -After building the archive it is being checked by _gym_. If it's valid, it gets packaged up and signed into an `ipa` file. - -_gym_ automatically chooses a different packaging method depending on the version of Xcode you're using. - -### Xcode 7 and above - -```no-highlight -/usr/bin/xcrun path/to/xcbuild-safe.sh -exportArchive \ --exportOptionsPlist '/tmp/gym_config_1442852529.plist' \ --archivePath '/Users/fkrause/Library/Developer/Xcode/Archives/2015-09-21/App 2015-09-21 09.21.56.xcarchive' \ --exportPath '/tmp/1442852529' -``` - -_gym_ makes use of the new Xcode 7 API which allows us to specify the export options using a `plist` file. You can find more information about the available options by running `xcodebuild --help`. - -Using this method there are no workarounds for WatchKit or Swift required, as it uses the same technique Xcode uses when exporting your binary. - -Note: the [xcbuild-safe.sh script](https://github.com/fastlane/fastlane/blob/master/gym/lib/assets/wrap_xcodebuild/xcbuild-safe.sh) wraps around xcodebuild to workaround some incompatibilities. - -## Use 'ProvisionQL' for advanced Quick Look in Finder - -Install [ProvisionQL](https://github.com/ealeksandrov/ProvisionQL). - -It will show you `ipa` files like this: -![img/actions/QuickLookScreenshot-App.png](/img/actions/QuickLookScreenshot-App.png) - -
build_ios_app || From d4608d7fccd31b46f3a8cd9fc61d8ed8e1de8883 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 17:48:09 +0200 Subject: [PATCH 3/8] Fix breadcrumbs for tools --- theme/breadcrumbs.html | 3 +++ 1 file changed, 3 insertions(+) diff --git a/theme/breadcrumbs.html b/theme/breadcrumbs.html index e6d3f0153f..43c0863642 100644 --- a/theme/breadcrumbs.html +++ b/theme/breadcrumbs.html @@ -6,6 +6,9 @@ {% if doc.title == "_Actions" %}
  • Actions »
    • + {% elif doc.title == "_Tools" %} + +
  • Tools »
    • {% elif doc.link %}
  • {{ doc.title }} »
    • {% else %} From 818c84042b852267b4ec579ef18b75a29a01ed75 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 17:52:09 +0200 Subject: [PATCH 4/8] headline maybe? --- docs/tools/gym.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools/gym.md b/docs/tools/gym.md index b7fdad2b1f..33e8ba0ad9 100644 --- a/docs/tools/gym.md +++ b/docs/tools/gym.md @@ -1,3 +1,5 @@ +# gym +

    From f55c48283277fc5c32c4d53ca1c94c5637dad54f Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 17:57:35 +0200 Subject: [PATCH 5/8] navigation --- theme/toc.html | 69 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 15 deletions(-) diff --git a/theme/toc.html b/theme/toc.html index 8027667b42..a7d4d8a438 100644 --- a/theme/toc.html +++ b/theme/toc.html @@ -1,25 +1,64 @@ -{% if nav_item.children %} - {% if not nav_item.title.startswith("_") %} +{# loop through all navigation items #} + +{# if the current item title does not start with _ #} +{% if not nav_item.title.startswith("_") %} + {# if the current item has children #} + {% if nav_item.children %}
    • {{ nav_item.title }}
      • + {# output children #} {% for nav_item in nav_item.children %} - {% include 'toc.html' %} + {% include 'toc.html' %} {% endfor %}
    - {% endif %} -{% else %} - {% if not nav_item.title.startswith("_") %} -
  • - {{ nav_item.title }} + {# if the current item does not have children #} + {% else %} +
  • + + {{ nav_item.title }} + + {# if current item is current page #} {% if nav_item == current_page %} -
      - {% for toc_item in toc %} - {% if loop.index != 1 %} -
    • {{ toc_item.title }}
      • - {% endif %} - {% endfor %} -
    +
      + {# output headlines #} + {% for toc_item in toc %} + {% if loop.index != 1 %} +
    • {{ toc_item.title }}
      • + {% endif %} + {% endfor %} +
    {% endif %}
    • {% endif %} {% endif %} + +{# if current page title is _Tools #} +{% if nav_item.title == "_Tools" %} + {% if current_page and current_page.title == "Tools" %} +
      + {% for nav_item in nav_item.children %} + {% include 'toc.html' %} + {% endfor %} +
    + {% else %} + {% if current_page and current_page.ancestors %} + {% for doc in current_page.ancestors %} + {% if nav_item.title == doc.title %} +
      + {% for nav_item in nav_item.children %} + {% include 'toc.html' %} + {% endfor %} +
    + {% endif %} + {% endfor %} + {% endif %} + {% endif %} +{% endif %} \ No newline at end of file From ef83ef285ee9ce2094d3482df29f59f7f222d941 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 20:27:28 +0200 Subject: [PATCH 6/8] stubs for all tools --- docs/tools/boarding.md | 1 + docs/tools/cert.md | 1 + docs/tools/deliver.md | 1 + docs/tools/frameit.md | 1 + docs/tools/match.md | 1 + docs/tools/pem.md | 1 + docs/tools/pilot.md | 1 + docs/tools/precheck.md | 1 + docs/tools/produce.md | 1 + docs/tools/scan.md | 1 + docs/tools/screengrab.md | 1 + docs/tools/sigh.md | 1 + docs/tools/snapshot.md | 1 + docs/tools/spaceship.md | 1 + docs/tools/supply.md | 1 + 15 files changed, 15 insertions(+) create mode 100644 docs/tools/boarding.md create mode 100644 docs/tools/cert.md create mode 100644 docs/tools/deliver.md create mode 100644 docs/tools/frameit.md create mode 100644 docs/tools/match.md create mode 100644 docs/tools/pem.md create mode 100644 docs/tools/pilot.md create mode 100644 docs/tools/precheck.md create mode 100644 docs/tools/produce.md create mode 100644 docs/tools/scan.md create mode 100644 docs/tools/screengrab.md create mode 100644 docs/tools/sigh.md create mode 100644 docs/tools/snapshot.md create mode 100644 docs/tools/spaceship.md create mode 100644 docs/tools/supply.md diff --git a/docs/tools/boarding.md b/docs/tools/boarding.md new file mode 100644 index 0000000000..570d8c5b79 --- /dev/null +++ b/docs/tools/boarding.md @@ -0,0 +1 @@ +# boarding \ No newline at end of file diff --git a/docs/tools/cert.md b/docs/tools/cert.md new file mode 100644 index 0000000000..d4d7de7175 --- /dev/null +++ b/docs/tools/cert.md @@ -0,0 +1 @@ +# cert \ No newline at end of file diff --git a/docs/tools/deliver.md b/docs/tools/deliver.md new file mode 100644 index 0000000000..a92632a588 --- /dev/null +++ b/docs/tools/deliver.md @@ -0,0 +1 @@ +# deliver \ No newline at end of file diff --git a/docs/tools/frameit.md b/docs/tools/frameit.md new file mode 100644 index 0000000000..0cea6c651f --- /dev/null +++ b/docs/tools/frameit.md @@ -0,0 +1 @@ +# frameit \ No newline at end of file diff --git a/docs/tools/match.md b/docs/tools/match.md new file mode 100644 index 0000000000..15b92de8ca --- /dev/null +++ b/docs/tools/match.md @@ -0,0 +1 @@ +# match \ No newline at end of file diff --git a/docs/tools/pem.md b/docs/tools/pem.md new file mode 100644 index 0000000000..4d39c3e880 --- /dev/null +++ b/docs/tools/pem.md @@ -0,0 +1 @@ +# pem \ No newline at end of file diff --git a/docs/tools/pilot.md b/docs/tools/pilot.md new file mode 100644 index 0000000000..7c2e128c88 --- /dev/null +++ b/docs/tools/pilot.md @@ -0,0 +1 @@ +# pilot \ No newline at end of file diff --git a/docs/tools/precheck.md b/docs/tools/precheck.md new file mode 100644 index 0000000000..8a1dfcec55 --- /dev/null +++ b/docs/tools/precheck.md @@ -0,0 +1 @@ +# precheck \ No newline at end of file diff --git a/docs/tools/produce.md b/docs/tools/produce.md new file mode 100644 index 0000000000..ef0e29438c --- /dev/null +++ b/docs/tools/produce.md @@ -0,0 +1 @@ +# produce \ No newline at end of file diff --git a/docs/tools/scan.md b/docs/tools/scan.md new file mode 100644 index 0000000000..f7d9395bff --- /dev/null +++ b/docs/tools/scan.md @@ -0,0 +1 @@ +# scan \ No newline at end of file diff --git a/docs/tools/screengrab.md b/docs/tools/screengrab.md new file mode 100644 index 0000000000..2e93120c2e --- /dev/null +++ b/docs/tools/screengrab.md @@ -0,0 +1 @@ +# screengrab \ No newline at end of file diff --git a/docs/tools/sigh.md b/docs/tools/sigh.md new file mode 100644 index 0000000000..6ef6f31468 --- /dev/null +++ b/docs/tools/sigh.md @@ -0,0 +1 @@ +# sigh \ No newline at end of file diff --git a/docs/tools/snapshot.md b/docs/tools/snapshot.md new file mode 100644 index 0000000000..61df8115ae --- /dev/null +++ b/docs/tools/snapshot.md @@ -0,0 +1 @@ +# snapshot \ No newline at end of file diff --git a/docs/tools/spaceship.md b/docs/tools/spaceship.md new file mode 100644 index 0000000000..5166c1c967 --- /dev/null +++ b/docs/tools/spaceship.md @@ -0,0 +1 @@ +# spaceship \ No newline at end of file diff --git a/docs/tools/supply.md b/docs/tools/supply.md new file mode 100644 index 0000000000..098056f2f8 --- /dev/null +++ b/docs/tools/supply.md @@ -0,0 +1 @@ +# supply \ No newline at end of file From ccaf439179fe8810fe5b0144c43a51d9692c93bf Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 20:34:55 +0200 Subject: [PATCH 7/8] add other tools to nav --- mkdocs.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index cc8c406c17..52c6b1913e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,7 +35,22 @@ pages: - Release Deployment: getting-started/android/release-deployment.md - Tools: tools.md - _Tools: + - boarding: tools/boarding.md + - cert: tools/cert.md + - deliver: tools/deliver.md + - frameit: tools/frameit.md - gym: tools/gym.md + - match: tools/match.md + - pem: tools/pem.md + - pilot: tools/pilot.md + - precheck: tools/precheck.md + - produce: tools/produce.md + - scan: tools/scan.md + - screengrab: tools/screengrab.md + - sigh: tools/sigh.md + - snapshot: tools/snapshot.md + - spaceship: tools/spaceship.md + - supply: tools/supply.md - Actions: actions.md - _Actions: - adb: actions/adb.md From dc8565b027310033c37ecb416d5e19762894cb94 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Wed, 1 Aug 2018 20:50:10 +0200 Subject: [PATCH 8/8] document tools.md a bit --- docs/tools.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 323a144550..bed80d15f9 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -1,11 +1,20 @@ {!docs/setup-fastlane-header.md!} -# fastlane actions +# fastlane tools + +## What are tools? TODO document what tools are and how they work +- tools are CLI command of fastlane: `fastlane ` +- they can offer subcommands: `fastlane ` +- they are usually configurable by a config file: `file` +- tools usually also have a corresponding action that makes their functionality available for use in lanes and other actions + This page contains a list of all fastlane tools: +## Available Tools + ### iOS #### App Store