diff --git a/docs/faq/1229-empty-buildkit-cache.md b/docs/faq/1229-empty-buildkit-cache.md new file mode 100644 index 00000000..f8c25f0d --- /dev/null +++ b/docs/faq/1229-empty-buildkit-cache.md @@ -0,0 +1,22 @@ +--- +slug: /1229/empty-buildkit-cache +displayed_sidebar: '0.2' +--- + +# 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 then 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 diff --git a/docs/faq/1230-better-logs.md b/docs/faq/1230-better-logs.md new file mode 100644 index 00000000..cee2bd4a --- /dev/null +++ b/docs/faq/1230-better-logs.md @@ -0,0 +1,23 @@ +--- +slug: /1230/better-logs +displayed_sidebar: '0.2' +--- + +# How can I have better logs ? + +Dagger exposes 2 logging format options: + +- `--log-format ` + +The default mode is `auto`. If you want to keep each actions' logs, use the `plain` mode + +- `--log-level ` + +`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: + +```console +export DAGGER_LOG_FORMAT="plain" +export DAGGER_LOG_LEVEL="debug" +``` diff --git a/docs/faq/1231-always-execute.md b/docs/faq/1231-always-execute.md new file mode 100644 index 00000000..bb99265b --- /dev/null +++ b/docs/faq/1231-always-execute.md @@ -0,0 +1,28 @@ +--- +slug: /1231/always-execute +displayed_sidebar: '0.2' +--- + +# How to always execute an action ? + +Dagger implemented a way invalidate 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 + ... +} +``` + +:::warning +Any dependent actions will also be retriggered +::: diff --git a/docs/faq/1232-chain-actions.md b/docs/faq/1232-chain-actions.md new file mode 100644 index 00000000..3e693530 --- /dev/null +++ b/docs/faq/1232-chain-actions.md @@ -0,0 +1,49 @@ +--- +slug: /1232/chain-actions +displayed_sidebar: '0.2' +--- + +# 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 + script: contents: #""" + echo "hello" + """# +} +``` + +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 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 + script: contents: #""" + echo "hello" + """# +} + +// Main action +bar: bash.#Run & { + input: _dockerCLI.output + script: contents: #""" + echo "hello" + """# + env: HACK: "\(test.success)" // <== HACK: CHAINING of action happening here +} +``` + +`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 new file mode 100644 index 00000000..88e2a043 --- /dev/null +++ b/docs/faq/index.md @@ -0,0 +1,33 @@ +--- +slug: /faq +displayed_sidebar: '0.2' +--- + +# 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['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] + 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..69e835a0 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -57,6 +57,20 @@ 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" }, + { docId: "faq/default-values-cue", href: "1233/default-values-cue" }, + ] + } + }, { type: "category", label: "References",