From 5a178aa6cf844bb0f10b0942a38d7f6b80c497a4 Mon Sep 17 00:00:00 2001 From: axtloss Date: Fri, 17 Jan 2025 21:23:46 +0100 Subject: [PATCH] chore: Update docs to prepare for v1.0.0 release Co-authored-by: K.B.Dharun Krishna --- docs/articles/en/built-in-modules.md | 35 +++++++--------------------- docs/articles/en/getting-started.md | 5 +--- docs/articles/en/github-action.md | 2 +- docs/articles/en/making-plugin.md | 9 ++++--- docs/articles/en/recipe-structure.md | 3 +++ docs/articles/en/use-modules.md | 16 ++++++------- 6 files changed, 28 insertions(+), 42 deletions(-) diff --git a/docs/articles/en/built-in-modules.md b/docs/articles/en/built-in-modules.md index d0c7ef8..b9e9bbe 100644 --- a/docs/articles/en/built-in-modules.md +++ b/docs/articles/en/built-in-modules.md @@ -46,7 +46,7 @@ The following specific fields are available: ```yaml - name: install-utils type: apt # or any other supported package manager - source: + sources: packages: - curl - git @@ -57,10 +57,11 @@ In the context of this module, this directive also supports the `packages` and ` ```yaml - name: install-utils type: apt # or any other supported package manager - source: - paths: + sources: + - path: - "./utils.inst" - - "./more-utils.inst" + - path: + - "./more-utils.inst" ``` where `utils.inst` and `more-utils.inst` follow the format: @@ -85,13 +86,13 @@ The `apt` module, has some additional fields under the `options` key: ```yaml - name: install-utils type: apt - source: + sources: packages: - curl - git options: noRecommends: true - installSuggestions: true + installSuggests: true fixMissing: true fixBroken: true ``` @@ -136,24 +137,6 @@ The following specific fields are available: type: tar ``` -## Dpkg - -The Dpkg module installs `.deb` packages directly using `dpkg` and resolves dependencies using `apt`. - -The following specific fields are available: - -- `source`: source of the `.deb` package(s) to install. - -### Example - -```yaml -- name: install-custom-deb - type: dpkg - source: - paths: - - "./packages/my-package.deb" -``` - ## Go The Go module compiles Go projects, allowing for customization through build variables and flags. @@ -192,7 +175,7 @@ The following specific fields are available: intermediateSteps: - "make docs-all -j4" installCommand: "make DESTDIR=/root install" - source: + sources: url: "https://example.com/make-project-source.tar.gz" type: tar ``` @@ -212,7 +195,7 @@ The following specific fields are available: type: meson buildflags: - "-Dfoo=bar" - source: + sources: url: "https://example.com/meson-project-source.tar.gz" type: tar ``` diff --git a/docs/articles/en/getting-started.md b/docs/articles/en/getting-started.md index 611cde8..d8accd8 100644 --- a/docs/articles/en/getting-started.md +++ b/docs/articles/en/getting-started.md @@ -28,7 +28,7 @@ Other container engines might work but have not been tested. If you have tested ## Installation -Vib is distributed as a single binary, so there's no need to install any runtime or dependencies. You can download the latest version of Vib from the [GitHub releases page](https://github.com/Vanilla-OS/Vib). In addition to this, Vib has official plugins which are used for all the Vanilla-OS images, they can also be downlaoded from the [Github releases page](https://github.com/Vanilla-OS/Vib) as the `plugins.tar.xz` archvie. Once downloaded, make vib executable and move it to a directory included in your PATH. Vib searches for plugins in a global search path at `/usr/share/vib/plugins/` and inside the `plugins` directory in your project directory. It is recommended to extract `plugins.tar.xz` to `/usr/share/vib/plugins/` as they are considered core vib plugins and may be used by a lot of images. +Vib is distributed as a single binary, so there's no need to install any runtime or dependencies. You can download the latest version of Vib from the [GitHub releases page](https://github.com/Vanilla-OS/Vib). In addition to this, Vib has official plugins which are used for all the Vanilla-OS images, they can also be downlaoded from the [Github releases page](https://github.com/Vanilla-OS/Vib) as the `plugins.tar.xz` archvie. Once downloaded, make `vib` executable and move it to a directory included in your `PATH`. Vib searches for plugins in a global search path at `/usr/share/vib/plugins/` and inside the `plugins` directory in your project directory. It is recommended to extract `plugins.tar.xz` to `/usr/share/vib/plugins/` as they are considered core vib plugins and may be used by a lot of images. The following commands will allow you to download and install Vib: @@ -127,9 +127,6 @@ changing `docker` with the container engine you have installed. Both `docker` an > **Note:** > On a Vanilla OS host, you need to run `vib compile` from the `host-shell`. -> **Note:** -> For versions of Vib before 0.5.0, the syntax of the `compile` command was different. The `--runtime` flag was not available, and the command was `vib compile vib.yml docker`. - The generated `Containerfile` is compatible with both Docker and Podman. ## Next Steps diff --git a/docs/articles/en/github-action.md b/docs/articles/en/github-action.md index e0b50e5..68e6f1e 100644 --- a/docs/articles/en/github-action.md +++ b/docs/articles/en/github-action.md @@ -32,7 +32,7 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: vanilla-os/vib-gh-action@v0.7.0 + - uses: vanilla-os/vib-gh-action@v1.0.0 with: recipe: "vib.yml" plugins: "org/repo:tag, org/repo:tag" diff --git a/docs/articles/en/making-plugin.md b/docs/articles/en/making-plugin.md index 1347a5f..536961e 100644 --- a/docs/articles/en/making-plugin.md +++ b/docs/articles/en/making-plugin.md @@ -50,17 +50,20 @@ The function returns the `api.PluginInfo` struct serialised as a json: ```json { "name": "", - "type": 0 + "type": 0, + "usecontainercmds": 0/1 } ``` Vib gets the plugin type from the `type` field: `0` means `BuildPlugin`, and `1` means `FinalizePlugin`. For this article, it should be set to `0`, as it does not cover the requirements for a finalize plugin. +`usecontainercmds` tells vib whether the plugin adds the relevant containerfile directives itself, or if vib should automatically prepend `CMD` to them, this allows plugins to do more advanced things outside of just specifing commands to run. + example function: ```C char* PlugInfo() { - return "{\"name\":\"example\",\"type\":0}"; + return "{\"name\":\"example\",\"type\":0,\"usecontainercmds\":0}"; } ``` @@ -101,5 +104,5 @@ echo "useradd -m ${username} && echo '${username}' | passwd ${username} --stdin" We provide a plugin template for plugins written in go in the [vib-plugin repo](https://github.com/Vanilla-OS/vib-plugin). -Example plugins written in other languages than go can be found in axtlos' [vib-plugins repo](https://github.com/axtloss/vib-plugins/) +Example plugins written in languages other than go can be found in axtlos' [vib-plugins repo](https://github.com/axtloss/vib-plugins/) diff --git a/docs/articles/en/recipe-structure.md b/docs/articles/en/recipe-structure.md index f54d698..cd8ea8f 100644 --- a/docs/articles/en/recipe-structure.md +++ b/docs/articles/en/recipe-structure.md @@ -165,6 +165,8 @@ The metadata block contains the following mandatory fields: - `name`: the name of the image. - `id`: the ID of the image is used to specify an image's unique identifier, it is used by platforms like [Atlas](https://images.vanillaos.org/#/) to identify the image. - `stages`: a list of stages to build the image, useful to split the build process into multiple stages (e.g. to build the application in one stage and copy the artifacts into another one). +- `vibversion`: the vib version with which this recipe was created, used to avoid vib from processing incompatible recipes +- `includsepath`: an alternative includes path other than `includes.container` ## Stages @@ -182,6 +184,7 @@ Each stage has the following fields: - `entrypoint`: the entry point for the container, it's similar to `cmd` but it's not overridden by the command passed to the container at runtime, useful to handle the container as an executable. - `copy`: a list of files or directories to copy from another stage (or copy from host), useful to copy files from one stage to another. - `modules`: a list of modules to use in the stage. +- `addincludes`: whether `includes.container` should be copied into this stage ### Modules diff --git a/docs/articles/en/use-modules.md b/docs/articles/en/use-modules.md index 79e51e4..453dbe7 100644 --- a/docs/articles/en/use-modules.md +++ b/docs/articles/en/use-modules.md @@ -47,9 +47,9 @@ You will find that some modules have a common `source` field, this instructs Vib ```yml - name: vanilla-tools type: shell - source: - type: tar - url: https://github.com/Vanilla-OS/vanilla-tools/releases/download/continuous/vanilla-tools.tar.gz + sources: + - type: tar + url: https://github.com/Vanilla-OS/vanilla-tools/releases/download/continuous/vanilla-tools.tar.gz commands: - mkdir -p /usr/bin - cp /sources/vanilla-tools/lpkg /usr/bin/lpkg @@ -69,11 +69,11 @@ In the latter case, you can specify the branch, tag or commit to checkout like t ```yaml name: apx-gui type: meson -source: - type: git - url: https://github.com/Vanilla-OS/apx-gui - branch: main - commit: latest +sources: + - type: git + url: https://github.com/Vanilla-OS/apx-gui + branch: main + commit: latest modules: - name: apx-gui-deps-install type: apt