From 6d27db6264e7a6623110cc2ec8c09f37f39aa22e Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Fri, 23 Nov 2018 18:09:19 +0100 Subject: [PATCH 1/3] Initial documentation draft --- docs/best-practices/linux-windows.md | 103 +++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/best-practices/linux-windows.md diff --git a/docs/best-practices/linux-windows.md b/docs/best-practices/linux-windows.md new file mode 100644 index 0000000000..03f7e14080 --- /dev/null +++ b/docs/best-practices/linux-windows.md @@ -0,0 +1,103 @@ +# Using _fastlane_ on Linux and Windows + +Fastlane was created to automate building iOS apps on macOS. Over time, support for building macOS +and Android applications was added. + +Over the last few months members of the [fastlane team](https://github.com/fastlane/fastlane#fastlane-team) +have worked on improving the support for operating systems besides macOS with fastlane, namely Linux and Windows + +## Installation + +Follow the [normal installations instructions](TODO). + +## Unsupported functionality + +Fastlane includes some functionality that does only work on macOS as it uses software that is not +available on all other platforms as for example [Xcode](https://developer.apple.com/xcode/), [Keychain](https://support.apple.com/guide/keychain-access/what-is-keychain-access-kyca1083/mac), [`xcodebuild`](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), [`security`](https://ss64.com/osx/security.html) or [`PTY`](http://man7.org/linux/man-pages/man7/pty.7.html). Where possible, +we added alternatives inside the fastlane codebase, but this was not possible everywhere. Whenever any of these +softwares or tools are triggered in fastlane, a crash will inevitably follow on Windows and Linux. + +To avoid this we went through all actions and marked the ones using unsupported software as "incompatible" to those +operating systems. When fastlane executes such an action, it will check this list and throw an _exception_ with a message and +a link to this page instead of crashing uncontrollably. This clearly communicates that some functionality is not available on +a platform: + +``` +... +[17:35:34]: Driving the lane 'test' 🚀 ++---------------+------+ +| Lane Context | ++---------------+------+ +| PLATFORM_NAME | | +| LANE_NAME | test | ++---------------+------+ +[16:39:53]: Action 'scan' is not compatible with operating system 'Windows'. For information how to handle this check out: TODO +[16:39:53]: fastlane finished with errors + +[!] Action 'scan' is not compatible with operating system 'Windows'. For information how to handle this check out: TODO +``` + +The compatibility or incompatibility of actions is documented in the [list of available actions](https://docs.fastlane.tools/actions/). + +### Handling different operating systems in your `Fastfile` + +If you have lanes that should run on multiple operating systems with different compatibility for the actions used, you can +wrap the calls of those actions in an `if` block to make sure it is skipped: + +```ruby +lane :foo do + if Helper.is_mac? + scan + else + puts "Skipping tests as only possible on Mac" + end + + if !Helper.is_windows? + build_app + end +end +``` + +This way you can e.g. upload a build that is created on the fly on macOS, but use a file from the file system (that was created +on a macOS machine before) on Linux or Windows. + + +### Running unsupported functionality anyway + +You can set the environment variable `FASTLANE_IGNORE_OS_INCOMPAT` to override this behavior. The exception +is then replaced with a non-blocking error that is output on the console. This is meant for those hackers out +there working on making the tools work on other platforms anyway, and also as a way to override this behavior if we +ever get an action wrong and some parts of it maybe work on those operating systems anyway. + +``` +... +[17:36:19]: Driving the lane 'test' 🚀 +[17:36:19]: ------------------------------------------------ +[17:36:19]: Action 'scan' is not compatible with operating system 'Windows'. For information how to handle this check out: TODO +[17:36:19]: Continuing anyway as `FASTLANE_IGNORE_OS_INCOMPAT` environment variable is set. +[17:36:19]: ------------------------------------------------ +[17:36:19]: ------------------ +[17:36:19]: --- Step: scan --- +[17:36:19]: ------------------ +... +``` + +### Documenting incompatibilities in custom or plugin action + +To support this incompatibility check in your custom or plugin actions, simply create an `is_incompatible?()` action that takes +the `operating_system` as a string parameter. It should return `true` if the supplied operating system is not supported: + +```ruby +def self.is_incompatible?(operating_system) + # you can do things like + # + # operating_system != "macOS" + # + # ["macOS", "Linux", "Windows"].include?(operating_system) + # + + false +end +``` + +New actions generated with `fastlane new_action` or `fastlane new_plugin` automatically include this method. From 795c225e2181e023f5a24fb339a3b37cbe61f108 Mon Sep 17 00:00:00 2001 From: Jan Piotrowski Date: Mon, 26 Nov 2018 17:20:26 +0100 Subject: [PATCH 2/3] Update docs/best-practices/linux-windows.md --- docs/best-practices/linux-windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/best-practices/linux-windows.md b/docs/best-practices/linux-windows.md index 03f7e14080..d56daa3d90 100644 --- a/docs/best-practices/linux-windows.md +++ b/docs/best-practices/linux-windows.md @@ -1,6 +1,6 @@ # Using _fastlane_ on Linux and Windows -Fastlane was created to automate building iOS apps on macOS. Over time, support for building macOS +fastlane was created to automate building iOS apps on macOS. Over time, support for building macOS and Android applications was added. Over the last few months members of the [fastlane team](https://github.com/fastlane/fastlane#fastlane-team) From 313a593f90d70de75c9232a21ddf43f8bdad441b Mon Sep 17 00:00:00 2001 From: Roger Oba Date: Sat, 6 Mar 2021 22:58:59 -0300 Subject: [PATCH 3/3] Update formatting and add some link references. --- docs/best-practices/linux-windows.md | 40 ++++++++++------------------ docs/index.md | 12 +++++---- 2 files changed, 21 insertions(+), 31 deletions(-) diff --git a/docs/best-practices/linux-windows.md b/docs/best-practices/linux-windows.md index d56daa3d90..95b2c50c15 100644 --- a/docs/best-practices/linux-windows.md +++ b/docs/best-practices/linux-windows.md @@ -1,26 +1,21 @@ # Using _fastlane_ on Linux and Windows -fastlane was created to automate building iOS apps on macOS. Over time, support for building macOS -and Android applications was added. +_fastlane_ was created to automate building iOS apps on macOS. Over time, support for building macOS and Android applications was added. -Over the last few months members of the [fastlane team](https://github.com/fastlane/fastlane#fastlane-team) -have worked on improving the support for operating systems besides macOS with fastlane, namely Linux and Windows +Over the last few months members of the [_fastlane_ team](https://github.com/fastlane/fastlane#fastlane-team) have worked on improving the support for operating systems besides macOS with _fastlane_, namely Linux and Windows ## Installation -Follow the [normal installations instructions](TODO). +Follow the normal installation instructions: + +- [Getting started with _fastlane_ for iOS](https://docs.fastlane.tools/getting-started/ios/setup/) +- [Getting started with _fastlane_ for Android](https://docs.fastlane.tools/getting-started/android/setup/) ## Unsupported functionality -Fastlane includes some functionality that does only work on macOS as it uses software that is not -available on all other platforms as for example [Xcode](https://developer.apple.com/xcode/), [Keychain](https://support.apple.com/guide/keychain-access/what-is-keychain-access-kyca1083/mac), [`xcodebuild`](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), [`security`](https://ss64.com/osx/security.html) or [`PTY`](http://man7.org/linux/man-pages/man7/pty.7.html). Where possible, -we added alternatives inside the fastlane codebase, but this was not possible everywhere. Whenever any of these -softwares or tools are triggered in fastlane, a crash will inevitably follow on Windows and Linux. +_fastlane_ includes some functionality that does only work on macOS as it uses software that is not available on all other platforms as for example [Xcode](https://developer.apple.com/xcode/), [Keychain](https://support.apple.com/guide/keychain-access/what-is-keychain-access-kyca1083/mac), [`xcodebuild`](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), [`security`](https://ss64.com/osx/security.html) or [`PTY`](http://man7.org/linux/man-pages/man7/pty.7.html). Where possible, we added alternatives inside the _fastlane_ codebase, but this was not possible everywhere. Whenever any of these softwares or tools are triggered in _fastlane_, a crash will inevitably follow on Windows and Linux. -To avoid this we went through all actions and marked the ones using unsupported software as "incompatible" to those -operating systems. When fastlane executes such an action, it will check this list and throw an _exception_ with a message and -a link to this page instead of crashing uncontrollably. This clearly communicates that some functionality is not available on -a platform: +To avoid this we went through all actions and marked the ones using unsupported software as "incompatible" to those operating systems. When _fastlane_ executes such an action, it will check this list and throw an _exception_ with a message and a link to this page instead of crashing uncontrollably. This clearly communicates that some functionality is not available on a platform: ``` ... @@ -41,8 +36,7 @@ The compatibility or incompatibility of actions is documented in the [list of av ### Handling different operating systems in your `Fastfile` -If you have lanes that should run on multiple operating systems with different compatibility for the actions used, you can -wrap the calls of those actions in an `if` block to make sure it is skipped: +If you have lanes that should run on multiple operating systems with different compatibility for the actions used, you can wrap the calls of those actions in an `if` block to make sure it is skipped: ```ruby lane :foo do @@ -58,16 +52,11 @@ lane :foo do end ``` -This way you can e.g. upload a build that is created on the fly on macOS, but use a file from the file system (that was created -on a macOS machine before) on Linux or Windows. - +This way you can e.g. upload a build that is created on the fly on macOS, but use a file from the file system (that was created on a macOS machine before) on Linux or Windows. ### Running unsupported functionality anyway -You can set the environment variable `FASTLANE_IGNORE_OS_INCOMPAT` to override this behavior. The exception -is then replaced with a non-blocking error that is output on the console. This is meant for those hackers out -there working on making the tools work on other platforms anyway, and also as a way to override this behavior if we -ever get an action wrong and some parts of it maybe work on those operating systems anyway. +You can set the environment variable `FASTLANE_IGNORE_OS_INCOMPAT` to override this behavior. The exception is then replaced with a non-blocking error that is output on the console. This is meant for those hackers out there working on making the tools work on other platforms anyway, and also as a way to override this behavior if we ever get an action wrong and some parts of it maybe work on those operating systems anyway. ``` ... @@ -84,17 +73,16 @@ ever get an action wrong and some parts of it maybe work on those operating syst ### Documenting incompatibilities in custom or plugin action -To support this incompatibility check in your custom or plugin actions, simply create an `is_incompatible?()` action that takes -the `operating_system` as a string parameter. It should return `true` if the supplied operating system is not supported: +To support this incompatibility check in your custom or plugin actions, simply create an `is_incompatible?()` action that takes the `operating_system` as a string parameter. It should return `true` if the supplied operating system is not supported: ```ruby def self.is_incompatible?(operating_system) # you can do things like - # + # # operating_system != "macOS" # # ["macOS", "Linux", "Windows"].include?(operating_system) - # + # false end diff --git a/docs/index.md b/docs/index.md index d3c2425ed3..712cf0caf8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -77,10 +77,12 @@ If that doesn't help, please [submit an issue](https://github.com/fastlane/fastl ## System requirements -Currently, _fastlane_ is officially supported to run on macOS. +Currently, _fastlane_ is officially supported to run on macOS. But we are working on 🐧 Linux and 🖥️ Windows support for parts of _fastlane_. Some underlying software like Xcode or iTunes Transporter is only available for macOS, but many other tools and actions can theoretically also work on other platforms. Please see [this Github issue for further information](https://github.com/fastlane/fastlane/issues/11687). +For more information, see [Using _fastlane_ on Linux and Windows](https://docs.fastlane.tools/best-practices/linux-windows/). + ## _fastlane_ team @@ -168,12 +170,12 @@ But we are working on 🐧 Linux and 🖥️ Windows support for parts of _fastl Special thanks to all [contributors](https://github.com/fastlane/fastlane/graphs/contributors) for extending and improving _fastlane_. ## Metrics - -_fastlane_ tracks a few key metrics to understand how developers are using the tool and to help us know what areas need improvement. No personal/sensitive information is ever collected. Metrics that are collected include: - + +_fastlane_ tracks a few key metrics to understand how developers are using the tool and to help us know what areas need improvement. No personal/sensitive information is ever collected. Metrics that are collected include: + * The number of _fastlane_ runs * A salted hash of the app identifier or package name, which helps us anonymously identify unique usage of _fastlane_ - + You can easily opt-out of metrics collection by adding `opt_out_usage` at the top of your `Fastfile` or by setting the environment variable `FASTLANE_OPT_OUT_USAGE`. [Check out the metrics code on GitHub](https://github.com/fastlane/fastlane/tree/master/fastlane_core/lib/fastlane_core/analytics) ## License