Skip to content

Latest commit

 

History

History
193 lines (146 loc) · 8.56 KB

configuration-linkspec.md

File metadata and controls

193 lines (146 loc) · 8.56 KB
Raw

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.