From 700bd2f2aa59a67b8eba9bc093f28ddc8b5678de Mon Sep 17 00:00:00 2001 From: guillaume Date: Tue, 12 Apr 2022 18:38:22 +0200 Subject: [PATCH 1/6] docs: guide - empty buildkit cache doc Signed-off-by: guillaume --- docs/guides/1227-empty-buildkit-cache.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/guides/1227-empty-buildkit-cache.md diff --git a/docs/guides/1227-empty-buildkit-cache.md b/docs/guides/1227-empty-buildkit-cache.md new file mode 100644 index 00000000..88e34946 --- /dev/null +++ b/docs/guides/1227-empty-buildkit-cache.md @@ -0,0 +1,22 @@ +--- +slug: /1227/empty-buildkit-cache +displayed_sidebar: europa +--- + +# How to empty BuildKit's cache ? + +There are two ways of emptying the BuildKit cache: + +- Run your action with the `--no-cache` option: + +```console +dagger do --no-cache +``` + +- Stop and remove the buildkitd container and remove its associated volume: + +```console +docker stop dagger-buildkitd ; docker rm dagger-buildkitd ; docker volume rm dagger-buildkitd +``` + +In 99.9% of the cases, the first solution is enough From 467620f0944c45c27015f8f99c1b99d74fb2321b Mon Sep 17 00:00:00 2001 From: guillaume Date: Tue, 12 Apr 2022 18:40:03 +0200 Subject: [PATCH 2/6] docs: guide - logs options in Dagger Signed-off-by: guillaume --- docs/guides/1228-better-logs.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/guides/1228-better-logs.md diff --git a/docs/guides/1228-better-logs.md b/docs/guides/1228-better-logs.md new file mode 100644 index 00000000..b9d33b10 --- /dev/null +++ b/docs/guides/1228-better-logs.md @@ -0,0 +1,23 @@ +--- +slug: /1228/better-logs +displayed_sidebar: europa +--- + +# How can I have better logs ? + +Dagger exposes 2 logging format options: + +- `--log-format auto|plain|tty|json` + +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` + +`debug` is useful to check whether an explicit dependency has been found between two actions. + +You can also export these options as env variables: + +```console +export DAGGER_LOG_FORMAT="plain" +export DAGGER_LOG_LEVEL="debug" +``` From 1ed5fdcab1a732942f72708d62bf29ad1c9847a2 Mon Sep 17 00:00:00 2001 From: guillaume Date: Tue, 12 Apr 2022 18:40:38 +0200 Subject: [PATCH 3/6] docs: guide - always execute an action Signed-off-by: guillaume --- docs/guides/1229-always-execute.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/guides/1229-always-execute.md diff --git a/docs/guides/1229-always-execute.md b/docs/guides/1229-always-execute.md new file mode 100644 index 00000000..9ba2cc89 --- /dev/null +++ b/docs/guides/1229-always-execute.md @@ -0,0 +1,24 @@ +--- +slug: /1229/always-execute +displayed_sidebar: europa +--- + +# How to make sure an action is always being executed ? + +Dagger implemented a way to tell Buildkit not to rely on cache for a specific action. + +The `docker.#Run` and `core.#Exec` definitions have an `always` field: + +```cue +// If set to true, the cache will never be triggered for that specific action. +always: bool | *false +``` + +Any package composed on top of it (`bash.#Run` for example) also exposes this field as it will inherit it from `docker.#Run`: + +```cue +test: bash.#Run & { + always: true + ... +} +``` From 15ccee2eaafb8d6d522728c0a91d7acba12d96f8 Mon Sep 17 00:00:00 2001 From: guillaume Date: Tue, 12 Apr 2022 18:40:54 +0200 Subject: [PATCH 4/6] docs: guide - chaining actions Signed-off-by: guillaume --- docs/guides/1230-chain-actions.md | 54 +++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/guides/1230-chain-actions.md diff --git a/docs/guides/1230-chain-actions.md b/docs/guides/1230-chain-actions.md new file mode 100644 index 00000000..e5811c4d --- /dev/null +++ b/docs/guides/1230-chain-actions.md @@ -0,0 +1,54 @@ +--- +slug: /1230/chain-actions +displayed_sidebar: europa +--- + +# 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: {} + } +} + +// Main action +foo: bash.#Run & { + input: _dockerCLI.output // <== CHAINING of action happening here + always: true + script: contents: #""" + echo "bonjour" + """# +} +``` + +On above example, `_dockerCLI` gets executed first, as the corresponding DAG shows that it is required for the action `foo` to be processed. + +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: + +```cue +foo: bash.#Run & { + input: _dockerCLI.output + always: true + script: contents: #""" + echo "bonjour" + """# +} + +// Main action +bar: bash.#Run & { + input: _dockerCLI.output + always: true + script: contents: #""" + echo "bonjour" + """# + 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 From 204d067bccb92a868c35d21685cd8ae05396c408 Mon Sep 17 00:00:00 2001 From: guillaume Date: Tue, 12 Apr 2022 18:41:07 +0200 Subject: [PATCH 5/6] docs: Implement FAQ page, default values in Cue + fix sidebar and titles Move faq pages from guide to specific FAQ page, shown as per tailscale format. Custom in-house logic implemented because Docusaurus doesn't manage it Signed-off-by: guillaume --- .../1229-empty-buildkit-cache.md} | 4 +-- .../1230-better-logs.md} | 4 +-- .../1231-always-execute.md} | 4 +-- .../1232-chain-actions.md} | 4 +-- docs/faq/index.md | 33 +++++++++++++++++++ website/sidebars.js | 13 ++++++++ 6 files changed, 54 insertions(+), 8 deletions(-) rename docs/{guides/1227-empty-buildkit-cache.md => faq/1229-empty-buildkit-cache.md} (86%) rename docs/{guides/1228-better-logs.md => faq/1230-better-logs.md} (89%) rename docs/{guides/1229-always-execute.md => faq/1231-always-execute.md} (85%) rename docs/{guides/1230-chain-actions.md => faq/1232-chain-actions.md} (95%) create mode 100644 docs/faq/index.md diff --git a/docs/guides/1227-empty-buildkit-cache.md b/docs/faq/1229-empty-buildkit-cache.md similarity index 86% rename from docs/guides/1227-empty-buildkit-cache.md rename to docs/faq/1229-empty-buildkit-cache.md index 88e34946..c47268b7 100644 --- a/docs/guides/1227-empty-buildkit-cache.md +++ b/docs/faq/1229-empty-buildkit-cache.md @@ -1,9 +1,9 @@ --- -slug: /1227/empty-buildkit-cache +slug: /1229/empty-buildkit-cache displayed_sidebar: europa --- -# How to empty BuildKit's cache ? +# Empty BuildKit's cache There are two ways of emptying the BuildKit cache: diff --git a/docs/guides/1228-better-logs.md b/docs/faq/1230-better-logs.md similarity index 89% rename from docs/guides/1228-better-logs.md rename to docs/faq/1230-better-logs.md index b9d33b10..d4e33901 100644 --- a/docs/guides/1228-better-logs.md +++ b/docs/faq/1230-better-logs.md @@ -1,9 +1,9 @@ --- -slug: /1228/better-logs +slug: /1230/better-logs displayed_sidebar: europa --- -# How can I have better logs ? +# Log formats Dagger exposes 2 logging format options: diff --git a/docs/guides/1229-always-execute.md b/docs/faq/1231-always-execute.md similarity index 85% rename from docs/guides/1229-always-execute.md rename to docs/faq/1231-always-execute.md index 9ba2cc89..363bd833 100644 --- a/docs/guides/1229-always-execute.md +++ b/docs/faq/1231-always-execute.md @@ -1,9 +1,9 @@ --- -slug: /1229/always-execute +slug: /1231/always-execute displayed_sidebar: europa --- -# How to make sure an action is always being executed ? +# Always executing an action Dagger implemented a way to tell Buildkit not to rely on cache for a specific action. diff --git a/docs/guides/1230-chain-actions.md b/docs/faq/1232-chain-actions.md similarity index 95% rename from docs/guides/1230-chain-actions.md rename to docs/faq/1232-chain-actions.md index e5811c4d..304849c8 100644 --- a/docs/guides/1230-chain-actions.md +++ b/docs/faq/1232-chain-actions.md @@ -1,9 +1,9 @@ --- -slug: /1230/chain-actions +slug: /1232/chain-actions displayed_sidebar: europa --- -# How can I chain actions together ? +# Chaining actions Dependencies are materialized at runtime, when your Cue files are parsed and the corresponding DAG gets generated: diff --git a/docs/faq/index.md b/docs/faq/index.md new file mode 100644 index 00000000..bdee3d3b --- /dev/null +++ b/docs/faq/index.md @@ -0,0 +1,33 @@ +--- +slug: /faq +displayed_sidebar: europa +--- + +# FAQ + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useDocsVersion} from '@docusaurus/theme-common'; + +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'); + {/* 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] + if(result) + return { + type: "link", + label: result.title, + description: result.description, + href: customPropsItem.href, + docId: customPropsItem.docId + } + }) + return +} + + +``` diff --git a/website/sidebars.js b/website/sidebars.js index 764842af..4dbc6a7c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -57,6 +57,19 @@ module.exports = { "guides/migrate-from-dagger-0.1", ], }, + { + type: "doc", + label: "FAQ", + id: "faq/index", + customProps: { + "items": [ + { docId: "faq/empty-buildkit-cache", href: "1229/empty-buildkit-cache" }, + { docId: "faq/better-logs", href: "1230/better-logs" }, + { docId: "faq/always-execute", href: "1231/always-execute" }, + { docId: "faq/chain-actions", href: "1232/chain-actions" }, + ] + } + }, { type: "category", label: "References", From 49de5d022cfc173797d24747ae5a88e979a25f71 Mon Sep 17 00:00:00 2001 From: guillaume Date: Thu, 14 Apr 2022 15:10:35 +0200 Subject: [PATCH 6/6] 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" }, ] } },