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

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

@@ -0,0 +1,55 @@
+---
+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
+(or fetched from) 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 creating symlinks that point to:
+
+- CUE code (e.g. `file.cue` points to `some.other.file`)
+- package directories (e.g. `foo/` points to `bar/`)
+- files that are included via the
+  [`@embed()` attribute]({{< relref "/docs/howto/embed-files-in-cue-evaluation" >}})
+  (e.g. `data.json` points to `../../../some.data`)
+
+Symlinks can point to targets anywhere on your computer's filesystem and not
+only files inside your CUE module.
+
+## 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?
+
+**It depends**.
+
+Your CUE code can have a dependency on any module that's published and
+accessible, but when the `cue` command fetches and unpacks a module from a
+registry it doesn't create any symlinks that it finds in the module.
+CUE's behaviour when it finds symlinks in published modules is undefined,
+but will never result in a working symlink being created.
+
+This means that CUE packages in a published module that rely on the presence of
+symlinks to work correctly will not behave as expected, after being fetched
+from a registry.
+Therefore: if your CUE code uses any such package, then your CUE may not work
+as you expect.

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,55 @@
+---
+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
+(or fetched from) 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 creating symlinks that point to:
+
+- CUE code (e.g. `file.cue` points to `some.other.file`)
+- package directories (e.g. `foo/` points to `bar/`)
+- files that are included via the
+  [`@embed()` attribute]({{< relref "/docs/howto/embed-files-in-cue-evaluation" >}})
+  (e.g. `data.json` points to `../../../some.data`)
+
+Symlinks can point to targets anywhere on your computer's filesystem and not
+only files inside your CUE module.
+
+## 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?
+
+**It depends**.
+
+Your CUE code can have a dependency on any module that's published and
+accessible, but when the `cue` command fetches and unpacks a module from a
+registry it doesn't create any symlinks that it finds in the module.
+CUE's behaviour when it finds symlinks in published modules is undefined,
+but will never result in a working symlink being created.
+
+This means that CUE packages in a published module that rely on the presence of
+symlinks to work correctly will not behave as expected, after being fetched
+from a registry.
+Therefore: if your CUE code uses any such package, then your CUE may not work
+as you expect.