This page explains dependencies (sources) by building upon the environments example. For the complete result of this example, see the GitLab repository. Note that this repository contains content for other examples as well, as the documentation uses a single package for all examples.
On This Page
Recursive Dependency
A recursive dependency is described by a source without a related directory. It points to the root directory of the package and enables self-maintenance.
Let's make this example link itself. Modify the content in the
production file fusion.json
as follows:
{
"name": "Package",
"description": "Basic example package.",
"id": "valvoid/package",
"version": "0.1.0",
"structure": {
"gitlab.com/valvoid/'fusion/'php": "package/==1.0.0-dev:main",
"/cache": "cache"
},
"environment": {
"php": {
"version": "8.1.0"
}
}
}
Note that the source is a key-value pair. Like the directory entry, it can also be a key segmented by a forward slash separator. To differentiate between the two associative key types, unlike the directory, the source does not start with a forward slash. Additionally, in order to explain as much as possible in this example, the source is built as follows:
- The source starts with the
gitlab.com
API. -
The superset
/valvoid/'fusion/'php/package
path, which represents the package identifiervalvoid/package
without the segments with the single-quote prefix'
. -
The
==1.0.0-dev:main
offset reference to pull the last commit in themain
branch, which Fusion then handles as the1.0.0-dev
version
.
Since sources link only production packages, reset the recursive source for
the shared development. Modify the shared fusion.dev.php
file as follows:
<?php
// metadata array
return [
"structure" => [
// directory prefix segments
// relative to package root
"/cache/loadable/tests" => "Valvoid\Package\Tests",
// API
"gitlab.com" => [
// path
"valvoid" => [
"'fusion" => [
"'php" => [
"package" =>
// reference
null
]
]
]
]
]
];
To illustrate the overlay and reset logic within the parser/normalizer, the
source is completely segmented. This is how both directory and source entries
appear during the overlay process. The reset value null
must be the
last segment. Otherwise, the parser creates two different source entries.
For example, if you attempt to reset the source at the 'php
segment, the
value would look like this:
// ...
"'php" => [
"package" => "==1.0.0-dev:main",
null
]
In your terminal, set the working directory to any directory within the package
and execute the following
build
command:
php fusion build
Once done, the /cache
directory will contain the files snapshot.json
,
snapshot.dev.json
, and snapshot.local.json
, created by the helper
snap
task.
Share and publish these files (even if empty) to enable replication for your package.
Nested Dependency
A nested dependency is described by a source that points to a directory relative to the package root.
For further examples in the Extensions chapter, we will need Fusion as a
dependency. To prepare for this, you could (but don't do this yet) modify the
content in the production file fusion.json
as follows:
{
"name": "Package",
"description": "Basic example package.",
"id": "valvoid/package",
"version": "0.1.0",
"structure": {
"/cache": "cache",
"gitlab.com/valvoid": {
"'fusion/'php/": "package/1.0.0-dev:main",
"/dependencies": "fusion/'php/'code/1.0.0"
}
},
"environment": {
"php": {
"version": "8.1.0"
}
}
}
Note that in this example metadata, both sources share a common prefix that also
wraps Fusion's directory. Within developer-optimized input, you can split sources
and directories by segments and mix them as needed. As mentioned above, the
directory key starts with a slash /
.
Alright, back to the "(but don't do this yet)" part. Modify the content in the
production file fusion.json
as follows:
{
"name": "Package",
"description": "Basic example package.",
"id": "valvoid/package",
"version": "0.1.0",
"structure": {
"gitlab.com/valvoid/'fusion/'php": "package/==1.0.0-dev:main",
"/cache": "cache",
"/dependencies": [
"valvoid.com/valvoid/fusion/1.0.0"
]
},
"environment": {
"php": {
"version": "8.1.0"
}
}
}
Since Fusion is a real-world default package, this metadata describes a pull from the default registry. It is recommended to pull production releases if possible. Use development platform APIs only for development purposes.
Now, execute the following
build
command
again:
php fusion build
Once done, the snapshot.json
file in the /cache
directory will contain
the following content:
{
"valvoid/fusion": "1.0.0"
}