# Configure Swift with Nexus

Configure your SPM registry to connect to and authenticate to a Nexus Swift Repository. Swift Package Manager (SPM) uses a `registries.json` file to define registry endpoints. Note that you must create a Swift repository in Nexus before configuring your Swift client to connect to it. Refer to [Create a Swift Repository](https://help.sonatype.com/en/create-a-swift-repository.html "Create a Swift Repository") for more details.

SPM can be configured through two methods:

- [Registry Login](https://help.sonatype.com/en/configure-spm-registry.html#registry-login "Registry Login")
- [Embedded Credentials](https://help.sonatype.com/en/configure-spm-registry.html#embedded-credentials "Embedded Credentials")

| Configuration Method | Platforms | Best For |
| --- | --- | --- |
| Registry Login | - MacOS<br>  <br>- Linux | HTTPS Only |
| Embedded Credentials | - MacOS<br>  <br>- Linux<br>  <br>- Windows | HTTPS and HTTP |

## Registry Login

Use the Registry Login configuration method when your SPM client is on MacOS/Linux and only HTTPS support is required.

1. From your Swift project directory, run the following command to add the Nexus repository to your Swift registry configuration:

```
   swift package-registry set "https://[NexusURL]/repository/<REPO_NAME>/"
   ```

**Note**

To configure the registry globally for all Swift projects, use the following command:
   
   
   ```
   swift package-registry set --global "https://[NexusURL]/repository/<REPO_NAME>/"
   ```
   
   Where,
   
   - `[NexusURL]` \- The URL of your Nexus instance
   - `<REPO_NAME>` \- The name of the target repository in Nexus

For example:
   
   ```
   swift package-registry set "https://example.nexus.com/repository/swift-proxy/"
   ```
   This will create the `.swiftpm/configuration/registries.json` file.

An example with `--global` flag:
   
   ```
   swift package-registry set --global "https://example.nexus.com/repository/swift-proxy/"
   ```
   This will create the `~/Library/org.swift.swiftpm/configuration/registries.json` file.

2. Authentication: Login to your Nexus instance with SPM.
   
   ```
   swift package-registry login https://[NexusURL]/repository/<REPO_NAME>/login \
       --username=<USER_TOKEN_NAME_CODE> \
       --password=<USER_TOKEN_PASS_CODE>
   ```
   
   **Note**

If you have Nexus Anonymous Access turned ON, you can skip this login step.
   
   Where,
   
   - `[NexusURL]` \- The URL of your Nexus instance
   - `<REPO_NAME>` \- The name of the target repository in Nexus
   - `<USER_TOKEN_NAME_CODE>` \- Your Nexus username or the Nexus Pro only User Token Name Code
   - `<USER_TOKEN_PASS_CODE>` \- Your Nexus password or the Nexus Pro only User Token Pass Code

**Tip**
   
   Sonatype recommends using User Token Name Code and User Token Pass Code instead of username and password. To access your Token Names:
   
   Go to _Account_ → _User Token_ → _Access User Token_ → _Authenticate_
   
   - Copy the User Token Name Code
   - Copy the User Token Pass Code

Example:
   ```
   swift package-registry login https://example.nexus.com/repository/swift-hosted/login \
    --username="abcdefg" \
    --password='-dXXXXXXXXXXXXXX'
   ```
   **Note**
   
   If your password contains "`-d`", use query parameters for the login request to avoid it being parsed incorrectly.

## Embedded Credentials

Use the Embedded Credentials configuration method when your SPM client is on MacOS/Linux/Windows and requires support of HTTP or HTTPS.

### macOS

1. Create the `configuration` directory and `registries.json` file.

```
   mkdir -p ~/Library/org.swift.swiftpm/configuration \
        && touch ~/Library/org.swift.swiftpm/configuration/registries.json
   ```

2. Insert registry and authentication content in `registries.json` file.

```
   cat > ~/Library/org.swift.swiftpm/configuration/registries.json <<'EOF'
   {
        "registries": {
          "[default]": {
            "url": "https://<USER_TOKEN_NAME_CODE>:<USER_TOKEN_PASS_CODE>@[NexusURL]/repository/<REPO_NAME>/"
          }
        },
        "version": 1
   }
   EOF
   ```
   
   Where,
   
   - `<USER_TOKEN_NAME_CODE>` \- Your Nexus username or the Nexus Pro only User Token Name Code.
   - `<USER_TOKEN_PASS_CODE>` \- Your Nexus password or the Nexus Pro only User Token Pass Code
   - `[NexusURL]` \- The URL of your Nexus instance
   - `<REPO_NAME>` \- The name of the target repository in Nexus

Example:
   ```
   cat > ~/Library/org.swift.swiftpm/configuration/registries.json <<'EOF'
   {
     "registries": {
       "[default]": {
         "url": "https://admin:admin123@example.nexus.com/repository/swift-hosted/"
       }
     },
     "version": 1
   }
   EOF
   ```

For Xcode configuration, see [Use Nexus with Xcode](https://help.sonatype.com/en/configure-spm-registry.html#use-nexus-with-xcode "Use Nexus with Xcode")

### Linux

1. Create the `configuration` directory and `registries.json` file.
   
   ```
   mkdir -p ~/.swiftpm/configuration \
        && touch ~/.swiftpm/configuration/registries.json
   ```

2. Insert registry and authentication content in `registries.json` file.

```
   cat > ~/.swiftpm/configuration/registries.json <<'EOF'
   {
        "registries": {
          "[default]": {
            "url": "https://<USER_TOKEN_NAME_CODE>:<USER_TOKEN_PASS_CODE>@[NexusURL]/repository/<REPO_NAME>/"
        },
        "version": 1
   }
   EOF
   ```
   
   Where
   
   - `<USER_TOKEN_NAME_CODE>` \- Your Nexus username or the Nexus Pro only User Token Name Code.
   - `<USER_TOKEN_PASS_CODE>` \- Your Nexus password or the Nexus Pro only User Token Pass Code
   - `[NexusURL]` \- The URL of your Nexus instance
   - `<REPO_NAME>` \- The name of the target repository in Nexus

Example:
   ```
   cat > ~/.swiftpm/configuration/registries.json <<'EOF'
   {
     "registries": {
       "[default]": {
         "url": "https://admin:admin123@example.nexus.com/repository/swift-hosted/"
       }
     },
     "version": 1
   }
   EOF
   ```

### Windows

1. Create the `configuration` directory and `registries.json` file.

```
   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.swiftpm\configuration" | Out-Null
   New-Item -ItemType File -Force -Path "$env:USERPROFILE\.swiftpm\configuration\registries.json"
   ```

2. Insert registry and authentication content in `registries.json` file. Note that while using anonymous access, it is not required to use user token name code and passcode.

```
   @'
   {
        "registries": {
          "[default]": {
            "url": "https://<USER_TOKEN_NAME_CODE>:<USER_TOKEN_PASS_CODE>@[NexusURL]/repository/<REPO_NAME>/"
          }
        },
        "version": 1
   }
   '@ | Set-Content -Encoding UTF8 "$env:USERPROFILE\.swiftpm\configuration\registries.json"
   ```
   
   Where,
   
   - `<USER_TOKEN_NAME_CODE>` \- Your Nexus username or the Nexus Pro only User Token Name Code.
   - `<USER_TOKEN_PASS_CODE>` \- Your Nexus password or the Nexus Pro only User Token Pass Code
   - `[NexusURL]` \- The URL of your Nexus instance
   - `<REPO_NAME>` \- The name of the target repository in Nexus

Example:
   ```
   @'
   {
     "registries": {
       "[default]": {
         "url": "https://admin:admin123@example.nexus.com/repository/swift-hosted/"
       }
     },
     "version": 1
   }
   '@ | Set-Content -Encoding UTF8 "$env:USERPROFILE\.swiftpm\configuration\registries.json"
   ```

## Use Nexus with Xcode

Xcode is Apple’s integrated development environment for building applications on Apple platforms. Developers use Xcode to create projects, add dependencies, build, run, and test applications. See [Xcode - Apple Developer](https://developer.apple.com/xcode/)

Use this section to configure Xcode to fetch Swift packages from a Nexus Swift registry.

### Prerequisites

Before you add packages in Xcode, make sure you have:

- Nexus repository URL
- Username and password or user token for the repository
- Access to the Xcode project where you want to add the package

### Configure Credentials

To let Xcode authenticate to the Nexus Swift registry, add your repository credentials to the `~/.netrc` file.

1. Open the `~/.netrc` file.

```
   ~/.netrc
   ```

2. Add an entry for the Nexus host.

```
   machine <host>
        login <username>
        password <password>
   ```

3. Save the file.

4. Set the required file permissions.

```
   chmod 600 ~/.netrc
   ```

### Configure Swift Package Registry for Xcode

To let Xcode locate the Nexus Swift registry, add the registry configuration to the `registries.json` file.

1. Open the `registries.json` file.

```
   ~/Library/org.swift.swiftpm/configuration/registries.json
   ```

If the configuration directory does not exist, create it.
   
   ```
   mkdir -p ~/Library/org.swift.swiftpm/configuration/
   ```

2. Add the registry configuration.

```
   {
        "authentication": {
          "<host>": {
            "loginAPIPath": "/repository/<repository-name>/login",
            "type": "basic"
          }
        },
        "registries": {
          "[default]": {
            "supportsAvailability": false,
            "url": "https://<host>/repository/<repository-name>/"
          }
        },
        "version": 1
   }
   ```
   
   Where,
   
   - `<host>`: Your Nexus URL, for example `example.nexus.com`
   - `<repository-name>`: Your Nexus repository name, for example _swift-group_

### Add a Package Dependency in Xcode

To add a package from the Nexus Swift registry to an Xcode project, use the _Add Package Dependencies_ command in Xcode.

1. Open Xcode. Create a project, or open an existing project.

2. From the _File_menu, select_Add Package Dependencies_.

3. In the _search_ field, enter the package identifier in `SCOPE.PACKAGENAME` format.

4. Select the package version and target.

5. Select _Add Package_.

Example package identifiers:

```
apple.swift-log
apple.swift-algorithms
```
If your project uses a `Package.swift` manifest, declare dependencies with registry identifiers:

```swift
// swift-tools-version:5.9
import PackageDescription

let package = Package(
    name: "MyApp",
    dependencies: [\
        .package(id: "apple.swift-log", from: "1.0.0"),\
        .package(id: "apple.swift-algorithms", from: "1.0.0"),\
    ],
    targets: [\
        .target(\
            name: "MyApp",\
            dependencies: [\
                .product(name: "Logging", package: "apple.swift-log"),\
                .product(name: "Algorithms", package: "apple.swift-algorithms"),\
            ]\
        ),\
    ]
)
```