Skip to content

Commit

Permalink
update add cmd docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ComradeVanti
ComradeVanti committed Oct 2, 2024
1 parent 6c12e8d commit 76c6963
Show file tree
Hide file tree
Showing 3 changed files with 166 additions and 69 deletions.
74 changes: 5 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@ The tool is designed to work with [the OpenUPM registry](https://openupm.com), b
- [Authenticate for the Windows system user](#authenticate-for-the-windows-system-user)
- [Troubleshooting](#troubleshooting)
- [Command options](#command-options)
- [Work with different registries](#work-with-different-registries)
- [Work with proxy](#work-with-proxy)
- [Contributors](#contributors)

Expand Down Expand Up @@ -77,42 +76,14 @@ Please install [Node.js 18 or above](https://nodejs.org/en/download/).

### Add packages

```
openupm add <pkg> [otherPkgs..]
openupm add <pkg>@<version>
openupm add <pkg>@git@github.com:...
openupm add <pkg>@https://github.com/...
openupm add <pkg>@file:...
```

The add command adds the package to the `manifest.json` and configures the scope registry by adding scopes for the package and its dependencies that available on the registry.

The add command doesn't verify package or resolve dependencies for Git, HTTPS, and file protocol. See https://docs.unity3d.com/Manual/upm-git.html for more examples of the version string.

The add command fails if the package is not qualified:

- the package has a missing dependency
- the package requires a non-existed dependency version
- the package requires a higher editor version

You shall either resolve these issues manually or add the option `-f` to continue.
Use `openupm add` to add one or more packages to your project.

You may specify the version to add in a few different ways:

- A specific version like `com.my.package@1.2.0`
- The latest tag like `com.my.package@latest` which will install the latest
published version, including pre-releases.
- No version at all like `com.my.package` which is identical to using the
"latest" tag.
- The stable tag like `com.my.package@stable` which will install the latest
stable version, ie. excluding pre-releases.

You can also add [testables](https://docs.unity3d.com/Manual/cus-tests.html) when importing:

```
openupm --test <pkg>
```sh
openupm add com.my.package@1.2.3
```

Checkout [the commands doc page](./docs/cmd-add.md) for more information.

### Remove packages
```
openupm remove <pkg> [otherPkgs...]
Expand Down Expand Up @@ -250,41 +221,6 @@ Show verbose logging
openupm --verbose ...
```

## Work with different registries

By default the openupm will query any package from the following registries:

1. Openupm (https://package.openupm.com)
2. Unity (https://packages.unity.com)

Any package will be searched on these registries in the order that they are listed above. If you want to install packages from your own third party registries you can do this via the `--registry` option.

```openupm --registry https://package.my-registry.com add com.my.package```

This will query the following registries:

1. The private registry (https://package.my-registry.com)
2. Unity (https://packages.unity.com)

Let's say `com.my.package` depends on a Openupm package. With the above configuration the install would fail because Openupm is not part of the queried registries. To fix, add Openupm to the --registry option.

```openupm --registry https://package.my-registry.com https://package.openupm.com add com.my.package```

The query will now look like this:

1. The private registry (https://package.my-registry.com)
2. Openupm (https://package.openupm.com)
3. Unity (https://packages.unity.com)

Finally, it may not always be desirable to search the Unity registry. If you want to remove it from the registry list, run with the `--no-upstream` option.

```openupm --registry https://package.my-registry.com https://package.openupm.com --no-upstream add com.my.package```

The resulting query is:

1. The private registry (https://package.my-registry.com)
2. Openupm (https://package.openupm.com)

## Work with proxy

OpenUPM-CLI supports HTTP, HTTPS, or SOCKS proxy specified by the http_proxy environment variable.
Expand Down
121 changes: 121 additions & 0 deletions docs/cmd-add.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# `openupm add`

The `add` command adds one or more dependencies to a Unity project. This
means that it adds the given packages to the projects direct dependencies as well as configuring scoped registries so that Unity can
resolve the dependencies.

_Currently openupm does not install the dependencies into the project itself. This is left for Unity to do._

You should run this command inside the projects root directory.

## Arguments

### Packages

Specify one or more packages for openupm to add. The general format for a package reference is `name@version`.

```sh
openupm add com.my.package@1.0.0
```

The version may be one of the following options:

#### No version

This is identical to using the `latest` tag.

Example: `com.my.package`

#### A specific version

Installs the specific given version.

Example: `com.my.package@1.2.0`

#### The latest tag

This resolves the latest published version, including pre-releases.

Example: `com.my.package@latest`

#### The stable tag

This resolves the latest published stable version, excluding pre-releases

Example: `com.my.package@latest`


#### A git url

A `http` or `git` based url to a git repository. Checkout the [Unity documentation on the topic](https://docs.unity3d.com/Manual/upm-git.html#syntax) [^1].

Examples (taken from the Unity documentation):

- `com.my.package@https://github.example.com/myuser/myrepository1.git`
- `com.my.package@git@github.example.com/myuser/myrepository2.git`

#### A local file url

A `file` based url to a local package. Check out the [Unity documentation on the topic](https://docs.unity3d.com/Manual/upm-localpath.html) [^1].

Example (Taken from Unity documentation): `com.my.package@file:../github/my_package_folder`

## Options

### Testables

If you also want to add packages to the [projects testables](https://docs.unity3d.com/Manual/upm-manifestPrj.html#testables) run the command with the `--test` option.

```sh
openupm add com.my.package --test
```

### Force

By default openupm validates added packages to check whether they can be added to the project [^1]. Specifically openupm will check whether all indirect dependencies can be resolved and whether the package is compatible with the projects editor version. If validation fails then the package can not be added.

If you know what you doing and want to add the package even though there are validation problems you can run with the `--force`/`-f` option to bypass validation.

```sh
openupm add com.my.package --force
```

### Registry

By default openupm resolves packages from the openupm and Unity registries in that order. This behavior is configurable, specifically if you want to work with 3rd party registries.

You can override the primary registry from which to resolve packages using the `--registry` option.

```sh
openupm add com.my.package --registry https://packages.my.registry
```

You can also use the `--no-upstream` option if you don't want to resolve from the Unity registry.

```sh
openupm add com.my.package --no-upstream
```

For more information read [the help article about working with 3rd party registries](./help-registry.md).

### Project directory

By default openupm expects that you run the add command inside your Unity projects root directory. Based on this it determines relative paths to your package manifest etc.

If you need to run openupm from somewhere else you can change the working directory using the `--chdir`/`-c` option. This option accepts an **absolute** path to a Unity projects root directory.

```sh
openupm add com.my.package -c /home/user/dev/MyProject
```

### Windows system user

By default openupm collects registry authentication credentials from the users local `.upmconfig.toml`.

If you want to authenticate with registries using the `.upmconfig.toml` file for the Windows system user then pass the `--system-user` option.

```sh
openupm add com.my.package --system-user
```

[^1]: openupm does not validate or resolve indirect dependencies for url-based dependencies.
40 changes: 40 additions & 0 deletions docs/help-registry.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Work with different registries

By default the openupm will query any package from the following registries:

1. Openupm (https://package.openupm.com)
2. Unity (https://packages.unity.com)

Any package will be searched on these registries in the order that they are listed above. If you want to install packages from your own third party registries you can do this via the `--registry` option.

```sh
openupm --registry https://package.my-registry.com add com.my.package
```

This will query the following registries:

1. The private registry (https://package.my-registry.com)
2. Unity (https://packages.unity.com)

Let's say `com.my.package` depends on a Openupm package. With the above configuration the install would fail because Openupm is not part of the queried registries. To fix, add Openupm to the --registry option.

```sh
openupm --registry https://package.my-registry.com https://package.openupm.com add com.my.package
```

The query will now look like this:

1. The private registry (https://package.my-registry.com)
2. Openupm (https://package.openupm.com)
3. Unity (https://packages.unity.com)

Finally, it may not always be desirable to search the Unity registry. If you want to remove it from the registry list, run with the `--no-upstream` option.

```sh
openupm --registry https://package.my-registry.com https://package.openupm.com --no-upstream add com.my.package
```

The resulting query is:

1. The private registry (https://package.my-registry.com)
2. Openupm (https://package.openupm.com)

0 comments on commit 76c6963

Please sign in to comment.