diff --git a/docs/shared/carthage-installation-panel.mdx b/docs/shared/carthage-installation-panel.mdx index 693c650adc..235e48edcf 100644 --- a/docs/shared/carthage-installation-panel.mdx +++ b/docs/shared/carthage-installation-panel.mdx @@ -11,43 +11,45 @@ import {

Set up your `Cartfile`

-Add `github "apollographql/apollo-ios"` to your Cartfile. +Add `github "apollographql/apollo-ios"` to your Cartfile. -

Checkout and build dependencies

+

Check out and build dependencies

-Run `carthage update --platform ios` (or `--platform ios,macos` to build both Mac and iOS). **NOTE:** There's an issue with the way Carthage uses Lipo in the Xcode 12 GM, please cd into `[YourProject]/Carthage/Checkouts/apollo-ios/scripts` and then run `./carthage-build-workaround.sh` to actually get Carthage builds that work. +Run `carthage update --use-xcframeworks --platform ios` (or `--platform ios,macos` to build both Mac and iOS). + +> **Note:** There's an issue with the way Carthage uses Lipo in the Xcode 12 GM. Please `cd` into `[YourProject]/Carthage/Checkouts/apollo-ios/scripts` and then run `./carthage-build-workaround.sh` to resolve this build issue. - +

Add built frameworks to your project

Drag and drop `Apollo.framework` from the appropriate `Carthage/Build/iOS` or `Carthage/Build/Mac` folder to the **Embedded Binaries** section of your application target's **General** settings tab. This should also cause them to appear in the **Linked Frameworks And Libraries** section automatically. - - If you also plan on using the `ApolloSQLite` library, also drag `ApolloSQLite.framework` and `SQLite.framework` to this area as well. - - If you also plan on using the `ApolloWebSocket` library, also drag `ApolloWebSocket.framework` and `Starscream.framework` to this area as well. + - To include the `ApolloSQLite` library, also drag `ApolloSQLite.framework` and `SQLite.framework` to this area. + - To include the `ApolloWebSocket` library, also drag `ApolloWebSocket.framework` and `Starscream.framework` to this area.

Work around Carthage submission bug

-On your application target's **Build Phases** settings tab, click the **+** icon and choose **New Run Script Phase**. Create a Run Script in which you specify your shell (ex: `bin/sh`), add the following contents to the script area below the shell: +On your application target's **Build Phases** settings tab, click the **+** icon and choose **New Run Script Phase**. Create a Run Script in which you specify your shell (e.g., `bin/sh`) and add the following contents to the script area below the shell: ```sh /usr/local/bin/carthage copy-frameworks ``` -and add the paths to the frameworks you want to use under **Input Files**, e.g.: +Then, add the paths to the frameworks you want to use under **Input Files**, e.g.: ``` $(SRCROOT)/Carthage/Build/iOS/Apollo.framework ``` - -Again, if you're adding `ApolloSQLite` or `ApolloWebSocket`, please make sure to add the other frameworks you added as Input Files. - + +Again, if you're adding `ApolloSQLite` or `ApolloWebSocket`, please make sure to add the other frameworks you added as Input Files. + This script works around an [App Store submission bug](http://www.openradar.me/radar?id=6409498411401216) triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving. diff --git a/docs/shared/carthage-run-script-panel.mdx b/docs/shared/carthage-run-script-panel.mdx index 600d14dcb2..02ec8b6966 100644 --- a/docs/shared/carthage-run-script-panel.mdx +++ b/docs/shared/carthage-run-script-panel.mdx @@ -6,13 +6,11 @@ import { -In the never-ending battle of what's going to be more painful when it comes to dependency management, we've decided to make working with Carthage a bit more of a pain in order to make working with NPM way less of a pain. +The scripts and binaries that you need to generate code are included in the `Carthage/Checkouts` folder. If this folder is not checked into version control, all developers on a team (and your CI machine) need to run `carthage checkout` when changes are made to the version to ensure they have the correct underlying binaries and scripts. -The scripts and binaries which you need to generate code will be included in the `Carthage/Checkouts` folder. If this folder is not checked into version control, all developers on a team (and your CI machine) will need to run `carthage checkout` when changes are made to the version to ensure they have the correct underlying binaries and scripts. +Team members can then use this build script: -Once everyone's on the same page about that, you should be able to use this build script: - -```sh +```bash # Don't run this during index builds if [ $ACTION = "indexbuild" ]; then exit 0; fi @@ -21,4 +19,4 @@ cd "${SRCROOT}/${TARGET_NAME}" "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift ``` - \ No newline at end of file + diff --git a/docs/shared/pods-installation-panel.mdx b/docs/shared/pods-installation-panel.mdx index f43a4ec339..5275dadaee 100644 --- a/docs/shared/pods-installation-panel.mdx +++ b/docs/shared/pods-installation-panel.mdx @@ -9,9 +9,9 @@ import { -

Install CocoaPods

+

Install or update CocoaPods

-Because Apollo iOS has been written using Swift 5, you need to use version `1.7.0` or higher. You can install CocoaPods using: +Because Apollo iOS uses Swift 5, you need to use CocoaPods version `1.7.0` or later. You can install CocoaPods with the following command: ```sh gem install cocoapods @@ -24,8 +24,8 @@ Because Apollo iOS has been written using Swift 5, you need to use version `1.7. Add `pod "Apollo"` to your Podfile. - - If you also want to use the `ApolloSQLite` framework, also add `pod "Apollo/SQLite"` - - If you also want to use the `ApolloWebSocket` framework, also add `pod "Apollo/WebSocket"` + - To include the `ApolloSQLite` framework, also add `pod "Apollo/SQLite"` + - To include the `ApolloWebSocket` framework, also add `pod "Apollo/WebSocket"` @@ -43,4 +43,4 @@ Use the `.xcworkspace` file generated by CocoaPods to work on your project. - \ No newline at end of file + diff --git a/docs/shared/pods-run-script-panel.mdx b/docs/shared/pods-run-script-panel.mdx index 339cec183b..9ac0edf6ac 100644 --- a/docs/shared/pods-run-script-panel.mdx +++ b/docs/shared/pods-run-script-panel.mdx @@ -8,7 +8,7 @@ import { Our CocoaPods install includes the code-generation scripts and binaries of the `apollo` CLI client as files which will not be added to the framework, but which you can still call from a Run Script Build Phase. Add the following to the Run Script: -```sh +```bash # Don't run this during index builds if [ $ACTION = "indexbuild" ]; then exit 0; fi @@ -17,4 +17,4 @@ cd "${SRCROOT}/${TARGET_NAME}" "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift ``` - \ No newline at end of file + diff --git a/docs/shared/spm-installation-panel.mdx b/docs/shared/spm-installation-panel.mdx index 8bf9967ec2..1b1772bc41 100644 --- a/docs/shared/spm-installation-panel.mdx +++ b/docs/shared/spm-installation-panel.mdx @@ -6,37 +6,39 @@ import { -**NOTE**: These instructions are intended for usage on Xcode 11 and higher. Xcode 11 is the first version of Xcode that integrates Swift Package manager and makes it _way_ easier to use than it was at the command line. If you are using older versions of Xcode, we recommend using CocoaPods. +> **Note:** These instructions use the Xcode 13 UI. Xcode 11 is the first version of Xcode that integrates Swift Package manager, whereas older versions require using the command line. If you're using an older version of Xcode, we recommend using CocoaPods instead. -Go to **File > Swift Packages > Add Package Dependency...** +Go to **File > Add Packages...** -![add a dependency](../source/screenshot/spm_packages_add_dependency.png) +Adding an SPM package -Paste the URL to the Apollo iOS repo on GitHub ([https://github.com/apollographql/apollo-ios.git](https://github.com/apollographql/apollo-ios.git)) into the search bar, then hit the **Next** button: +In the dialog that appears, paste the URL of the Apollo iOS GitHub repo (`https://github.com/apollographql/apollo-ios.git`) into the search bar, then select the `apollo-ios` package that appears: -![paste in the url](../source/screenshot/spm_paste_url.png) +Pasting the Apollo iOS GitHub URL -Select what version you want to use, then hit next. Xcode will automatically suggest the current version `Up to Next Major`, we **strongly** suggest that while the iOS SDK is on a `0.x.x` version scheme, you select `Up To Next Minor` instead, as we will still be releasing breaking changes on minor versions: +Select which version you want to use ([see version history](https://github.com/apollographql/apollo-ios/releases)), then click **Add Package**. Note that Xcode might not automatically select the latest version number! -![select a version](../source/screenshot/spm_select_version.png) +> Xcode automatically suggests the dependency rule `Up to Next Major`. We **strongly** suggest that until the release of Apollo iOS `1.x`, you select `Up To Next Minor` instead, because we might release breaking changes in a minor version. - -Select which packages you want to use. If you're just getting started, try selecting just the main `Apollo` library first - you can always come back and add the other packages later if you need them. Then hit finish. -![select the packages you want to use](../source/screenshot/spm_select_package.png) +Select which packages you want to use. If you're getting started, we recommend selecting just the main `Apollo` library for now. You can always add other packages later if you need them. -_Note: Do **not** select the `Apollo-Dynamic` target, this is only for use for projects linking to our library dynamically. Most projects will not need to do this._ +Selecting Apollo iOS packages + +> **Note:** Do **not** select the `Apollo-Dynamic` target. This target is only for projects that link to Apollo iOS. Most projects do not need to do this. + +Then, click **Add Package**. @@ -44,4 +46,4 @@ _Note: Do **not** select the `Apollo-Dynamic` target, this is only for use for p - \ No newline at end of file + diff --git a/docs/shared/spm-run-script-panel.mdx b/docs/shared/spm-run-script-panel.mdx index ccad533f2b..944e71d8c5 100644 --- a/docs/shared/spm-run-script-panel.mdx +++ b/docs/shared/spm-run-script-panel.mdx @@ -6,11 +6,11 @@ import { -> **NOTE**: If your Derived Data is in a custom location, stop, go back, and use the [Swift Scripting](./swift-scripting) method instead. This script relies on Derived Data being in the default location. Swift Scripting doesn't rely on Derived Data at all. +> **Note:** If your Derived Data is in a custom location, go back and use the [Swift Scripting](./swift-scripting) method instead. This script relies on Derived Data being in the default location. Swift Scripting doesn't rely on Derived Data at all. -If you're using Xcode 11 or higher, SPM will check out the appropriate build script along with the rest of the files when it checks out the repo. Add the following to your Run Script build phase: +If you're using Xcode 11 or higher, SPM checks out the appropriate build script along with the rest of the files when it checks out the repo. Add the following to your Run Script build phase: -```sh +```bash # Don't run this during index builds if [ $ACTION = "indexbuild" ]; then exit 0; fi @@ -38,6 +38,6 @@ cd "${SRCROOT}/${TARGET_NAME}" "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift ``` -> NOTE: If you try to use this with command line SPM, when you regenerate your `xcodeproj` this build script will get wiped out. We strongly recommend using Xcode 11's built-in SPM handling rather than the command line because of this. +> **Note:** If you try to use this with command line SPM, when you regenerate your `xcodeproj` this build script will get wiped out. We strongly recommend using Xcode 11's built-in SPM handling instead of the command line because of this. - \ No newline at end of file + diff --git a/docs/source/downloading-schema.md b/docs/source/downloading-schema.md index 1f75482527..55e2396fe7 100644 --- a/docs/source/downloading-schema.md +++ b/docs/source/downloading-schema.md @@ -8,13 +8,13 @@ Apollo iOS requires a GraphQL schema file as input to the code generation proces You can use the [Apollo CLI](https://www.apollographql.com/docs/devtools/cli/) to download a GraphQL schema by sending an introspection query to the server. -If you've installed the CLI globally, you can use the following command to download your schema: +If you've installed the CLI globally, you can use the following command to download your schema: ```sh apollo schema:download --endpoint=http://localhost:8080/graphql schema.json ``` -Note that if you're using the local version set up for codegen, you'll want to use the same method you're using in the [Adding A Code Generation Build Step](installation#adding-a-code-generation-build-step) instructions to access that specific CLI. For example, if you're using CocoaPods, you can set it up like this to download your schema: +Note that if you're using the local version set up for codegen, you'll want to use the same method you're using in the [Add a code generation build step](/installation/#5-add-a-code-generation-build-step) instructions to access that specific CLI. For example, if you're using CocoaPods, you can set it up like this to download your schema: ```sh SCRIPT_PATH="${PODS_ROOT}/Apollo/scripts" diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 6821c93355..8a6684324a 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,35 +1,48 @@ --- -title: Introduction +title: Introduction to Apollo iOS +sidebar_title: Introduction description: A strongly-typed, caching GraphQL client for iOS, written in Swift --- -[Apollo iOS](https://github.com/apollographql/apollo-ios) is a strongly-typed, caching GraphQL client for native iOS apps written in Swift. +import { Button } from '@apollo/space-kit/Button'; +import { Link } from 'gatsby'; +import { colors } from 'gatsby-theme-apollo-core'; -It allows you to execute queries and mutations against a GraphQL server and returns results as query-specific Swift types. This means you don't have to deal with parsing JSON, or passing around dictionaries and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your UI uses. +**Apollo iOS** is an [open-source](https://github.com/apollographql/apollo-ios) GraphQL client for native iOS apps, written in Swift. It enables you to execute queries and mutations against a GraphQL server and returns results as operation-specific Swift types. -As the generated types are query-specific, you're only able to access data you actually specify as part of a query. If you don't ask for a field in a particular query, you won't be able to access the corresponding property on the returned data structure. +

+ + +

-In effect, this means you can now rely on the Swift type checker to make sure errors in data access show up at compile time. With our Xcode integration, you can conveniently work with your UI code and corresponding GraphQL definitions side by side, and it will even validate your query documents, and show errors inline. +## Benefits -Apollo iOS does more than simply run your queries against a GraphQL server, however. It normalizes query results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run. This means your UI is always internally consistent, and can be kept fully up-to-date with the state on the server with the minimum number of queries required. +### Strong typing with codegen -This combination of immutable models, one way data flow, and automatic consistency management, leads to a very powerful and elegant programming model that allows you to eliminate common glue code and greatly simplifies app development. +Thanks to strong typing in Apollo iOS, you don't need to deal with parsing JSON responses or passing around dictionaries of values that require manual casting. You also don't need to write model types yourself, because models are generated from the GraphQL operations your UI defines. -## Getting Started +Because generated types are operation-specific, they include properties _only_ for the GraphQL fields included in their corresponding operation. This means you can rely on the Swift type checker to flag data access errors at compile time. -We have a [detailed iOS tutorial](./tutorial/tutorial-introduction) walking you through how to build an app called [RocketResever](https://github.com/apollographql/iOSTutorial), which talks to the backend built in the [Fullstack Tutorial](https://www.apollographql.com/docs/tutorial/introduction/). +Apollo's Xcode integration enables you to work with your UI code and corresponding GraphQL definitions side by side. It even validates your query documents, showing errors inline. -If you have questions or would like to contribute, please join our community at [https://community.apollographql.com/](http://community.apollographql.com/new-topic?category=Help&tags=mobile,client). +### Normalized caching -## Related platforms +Apollo iOS normalizes operation results to build a client-side cache of your data, which is updated with every operation you execute. This means your UI is always internally consistent, and it can stay up to date with your backend with as few operation as possible. -[Apollo Android](https://github.com/apollographql/apollo-android) is a GraphQL client for native Android apps written in Java and Kotlin, and offers Kotlin Multi-Platform integration as well. +[Learn more about caching.](./caching/) -Apollo Client for JavaScript's [React integration](https://apollographql.com/docs/react) works with [React Native](https://facebook.github.io/react-native/) on both iOS and Android. +## Related libraries -## Other resources +[Apollo Kotlin](https://www.apollographql.com/docs/kotlin/) is a GraphQL client for native Android apps written in Java and Kotlin. It offers Kotlin Multi-Platform integration as well. -- [GraphQL.org](http://graphql.org) for an introduction and reference to the GraphQL itself, partially written and maintained by the Apollo team. -- [Our website](http://www.apollographql.com/) to learn about Apollo open-source and commercial tools. -- [Our blog](https://www.apollographql.com/blog/) for long-form articles about GraphQL, feature announcements for Apollo, and guest articles from the community. -- [Our Twitter](https://twitter.com/apollographql) for in-the-moment news. +Apollo Client for JavaScript's [React integration](https://apollographql.com/docs/react) works with [React Native](https://facebook.github.io/react-native/) on both iOS and Android. diff --git a/docs/source/installation.mdx b/docs/source/installation.mdx index 232e4f8055..b272b70305 100644 --- a/docs/source/installation.mdx +++ b/docs/source/installation.mdx @@ -1,5 +1,6 @@ --- -title: Installation +title: Installing Apollo iOS +sidebar_title: Installation --- import SPMInstallationPanel from "../shared/spm-installation-panel.mdx" @@ -9,19 +10,13 @@ import PodsRunScriptPanel from "../shared/pods-run-script-panel.mdx" import CarthageInstallationPanel from "../shared/carthage-installation-panel.mdx" import CarthageRunScriptPanel from "../shared/carthage-run-script-panel.mdx" -Apollo iOS requires the latest Xcode, which can be installed from the [Mac App Store](http://appstore.com/mac/apple/xcode). +Follow the steps below to add Apollo iOS to your app: -Follow along with these steps (described in detail below) to use Apollo iOS in your app: +## 1. Update Xcode -1. Install the Apollo framework into your project and link it to your application target -1. Add a schema file to your target directory -1. (optional) Install the Xcode add-ons to get syntax highlighting for your `.graphql` files -1. Create `.graphql` files with your queries or mutations and add them to your target -1. Add a code generation build step to your target -1. Build your target -1. Add the generated API file to your target +Before installing Apollo iOS, make sure you're using the latest version of Xcode. You can update Xcode via the [Mac App Store](http://appstore.com/mac/apple/xcode). -## Installing the Apollo framework +## 2. Install the Apollo framework You can install `Apollo.framework` into your project using any of the three major Cocoa ecosystem package managers: Swift Package Manager, CocoaPods, or Carthage. @@ -34,18 +29,18 @@ You can install `Apollo.framework` into your project using any of the three majo -## Adding a schema file to your target directory +## 3. Add a schema file to your target directory -You'll have to copy or [download a schema](/downloading-schema/) to your target's directory before generating code. +For Apollo iOS to generate models for your GraphQL operations, you need a local copy of your GraphQL server's schema. To acquire this schema, see [Downloading a schema](/downloading-schema/). -Apollo iOS requires a GraphQL schema file as input to the code generation process. A schema file is a JSON file that contains the results of an introspection query. Conventionally this file is called `schema.json`. +Make sure to add your `schema.json`/`schema.graphqls` file to the folder where most of your code is, _not_ to the folder where your `.xcodeproj` and/or `.xcworkspace` files are located. -Note that you need to add this in the folder where most of your code is, NOT in the same folder where the `.xcodeproj` and/or `.xcworkspace` are located. Here is a rough ASCII representation of what this should look like: +Here's an example file structure: -``` +```{4} | - your_project_folder | your_project.xcodeproj - | - your_target_folder + | - your_target_folder | schema.json | AppDelegate.swift | ViewController.swift @@ -54,35 +49,33 @@ Note that you need to add this in the folder where most of your code is, NOT in | etc... ``` -> **NOTE:** You _can_ add this file someplace else, but if you do, you will need to update the relative paths in the scripts in the steps below. - -## [Optional] Installing the Xcode add-ons to get syntax highlighting +> **Note:** You _can_ put the schema file in a different location, but if you do, you need to modify all relative paths to the file shown in future steps. -Check out[`xcode-apollo`](https://github.com/apollographql/xcode-graphql) the repository and follow the [installation guide](https://github.com/apollographql/xcode-graphql#installation). +## 3. Install the Xcode add-ons for syntax highlighting (optional) -## Creating `.graphql` files with your queries or mutations +Check out the [`xcode-apollo`](https://github.com/apollographql/xcode-graphql) repository and follow its [installation guide](https://github.com/apollographql/xcode-graphql#installation). -Apollo iOS will generate code from queries and mutations contained in `.graphql` files in your target. +## 4. Create `.graphql` files for your GraphQL operations -A useful convention is to colocate queries, mutations or fragments with the Swift code that uses them by creating `.graphql` next to `.swift`. +Apollo iOS generates code from GraphQL queries and mutations defined in `.graphql` files in your target. As a useful convention, you can define each `[operation].graphql` file alongside whichever `[operation].swift` file uses the corresponding operation. -If you have the Xcode add-ons installed, you can use the Xcode companion view to show a `.swift` file and the corresponding `.graphql` file side by side. +If you have the Xcode add-ons installed, you can use the Xcode companion view to show a `.swift` file and its corresponding `.graphql` file side by side. -> NOTE: If you don't have pre-existing `.graphql` files in your file tree, create a very simple query and add it to a `.graphql` file in your file tree so that when you run the code generation build step, it actually finds something. If you don't, you'll get the error `No operations or fragments found to generate code for`. +> **Note:** If you don't have _any_ `.graphql` files in your build tree yet, create one that contains a basic valid operation. If you don't, the code generation build step generates the error `No operations or fragments found to generate code for`. -## Adding a code generation build step +## 5. Add a code generation build step -Code generation uses your `.graphql` files to generate API code that will help you send queries, subscriptions, and mutations, as well as parse and cache responses. To run code generation as part of the Xcode build process, you need to create a build step that runs before "Compile Sources" to invoke a wrapper script. +Apollo iOS code generation uses your `.graphql` files to generate API code that helps you execute all forms of GraphQL operations, as well as parse and cache operation responses. To run code generation as part of the Xcode build process, you need to create a build step that runs before "Compile Sources" to invoke a wrapper script. -The wrapper will call through to the included binaries and files that constitute the `apollo` command-line interface. This ensures that you can use our tooling without having to worry about NPM Version Hellβ„’, and that the version of the framework you're using is compatible with the version of the codegen you're using. +The wrapper script calls through to the included binaries and files that constitute the `apollo` command-line interface. This helps ensure that you can use our tooling without having to worry about mismatched versioning between libraries. -> πŸŽ‰ NEW SHINY ALERT πŸŽ‰ : Instead of writing the rest of this in Bash, try using our new [Swift Scripting Library](./swift-scripting), now in Beta! It supports downloading a schema and generating code. +> πŸ“£ **Check it out:** Instead of writing the rest of this in Bash, try using our new [Swift Scripting Library](./swift-scripting), now in Beta! It supports downloading a schema and generating code. -The location of this wrapper script is slightly different based on how you've integrated Apollo into your project, but the first steps are the same everywhere: +The location of this wrapper script depends on how you've integrated Apollo into your project, but these first steps are always the same: -1. On your application target's **Build Phases** settings tab, click the **+** icon and choose **New Run Script Phase**. -2. In the created Run Script, change its name to **Generate Apollo GraphQL API** -3. Drag this new run script just above **Compile Sources** in your list of **Build Phases** so that it executes before your code is compiled. +1. On your application target's **Build Phases** settings tab, click the **+** icon and choose **New Run Script Phase**. +2. In the created Run Script, change its name to **Generate Apollo GraphQL API**. +3. Drag this new run script just above **Compile Sources** in your list of **Build Phases** so that it executes _before_ your code is compiled. 4. Add the contents of the appropriate run script for the package manager you're using: @@ -94,65 +87,69 @@ The location of this wrapper script is slightly different based on how you've in -## Build your target +## 6. Build your target -At this point, you can try building your target in Xcode. This will verify that the `schema.json` file can be found by the `apollo` script created above, and run the codegen. +At this point, you can try building your target in Xcode. This verifies that the code generation build step can correctly locate your schema file. ### Troubleshooting -If you get this error: +If you get this error: -> Cannot find GraphQL schema file [...] +> `Cannot find GraphQL schema file [...]` -The script is not able to find your schema file - double check the path you've used. +The script can't locate your schema file. Double check the path you've used. -If you get this error: +If you get this error: -> No operations or fragments found to generate code for. +> `No operations or fragments found to generate code for.` -If you don't have any `.graphql` files in your build tree, and you need to create at least `.graphql` file with a valid query. +You haven't defined at least one `.graphql` file with a valid operation in your build tree. -If you need to validate the structure of your query, please use the [GraphiQL](https://github.com/graphql/graphiql) instance provided by your API, which will show errors if your query is invalid. If you don't have access to a GraphiQL instance, you can use [Prettier.io's playground](https://prettier.io/playground/) to format arbitrary GraphQL queries by clicking "Show Options" and selecting the GraphQL parser from the "Global" drop-down. +If you need to validate the structure of a GraphQL operation, you can test it against your GraphQL server using [Apollo Sandbox](https://studio.apollographql.com/sandbox). -## Adding the generated API file to your target +## 7. Add the generated API file to your target Drag the generated `API.swift` file to your target. -> Note that because Apollo iOS generates query-specific result types, `API.swift` will be mostly empty at this point unless you've already added some `.graphql` files with queries or mutations to your target directory. +> **Note:** Because Apollo iOS generates operation-specific result types, `API.swift` is mostly empty at this point unless you've already added multiple `.graphql` files to your target directory. + +Make sure to uncheck the "Copy Files If Needed" checkbox, because it should already be in your project's folder system. Then, make sure you've checked all the Targets the API file needs to be included in. -Make sure to uncheck the "Copy Files If Needed" checkbox, since it should already be within your project's folder system. Then, make sure you've checked all the Targets the API file needs to be included in. +**Installation complete!** You can now start executing GraphQL operations in your app. To learn how, next check out [Creating a client](/initialization/) and [Fetching queries](/fetching-queries/). -## Advanced Codegen Tips And Tricks +You can also continue reading below for some [advanced codegen tips](#advanced-codegen-tips-and-tricks). -Here are a few things you can do to make your code generation even better once you've gotten up and running with the basics above: +## Advanced codegen tips and tricks -### Prevent Unnecessary Recompilation +After you get up and running, here are a few improvements you can make to your codegen process. -#### Set Up Input And Output Files In Your Build Phase +### Prevent unnecessary recompilation -Particularly if you're using Interface Builder or SwiftUI to talk to a module which also has a code generation build step, this is helpful to prevent the `API.swift` file from causing an auto-regeneration loop. +#### Set up input and output files in your build phase -For example, if you're using something like this to run your code generation for a target called `YourTarget`: +If you're using a tool like Interface Builder or SwiftUI to talk to a module with its own code generation build step, this is helpful to prevent the `API.swift` file from causing an auto-regeneration loop. + +For example, if you're using something like this to run your code generation for a target called `YourTarget`: ``` "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift ``` -Assuming you've set the script out to run from `$(SRCROOT)/YourTarget`, you can add `$(SRCROOT)/YourTarget/**/*.graphql` (the path you're running it from + the glob you're passing to the `includes` CLI parameter) to the list of `Input Files` for your Apollo Run Script Build phase. Then you can add `$(SRCROOT)/YourTarget/API.swift` (the path you're running it from + the output file) to the list of `Output Files`: +Assuming you've set the script to run from `$(SRCROOT)/YourTarget`, you can add `$(SRCROOT)/YourTarget/**/*.graphql` (the path you're running it from + the glob you're passing to the `includes` CLI parameter) to the list of `Input Files` for your Apollo Run Script Build phase. Then, you can add `$(SRCROOT)/YourTarget/API.swift` (the path you're running it from + the output file) to the list of `Output Files`: -![screenshot of input and output files](screenshot/input_output_files.png) +Setting input and output files -This should prevent automatic rebuild cycles if none of the `InputFiles` are changed. The script *will* still run if you explicitly build and run. +This should prevent automatic rebuild cycles if none of the `InputFiles` are changed. The script *will* still run if you explicitly build and run. -There's an [open issue to auto-generate input and output file lists](https://github.com/apollographql/apollo-ios/issues/636) which will be addressed as part of the Swift Codegen project, but this will help until that's done. +There's an [open issue to auto-generate input and output file lists](https://github.com/apollographql/apollo-ios/issues/636) which will be addressed as part of Apollo iOS 1.0, but this will help until that's done. -#### Write to a Temporary File +#### Write to a temporary file -If for some reason the input/output file setup above doesn't work for you, you can also decide to first write the file to a temporary location, and then compare this temporary file to the current one. And then only when the files differ you move the temporary file into place. +If for some reason the input/output file setup above doesn't work for you, you can also decide to first write the file to a temporary location, and then compare this temporary file to the current one. Then, only when the files differ you move the temporary file into place. -For a target called `YourTarget` the script could look something like; +For a target called `YourTarget`, the script could look something like this: -``` +```bash "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" "${SRCROOT}/YourTarget/API.swift.new" if ! diff -q "${SRCROOT}/YourTarget/API.swift.new" "${SRCROOT}/YourTarget/API.swift"; then mv "${SRCROOT}/YourTarget/API.swift.new" "${SRCROOT}/YourTarget/API.swift" @@ -161,8 +158,8 @@ else fi ``` -### Generate Multiple Files In A Folder Instead Of One Giant File +### Generate multiple files in a folder instead of one large file -Instead of passing a single `API.swift` file, pass a (pre-existing) relative folder path such as `API` as the final parameter. This will cause the codegen to create individual files and place them in that folder. +Instead of passing a single `API.swift` file, you can pass a (pre-existing) relative folder path such as `API` as the final parameter. This causes the codegen to create individual files and place them in that folder. -With small sets of `graphql` files this is usually overkill, but with large sets that can cause `API.swift` to be huge, this can help significantly reduce compilation time. +With small sets of `graphql` files this is usually unnecessary, but with large sets that can cause `API.swift` to be huge. Dividing it up like this can help significantly reduce compilation time. diff --git a/docs/source/screenshot/spm_packages_add_package.jpg b/docs/source/screenshot/spm_packages_add_package.jpg new file mode 100644 index 0000000000..b6a3d8f1a1 Binary files /dev/null and b/docs/source/screenshot/spm_packages_add_package.jpg differ diff --git a/docs/source/screenshot/spm_packages_dialog.jpg b/docs/source/screenshot/spm_packages_dialog.jpg new file mode 100644 index 0000000000..abaf1d0541 Binary files /dev/null and b/docs/source/screenshot/spm_packages_dialog.jpg differ diff --git a/docs/source/screenshot/spm_select_package.jpg b/docs/source/screenshot/spm_select_package.jpg new file mode 100644 index 0000000000..e87b7d0c53 Binary files /dev/null and b/docs/source/screenshot/spm_select_package.jpg differ diff --git a/docs/source/tutorial/tutorial-obtain-schema.md b/docs/source/tutorial/tutorial-obtain-schema.md index ec383dc594..eaff6ab827 100644 --- a/docs/source/tutorial/tutorial-obtain-schema.md +++ b/docs/source/tutorial/tutorial-obtain-schema.md @@ -6,11 +6,11 @@ This tutorial uses a modified version of the GraphQL server you build as part of The Sandbox query explorer -You'll know that this Sandbox instance is pointed at our server because its URL, `https://apollo-fullstack-tutorial.herokuapp.com`, is in the box at the top left of the page. If Sandbox is properly connected, you'll see a green dot: +You'll know that this Sandbox instance is pointed at our server because its URL, `https://apollo-fullstack-tutorial.herokuapp.com`, is in the box at the top left of the page. If Sandbox is properly connected, you'll see a green dot: A closeup of the URL box with a dot indicating it's connected -The schema defines which GraphQL operations your server can execute. At the top left, click the schema icon to get an overview of your schema: +The schema defines which GraphQL operations your server can execute. At the top left, click the schema icon to get an overview of your schema: The schema icon to click @@ -24,11 +24,11 @@ The Apollo iOS SDK needs a local copy of your server's schema to generate code f To use the Apollo CLI from Xcode, add a **Run Script** build phase to your app: -1. Select the `xcodeproj` file in the Project Navigator, and then select the `RocketReserver` application target: +1. Select the `xcodeproj` file in the Project Navigator, and then select the `RocketReserver` application target: Selecting application target -2. A list of tabs appears. Select the **Build Phases** tab: +2. A list of tabs appears. Select the **Build Phases** tab: Build phases menu item @@ -37,7 +37,7 @@ To use the Apollo CLI from Xcode, add a **Run Script** build phase to your app: Creating a new run script build phase This adds a new Run Script build phase to the bottom of your list of build phases. - + 4. Drag the newly created phase up between "Dependencies" and "Compile Sources": Where to drag the run script @@ -46,7 +46,7 @@ To use the Apollo CLI from Xcode, add a **Run Script** build phase to your app: UI for renaming -6. Expand the Apollo phase. Paste the **Swift Package Manager Run Script** from [Adding a code generation build step](/installation/#adding-a-code-generation-build-step) into the text area. This script uses your schema to generate the code that the Apollo iOS SDK uses to interact with your server. +6. Expand the Apollo phase. Paste the **Swift Package Manager Run Script** from [Add a code generation build step](/installation/#5-add-a-code-generation-build-step) into the text area. This script uses your schema to generate the code that the Apollo iOS SDK uses to interact with your server. 7. Before the script can generate code, it needs a local copy of your GraphQL server's schema. For now, using a `#`, **comment out the last line** of the script you pasted and add the following line below it: @@ -60,7 +60,7 @@ To use the Apollo CLI from Xcode, add a **Run Script** build phase to your app: Where to drag the schema file - When Xcode offers to add the schema file, make sure **all targets are unchecked** to reduce the size of your application bundle: + When Xcode offers to add the schema file, make sure **all targets are unchecked** to reduce the size of your application bundle: All targets unchecked in dialog