From 49de5d022cfc173797d24747ae5a88e979a25f71 Mon Sep 17 00:00:00 2001 From: guillaume Date: Thu, 14 Apr 2022 15:10:35 +0200 Subject: [PATCH] docs: docs: guide - default values cue Add default values cue doc page + implement all maintainers suggestions Signed-off-by: guillaume --- docs/faq/1229-empty-buildkit-cache.md | 6 +-- docs/faq/1230-better-logs.md | 10 ++--- docs/faq/1231-always-execute.md | 10 +++-- docs/faq/1232-chain-actions.md | 21 ++++------- docs/faq/1233-default-values-cue.md | 54 +++++++++++++++++++++++++++ docs/faq/index.md | 4 +- website/sidebars.js | 1 + 7 files changed, 80 insertions(+), 26 deletions(-) create mode 100644 docs/faq/1233-default-values-cue.md diff --git a/docs/faq/1229-empty-buildkit-cache.md b/docs/faq/1229-empty-buildkit-cache.md index c47268b7..f8c25f0d 100644 --- a/docs/faq/1229-empty-buildkit-cache.md +++ b/docs/faq/1229-empty-buildkit-cache.md @@ -1,9 +1,9 @@ --- slug: /1229/empty-buildkit-cache -displayed_sidebar: europa +displayed_sidebar: '0.2' --- -# Empty BuildKit's cache +# How to empty BuildKit's cache ? There are two ways of emptying the BuildKit cache: @@ -13,7 +13,7 @@ There are two ways of emptying the BuildKit cache: dagger do --no-cache ``` -- Stop and remove the buildkitd container and remove its associated volume: +- Stop and remove the buildkitd container then remove its associated volume: ```console docker stop dagger-buildkitd ; docker rm dagger-buildkitd ; docker volume rm dagger-buildkitd diff --git a/docs/faq/1230-better-logs.md b/docs/faq/1230-better-logs.md index d4e33901..cee2bd4a 100644 --- a/docs/faq/1230-better-logs.md +++ b/docs/faq/1230-better-logs.md @@ -1,19 +1,19 @@ --- slug: /1230/better-logs -displayed_sidebar: europa +displayed_sidebar: '0.2' --- -# Log formats +# How can I have better logs ? Dagger exposes 2 logging format options: -- `--log-format auto|plain|tty|json` +- `--log-format ` The default mode is `auto`. If you want to keep each actions' logs, use the `plain` mode -- `--log-level panic|fatal|error|warn|info|debug|trace` +- `--log-level ` -`debug` is useful to check whether an explicit dependency has been found between two actions. +`debug` is useful to check whether an explicit dependency has been found between two actions and see CUE DAG at run time. You can also export these options as env variables: diff --git a/docs/faq/1231-always-execute.md b/docs/faq/1231-always-execute.md index 363bd833..bb99265b 100644 --- a/docs/faq/1231-always-execute.md +++ b/docs/faq/1231-always-execute.md @@ -1,11 +1,11 @@ --- slug: /1231/always-execute -displayed_sidebar: europa +displayed_sidebar: '0.2' --- -# Always executing an action +# How to always execute an action ? -Dagger implemented a way to tell Buildkit not to rely on cache for a specific action. +Dagger implemented a way invalidate cache for a specific action. The `docker.#Run` and `core.#Exec` definitions have an `always` field: @@ -22,3 +22,7 @@ test: bash.#Run & { ... } ``` + +:::warning +Any dependent actions will also be retriggered +::: diff --git a/docs/faq/1232-chain-actions.md b/docs/faq/1232-chain-actions.md index 304849c8..3e693530 100644 --- a/docs/faq/1232-chain-actions.md +++ b/docs/faq/1232-chain-actions.md @@ -1,26 +1,23 @@ --- slug: /1232/chain-actions -displayed_sidebar: europa +displayed_sidebar: '0.2' --- -# Chaining actions +# How can I chain actions together ? Dependencies are materialized at runtime, when your Cue files are parsed and the corresponding DAG gets generated: ```cue // Prerequisite action that runs when `test` is being called _dockerCLI: alpine.#Build & { - packages: { - bash: {} - } + packages: bash: _ } // Main action foo: bash.#Run & { input: _dockerCLI.output // <== CHAINING of action happening here - always: true script: contents: #""" - echo "bonjour" + echo "hello" """# } ``` @@ -29,26 +26,24 @@ On above example, `_dockerCLI` gets executed first, as the corresponding DAG sho This is the `input-output` model: `foo`'s input is `_dockerCLI`'s output. -We currently don't support explicit dependencies at the moment (one of our top priority). But, if you need one, here is how your can hack your way around it: +We currently do not support explicit dependencies at the moment (one of our top priority). But, if you need one, here is how you can hack your way around it: ```cue foo: bash.#Run & { input: _dockerCLI.output - always: true script: contents: #""" - echo "bonjour" + echo "hello" """# } // Main action bar: bash.#Run & { input: _dockerCLI.output - always: true script: contents: #""" - echo "bonjour" + echo "hello" """# env: HACK: "\(test.success)" // <== HACK: CHAINING of action happening here } ``` -`foo` and `bar` are similar actions. I don't want to rely on the `input-output` model but still want to force a dependency between them. The easiest way is to create an environment variable that relies on the other action's success +`foo` and `bar` are similar actions. If you do not want to rely on the `input-output` model but still want to force a dependency between them. The easiest way is to create an environment variable that relies on the other action's success diff --git a/docs/faq/1233-default-values-cue.md b/docs/faq/1233-default-values-cue.md new file mode 100644 index 00000000..ce62c355 --- /dev/null +++ b/docs/faq/1233-default-values-cue.md @@ -0,0 +1,54 @@ +--- +slug: /1233/default-values-cue +displayed_sidebar: '0.2' +--- + +# Default values and optional fields + +When writing a Cue config, you will sometimes want to set default values in your package. + +The most common way you'll encounter in our codebase is: `key: type | *value`: + +```cue +defaultValue: string | *"foo" +defaultValue: bool | *false +``` + +You'll also encounter the `*null` default value, which is self explanatory: + +```cue +// here, defaultValue either accepts a #PersonalDefinition, or stays null by default +defaultValue: #PersonalDefinition | *null +``` + +To test the type of `defaultValue`, you can directly do such assertion: + +```cue +if defaultValue != "foo" | if defaultValue != false | if defaultValue != null { + ... +} + +if defaultValue == "foo" | if defaultValue == false | if defaultValue == null { + ... +} +``` + +However, don't get confused with the optional fields. Optional fields check whether a key is concrete at the given scope in the DAG. You declare them with `?` at the end of their name: `foo?`. + +```cue +foo?: string // 1. declare foo. It remains undefined for now + +foo: "bar" // 2. Now, `foo` gets concrete. The field isn't undefined anymore +``` + +To check on a field's concreteness, use the bottom value `_|_`: + +```cue +if foo != _|_ { // if foo is not `undefined` + ... +} + +if foo == _|_ { // if foo is `undefined` + ... +} +``` diff --git a/docs/faq/index.md b/docs/faq/index.md index bdee3d3b..88e2a043 100644 --- a/docs/faq/index.md +++ b/docs/faq/index.md @@ -1,6 +1,6 @@ --- slug: /faq -displayed_sidebar: europa +displayed_sidebar: '0.2' --- # FAQ @@ -13,7 +13,7 @@ export const FaqItems = () => { {/* access root category object from Docusaurus */} const docsVersion = useDocsVersion(); {/* customProps object retrieved from sidebar.js */} - const faqItem = docsVersion.docsSidebars.europa.filter(item => item.label === 'FAQ'); + const faqItem = docsVersion.docsSidebars['0.2'].filter(item => item.label === 'FAQ'); {/* Return custom FAQ Items array */} const customPropsItem = faqItem[0].customProps.items.map(customPropsItem => { const result = Object.values(docsVersion.docs).filter(item => item.id === customPropsItem.docId)[0] diff --git a/website/sidebars.js b/website/sidebars.js index 4dbc6a7c..69e835a0 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -67,6 +67,7 @@ module.exports = { { docId: "faq/better-logs", href: "1230/better-logs" }, { docId: "faq/always-execute", href: "1231/always-execute" }, { docId: "faq/chain-actions", href: "1232/chain-actions" }, + { docId: "faq/default-values-cue", href: "1233/default-values-cue" }, ] } },