Skip to content

Commit ebbdbdf

Browse files
0xTim0xTim
authored
Merge pull request #3265 from samuelmurray/global-mirrors-configuration-cli
SE-NNNN Add CLI for editing global mirrors configuration
2 parents b8e1751 + 32ab291 commit ebbdbdf

1 file changed

Lines changed: 139 additions & 0 deletions

File tree

‎proposals/NNNN-global-mirrors-configuration-cli.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Add CLI for editing global mirrors configuration
2+
3+
* Proposal: [SE-NNNN](NNNN-global-mirrors-configuration-cli.md)
4+
* Authors: [Samuel Murray](https://github.com/samuelmurray)
5+
* Review Manager: TBD
6+
* Status: **Awaiting implementation**
7+
* Implementation: [swiftlang/swift-package-manager#9950](https://github.com/swiftlang/swift-package-manager/pull/9950)
8+
9+
## Introduction
10+
11+
SPM has support for both local (per-project) and shared (per-user) mirrors configuration, though the CLI only allows for editing the local configuration file. This proposal adds an optional `--global` flag to the existing CLI for editing the global configuration.
12+
13+
Swift-evolution thread: [Pitch: Add CLI to edit global configuration of mirrors](https://forums.swift.org/t/pitch-add-cli-to-edit-global-configuration-of-mirrors/86091)
14+
15+
## Motivation
16+
17+
Originally, mirrors could only be configured locally, per project, as described by the [original proposal](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0219-package-manager-dependency-mirroring.md).
18+
However, support for a global configuration file was added in a [later release](https://github.com/swiftlang/swift-package-manager/pull/3670), mirroring the design of package registries, which has supported local and global configuration since the start. Global configuration files for mirrors and package registries are especially useful in enterprise environments, where certain packages will always be accessed from a custom URL. The usefulness of global configuration is increased even further with the upcoming [support for mirroring of binary targets](https://github.com/swiftlang/swift-package-manager/pull/9647).
19+
20+
However, there is currently no easy way to edit and view the global mirrors configuration. The only option is to manually create and edit the configuration file. Providing a CLI for this aligns the feature with global package registries, while also increasing the discoverability of global mirrors configuration.
21+
22+
## Proposed solution
23+
24+
The CLI for interacting with the local configuration file is
25+
26+
* `swift package config set-mirror`
27+
* `swift package config unset-mirror`
28+
* `swift package config get-mirror`
29+
30+
This proposal adds an optional `--global` flag to each of these commands.
31+
32+
### Example
33+
34+
To add global configuration for a mirror of `https://example.com/file.json`:
35+
36+
```bash
37+
$ swift package config set-mirror --global --original https://example.com/file.json --mirror https://internal.com/file.json
38+
```
39+
40+
This adds the following to `~/.swiftpm/configuration/mirrors.json` (creating the file if it doesn't exist):
41+
42+
```json
43+
{
44+
"object" : [
45+
{
46+
"mirror" : "https://internal.com/file.json",
47+
"original" : "https://example.com/file.json"
48+
}
49+
// ...
50+
],
51+
"version" : 1
52+
}
53+
```
54+
55+
To view this configuration:
56+
57+
```bash
58+
$ swift package config get-mirror --global --original https://example.com/file.json
59+
https://internal.com/file.json
60+
```
61+
62+
To unset the configuration:
63+
64+
```bash
65+
$ swift package config unset-mirror --global --original https://example.com/file.json
66+
```
67+
68+
Taking inspiration from the CLI for package registries, I suggest that we add a `--global` flag for each of these commands, e.g. `swift package config set-mirror --global [...]`. All of these commands, when used with this flag, will only consider the global configuration file. By using this flag, the command can be run in any directory, unlike the current (unflagged) command which fails if the current directory (or any of its parents) does not contain a Package.swift file.
69+
The current behaviour of swift package config get-mirror is that if the local configuration files is empty, or doesn't exist, then the global configuration file is read. I propose to leave this behaviour unchanged. To me, it would make more sense if the local and global configuration was merged (with local having higher priority) rather than ignoring all global configuration if any local configuration exists. However, I think such a changed is somewhat unrelated, and could be made as a follow-up proposal to this one.
70+
71+
## Detailed design
72+
73+
All of the commands, when used with the `--global` flag, can be used in any directory. That is, the current directory (or any parent directories) is not required to contain a `Package.swift` file.
74+
75+
When used without the `--global` flag, the behaviour of all commands are unchanged.
76+
77+
### set-mirror
78+
79+
```bash
80+
$ swift package config set-mirror --help
81+
OVERVIEW: Set a mirror for a dependency.
82+
83+
USAGE: swift package config set-mirror [--global] [--original <original>] [--mirror <mirror>]
84+
85+
OPTIONS:
86+
--global Apply settings to all projects for this user.
87+
--original <original> The original url or identity.
88+
--mirror <mirror> The mirror url or identity.
89+
--version Show the version.
90+
-h, -help, --help Show help information.
91+
```
92+
93+
Running this command appends the mirror configuration to `~/.swiftpm/configuration/mirrors.json`, or create the file if it does not exist.
94+
95+
### unset-mirror
96+
97+
```bash
98+
$ swift package config unset-mirror --help
99+
OVERVIEW: Remove an existing mirror.
100+
101+
USAGE: swift package config unset-mirror [--original <original>] [--mirror <mirror>]
102+
103+
OPTIONS:
104+
--global Apply settings to all projects for this user.
105+
--original <original> The original url or identity.
106+
--mirror <mirror> The mirror url or identity.
107+
--version Show the version.
108+
-h, -help, --help Show help information.
109+
```
110+
111+
Running this command removes the matching mirror configuration from `~/.swiftpm/configuration/mirrors.json`. If no matching entry is found, or the file does not exist, display an error message.
112+
113+
### get-mirror
114+
115+
```bash
116+
OVERVIEW: Print mirror configuration for the given package dependency.
117+
118+
USAGE: swift package config get-mirror [--original <original>]
119+
120+
OPTIONS:
121+
--global Only read settings applied to all projects for this user.
122+
--original <original> The original url or identity.
123+
--version Show the version.
124+
-h, -help, --help Show help information.
125+
```
126+
127+
Running this command retrieves the matching mirror configuration from `~/.swiftpm/configuration/mirrors.json`. If no matching entry is found, or the file does not exist, display an error message.
128+
129+
## Security
130+
131+
This proposal has minimal impact on security. It modifies (or reads from) a file in the user's home directory. In the [original proposal](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0219-package-manager-dependency-mirroring.md) for mirrors, it was argued that a global configuration risk causing "gotcha moments". However, since support for global mirrors configuration has since been added to SPM, adding this CLI introduces no new issues.
132+
133+
## Impact on existing packages
134+
135+
This proposal has no impact on existing packages. It only adds a new CLI flag; no existing behavior is changed.
136+
137+
## Alternatives considered
138+
139+
_None_

0 commit comments

Comments
 (0)