From 36bcd44b80f54d4db7c25c722a172276c0427970 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":11,"ref":"refs/changes/84/1203884/11","targetBranch":"master"} --- .../concept/faq/symbolic-link-support/en.md | 55 +++++++++++++++++++ .../faq/symbolic-link-support/page.cue | 3 + .../faq/symbolic-link-support/index.md | 55 +++++++++++++++++++ 3 files changed, 113 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..a8fe2fc3a --- /dev/null +++ b/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. 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..a8fe2fc3a --- /dev/null +++ b/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.