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":9,"ref":"refs/changes/84/1203884/9","targetBranch":"master"}

content/docs/concept/faq/symbolic-link-support/en.md

@@ -0,0 +1,44 @@
+---
+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 ignored when they are part of a CUE module published to
+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 include symlinks when publishing a CUE module?
+
+**No**.
+When the `cue mod publish` command publishes 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 published module relies on the presence of symlinks
+to work correctly then it will not work as expected after being unpacked.
+CUE's behaviour when it finds symlinks in published modules is undefined,
+but will not result in a working symlink being created in any case.

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,44 @@
+---
+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 ignored when they are part of a CUE module published to
+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 include symlinks when publishing a CUE module?
+
+**No**.
+When the `cue mod publish` command publishes 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 published module relies on the presence of symlinks
+to work correctly then it will not work as expected after being unpacked.
+CUE's behaviour when it finds symlinks in published modules is undefined,
+but will not result in a working symlink being created in any case.