From ca09f8e9ad4e1bcbf49985efa791453df0b39ccc 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":9,"ref":"refs/changes/84/1203884/9","targetBranch":"master"} --- .../concept/faq/symbolic-link-support/en.md | 44 +++++++++++++++++++ .../faq/symbolic-link-support/page.cue | 3 ++ .../faq/symbolic-link-support/index.md | 44 +++++++++++++++++++ 3 files changed, 91 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..6493a1286 --- /dev/null +++ b/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. 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..6493a1286 --- /dev/null +++ b/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.