diff --git a/docs/shared/spm-install-cli.mdx b/docs/shared/spm-install-cli.mdx new file mode 100644 index 0000000000..3d8d0a6d29 --- /dev/null +++ b/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. + +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. diff --git a/docs/shared/spm-setup-codegen-panel.mdx b/docs/shared/spm-setup-codegen-panel.mdx new file mode 100644 index 0000000000..2a2166ce0d --- /dev/null +++ b/docs/shared/spm-setup-codegen-panel.mdx @@ -0,0 +1,68 @@ +import SPMInstallCLI from "../shared/spm-install-cli.mdx" + + + + + + + +#### Install the Codegen CLI + + + + + + + +#### 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. + + + + +#### 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. + + + + +#### 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`. + + + + +#### 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). + + + + diff --git a/docs/source/code-generation/codegen-cli.mdx b/docs/source/code-generation/codegen-cli.mdx index 2fa9cc131d..366d3d1ff9 100644 --- a/docs/source/code-generation/codegen-cli.mdx +++ b/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: @@ -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: + + + + + + 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`. diff --git a/docs/source/get-started.mdx b/docs/source/get-started.mdx index f0abe94683..67d86ee26a 100644 --- a/docs/source/get-started.mdx +++ b/docs/source/get-started.mdx @@ -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: @@ -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). - + + + + ## 5. Create an `ApolloClient` Before you can execute GraphQL operations in your app, you need to initialize an `ApolloClient` instance. diff --git a/docs/source/screenshot/apollo-xcode-plugin.png b/docs/source/screenshot/apollo-xcode-plugin.png new file mode 100644 index 0000000000..db1251bcfc Binary files /dev/null and b/docs/source/screenshot/apollo-xcode-plugin.png differ diff --git a/docs/source/screenshot/xcode_menu_plugins.png b/docs/source/screenshot/xcode_menu_plugins.png deleted file mode 100644 index dfe858311a..0000000000 Binary files a/docs/source/screenshot/xcode_menu_plugins.png and /dev/null differ