Merge pull request #2152 from grouville/faq

docs: add an FAQ section
This commit is contained in:
Gerhard Lazu 2022-04-14 15:24:36 +01:00 committed by GitHub
commit e6209220e0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 223 additions and 0 deletions

View File

@ -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 <your-action> --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

View File

@ -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 <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 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"
```

View File

@ -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
:::

View File

@ -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

View File

@ -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`
...
}
```

33
docs/faq/index.md Normal file
View File

@ -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 <DocCardList items={customPropsItem}/>
}
<FaqItems />
```

View File

@ -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",