From 680a0295c1dc37ba93dac7ec39d0bbc5195d23f0 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Tue, 19 Nov 2024 12:31:23 +0000 Subject: [PATCH] docs/concept: symbolic link support FAQ This adds an FAQ page on CUE's now-formalised support for symbolic links, as per https://cuelang.org/issue/3300#issuecomment-2429401231. Closes cue-lang/docs-and-content#187. Preview-Path: /docs/concept/faq/symbolic-link-support/ Signed-off-by: Jonathan Matthews Change-Id: If8f735118d92d1e9918f73a3597262c214377ff0 Dispatch-Trailer: {"type":"trybot","CL":1203884,"patchset":7,"ref":"refs/changes/84/1203884/7","targetBranch":"master"} --- .../concept/faq/symbolic-link-support/en.md | 53 +++++++++++++++++++ .../faq/symbolic-link-support/page.cue | 3 ++ .../faq/symbolic-link-support/index.md | 53 +++++++++++++++++++ 3 files changed, 109 insertions(+) create mode 100644 content/docs/concept/faq/symbolic-link-support/en.md create mode 100644 content/docs/concept/faq/symbolic-link-support/page.cue create mode 100644 hugo/content/en/docs/concept/faq/symbolic-link-support/index.md diff --git a/content/docs/concept/faq/symbolic-link-support/en.md b/content/docs/concept/faq/symbolic-link-support/en.md new file mode 100644 index 000000000..73c6aebf1 --- /dev/null +++ b/content/docs/concept/faq/symbolic-link-support/en.md @@ -0,0 +1,53 @@ +--- +title: Symbolic link support in CUE +author: [jpluscplusm] +toc_hide: false +--- + +Both the `cue` command and the CUE Go API support +[symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) +("symlinks") on operating systems where the feature is available. +However, symlinks are rejected and ignored whenever they become the contents of +a CUE module stored in a module registry. + +This guide answers some questions about CUE's support for symlinks. + +## Can I use symlinks to help organise my CUE code? + +**Yes**. +When writing your own CUE code you can rely on CUE to respect any filesystem +symlinks you put in place. +This includes establishing symlinks that create: + +- CUE files (e.g. `file.cue` links to `some.other.file`) +- package directories (e.g. `foo/` links to `bar/`) +- data files that are included via the + [`@embed()` attribute]({{< relref "/docs/howto/embed-files-in-cue-evaluation" >}}) + (e.g. `data.json` links to `../../../some.data`) + +## Can I publish a CUE module that relies on symlinks? + +**No**. +When the `cue mod publish` command is used to publish a module to a registry, +it silently ignores any symlinks contained in the module. +Any symlinks are left in place locally (on the computer that publishes the +module) but they will not be present in the published module. + +## Can I depend on a CUE module that relies on symlinks? + +**No**. +When the `cue` command fetches and unpacks a module from a registry, it +doesn't create any symlinks that it finds in the module. +If any CUE contained in a module relies on the presence of symlinks to work +correctly then it will not work as expected after being unpacked. +CUE's exact behaviour when processing symlinks in published modules is system- +and release-dependent, but a working symlink will not be created in any +situation. + +This is done separately from `cue mod publish` ignoring symlinks when +*publishing* modules because CUE uses industry-standard +[OCI registries]({{< relref "docs/reference/modules" >}}#modules-overview) +to store modules, and CUE cannot be certain that the `cue` command was used to +publish the module artifact being fetched. +Therefore, even if a published module somehow contains symlinks, those links +will not be usable by any consumer of the module. diff --git a/content/docs/concept/faq/symbolic-link-support/page.cue b/content/docs/concept/faq/symbolic-link-support/page.cue new file mode 100644 index 000000000..8bf6d2a22 --- /dev/null +++ b/content/docs/concept/faq/symbolic-link-support/page.cue @@ -0,0 +1,3 @@ +package site + +content: docs: concept: faq: "symbolic-link-support": page: _ diff --git a/hugo/content/en/docs/concept/faq/symbolic-link-support/index.md b/hugo/content/en/docs/concept/faq/symbolic-link-support/index.md new file mode 100644 index 000000000..73c6aebf1 --- /dev/null +++ b/hugo/content/en/docs/concept/faq/symbolic-link-support/index.md @@ -0,0 +1,53 @@ +--- +title: Symbolic link support in CUE +author: [jpluscplusm] +toc_hide: false +--- + +Both the `cue` command and the CUE Go API support +[symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) +("symlinks") on operating systems where the feature is available. +However, symlinks are rejected and ignored whenever they become the contents of +a CUE module stored in a module registry. + +This guide answers some questions about CUE's support for symlinks. + +## Can I use symlinks to help organise my CUE code? + +**Yes**. +When writing your own CUE code you can rely on CUE to respect any filesystem +symlinks you put in place. +This includes establishing symlinks that create: + +- CUE files (e.g. `file.cue` links to `some.other.file`) +- package directories (e.g. `foo/` links to `bar/`) +- data files that are included via the + [`@embed()` attribute]({{< relref "/docs/howto/embed-files-in-cue-evaluation" >}}) + (e.g. `data.json` links to `../../../some.data`) + +## Can I publish a CUE module that relies on symlinks? + +**No**. +When the `cue mod publish` command is used to publish a module to a registry, +it silently ignores any symlinks contained in the module. +Any symlinks are left in place locally (on the computer that publishes the +module) but they will not be present in the published module. + +## Can I depend on a CUE module that relies on symlinks? + +**No**. +When the `cue` command fetches and unpacks a module from a registry, it +doesn't create any symlinks that it finds in the module. +If any CUE contained in a module relies on the presence of symlinks to work +correctly then it will not work as expected after being unpacked. +CUE's exact behaviour when processing symlinks in published modules is system- +and release-dependent, but a working symlink will not be created in any +situation. + +This is done separately from `cue mod publish` ignoring symlinks when +*publishing* modules because CUE uses industry-standard +[OCI registries]({{< relref "docs/reference/modules" >}}#modules-overview) +to store modules, and CUE cannot be certain that the `cue` command was used to +publish the module artifact being fetched. +Therefore, even if a published module somehow contains symlinks, those links +will not be usable by any consumer of the module.