1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
# SwiftRefactor Source Editor Extension
This directory contains an Xcode project that can be used for rapidly iterating
on refactorings built with the SwiftRefactor library.
## Project Structure
The attached project contains two build schemes:
- A host application
- A [Source Editor Extension](https://developer.apple.com/documentation/xcodekit/creating_a_source_editor_extension)
The Source Editor Extension is the only target of interest - the host
application is vestigial and merely exists to provide a container application we
can host the editor extension in.
## Adding Refactoring Actions
This extension automatically discovers refactoring actions present in the
[SwiftRefactor](../Sources/SwiftRefactor) library in the SwiftSyntax package. To add a new refactoring
action, add the corresponding conformance to `RefactoringProvider` and ensure
that it is `public`. Rebuilding and relaunching the extension will pick up your
changes and make them available in Xcode.
## Testing Refactoring Actions in Xcode
Because of code signature requirements, there is some one-time bookkeeping
to perform before Xcode will accept the plugin:
### Code Signing
- Open SwiftRefactorExtension.xcodeproj in Xcode 14+
- Select the SwiftRefactorExtension project in the project navigator
- Select the 'Host' Target
- Navigate to the 'Signing & Capabilities' tab
- Change the 'Team' field to your development team
- Change the 'Signing Certificate' field to an appropriate Development certificate
- Select the 'SwiftRefactorExtension' Target
- Navigate to the 'Signing & Capabilities' tab
- Change the 'Team' field to your development team
- Change the 'Signing Certificate' field to an appropriate Development certificate
### Running The Editor Extension
- Select the 'SwiftRefactorExtension' scheme
- Select 'My Mac' as the run destination
- Select Product > Run
- When prompted, select 'Xcode' as the app to run
- Click 'Run'
### Executing the Refactoring Action
By now, there should be two copies of Xcode running: The Xcode you used to open
this project, and a new Xcode that has a gray dock icon. This gray Xcode is
called the "inferior". The inferior is where the plugin runs both for security
and debuggability. It is a full copy of Xcode, so you can open projects,
edit and run code, and use all of the IDE's normal functionalities.
To run the refactoring actions provided by SwiftRefactorExtension, open
a project or package and select a Swift file in the file navigator. Select
the `Editor` menu. At the very bottom of this menu, an entry called "Swift
Refactoring" should now be visible. Each refactoring action is listed as a
sub-menu, so mousing over it will reveal all of the actions that the editor
extension detected at start up.
Selecting a refactoring action will run it over the entire file. The plugin
executes the corresponding `RefactoringProvider` and, whenever it receives a
non-`nil` response, it performs a structured edit of the syntax of the code.
## Troubleshooting
Here are some common issues you might encounter when using this project
### The Code Doesn't Build
You may be using a version of Xcode that is too old and does not contain Swift
5.7 tools. Please ensure that you have the latest available tools from
the Apple developer portal or Mac App Store.
### I Don't See 'Swift Refactoring' in the Editor Menu
This is usually caused by a code signing issue. Please ensure that you are
signing *both* the Host application and the SwiftRefactorExtension products
with a valid development team and are using a Development signing certificate.
Xcode will refuse to load any improperly signed plugins.
### I Don't See My Refactoring in the 'Swift Refactoring' Menu
SwiftRefactoring relies on type metadata in the SwiftRefactor library to
automatically ingest refactoring actions. To ensure that this metadata is
available, make sure that any instances of `RefactoringProvider ` are declared
`public`. Then rebuild the extension and relaunch the inferior Xcode.
### I Still Don't See My Refactoring in the 'Swift Refactoring' Menu
There is a known limitation of the automatic refactoring action discovery
mechanism where it will not detect refactorings with `Context`s that are
not Void. This is because the plugin has no way of knowing how to build custom
`Context` instances. We hope to lift this restriction soon.
## Requirements
This project uses modern Swift features included with the Swift 5.7 release. As
such, Xcode 14 is required to build this project. Additionally, source editor
extensions are required to be code signed and associated with a development
team. This extension *will not* be run if it is ad-hoc signed.
|
