diff --git a/docs/developing/android.md b/docs/developing/android.md index d734f985a52..f5b5c0180cd 100644 --- a/docs/developing/android.md +++ b/docs/developing/android.md @@ -11,218 +11,28 @@ sidebar_label: Developing for Android /> -This guide covers how to run and debug Ionic apps on Android emulators and devices using [Capacitor](../reference/glossary.md#capacitor) or [Cordova](../reference/glossary.md#cordova). Android apps can be developed on Windows, macOS, and Linux. +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; -## Android Studio +:::info Looking for the legacy Android guide? -[Android Studio](https://developer.android.com/studio/) is the IDE for creating native Android apps. It includes the [Android SDK](../reference/glossary.md#android-sdk), which will need to be configured for use in the command line. +The Developing for Android guide has officially migrated to the [Capacitor documentation for Android](https://capacitorjs.com/docs/android). If you need to access the legacy documentation, you can find it under the [legacy developing for Android guide](/docs/v6/developing/android). -Android Studio is also used to [create Android virtual devices](android.md#creating-an-android-virtual-device), which are required for the Android emulator. Ionic apps can also be [launched to a device](android.md#set-up-an-android-device). - -:::note -We don't recommend using Android Studio for _developing_ Ionic apps. Instead, it should only really be used to build and run your apps for the native Android platform and to manage the Android SDK and virtual devices. -::: - -### Installing Android Studio - -Download Android Studio from the Android website. More detailed installation instructions can be found in the User Guide. - -### Installing the Android SDK - -Once installed, open Android Studio. The IDE should detect that the Android SDK needs to be installed. In the **SDK Components Setup** screen, finish installing the SDK. Keep note of the **Android SDK Location**. - -![Android Studio SDK Setup](/img/installation/android-studio-sdk-setup.png) - -By default, the latest stable SDK Platform is installed, which includes a collection of packages required to target that version of Android. - -To install system images and other minor SDK platform packages, you may need to ensure **Show Package Details** is checked at the bottom of the SDK Manager. -![Android Studio SDK Manager](/img/installation/android-studio-sdk.png) - -For future reference, the Android SDK can be managed with Android Studio from the context menu at the top right of the Android Studio welcome screen (select **SDK Manager**) or **Tools** » **SDK Manager** inside Android projects. - -### Configuring Command Line Tools - -The Android SDK ships with useful command-line tools. Before they can be used, some environment variables must be set. The following instructions are for macOS and Linux. For Windows, check the documentation on setting and persisting environment variables in terminal sessions. - -In `~/.bashrc`, `~/.bash_profile`, or similar shell startup scripts, make the following modifications: - -1. Set the `ANDROID_SDK_ROOT` environment variable. This path should be the **Android SDK Location** used in the previous section. To find the SDK Location in Android Studio, click **File** > **Project Structure**. Select **SDK Location** in the left pane. The path is shown under **Android SDK location**. - - ```shell - $ export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk - ``` - -2. Add the Android SDK command-line directories to `PATH`. Each directory corresponds to the category of command-line tool. - - ```shell-session - $ # avdmanager, sdkmanager - $ export PATH=$PATH:$ANDROID_SDK_ROOT/tools/bin - $ # adb, logcat - $ export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools - $ # emulator - $ export PATH=$PATH:$ANDROID_SDK_ROOT/emulator - ``` - - :::note - For `apksigner` and `zipalign`, `$ANDROID_SDK_ROOT/build-tools` must also be added to `PATH`. - ::: - -### Creating an Android Virtual Device - -Android Virtual Devices (AVDs) are blueprints that the Android emulator uses to run the Android OS. The following documentation is a quick way to get the Android emulator set up. For more detailed instructions and information, see the Android documentation. - -AVDs are managed with the Virtual Device Manager. In the Android Studio welcome screen, the context menu at the top right, then **Virtual Device Manager**. The Virtual Device Manager can also be opened inside Android projects in the **Tools** » **Device Manager** menu. - -![AVD Setup](/img/installation/android-studio-avd-setup.png) - -Click **Create Virtual Device** and select a suitable device definition. If unsure, choose **Pixel 2**. Then, select a suitable system image. If unsure, choose **Pie** (API 28) with Google Play services. See Android version history for information on Android versions. - -Once the AVD is created, launch the AVD into the Android emulator. Keeping the emulator running is the best way to ensure detection while developing Ionic apps for Android. - -
- Android Emulator Booting -
- -### Set up an Android Device - -Actual Android hardware can also be used for Ionic app development. But first, the device must be set up for development. The following documentation is a quick way to set up Android devices for development. For more detailed instructions and information, see the Android documentation. - -1. Enable USB debugging on the device. Open **Settings**, navigate to **Developer options**, and enable **USB debugging**. The **Developer options** menu may need to be enabled first. See the Android documentation for instructions. -1. Ensure the device has permission to connect to the computer. For macOS, no additional setup is required. For Windows, install the OEM USB drivers. - -Verify the connection works by connecting the device to the computer with a USB cable and using the following command: - -```shell -adb devices -``` - -The device should be listed. See the full `adb` documentation for troubleshooting and detailed information. - -## Cordova Setup - -Additional setup is required for Cordova to support programmatic builds. This section is not necessary for Capacitor. - -### Java - -Native Android apps are compiled with the Java programming language. Download the Java Development Kit (JDK) 11 if you are using **`cordova-android`** `10.0.0` or greater. - -:::note -If you are using any version of **`cordova-android`** below `10.0.0`, install the Java Development Kit (JDK) 8. -::: - -### Gradle - - - Gradle - is the build tool used in Android apps and must be installed separately. See the - install page - for details. - -## Project Setup - -Before apps can be deployed to Android simulators and devices, the native project must be configured. - -1. **Perform an Ionic build, if you haven't already.** - - ``` - $ ionic build - ``` - -2. **Generate the native project, if it does not already exist.** - - For Capacitor, run the following: - - ```shell - $ ionic capacitor add android - ``` - - For Cordova, run the following: - - ```shell - $ ionic cordova prepare android - ``` - -3. **Set the [Package ID](../reference/glossary.md#package-id).** - - For Capacitor, open the `capacitor.config.json` file and modify the `appId` property. - - For Cordova, open the `config.xml` file and modify the `id` attribute of the root element, ``. See [the Cordova documentation](https://cordova.apache.org/docs/en/latest/config_ref/#widget) for more information. - -## Running with Capacitor - -Capacitor uses Android Studio to build and run apps to simulators and devices. - -1. **Develop the Ionic app and sync it to the native project.** - - With each meaningful change, Ionic apps must be built into web assets before the change can appear on Android simulators and devices. The web assets then must be copied into the native project. Luckily, this process is made easy with a single Ionic CLI command. - - ```shell - $ ionic capacitor copy android - ``` - -2. **Run the app on a simulator or device.** - - You can open the Android Studio Project using: - - ```shell - $ ionic capacitor open android - ``` - - In Android Studio, click the Run button and then select the target simulator or device. - - ![Android Studio Run Button Area](/img/running/android-studio-run-button-area.png) - -### Live reload - -To start a live-reload server run the following command. - -```shell -ionic capacitor run android -l --external -``` - -When running on a device make sure the device and your development machine are connected to the same network. - -## Running with Cordova - -The Ionic CLI can build, copy, and deploy Ionic apps to Android simulators and devices with a single command. It can also spin up a development server, like the one used in `ionic serve`, to provide [live-reload](../reference/glossary.md#livereload) functionality. - -Run the following to start a long-running CLI process that boots up a live-reload server: - -```shell -ionic cordova run android -l -``` - -Now, when changes are made to the app's source files, web assets are rebuilt and the changes are reflected on the simulator or device without having to deploy again. - -## Debugging Android Apps - -Once an app is running on an Android device or emulator, it can be debugged with Chrome DevTools. - -### Using Chrome DevTools - -Chrome has web developer tool support for Android simulators and devices. Go to `chrome://inspect` in Chrome while the simulator is running or a device is connected to the computer and **Inspect** the app that needs to be debugged. - -:::note -Make sure your application is running on the device or simulator, or it will not show up in the list. -::: - -![Android Chrome DevTools](/img/running/android-chrome-devtools.png) - -### Viewing Native Logs - -If running with Android Studio, native logs can be found in **Logcat**. - -:::note -If the **Logcat** window is hidden, you can enable it in **View** » **Tool Windows** » **Logcat**. ::: -![Android Studio Logcat](/img/running/android-studio-logcat.png) - -You can also access **Logcat** with [ADB](https://developer.android.com/studio/command-line/adb). - -```shell -adb logcat -``` + + +

Learn the fundamentals you need to know to start building Android apps with Ionic Framework and Capacitor.

+ + +

Learn the fundamentals you need to know to start building Android apps with Ionic Framework and Cordova.

+ + diff --git a/docs/developing/ios.md b/docs/developing/ios.md index 553c3580655..5213325ac35 100644 --- a/docs/developing/ios.md +++ b/docs/developing/ios.md @@ -12,173 +12,28 @@ skipIntros: true /> -This guide covers how to run and debug Ionic apps on iOS simulators and devices using [Capacitor](../reference/glossary.md#capacitor) or [Cordova](../reference/glossary.md#cordova). iOS apps can only be developed on macOS with Xcode installed. +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; -There are two workflows for running Ionic apps on iOS: +:::info Looking for the legacy iOS guide? -- [Running with Xcode](#running-with-xcode) -- [Running with the Ionic CLI](#running-with-the-ionic-cli) +The Developing for iOS guide has officially migrated to the [Capacitor documentation for iOS](https://capacitorjs.com/docs/ios). If you need to access the legacy documentation, you can find it under the [legacy developing for iOS guide](/docs/v6/developing/ios). -The Xcode approach is generally more stable, but the Ionic CLI approach offers [live-reload](../reference/glossary.md#livereload) functionality. - -## Xcode Setup - -[Xcode](https://developer.apple.com/xcode/) is the IDE for creating native iOS apps. It includes the iOS SDK and Xcode command-line tools. Xcode can be [downloaded for free](https://developer.apple.com/download/) with an Apple account or it can be installed through the App Store. - -Once Xcode is installed, make sure the command-line tools are selected for use: - -```shell -xcode-select --install -``` - -### Setting up a Development Team - -All iOS apps must be code signed, even for development. Luckily, Xcode makes this easy with automatic code signing. The only prerequisite is an Apple ID. - -Open Xcode and navigate to **Xcode** » **Preferences** » **Accounts**. Add an Apple ID if none are listed. Once logged in, a Personal Team will appear in the team list of the Apple ID. - -![Xcode Accounts](/img/installation/ios-xcode-accounts.png) - -### Creating an iOS Simulator - -The iOS simulator emulates iOS devices on Macs. The following documentation is a quick way to get the iOS simulator set up. For more information, see [Apple's documentation](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/simulator_help_topics/Chapter/Chapter.html). - -Open Xcode and navigate to **Window** » **Devices and Simulators**. Create an **iPhone 11** simulator if one does not already exist. - -![iOS Simulators](/img/installation/ios-xcode-simulators-setup.png) - -## Cordova Setup - -Additional setup is required for Cordova to support programmatic builds. This section is not necessary for Capacitor. - -### ios-sim & ios-deploy - -The [`ios-sim`](https://github.com/ios-control/ios-sim) and [`ios-deploy`](https://github.com/ios-control/ios-deploy) are utilities that deploy apps to the iOS simulator and iOS devices during development. They can be installed globally with [npm](../reference/glossary.md#npm). - -```shell -$ npm install -g ios-sim -$ brew install ios-deploy -``` - -## Project Setup - -Before apps can be deployed to iOS simulators and devices, the native project must be configured. - -1. **Generate the native project, if it does not already exist.** - - For Capacitor, run the following: - - ```shell - $ ionic capacitor add ios - ``` - - For Cordova, run the following: - - ```shell - $ ionic cordova prepare ios - ``` - -1. **Set the [Package ID](/reference/glossary.md#package-id).** - - For Capacitor, open the `capacitor.config.json` file and modify the `appId` property. - - For Cordova, open the `config.xml` file and modify the `id` attribute of the root element, ``. See [the Cordova documentation](https://cordova.apache.org/docs/en/latest/config_ref/#widget) for more information. - -1. **Open the project in Xcode.** - - For Capacitor, run the following to open the app in Xcode: - - ```shell - $ ionic capacitor open ios - ``` - - For Cordova, open Xcode. Use **File** » **Open** and locate the app. Open the app's `platforms/ios` directory. - -1. **In Project navigator, select the project root to open the project editor. Under the **Identity** section, verify that the Package ID that was set matches the Bundle Identifier.** - - ![Xcode Identity Setup](/img/running/ios-xcode-identity-setup.png) - -1. **In the same project editor, under the Signing section, ensure Automatically manage signing is enabled.** Then, select a Development Team. Given a Development Team, Xcode will attempt to automatically prepare provisioning and signing. - - ![Xcode Signing Setup](/img/running/ios-xcode-signing-setup.png) - -## Running with Xcode - -In this workflow, Xcode can automatically fix common compilation and signing issues that can occur. - -1. **Develop the Ionic app and sync it to the native project.** - - With each meaningful change, Ionic apps must be built into web assets before the change can appear on iOS simulators and devices. The web assets then must be copied into the native project. Luckily, this process is made easy with a single Ionic CLI command. - - For Capacitor, run the following: - - ```shell - $ ionic capacitor copy ios - $ ionic capacitor update - ``` - - For Cordova, run the following: - - ```shell - $ ionic cordova prepare ios - ``` - -1. **In Xcode, select a target simulator or device and click the play button.** - - ![Xcode Play Button Area](/img/running/ios-xcode-play-button-area.png) - -## Running with the Ionic CLI - -The Ionic CLI can build, copy, and deploy Ionic apps to iOS simulators and devices with a single command. It can also spin up a development server, like the one used in `ionic serve`, to provide [live-reload](../reference/glossary.md#livereload) functionality. - -With live-reload, changes made to the app's source files trigger a rebuild of web assets and the changes are reflected on the simulator or device without having to deploy again. - -:::caution -For iOS devices, the device and the computer need to be on the same Wi-Fi network. An external URL for the dev server is also required so the device can connect to it. Use `--external` (or `--host=0.0.0.0`) to bind to external addresses. -::: - -### Live-reload with Capacitor - -Capacitor does not yet have a way to build native projects. It relies on Xcode to build and deploy app binaries. However, the Ionic CLI can boot up a live-reload server and configure Capacitor to use it with a single command. - -Run the following, then select a target simulator or device and click the play button in Xcode: - -```shell -ionic capacitor run ios -l --external -``` - -### Live-reload with Cordova - -Cordova can build and deploy native projects programmatically. - -To boot up a live-reload server, build, and deploy the app, run the following: - -```shell -ionic cordova run ios -l --external -``` - -## Debugging iOS Apps - -Once an app is running on an iOS device or simulator, it can be debugged in Safari. - -### Using Safari Web Inspector - -Safari has Web Inspector support for iOS simulators and devices. Open the **Develop** menu and select the simulator or device, then select the Ionic App to open Web Inspector. - -:::note -If the **Develop** menu is hidden, enable it in **Safari** » **Preferences** » **Advanced** » **Show Develop menu in menu bar**. - -If the app isn't listed, the Web Inspector may need to be enabled on the device in **Settings** » **Safari** » **Advanced** » **Web Inspector**. -::: - -![Safari Web Inspector](/img/running/ios-safari-web-inspector-timelines.png) - -### Viewing Native Logs - -If running with Xcode, native logs can be found in the Xcode **Console**. - -:::note -If the **Console** is hidden, enable it in **View** » **Debug Area** » **Activate Console**. ::: -![Xcode Console](/img/running/ios-xcode-console.png) + + +

Learn the fundamentals you need to know to start building iOS apps with Ionic Framework and Capacitor.

+ + +

Learn the fundamentals you need to know to start building iOS apps with Ionic Framework and Cordova.

+ + diff --git a/static/icons/capacitor-logo.svg b/static/icons/capacitor-logo.svg new file mode 100644 index 00000000000..1879564177c --- /dev/null +++ b/static/icons/capacitor-logo.svg @@ -0,0 +1 @@ + \ No newline at end of file