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 <[email protected]>
Change-Id: If8f735118d92d1e9918f73a3597262c214377ff0
Dispatch-Trailer: {"type":"trybot","CL":1203884,"patchset":7,"ref":"refs/changes/84/1203884/7","targetBranch":"master"}

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.

content/docs/concept/faq/symbolic-link-support/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: faq: "symbolic-link-support": page: _

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.