Skip to content

Commit

Permalink
Update docs for install via SPM plugin
Browse files Browse the repository at this point in the history
  • Loading branch information
AnthonyMDev committed Nov 15, 2022
1 parent ca2d2b0 commit 7e71aae
Show file tree
Hide file tree
Showing 6 changed files with 102 additions and 3 deletions.
19 changes: 19 additions & 0 deletions docs/shared/spm-install-cli.mdx
@@ -0,0 +1,19 @@
The Apollo iOS SPM package includes the Codegen CLI as an executable target. This ensures you always have a valid CLI version for your Apollo iOS version.

To simplify accessing the Codegen CLI, you can run the included `InstallCLI` SPM plugin.

This plugin builds the CLI and creates a sybmolic link to the executable in your project root.

When using a `Package.swift` file, install the CLI by running:

```bash
swift package --allow-writing-to-package-directory apollo-cli-install
```

When using Swift packages through Xcode, right-click on your project in the Xcode file explorer and at the bottom of the menu you will find the `InstallCLI` plugin command. Clicking on this will present a dialog asking for permission for the plugin to write to your project directory.

<img class="screenshot" src="../source/screenshot/apollo-xcode-plugin.png" alt="Where to find the SPM plugin commands in Xcode" />

After running the installation plugin, a symbolic link to the Codegen CLI named `apollo-ios-cli` is located in your project root folder. You can now run the CLI from the command line with `./apollo-ios-cli`.

> **Note:** Because the `apollo-ios-cli` in your project root is only a symbolic link, it will only work if the compiled CLI exectuable exists. This is generally located in your Xcode Derived Data or the `.build` folder. If these are cleared, you can run the install plugin again to re-build the CLI executable.
68 changes: 68 additions & 0 deletions docs/shared/spm-setup-codegen-panel.mdx
@@ -0,0 +1,68 @@
import SPMInstallCLI from "../shared/spm-install-cli.mdx"

<ExpansionPanel title="Swift Package Manager">

<ExpansionPanelList>

<ExpansionPanelListItem>

#### Install the Codegen CLI

<SPMInstallCLI />

</ExpansionPanelListItem>

<ExpansionPanelListItem>

#### Initialize the code generation configuration

The Codegen CLI uses a JSON file to configure the code generation engine. Use the Codegen CLI `init` command to create this file with default values. From your project's root directory, run:

```bash
./apollo-ios-cli init --schema-name ${MySchemaName}
```

`${MySchemaName}` should be the name you want for the namespace of your generated schema files.

This will create an `apollo-codegen-config.json` file with the default values.

</ExpansionPanelListItem>
<ExpansionPanelListItem>

#### Configure code generation options

Open the `apollo-codegen-config.json` file to configure code generation for your project.

The default configuration will:
- Find all GraphQL schema files ending with the file extension `.graphqls` within your project directory.
- Find all GraphQL operation and fragment definition files ending with the file extension `.graphql` within your project directory.
- Generate Swift code for the schema types in a directory with the `schema-name` provided.
- Generate Swift code for the operation and fragment models relative to the `.graphql` files that define them.

</ExpansionPanelListItem>
<ExpansionPanelListItem>

#### Run code generation

From your project's root directory, run:

```bash
./apollo-ios-cli generate
```

Your generated files will be created with the file extension `.graphql.swift`.

</ExpansionPanelListItem>
<ExpansionPanelListItem>

#### Add the generated schema and operation files to your target

By default, a directory containing your generated schema files will be located in a directory with the `schema-name` you provided; your generated operation and fragment files will be in the same location as the `.graphql` files they are defined by.

If your target is created in an Xcode project or workspace, you will need to manually add the generated files to your target.

> **Note:** Because adding generated files to your Xcode targets must be done manually each time you generate new files, we highly recommend defining your project targets with SPM. Alternatively, you can generate your operations into the package that includes your schema files. For more information see the documentation for [Code Generation Configuration](./codegen-configuration).
</ExpansionPanelListItem>
</ExpansionPanelList>
</ExpansionPanel>
12 changes: 10 additions & 2 deletions docs/source/code-generation/codegen-cli.mdx
@@ -1,7 +1,9 @@
---
title: The codegen CLI
title: The Codegen CLI
---

import SPMInstallCLI from "../../shared/spm-install-cli.mdx"

The Codegen CLI provides a command line tool that streamlines the process of running code generation. The CLI can be ran manually from Terminal (or any other shell program) or can be called into from bash scripts.

The Codegen CLI has three primary commands:
Expand All @@ -15,10 +17,16 @@ The Codegen CLI has three primary commands:
## Installation

When Apollo iOS is included as a dependency through Cocoapods the CLI is built and packaged with the dependency automatically. This ensures you always have a valid version of the CLI for the version of Apollo iOS you are using and you never have to worry about installation or updates.
When Apollo iOS is included as a dependency through Swift Package Manager (SPM) or Cocoapods, the CLI is built and packaged with the dependency automatically. This ensures you always have a valid version of the CLI for the version of Apollo iOS you are using and you never have to worry about installation or updates.

To learn how to run the Codegen CLI with your chosen package manager, open the appropriate section:

<ExpansionPanel title="Swift Package Manager - Xcode">

<SPMInstallCLI />

</ExpansionPanel>

<ExpansionPanel title="CocoaPods">

When using Cocoapods, Apollo iOS compiles the Codegen CLI into an executable shell application during `pod install`, which is located in your project at `Pods/Apollo/apollo-ios-cli`.
Expand Down
6 changes: 5 additions & 1 deletion docs/source/get-started.mdx
Expand Up @@ -6,6 +6,7 @@ sidebar_title: Get Started
import SPMXcodeInstallationPanel from "../shared/spm-xcode-installation-panel.mdx"
import SPMPackageInstallationPanel from "../shared/spm-package-installation-panel.mdx"
import PodsInstallationPanel from "../shared/pods-installation-panel.mdx"
import SPMSetupCodegenPanel from "../shared/spm-setup-codegen-panel.mdx"
import PodsSetupCodegenPanel from "../shared/pods-setup-codegen-panel.mdx"

Follow the steps below to add Apollo iOS to your app:
Expand Down Expand Up @@ -45,9 +46,12 @@ The easiest way to do this is with the Codegen CLI provided with Apollo iOS.
>
> To use Apollo's code generation and schema downloader from within any Swift script or library, check out [Running code generation in Swift code](./code-generation/run-codegen-in-swift-code).
<a name="pods-run-codegen" />
<a name="pods-setup-codegen" />
<PodsSetupCodegenPanel />

<a name="spm-setup-codegen" />
<SPMSetupCodegenPanel />

## 5. Create an `ApolloClient`

Before you can execute GraphQL operations in your app, you need to initialize an `ApolloClient` instance.
Expand Down
Binary file added docs/source/screenshot/apollo-xcode-plugin.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/source/screenshot/xcode_menu_plugins.png
Binary file not shown.

0 comments on commit 7e71aae

Please sign in to comment.