// Copyright (C) 2023 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[xcode_plugin]]
= Xcode

WARNING: The Xcode Plugin is not compatible with the <<configuration_cache.adoc#config_cache:plugins:core,configuration cache>>.

The Xcode Plugin generate files that are used by the https://developer.apple.com/xcode/[Xcode IDE] to open Gradle projects into Xcode (`File` - `Open...`). The generated Xcode project delegates build actions to Gradle.

What exactly the `xcode` plugin generates depends on which other plugins are used:

.Xcode Plugin behavior
[%header%autowidth,compact]
|===
| Plugin | Description

| None
| Generates minimal solution file.

| <<cpp_application_plugin.adoc#cpp_application_plugin,{cpp} Application>>
| Adds a target representing the {cpp} application to the project file.

| <<cpp_library_plugin.adoc#cpp_library_plugin,{cpp} Library>>
| Adds a target for each specified linkage representing the shared and/or static library to the project file.

| <<swift_application_plugin.adoc#swift_application_plugin,Swift Application>>
| Adds a target representing the Swift application to the project file.

| <<swift_library_plugin.adoc#swift_library_plugin,Swift Library>>
| Adds a target for each specified linkage representing the shared and/or static library to the project file.

| <<xctest_plugin.adoc#xctest_plugin,XCTest>>
| Adds a target representing the XCTest bundle to the project file.
| The tested target is also configured to enable a seamless workflow from the IDE.
|===

[[sec:xcode_usage]]
== Usage

.Applying the Xcode Plugin
====
include::sample[dir="snippets/ide/xcode/kotlin",files="build.gradle.kts[tags=apply-plugin]"]
include::sample[dir="snippets/ide/xcode/groovy",files="build.gradle[tags=apply-plugin]"]
====

[[sec:xcode_tasks]]
== Tasks

The Xcode Plugin adds a number of tasks to your project.
The main tasks that you will use are the `xcode`, `cleanXcode` and `openXcode` tasks.

The following diagram shows the relationships between tasks added by this plugin.

.Xcode Plugin default task graph
image::xcode-task-graph.png[]

[[sec:xcode_lifecycle_tasks]]
=== Lifecycle Tasks

`xcode` — link:{groovyDslPath}/org.gradle.api.Task.html[Task]::
_Depends on_: `__projectName__XcodeWorkspace` and all `xcodeProject` tasks
+
Generates all Xcode configuration files.

`cleanXcode` — link:{groovyDslPath}/org.gradle.api.tasks.Delete.html[Delete]::
_Depends on_: all Xcode project and workspace file clean tasks
+
Removes all Xcode configuration files.

`openXcode` - link:{groovyDslPath}/org.gradle.api.Task.html[Task]::
_Depends on_: `xcode`
+
Open the Xcode workspace inside the IDE.

[[sec:xcode_workspace_tasks]]
=== IDE Workspace Tasks

`xcodeWorkspaceWorkspaceSettings` - link:{groovyDslPath}/org.gradle.ide.xcode.tasks.GenerateWorkspaceSettingsFileTask.html[GenerateWorkspaceSettingsFileTask]::
+
Generates the `__projectName__.xcworkspace` file. This task is only available on the root project.

`xcodeWorkspace` - link:{groovyDslPath}/org.gradle.ide.xcode.tasks.GenerateXcodeProjectFileTask.html[GenerateXcodeProjectFileTask]::
_Depends on_: `xcodeWorkspaceWorkspaceSettings`
+
Generates the `__projectName__.xcworkspace` file. This task is only available on the root project.

[[sec:xcode_project_tasks]]
=== IDE Project Tasks

Both the <<cpp_application_plugin.adoc#cpp_application_plugin,{cpp} Application Plugin>> and <<cpp_library_plugin.adoc#cpp_library_plugin,{cpp} Library Plugin>> introduce the same tasks for generating Xcode projects to be included in an Xcode workspace.

`xcodeProjectWorkspaceSettings` — link:{groovyDslPath}/org.gradle.ide.xcode.tasks.GenerateWorkspaceSettingsFileTask.html[GenerateWorkspaceSettingsFileTask]::
+
Generates the `__projectName__.xcodeproj/project.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings` file.

`xcodeScheme` — link:{groovyDslPath}/org.gradle.ide.xcode.tasks.GenerateSchemeFileTask.html[GenerateSchemeFileTask]::
+
Generates the `__projectName__.xcodeproj/xcshareddata/xcschemes/__ProjectName__.xcscheme` file.

`xcodeProject` — link:{groovyDslPath}/org.gradle.ide.xcode.tasks.GenerateXcodeProjectFileTask.html[GenerateXcodeProjectFileTask]::
_Depends on_: `xcodeProjectWorkspaceSettings` and `xcodeScheme` (if buildable binary present)
+
Generates the `__projectName__.xcodeproj/project.pbxproj` file.

[[sec:xcode_configuration]]
== Configuration

The Xcode Plugin doesn't allows any customization of the generated files.
