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 syntaxnuget:(package_id)@(package_version)[#(sub_path)]
, in which:package_id
andpackage_verion
are required.sub_path
is optional.
- A Git repository, when
source
takes the syntaxgit:(repository_url)[@(branch_or_tag)][#(sub_path)]
, in which:repository_url
is required.branch_or_tag
andsub_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.