Link configuration and linkspec¶

Link configuration file¶

At the heart of each link operation is a YAML configuration file, which defines how symbolic links should be created to make a Unity project. By default, the file is named upkit.yaml, and can be changed to whatever needed. A typical configuration should look like this:

params:
  project: '{{__dir__}}/project'
  project_packages: '{{__dir__}}/packages'

links:
  - source: '{{project_packages}}/Scripts'
    target: '{{__assets__}}/Scripts'

Parameters¶

To make linking more configurable, there are two types of parameters supported by Upkit:

Built-in parameters: those with name enclosed by __, for instance __dir__ and __assets__, are generated by Upkit and shall not be defined. The list of built-in parameters are defined here.
User parameters: those defined by user, under params section.

For each configuration file, there MUST be a project parameter defined, which tells Upkit where to generate the links.

Defining and expanding parameters¶

Defining a parameter can be as simple as:

params:
  some_param: 'some value'

However, most of the time, parameters are defined by expanding other existing parameters using Jinja syntax, such as:

params:
  platform: 'ios'
  project: '{{__dir__}}/project-{{platform}}'
  project_settings: '{{project}}/ProjectSettings'

Builtin parameters¶

The table below describes Upkit built-in parameters.

Name	Description
`__cwd__`	Path to current working folder.
`__dir__`	Path to the folder containing the current configuration or linkspec file.
`__project__`	Path to the Unity project.
`__assets__`	Path to the Unity project's Assets folder.
`__plugins__`	Path to the Unity project's Plugins folder.
`__source__`	The source parameter in a linkspec.
`__target__`	The target parameter in a linkspec.

Note that only __cwd__ and __dir__ are accessible in params section.

Overwriting parameters¶

Given a configuration, its user-defined parameters can be overwriten at link-time by passing -p param_name=param_value to link command. This is particularly useful when you need to use the configuration file as a template for multiple Unity projects with slightly different parameters. For example, a configuration for multiple platforms may look like:

params:
  platform: 'ios'
  project: '{{__dir__}}/project-{{platform}}'
...

Execute the following commands:

$ upkit link
$ upkit link -p platform=android
$ upkit link -p platform=windows 

will create project-ios, project-android and project-windows as separate Unity project folders.

Linkspec¶

To generate Unity projects, Upkit requires a list of link specifications, or linkspecs, which basically is a way to tell Upkit where to find a package, its content (all or partial) and a target to which the content is linked. A linkspec may be defined using properties in the table below:

Linkspec properties

Name	Description
`source`	Source package location, can be a local or remote package.
`content`	Patterns describing source content.
`exclude`	Patterns describing files and folders not included in the source content.
`target`	The target to which the source or its content is linked.
`links`	A list of sub-linkspecs for more complex linking.

`source` property¶

The source property describes a source package location containing files and folder to link. There are three types of source packages supported by Upkit:

Local file or folder, when source takes the syntax /path/to/local-file-or-folder.
A Nuget package, when source takes the syntax nuget:(package_id)@(package_version)[#(sub_path)], in which:
- package_id and package_verion are required.
- sub_path is optional.
A Git repository, when source takes the syntax git:(repository_url)[@(branch_or_tag)][#(sub_path)], in which:
- repository_url is required.
- branch_or_tag and sub_path are optional.

When source refers to a Nuget package or a Git repository, Upkit first resolves the package or repository into a local folder under the container folder given by -w parameter (default to .packages), and then uses the resolved folder as a local source. If sub_path is given, the sub-path in the resolved folder is used as the local source instead.

Examples:

{{__dir__}}/Scripts
nuget:NewtonSoft.Json@11.0.2
nuget:NewtonSoft.Json@11.0.2#lib/net35
git:https://github.com/finderseyes/upkit.git@develop
git:https://github.com/finderseyes/upkit.git#examples/simple-app
git:https://github.com/finderseyes/upkit.git@develop#examples/simple-app

`content` property¶

By default, if content is not specified, Upkit treats a linkspec as link-all i.e. it will create one link from its source to its target. To patially link a source, declare its content as a list of glob patterns in the example below:

# include everything
content: ['*']

# include only files or folders under scripts/ and textures/.
content: ['scripts/*', 'textures/*']

When content is specified, Upkit will create multiple links, one for each item in the source content to an item with the same name under target. For example, given the following content items:

(source)/data/child/A/
(source)/data/B.txt
(source)/C.png

Upon linking, the following links will be created:

(target)/A/    --> (source)/data/child/A/
(target)/B.txt --> (source)/data/B.txt
(target)/C.png --> (source)/C.png

`exclude` property¶

exclude can be used in tandem with content to ignore some of the files and folders in a source content. exclude takes a list of patterns similar to content. For example:

content: ['*']
exclude: ['Document', 'Document.meta']

will include everything under a source package, except its Document and Document.meta.

`target` property¶

As the name implies, target is a local path defining where a source or its content should be linked to.

`links` property¶

A linkspec may use sub-links, under links property, when it needs to define multiple link targets. Each item in links is also a linkspec, except that it shall not have further sub-links i.e. source, target, content, and exclude are allowed but not links.

links is often used in package linkspec files as explained in Package linkspec. However, it can also be used to link packages where no linkspec file is provided, or to overwrite the linkspec of incompatible packages.

Package linkspec¶

A package linkspec file could be included in a package to make linking with it easier when shared across multiple projects. Given a package A, Upkit tries to look for its linkspec file in the following paths:

A/linkspec.yaml
A/linkspec.yml
A/content/linkspec.yaml
A/content/linkspec.yml

The format of linkspec file is also a linkspec as explained in Linkspec section.

In the case where a package A has a linkspec file, linking with it can be as simple as:

# upkit.yaml
links:
  - source: '/source/to/A'

`source` and `target` parameters¶

In linkspec files, two additional built-in parameters __source__ and __target__ are available, if specified.

Overwrite package linkspec¶

A package linkspec can be overwriten in a configuration file if one of these properties are defined:

content
exclude
links

In such case, Upkit will ignore the package linkspec and use the one in link configuration. For example:

# upkit.yaml
links:
  - source: '/source/to/A'
    target: '/target/to-link'
    content: ['data/*']

In this case, Upkit links all items under A/data to target, regardless of whatever A linkspec file defines.