diff --git a/docs/get_the_code.md b/docs/get_the_code.md index cc834b5622e729..0d637d44bf5a00 100644 --- a/docs/get_the_code.md +++ b/docs/get_the_code.md @@ -12,7 +12,7 @@ you might want to build: * [Android](android_build_instructions.md) * [Cast](old_cast_build_instructions.md) * [Chrome OS](old_chromeos_build_instructions.md) -* [iOS](ios_build_instructions.md) +* [iOS](ios/build_instructions.md) * [Linux](linux_build_instructions.md) * [Mac](mac_build_instructions.md) * [Windows](windows_build_instructions.md) diff --git a/docs/ios/build_instructions.md b/docs/ios/build_instructions.md new file mode 100644 index 00000000000000..1fb0988498f961 --- /dev/null +++ b/docs/ios/build_instructions.md @@ -0,0 +1,315 @@ +# Checking out and building Chromium for iOS + +There are instructions for other platforms linked from the +[get the code](../get_the_code.md) page. + +## Instructions for Google Employees + +Are you a Google employee? See +[go/building-chrome](https://goto.google.com/building-chrome) instead. + +[TOC] + +## System requirements + +* A 64-bit Mac running 10.11+. +* [Xcode](https://developer.apple.com/xcode) 8.0+. +* The OS X 10.10 SDK. Run + + ```shell + $ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs + ``` + + to check whether you have it. Building with the 10.11 SDK works too, but + the releases currently use the 10.10 SDK. +* The current version of the JDK (required for the Closure compiler). + +## Install `depot_tools` + +Clone the `depot_tools` repository: + +```shell +$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git +``` + +Add `depot_tools` to the end of your PATH (you will probably want to put this +in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to +`/path/to/depot_tools`: + +```shell +$ export PATH="$PATH:/path/to/depot_tools" +``` + +## Get the code + +Create a `chromium` directory for the checkout and change to it (you can call +this whatever you like and put it wherever you like, as +long as the full path has no spaces): + +```shell +$ mkdir chromium && cd chromium +``` + +Run the `fetch` tool from `depot_tools` to check out the code and its +dependencies. + +```shell +$ fetch ios +``` + +If you don't want the full repo history, you can save a lot of time by +adding the `--no-history` flag to `fetch`. + +Expect the command to take 30 minutes on even a fast connection, and many +hours on slower ones. + +When `fetch` completes, it will have created a hidden `.gclient` file and a +directory called `src` in the working directory. The remaining instructions +assume you have switched to the `src` directory: + +```shell +$ cd src +``` + +*Optional*: You can also [install API +keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your +build to talk to some Google services, but this is not necessary for most +development and testing purposes. + +## Setting up the build + +Since the iOS build is a bit more complicated than a desktop build, we provide +`ios/build/tools/setup-gn.py`, which will create four appropriately configured +build directories under `out` for Release and Debug device and simulator +builds, and generates an appropriate Xcode workspace as well. + +This script is run automatically by fetch (as part of `gclient runhooks`). + +You can customize the build by editing the file `$HOME/.setup-gn` (create it if +it does not exist). Look at `src/ios/build/tools/setup-gn.config` for +available configuration options. + +From this point, you can either build from Xcode or from the command line using +`ninja`. `setup-gn.py` creates sub-directories named +`out/${configuration}-${platform}`, so for a `Debug` build for simulator use: + +```shell +$ ninja -C out/Debug-iphonesimulator gn_all +``` + +Note: you need to run `setup-gn.py` script every time one of the `BUILD.gn` +file is updated (either by you or after rebasing). If you forget to run it, +the list of targets and files in the Xcode solution may be stale. + +You can also follow the manual instructions on the +[Mac page](../mac_build_instructions.md), but make sure you set the +GN arg `target_os="ios"`. + +## Building for device + +To be able to build and run Chromium and the tests for devices, you need to +have an Apple developer account (a free one will work) and the appropriate +provisioning profiles, then configure the build to use them. + +### Code signing identity + +Please refer to the Apple documentation on how to get a code signing identity +and certificates. You can check that you have a code signing identity correctly +installed by running the following command. + +```shell +$ xcrun security find-identity -v -p codesigning + 1) 0123456789ABCDEF0123456789ABCDEF01234567 "iPhone Developer: someone@example.com (XXXXXXXXXX)" + 1 valid identities found +``` + +If the command output says you have zero valid identities, then you do not +have a code signing identity installed and need to get one from Apple. If +you have more than one identity, the build system may select the wrong one +automatically, and you can use the `ios_code_signing_identity` gn variable +to control which one to use by setting it to the identity hash, e.g. to +`"0123456789ABCDEF0123456789ABCDEF01234567"`. + +### Mobile provisioning profiles + +Once you have the code signing identity, you need to decide on a prefix +for the application bundle identifier. This is controlled by the gn variable +`ios_app_bundle_id_prefix` and usually corresponds to a reversed domain name +(the default value is `"org.chromium"`). + +You then need to request provisioning profiles from Apple for your devices +for the following bundle identifiers to build and run Chromium with these +application extensions: + +- `${prefix}.chrome.ios.herebedragons` +- `${prefix}.chrome.ios.herebedragons.ShareExtension` +- `${prefix}.chrome.ios.herebedragons.TodayExtension` + +All these certificates need to have the "App Groups" +(`com.apple.security.application-groups`) capability enabled for +the following groups: + +- `group.${prefix}.chrome` +- `group.${prefix}.common` + +The `group.${prefix}.chrome` is only shared by Chromium and its extensions +to share files and configurations while the `group.${prefix}.common` is shared +with Chromium and other applications from the same organisation and can be used +to send commands to Chromium. + +### Mobile provisioning profiles for tests + +In addition to that, you need provisioning profiles for the individual test +suites that you want to run. Their bundle identifier depends on whether the +gn variable `ios_automatically_manage_certs` is set to true (the default) +or false. + +If set to true, then you just need a provisioning profile for the bundle +identifier `${prefix}.gtest.generic-unit-test` but you can only have a +single test application installed on the device (all the test application +will share the same bundle identifier). + +If set to false, then you need a different provisioning profile for each +test application. Those provisioning profile will have a bundle identifier +matching the following pattern `${prefix}.gtest.${test-suite-name}` where +`${test-suite-name}` is the name of the test suite with underscores changed +to dashes (e.g. `base_unittests` app will use `${prefix}.gest.base-unittests` +as bundle identifier). + +To be able to run the EarlGrey tests on a device, you'll need two provisioning +profiles for EarlGrey and OCHamcrest frameworks: + +- `${prefix}.test.OCHamcrest` +- `${prefix}.test.EarlGrey` + +In addition to that, then you'll need one additional provisioning profile for +the XCTest module too. This module bundle identifier depends on whether the +gn variable `ios_automatically_manage_certs` is set to true or false. If set +to true, then `${prefix}.test.gtest.generic-unit-test.generic-unit-test-module` +will be used, otherwise it will match the following pattern: +`${prefix}.test.${test-suite-name}.${test-suite-name}-module`. + +### Other applications + +Other applications like `ios_web_shell` usually will require mobile provisioning +profiles with bundle identifiers that may usually match the following pattern +`${prefix}.${application-name}` and may require specific capabilities. + +Generally, if the mobile provisioning profile is missing then the code signing +step will fail and will print the bundle identifier of the bundle that could not +be signed on the command line, e.g.: + +```shell +$ ninja -C out/Debug-iphoneos ios_web_shell +ninja: Entering directory `out/Debug-iphoneos' +FAILED: ios_web_shell.app/ios_web_shell ios_web_shell.app/_CodeSignature/CodeResources ios_web_shell.app/embedded.mobileprovision +python ../../build/config/ios/codesign.py code-sign-bundle -t=iphoneos -i=0123456789ABCDEF0123456789ABCDEF01234567 -e=../../build/config/ios/entitlements.plist -b=obj/ios/web/shell/ios_web_shell ios_web_shell.app +Error: no mobile provisioning profile found for "org.chromium.ios-web-shell". +ninja: build stopped: subcommand failed. +``` + +Here, the build is failing because there are no mobile provisioning profiles +installed that could sign the `ios_web_shell.app` bundle with the identity +`0123456789ABCDEF0123456789ABCDEF01234567`. To fix the build, you'll need to +request such a mobile provisioning profile from Apple. + +You can inspect the file passed via the `-e` flag to the `codesign.py` script +to check which capabilites are required for the mobile provisioning profile +(e.g. `src/build/config/ios/entitlements.plist` for the above build error, +remember that the paths are relative to the build directory, not to the source +directory). + +If the required capabilities are not enabled on the mobile provisioning profile, +then it will be impossible to install the application on a device (Xcode will +display an error stating that "The application was signed with invalid +entitlements"). + +## Running apps from the commandline + +Any target that is built and runs on the bots (see [below](#Troubleshooting)) +should run successfully in a local build. To run in the simulator from the +command line, you can use `iossim`. For example, to run a debug build of +`Chromium`: + +```shell +$ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/Chromium.app +``` + +## Update your checkout + +To update an existing checkout, you can run + +```shell +$ git rebase-update +$ gclient sync +``` + +The first command updates the primary Chromium source repository and rebases +any of your local branches on top of tip-of-tree (aka the Git branch +`origin/master`). If you don't want to use this script, you can also just use +`git pull` or other common Git commands to update the repo. + +The second command syncs dependencies to the appropriate versions and re-runs +hooks as needed. + +## Tips, tricks, and troubleshooting + +If you have problems building, join us in `#chromium` on `irc.freenode.net` and +ask there. As mentioned above, be sure that the +[waterfall](https://build.chromium.org/buildbot/waterfall/) is green and the tree +is open before checking out. This will increase your chances of success. + +### Improving performance of `git status` + +`git status` is used frequently to determine the status of your checkout. Due +to the large number of files in Chromium's checkout, `git status` performance +can be quite variable. Increasing the system's vnode cache appears to help. +By default, this command: + +```shell +$ sysctl -a | egrep kern\..*vnodes +``` + +Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this +setting: + +```shell +$ sudo sysctl kern.maxvnodes=$((512*1024)) +``` + +Higher values may be appropriate if you routinely move between different +Chromium checkouts. This setting will reset on reboot, the startup setting can +be set in `/etc/sysctl.conf`: + +```shell +$ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf +``` + +Or edit the file directly. + +If `git --version` reports 2.6 or higher, the following may also improve +performance of `git status`: + +```shell +$ git update-index --untracked-cache +``` + +### Xcode license agreement + +If you're getting the error + +> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as +> root via sudo. + +the Xcode license hasn't been accepted yet which (contrary to the message) any +user can do by running: + +```shell +$ xcodebuild -license +``` + +Only accepting for all users of the machine requires root: + +```shell +$ sudo xcodebuild -license +``` diff --git a/docs/ios/infra.md b/docs/ios/infra.md new file mode 100644 index 00000000000000..80a1303dc4ccc1 --- /dev/null +++ b/docs/ios/infra.md @@ -0,0 +1,367 @@ +# Continuous build and test infrastructure for Chromium for iOS + +See the [instructions] for how to check out and build Chromium for iOS. + +The Chromium projects use buildbot for continuous integration. This doc starts +with an overview of the system, then gives detailed explanations about each +part. + +[TOC] + +## Overview + +Commits are made using the [commit queue], which triggers a series of try jobs +to compile and test the proposed patch against Chromium tip of tree before +actually making the commit. If the try jobs succeed the patch is committed. A +newly committed change triggers the builders (or "bots") to compile and test +the change again. + +## Bots + +Bots are slaves attached to a buildbot master (or "waterfall"). A buildbot +master is a server which polls for commits to a repository and triggers workers +to compile and test new commits whenever they are detected. [chromium.mac] is +the main waterfall for Mac desktop and iOS. [tryserver.chromium.mac] serves +as the try server for Mac desktop and iOS. + +The bots know how to check out a given revision of Chromium, compile, and test. + +### Code location + +#### Master configs + +The masters are configured in [tools/build], a separate repository which +contains various infra-related scripts. + +#### Pollers + +[chromium.mac] uses a `GitilesPoller` which polls the Chromium repository for +new commits using the [gitiles] interface. When a new commit is detected, the +bots are triggered. + +#### Recipes + +The bots run [recipes], which are scripts that specify their sequence of steps +located in [tools/build]. An iOS-specific [recipe module] contains common +functionality that the various [iOS recipes] use. + +#### Configs + +Because the recipes live in another repository, changes to the recipes don't +go through the Chromium [commit queue] and aren't tested on the [try server]. +In order to allow bot changes to be tested by the commit queue, the recipes +for iOS are generic instead of bot-specific, and rely on configuration files +which live in master-specific JSON config files located in [src/ios/build/bots]. +These configs define the `gn_args` to use during compilation as well as the +tests to run. + +#### Scripts + +The [test runner] is the script which installs and runs the tests, interprets +the results, and collects any files emitted by the test ("test data"). It can +be found in [src/ios/build/bots/scripts], which means changes to the test runner +can be tested on the [try server]. + +### Compiling with goma + +Goma is the distributed build system used by Chromium. It reduces compilation +time by avoiding recompilation of objects which have already been compiled +elsewhere. + +### Testing with swarming + +Tests run on [swarming], a distributed test system used by Chromium. After +compilation, configured tests will be zipped up along with their necessary +dependencies ("isolated") and sent to the [swarming server] for execution. The +server issues tasks to its attached workers for execution. The bots themselves +don't run any tests, they trigger tests to be run remotely on the swarming +server, then wait and display the results. This allows multiple tests to be +executed in parallel. + +## Try bots + +Try bots are bots which test proposed patches which are not yet committed. + +Request [try job access] in order to trigger try jobs against your patch. The +relevant try bots for an iOS patch are `ios-device`, `ios-device-xcode-clang`, +`ios-simulator`, and `ios-simulator-xcode-clang`. These bots can be found on +the Mac-specific [try server]. A try job is said to succeed when the build +passes (i.e. when the bot successfully compiles and tests the patch). + +`ios-device` and `ios-device-xcode-clang` both compile for the iOS device +architecture (ARM), and neither run any tests. A build is considered successful +so long as compilation is successful. + +`ios-simulator` and `ios-simulator-xcode-clang` both compile for the iOS +simulator architecture (x86), and run tests in the iOS [simulator]. A build is +considered successful when both compilation and all configured test succeed. + +`ios-device` and `ios-simulator` both compile using the version of [clang] +defined by the `CLANG_REVISION` in the Chromium tree. + +`ios-device-xcode-clang` and `ios-simulator-xcode-clang` both compile using the +version of clang that ships with Xcode. + +### Scheduling try jobs using buildbucket + +Triggering a try job and collecting its results is accomplished using +[buildbucket]. The service allows for build requests to be put into buckets. A +request in this context is a set of properties indicating things such as where +to get the patch. The try bots are set up to poll a particular bucket for build +requests which they execute and post the results of. + +### Compiling with the analyzer + +In addition to goma, the try bots use another time-saving mechanism called the +[analyzer] to determine the subset of compilation targets affected by the patch +that need to be compiled in order to run the affected tests. If a patch is +determined not to affect a certain test target, compilation and execution of the +test target will be skipped. + +## Configuring the bots + +See the [configs code location](#Configs) for where to find the config files for +the bots. The config files are JSON which describe how the bot should compile +and which tests it should run. The config files are located in the configs +directory. The configs directory contains a named directory for each master. For +example: +```shell +$ ls ios/build/bots +OWNERS scripts tests chromium.fyi chromium.mac +``` +In this case, configs are defined for iOS bots on [chromium.fyi] and +[chromium.mac]. Inside each master-specific directory are JSON config files +named after each bot. For example: +```shell +$ ls ios/build/bots/chromium.mac +ios-device.json ios-simulator.json +``` +The `ios-device` bot on [chromium.mac] will read its configuration from +`chromium.mac/ios-device.json` in the configs directory. + +### Example + +```json +{ + "comments": [ + "Sample config for a bot." + ], + "gn_args": [ + "is_debug=true", + "target_cpu=\"x64\"" + ], + "tests": [ + { + "app": "ios_chrome_unittests", + "device type": "iPhone 5s", + "os": "10.0", + "xcode version": "8.0" + } + ] +} +``` +The `comments` key is optional and defines a list of strings which can be used +to annotate the config. You may want to explain why the bot exists and what it's +doing, particularly if there are extensive and atypical `gn_args`. + +The `gn_args` key is a required list of arguments to pass to [GN] to generate +the build files. Two GN args are required, `is_debug` and `target_cpu`. Use +`is_debug` to define whether to compile for Debug or Release, and `target_cpu` +to define whether to compile for x86, x64, arm, or arm64. The iOS bots typically +perform Debug builds for x86 and x64, and Release builds for arm and arm64. An +x86/x64 build can only be tested on the [iOS simulator], while an arm/arm64 +build can only be tested on a physical device. + +Since Chromium for iOS is shipped as a [universal binary], it's also fairly +common to set `additional_target_cpus`. For simulator builds, we typically set: +```json +"gn_args": [ + "additional_target_cpus=[\"x86\"]", + "is_debug=true", + "target_cpu=\"x64\"" +] +``` +This builds universal binaries which run in 32-bit mode on 32-bit simulators and +64-bit mode on 64-bit simulators. For device builds we typically set: +```json +"gn_args": [ + "additional_target_cpus=[\"arm\"]", + "is_debug=false", + "target_cpu=\"arm64\"" +] +``` +In order to build universal binaries which run in 32-bit mode on 32-bit devices +and 64-bit mode on 64-bit devices. + +The `tests` key is an optional list of dictionaries defining tests to run. There +are two types of test dictionary, `app` and `include`. An `app` dict defines a +specific compiled app to run, for example: +```json +"tests": [ + { + "app": "ios_chrome_unittests", + "device type": "iPhone 5s", + "os": "10.0", + "xcode version": "8.0" + } +] +``` +This dict says to run `ios_chrome_unittests` on an `iPhone 5s` running iOS +`10.0` using Xcode `8.0`. A test dict may optionally define a list of `test +args`, which are arguments to pass directly to the test on the command line, +and it may define a boolean value `xctest` to indicate whether the test is an +[xctest] \(default if unspecified is `false`\). For example: +```json +"tests": [ + { + "app": "ios_chrome_unittests", + "device type": "iPhone 5s", + "os": "10.0", + "test args": [ + "--foo", + "--bar" + ], + "xcode version": "8.0" + }, + { + "app": "ios_chrome_integration_egtests", + "device type": "iPhone 5s", + "os": "10.0", + "xcode version": "8.0", + "xctest": true + } +] +``` +This defines two tests to run, first `ios_chrome_unittests` will be run with +`--foo` and `--bar` passed directly to the test on the command line. Next, +`ios_chrome_integration_egtests` will be run as an xctest. `"xctest": true` +must be specified for all xctests, it is an error to try and launch an xctest as +a regular test. + +An `include` dict defines a list of tests to import from the `tests` +subdirectory in the configs directory. For example: +```json +"tests": [ + { + "include": "common_tests.json", + "device type": "iPhone 5s", + "os": "10.0", + "xcode version": "8.0" + } +] +``` +This dict says to import the list of tests from the `tests` subdirectory and run +each one on an `iPhone 5s` running iOS `10.0` using Xcode `8.0`. Here's what +`common_tests.json` might look like: +```json +"tests": [ + { + "app": "ios_chrome_unittests" + }, + { + "app": "ios_net_unittests" + }, + { + "app": "ios_web_unittests" + }, +] +``` +Includes may contain other keys besides `app` which can then be omitted in the +bot config. For example if `common_tests.json` specifies: +```json +"tests": [ + { + "app": "ios_chrome_integration_egtests", + "xctest": true, + "xcode version": "8.0" + } +] +``` +Then the bot config may omit the `xctest` or `xcode version` keys, for example: +```json +{ + "comments": [ + "Sample config for a bot." + ], + "gn_args": [ + "is_debug=true", + "target_cpu=\"x64\"" + ], + "tests": [ + { + "include": "common_tests.json", + "device type": "iPhone 5s", + "os": "10.0" + } + ] +} +``` +Includes are not recursive, so `common_tests.json` may not itself include any +`include` dicts. + +### Uploading compiled artifacts from a bot + +A bot may be configured to upload compiled artifacts. This is defined by the +`upload` key. For example: +```json +{ + "comments": [ + "Sample config for a bot which uploads artifacts." + ], + "gn_args": [ + "is_debug=true", + "target_cpu=\"x64\"" + ], + "upload": [ + { + "artifact": "Chromium.breakpad", + "bucket": "my-gcs-bucket", + }, + { + "artifact": "Chromium.app", + "bucket": "my-gcs-bucket", + "compress": true, + }, + { + "artifact": "Chromium.breakpad", + "symupload": true, + } + ] +} +``` +After compilation, the bot will upload three artifacts. First the +`Chromium.breakpad` symbols will be uploaded to +`gs://my-gcs-bucket///Chromium.breakpad`. Next +`Chromium.app` will be tarred, gzipped, and uploaded to +`gs://my-gcs-bucket///Chromium.tar.gz`. Finally +the `Chromium.breakpad` symbols will be uploaded to the [breakpad] crash +reporting server where they can be used to symbolicate stack traces. + +If `artifact` is a directory, you must specify `"compress": true`. + +[analyzer]: ../../tools/mb +[breakpad]: https://chromium.googlesource.com/breakpad/breakpad +[buildbucket]: https://cr-buildbucket.appspot.com +[chromium.fyi]: https://build.chromium.org/p/chromium.fyi/waterfall +[chromium.mac]: https://build.chromium.org/p/chromium.mac +[clang]: ../../tools/clang +[commit queue]: https://dev.chromium.org/developers/testing/commit-queue +[gitiles]: https://gerrit.googlesource.com/gitiles +[GN]: ../../tools/gn +[instructions]: ./build_instructions.md +[iOS recipes]: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/slave/recipes/ios +[iOS simulator]: ../../testing/iossim +[recipe module]: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/slave/recipe_modules/ios +[recipes]: https://chromium.googlesource.com/infra/infra/+/HEAD/doc/users/recipes.md +[simulator]: https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/Introduction/Introduction.html +[src/ios/build/bots]: ../../ios/build/bots +[src/ios/build/bots/scripts]: ../../ios/build/bots/scripts +[swarming]: https://github.com/luci/luci-py/tree/master/appengine/swarming +[swarming server]: https://chromium-swarm.appspot.com +[test runner]: ../../ios/build/bots/scripts/test_runner.py +[tools/build]: https://chromium.googlesource.com/chromium/tools/build +[try job access]: https://www.chromium.org/getting-involved/become-a-committer#TOC-Try-job-access +[try server]: https://build.chromium.org/p/tryserver.chromium.mac/waterfall +[tryserver.chromium.mac]: https://build.chromium.org/p/tryserver.chromium.mac/waterfall +[universal binary]: https://en.wikipedia.org/wiki/Universal_binary +[xctest]: https://developer.apple.com/reference/xctest diff --git a/docs/ios/voiceover.md b/docs/ios/voiceover.md new file mode 100644 index 00000000000000..3f8a5cdf798907 --- /dev/null +++ b/docs/ios/voiceover.md @@ -0,0 +1,48 @@ +# VoiceOver + +VoiceOver is an Accessibility feature available on Apple platforms. It provides +an interface between your app and your blind or low-vision users. In short, it's +a screen reader. + +## Overview + +[Activating VoiceOver](#Activate-VoiceOver) fundamentally changes the touch +interface of an iOS device, so when you activate it, you need to know these +basic commands to navigate: + +- VoiceOver focuses an item on the screen and speaks it to the user. +- To navigate between items, you can either flick left/right to go to the + previous/next item, or you can drag your finger around the screen. +- Double tapping anywhere on the screen activates the item (no need to double + tap exactly on the item on the screen). +- Items have a label (describing the item) and can have among others: + - traits (describing the item: a header, a button, selection state, etc.); + - a hint (describing how to interact with the item). + +The following video is a great summary. The content is succinct, high quality +and up-to-date, even though the video quality is low and the demo is on an +iPhone 3GS. + +[![Video screenshot]][Video link] + +## Activate VoiceOver + +Go to `Settings > General > Accessibility > VoiceOver` and toggle the top +switch. + +Alternatively, if you are activating/deactivating VoiceOver often, I'd advise +to set it as the Accessibility Shortcut. When enabled, a triple tap on the Home +button will toggle VoiceOver ON and OFF from anywhere. +``` +Settings > General > Accessibility > Accessibility Shortcut +``` + +## Additional Resources + +- [Apple presentation of VoiceOver] +- [AppleVis intro to VoiceOver] + +[Apple presentation of VoiceOver]: http://www.apple.com/accessibility/osx/voiceover/ +[AppleVis intro to VoiceOver]: http://www.applevis.com/guides/ios-miscellaneous-voiceover/intro-ios-accessibility-blind-and-low-vision-users +[Video screenshot]: https://img.youtube.com/vi/WxQ2qKShvmc/0.jpg +[Video link]: https://www.youtube.com/watch?v=WxQ2qKShvmc "iPhone VoiceOver Function For People With Disabilities" diff --git a/docs/ios_build_instructions.md b/docs/ios_build_instructions.md index 2d7a013236fb38..71a9e4c314c57d 100644 --- a/docs/ios_build_instructions.md +++ b/docs/ios_build_instructions.md @@ -1,315 +1,5 @@ -# Checking out and building Chromium for iOS +# This document has moved -There are instructions for other platforms linked from the -[get the code](get_the_code.md) page. +NOTE: Please update your link to this file! -## Instructions for Google Employees - -Are you a Google employee? See -[go/building-chrome](https://goto.google.com/building-chrome) instead. - -[TOC] - -## System requirements - -* A 64-bit Mac running 10.11+. -* [Xcode](https://developer.apple.com/xcode) 8.0+. -* The OS X 10.10 SDK. Run - - ```shell - $ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs - ``` - - to check whether you have it. Building with the 10.11 SDK works too, but - the releases currently use the 10.10 SDK. -* The current version of the JDK (required for the Closure compiler). - -## Install `depot_tools` - -Clone the `depot_tools` repository: - -```shell -$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git -``` - -Add `depot_tools` to the end of your PATH (you will probably want to put this -in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to -`/path/to/depot_tools`: - -```shell -$ export PATH="$PATH:/path/to/depot_tools" -``` - -## Get the code - -Create a `chromium` directory for the checkout and change to it (you can call -this whatever you like and put it wherever you like, as -long as the full path has no spaces): - -```shell -$ mkdir chromium && cd chromium -``` - -Run the `fetch` tool from `depot_tools` to check out the code and its -dependencies. - -```shell -$ fetch ios -``` - -If you don't want the full repo history, you can save a lot of time by -adding the `--no-history` flag to `fetch`. - -Expect the command to take 30 minutes on even a fast connection, and many -hours on slower ones. - -When `fetch` completes, it will have created a hidden `.gclient` file and a -directory called `src` in the working directory. The remaining instructions -assume you have switched to the `src` directory: - -```shell -$ cd src -``` - -*Optional*: You can also [install API -keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your -build to talk to some Google services, but this is not necessary for most -development and testing purposes. - -## Setting up the build - -Since the iOS build is a bit more complicated than a desktop build, we provide -`ios/build/tools/setup-gn.py`, which will create four appropriately configured -build directories under `out` for Release and Debug device and simulator -builds, and generates an appropriate Xcode workspace as well. - -This script is run automatically by fetch (as part of `gclient runhooks`). - -You can customize the build by editing the file `$HOME/.setup-gn` (create it if -it does not exist). Look at `src/ios/build/tools/setup-gn.config` for -available configuration options. - -From this point, you can either build from Xcode or from the command line using -`ninja`. `setup-gn.py` creates sub-directories named -`out/${configuration}-${platform}`, so for a `Debug` build for simulator use: - -```shell -$ ninja -C out/Debug-iphonesimulator gn_all -``` - -Note: you need to run `setup-gn.py` script every time one of the `BUILD.gn` -file is updated (either by you or after rebasing). If you forget to run it, -the list of targets and files in the Xcode solution may be stale. - -You can also follow the manual instructions on the -[Mac page](mac_build_instructions.md), but make sure you set the -GN arg `target_os="ios"`. - -## Building for device - -To be able to build and run Chromium and the tests for devices, you need to -have an Apple developer account (a free one will work) and the appropriate -provisioning profiles, then configure the build to use them. - -### Code signing identity - -Please refer to the Apple documentation on how to get a code signing identity -and certificates. You can check that you have a code signing identity correctly -installed by running the following command. - -```shell -$ xcrun security find-identity -v -p codesigning - 1) 0123456789ABCDEF0123456789ABCDEF01234567 "iPhone Developer: someone@example.com (XXXXXXXXXX)" - 1 valid identities found -``` - -If the command output says you have zero valid identities, then you do not -have a code signing identity installed and need to get one from Apple. If -you have more than one identity, the build system may select the wrong one -automatically, and you can use the `ios_code_signing_identity` gn variable -to control which one to use by setting it to the identity hash, e.g. to -`"0123456789ABCDEF0123456789ABCDEF01234567"`. - -### Mobile provisioning profiles - -Once you have the code signing identity, you need to decide on a prefix -for the application bundle identifier. This is controlled by the gn variable -`ios_app_bundle_id_prefix` and usually corresponds to a reversed domain name -(the default value is `"org.chromium"`). - -You then need to request provisioning profiles from Apple for your devices -for the following bundle identifiers to build and run Chromium with these -application extensions: - -- `${prefix}.chrome.ios.herebedragons` -- `${prefix}.chrome.ios.herebedragons.ShareExtension` -- `${prefix}.chrome.ios.herebedragons.TodayExtension` - -All these certificates need to have the "App Groups" -(`com.apple.security.application-groups`) capability enabled for -the following groups: - -- `group.${prefix}.chrome` -- `group.${prefix}.common` - -The `group.${prefix}.chrome` is only shared by Chromium and its extensions -to share files and configurations while the `group.${prefix}.common` is shared -with Chromium and other applications from the same organisation and can be used -to send commands to Chromium. - -### Mobile provisioning profiles for tests - -In addition to that, you need provisioning profiles for the individual test -suites that you want to run. Their bundle identifier depends on whether the -gn variable `ios_automatically_manage_certs` is set to true (the default) -or false. - -If set to true, then you just need a provisioning profile for the bundle -identifier `${prefix}.gtest.generic-unit-test` but you can only have a -single test application installed on the device (all the test application -will share the same bundle identifier). - -If set to false, then you need a different provisioning profile for each -test application. Those provisioning profile will have a bundle identifier -matching the following pattern `${prefix}.gtest.${test-suite-name}` where -`${test-suite-name}` is the name of the test suite with underscores changed -to dashes (e.g. `base_unittests` app will use `${prefix}.gest.base-unittests` -as bundle identifier). - -To be able to run the EarlGrey tests on a device, you'll need two provisioning -profiles for EarlGrey and OCHamcrest frameworks: - -- `${prefix}.test.OCHamcrest` -- `${prefix}.test.EarlGrey` - -In addition to that, then you'll need one additional provisioning profile for -the XCTest module too. This module bundle identifier depends on whether the -gn variable `ios_automatically_manage_certs` is set to true or false. If set -to true, then `${prefix}.test.gtest.generic-unit-test.generic-unit-test-module` -will be used, otherwise it will match the following pattern: -`${prefix}.test.${test-suite-name}.${test-suite-name}-module`. - -### Other applications - -Other applications like `ios_web_shell` usually will require mobile provisioning -profiles with bundle identifiers that may usually match the following pattern -`${prefix}.${application-name}` and may require specific capabilities. - -Generally, if the mobile provisioning profile is missing then the code signing -step will fail and will print the bundle identifier of the bundle that could not -be signed on the command line, e.g.: - -```shell -$ ninja -C out/Debug-iphoneos ios_web_shell -ninja: Entering directory `out/Debug-iphoneos' -FAILED: ios_web_shell.app/ios_web_shell ios_web_shell.app/_CodeSignature/CodeResources ios_web_shell.app/embedded.mobileprovision -python ../../build/config/ios/codesign.py code-sign-bundle -t=iphoneos -i=0123456789ABCDEF0123456789ABCDEF01234567 -e=../../build/config/ios/entitlements.plist -b=obj/ios/web/shell/ios_web_shell ios_web_shell.app -Error: no mobile provisioning profile found for "org.chromium.ios-web-shell". -ninja: build stopped: subcommand failed. -``` - -Here, the build is failing because there are no mobile provisioning profiles -installed that could sign the `ios_web_shell.app` bundle with the identity -`0123456789ABCDEF0123456789ABCDEF01234567`. To fix the build, you'll need to -request such a mobile provisioning profile from Apple. - -You can inspect the file passed via the `-e` flag to the `codesign.py` script -to check which capabilites are required for the mobile provisioning profile -(e.g. `src/build/config/ios/entitlements.plist` for the above build error, -remember that the paths are relative to the build directory, not to the source -directory). - -If the required capabilities are not enabled on the mobile provisioning profile, -then it will be impossible to install the application on a device (Xcode will -display an error stating that "The application was signed with invalid -entitlements"). - -## Running apps from the commandline - -Any target that is built and runs on the bots (see [below](#Troubleshooting)) -should run successfully in a local build. To run in the simulator from the -command line, you can use `iossim`. For example, to run a debug build of -`Chromium`: - -```shell -$ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/Chromium.app -``` - -## Update your checkout - -To update an existing checkout, you can run - -```shell -$ git rebase-update -$ gclient sync -``` - -The first command updates the primary Chromium source repository and rebases -any of your local branches on top of tip-of-tree (aka the Git branch -`origin/master`). If you don't want to use this script, you can also just use -`git pull` or other common Git commands to update the repo. - -The second command syncs dependencies to the appropriate versions and re-runs -hooks as needed. - -## Tips, tricks, and troubleshooting - -If you have problems building, join us in `#chromium` on `irc.freenode.net` and -ask there. As mentioned above, be sure that the -[waterfall](https://build.chromium.org/buildbot/waterfall/) is green and the tree -is open before checking out. This will increase your chances of success. - -### Improving performance of `git status` - -`git status` is used frequently to determine the status of your checkout. Due -to the large number of files in Chromium's checkout, `git status` performance -can be quite variable. Increasing the system's vnode cache appears to help. -By default, this command: - -```shell -$ sysctl -a | egrep kern\..*vnodes -``` - -Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this -setting: - -```shell -$ sudo sysctl kern.maxvnodes=$((512*1024)) -``` - -Higher values may be appropriate if you routinely move between different -Chromium checkouts. This setting will reset on reboot, the startup setting can -be set in `/etc/sysctl.conf`: - -```shell -$ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf -``` - -Or edit the file directly. - -If `git --version` reports 2.6 or higher, the following may also improve -performance of `git status`: - -```shell -$ git update-index --untracked-cache -``` - -### Xcode license agreement - -If you're getting the error - -> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as -> root via sudo. - -the Xcode license hasn't been accepted yet which (contrary to the message) any -user can do by running: - -```shell -$ xcodebuild -license -``` - -Only accepting for all users of the machine requires root: - -```shell -$ sudo xcodebuild -license -``` +The new file location is [//docs/ios/build_instructions.md](ios/build_instructions.md) \ No newline at end of file diff --git a/docs/ios_infra.md b/docs/ios_infra.md index 3ab0d7f299ce99..7fdef0d8c95a30 100644 --- a/docs/ios_infra.md +++ b/docs/ios_infra.md @@ -1,367 +1,5 @@ -# Continuous build and test infrastructure for Chromium for iOS +# This document has moved -See the [instructions] for how to check out and build Chromium for iOS. +NOTE: Please update your link to this file! -The Chromium projects use buildbot for continuous integration. This doc starts -with an overview of the system, then gives detailed explanations about each -part. - -[TOC] - -## Overview - -Commits are made using the [commit queue], which triggers a series of try jobs -to compile and test the proposed patch against Chromium tip of tree before -actually making the commit. If the try jobs succeed the patch is committed. A -newly committed change triggers the builders (or "bots") to compile and test -the change again. - -## Bots - -Bots are slaves attached to a buildbot master (or "waterfall"). A buildbot -master is a server which polls for commits to a repository and triggers workers -to compile and test new commits whenever they are detected. [chromium.mac] is -the main waterfall for Mac desktop and iOS. [tryserver.chromium.mac] serves -as the try server for Mac desktop and iOS. - -The bots know how to check out a given revision of Chromium, compile, and test. - -### Code location - -#### Master configs - -The masters are configured in [tools/build], a separate repository which -contains various infra-related scripts. - -#### Pollers - -[chromium.mac] uses a `GitilesPoller` which polls the Chromium repository for -new commits using the [gitiles] interface. When a new commit is detected, the -bots are triggered. - -#### Recipes - -The bots run [recipes], which are scripts that specify their sequence of steps -located in [tools/build]. An iOS-specific [recipe module] contains common -functionality that the various [iOS recipes] use. - -#### Configs - -Because the recipes live in another repository, changes to the recipes don't -go through the Chromium [commit queue] and aren't tested on the [try server]. -In order to allow bot changes to be tested by the commit queue, the recipes -for iOS are generic instead of bot-specific, and rely on configuration files -which live in master-specific JSON config files located in [src/ios/build/bots]. -These configs define the `gn_args` to use during compilation as well as the -tests to run. - -#### Scripts - -The [test runner] is the script which installs and runs the tests, interprets -the results, and collects any files emitted by the test ("test data"). It can -be found in [src/ios/build/bots/scripts], which means changes to the test runner -can be tested on the [try server]. - -### Compiling with goma - -Goma is the distributed build system used by Chromium. It reduces compilation -time by avoiding recompilation of objects which have already been compiled -elsewhere. - -### Testing with swarming - -Tests run on [swarming], a distributed test system used by Chromium. After -compilation, configured tests will be zipped up along with their necessary -dependencies ("isolated") and sent to the [swarming server] for execution. The -server issues tasks to its attached workers for execution. The bots themselves -don't run any tests, they trigger tests to be run remotely on the swarming -server, then wait and display the results. This allows multiple tests to be -executed in parallel. - -## Try bots - -Try bots are bots which test proposed patches which are not yet committed. - -Request [try job access] in order to trigger try jobs against your patch. The -relevant try bots for an iOS patch are `ios-device`, `ios-device-xcode-clang`, -`ios-simulator`, and `ios-simulator-xcode-clang`. These bots can be found on -the Mac-specific [try server]. A try job is said to succeed when the build -passes (i.e. when the bot successfully compiles and tests the patch). - -`ios-device` and `ios-device-xcode-clang` both compile for the iOS device -architecture (ARM), and neither run any tests. A build is considered successful -so long as compilation is successful. - -`ios-simulator` and `ios-simulator-xcode-clang` both compile for the iOS -simulator architecture (x86), and run tests in the iOS [simulator]. A build is -considered successful when both compilation and all configured test succeed. - -`ios-device` and `ios-simulator` both compile using the version of [clang] -defined by the `CLANG_REVISION` in the Chromium tree. - -`ios-device-xcode-clang` and `ios-simulator-xcode-clang` both compile using the -version of clang that ships with Xcode. - -### Scheduling try jobs using buildbucket - -Triggering a try job and collecting its results is accomplished using -[buildbucket]. The service allows for build requests to be put into buckets. A -request in this context is a set of properties indicating things such as where -to get the patch. The try bots are set up to poll a particular bucket for build -requests which they execute and post the results of. - -### Compiling with the analyzer - -In addition to goma, the try bots use another time-saving mechanism called the -[analyzer] to determine the subset of compilation targets affected by the patch -that need to be compiled in order to run the affected tests. If a patch is -determined not to affect a certain test target, compilation and execution of the -test target will be skipped. - -## Configuring the bots - -See the [configs code location](#Configs) for where to find the config files for -the bots. The config files are JSON which describe how the bot should compile -and which tests it should run. The config files are located in the configs -directory. The configs directory contains a named directory for each master. For -example: -```shell -$ ls ios/build/bots -OWNERS scripts tests chromium.fyi chromium.mac -``` -In this case, configs are defined for iOS bots on [chromium.fyi] and -[chromium.mac]. Inside each master-specific directory are JSON config files -named after each bot. For example: -```shell -$ ls ios/build/bots/chromium.mac -ios-device.json ios-simulator.json -``` -The `ios-device` bot on [chromium.mac] will read its configuration from -`chromium.mac/ios-device.json` in the configs directory. - -### Example - -```json -{ - "comments": [ - "Sample config for a bot." - ], - "gn_args": [ - "is_debug=true", - "target_cpu=\"x64\"" - ], - "tests": [ - { - "app": "ios_chrome_unittests", - "device type": "iPhone 5s", - "os": "10.0", - "xcode version": "8.0" - } - ] -} -``` -The `comments` key is optional and defines a list of strings which can be used -to annotate the config. You may want to explain why the bot exists and what it's -doing, particularly if there are extensive and atypical `gn_args`. - -The `gn_args` key is a required list of arguments to pass to [GN] to generate -the build files. Two GN args are required, `is_debug` and `target_cpu`. Use -`is_debug` to define whether to compile for Debug or Release, and `target_cpu` -to define whether to compile for x86, x64, arm, or arm64. The iOS bots typically -perform Debug builds for x86 and x64, and Release builds for arm and arm64. An -x86/x64 build can only be tested on the [iOS simulator], while an arm/arm64 -build can only be tested on a physical device. - -Since Chromium for iOS is shipped as a [universal binary], it's also fairly -common to set `additional_target_cpus`. For simulator builds, we typically set: -```json -"gn_args": [ - "additional_target_cpus=[\"x86\"]", - "is_debug=true", - "target_cpu=\"x64\"" -] -``` -This builds universal binaries which run in 32-bit mode on 32-bit simulators and -64-bit mode on 64-bit simulators. For device builds we typically set: -```json -"gn_args": [ - "additional_target_cpus=[\"arm\"]", - "is_debug=false", - "target_cpu=\"arm64\"" -] -``` -In order to build universal binaries which run in 32-bit mode on 32-bit devices -and 64-bit mode on 64-bit devices. - -The `tests` key is an optional list of dictionaries defining tests to run. There -are two types of test dictionary, `app` and `include`. An `app` dict defines a -specific compiled app to run, for example: -```json -"tests": [ - { - "app": "ios_chrome_unittests", - "device type": "iPhone 5s", - "os": "10.0", - "xcode version": "8.0" - } -] -``` -This dict says to run `ios_chrome_unittests` on an `iPhone 5s` running iOS -`10.0` using Xcode `8.0`. A test dict may optionally define a list of `test -args`, which are arguments to pass directly to the test on the command line, -and it may define a boolean value `xctest` to indicate whether the test is an -[xctest] \(default if unspecified is `false`\). For example: -```json -"tests": [ - { - "app": "ios_chrome_unittests", - "device type": "iPhone 5s", - "os": "10.0", - "test args": [ - "--foo", - "--bar" - ], - "xcode version": "8.0" - }, - { - "app": "ios_chrome_integration_egtests", - "device type": "iPhone 5s", - "os": "10.0", - "xcode version": "8.0", - "xctest": true - } -] -``` -This defines two tests to run, first `ios_chrome_unittests` will be run with -`--foo` and `--bar` passed directly to the test on the command line. Next, -`ios_chrome_integration_egtests` will be run as an xctest. `"xctest": true` -must be specified for all xctests, it is an error to try and launch an xctest as -a regular test. - -An `include` dict defines a list of tests to import from the `tests` -subdirectory in the configs directory. For example: -```json -"tests": [ - { - "include": "common_tests.json", - "device type": "iPhone 5s", - "os": "10.0", - "xcode version": "8.0" - } -] -``` -This dict says to import the list of tests from the `tests` subdirectory and run -each one on an `iPhone 5s` running iOS `10.0` using Xcode `8.0`. Here's what -`common_tests.json` might look like: -```json -"tests": [ - { - "app": "ios_chrome_unittests" - }, - { - "app": "ios_net_unittests" - }, - { - "app": "ios_web_unittests" - }, -] -``` -Includes may contain other keys besides `app` which can then be omitted in the -bot config. For example if `common_tests.json` specifies: -```json -"tests": [ - { - "app": "ios_chrome_integration_egtests", - "xctest": true, - "xcode version": "8.0" - } -] -``` -Then the bot config may omit the `xctest` or `xcode version` keys, for example: -```json -{ - "comments": [ - "Sample config for a bot." - ], - "gn_args": [ - "is_debug=true", - "target_cpu=\"x64\"" - ], - "tests": [ - { - "include": "common_tests.json", - "device type": "iPhone 5s", - "os": "10.0" - } - ] -} -``` -Includes are not recursive, so `common_tests.json` may not itself include any -`include` dicts. - -### Uploading compiled artifacts from a bot - -A bot may be configured to upload compiled artifacts. This is defined by the -`upload` key. For example: -```json -{ - "comments": [ - "Sample config for a bot which uploads artifacts." - ], - "gn_args": [ - "is_debug=true", - "target_cpu=\"x64\"" - ], - "upload": [ - { - "artifact": "Chromium.breakpad", - "bucket": "my-gcs-bucket", - }, - { - "artifact": "Chromium.app", - "bucket": "my-gcs-bucket", - "compress": true, - }, - { - "artifact": "Chromium.breakpad", - "symupload": true, - } - ] -} -``` -After compilation, the bot will upload three artifacts. First the -`Chromium.breakpad` symbols will be uploaded to -`gs://my-gcs-bucket///Chromium.breakpad`. Next -`Chromium.app` will be tarred, gzipped, and uploaded to -`gs://my-gcs-bucket///Chromium.tar.gz`. Finally -the `Chromium.breakpad` symbols will be uploaded to the [breakpad] crash -reporting server where they can be used to symbolicate stack traces. - -If `artifact` is a directory, you must specify `"compress": true`. - -[analyzer]: ../tools/mb -[breakpad]: https://chromium.googlesource.com/breakpad/breakpad -[buildbucket]: https://cr-buildbucket.appspot.com -[chromium.fyi]: https://build.chromium.org/p/chromium.fyi/waterfall -[chromium.mac]: https://build.chromium.org/p/chromium.mac -[clang]: ../tools/clang -[commit queue]: https://dev.chromium.org/developers/testing/commit-queue -[gitiles]: https://gerrit.googlesource.com/gitiles -[GN]: ../tools/gn -[instructions]: ./ios_build_instructions.md -[iOS recipes]: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/slave/recipes/ios -[iOS simulator]: ../testing/iossim -[recipe module]: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/slave/recipe_modules/ios -[recipes]: https://chromium.googlesource.com/infra/infra/+/HEAD/doc/users/recipes.md -[simulator]: https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/Introduction/Introduction.html -[src/ios/build/bots]: ../ios/build/bots -[src/ios/build/bots/scripts]: ../ios/build/bots/scripts -[swarming]: https://github.com/luci/luci-py/tree/master/appengine/swarming -[swarming server]: https://chromium-swarm.appspot.com -[test runner]: ../ios/build/bots/scripts/test_runner.py -[tools/build]: https://chromium.googlesource.com/chromium/tools/build -[try job access]: https://www.chromium.org/getting-involved/become-a-committer#TOC-Try-job-access -[try server]: https://build.chromium.org/p/tryserver.chromium.mac/waterfall -[tryserver.chromium.mac]: https://build.chromium.org/p/tryserver.chromium.mac/waterfall -[universal binary]: https://en.wikipedia.org/wiki/Universal_binary -[xctest]: https://developer.apple.com/reference/xctest +The new file location is [//docs/ios/infra.md](ios/infra.md) \ No newline at end of file diff --git a/docs/ios_voiceover.md b/docs/ios_voiceover.md index 3f8a5cdf798907..a217457554e941 100644 --- a/docs/ios_voiceover.md +++ b/docs/ios_voiceover.md @@ -1,48 +1,5 @@ -# VoiceOver +# This document has moved -VoiceOver is an Accessibility feature available on Apple platforms. It provides -an interface between your app and your blind or low-vision users. In short, it's -a screen reader. +NOTE: Please update your link to this file! -## Overview - -[Activating VoiceOver](#Activate-VoiceOver) fundamentally changes the touch -interface of an iOS device, so when you activate it, you need to know these -basic commands to navigate: - -- VoiceOver focuses an item on the screen and speaks it to the user. -- To navigate between items, you can either flick left/right to go to the - previous/next item, or you can drag your finger around the screen. -- Double tapping anywhere on the screen activates the item (no need to double - tap exactly on the item on the screen). -- Items have a label (describing the item) and can have among others: - - traits (describing the item: a header, a button, selection state, etc.); - - a hint (describing how to interact with the item). - -The following video is a great summary. The content is succinct, high quality -and up-to-date, even though the video quality is low and the demo is on an -iPhone 3GS. - -[![Video screenshot]][Video link] - -## Activate VoiceOver - -Go to `Settings > General > Accessibility > VoiceOver` and toggle the top -switch. - -Alternatively, if you are activating/deactivating VoiceOver often, I'd advise -to set it as the Accessibility Shortcut. When enabled, a triple tap on the Home -button will toggle VoiceOver ON and OFF from anywhere. -``` -Settings > General > Accessibility > Accessibility Shortcut -``` - -## Additional Resources - -- [Apple presentation of VoiceOver] -- [AppleVis intro to VoiceOver] - -[Apple presentation of VoiceOver]: http://www.apple.com/accessibility/osx/voiceover/ -[AppleVis intro to VoiceOver]: http://www.applevis.com/guides/ios-miscellaneous-voiceover/intro-ios-accessibility-blind-and-low-vision-users -[Video screenshot]: https://img.youtube.com/vi/WxQ2qKShvmc/0.jpg -[Video link]: https://www.youtube.com/watch?v=WxQ2qKShvmc "iPhone VoiceOver Function For People With Disabilities" +[The new file location is //docs/ios/voiceover.md](ios/voiceover.md) \ No newline at end of file