### Dalec Spec File for go-md2man

Source: https://project-dalec.github.io/dalec/quickstart

This is a complete Dalec spec file used to define the build process for the go-md2man package. It includes metadata, source retrieval, build dependencies, build steps, artifacts to include, container image configuration, and tests. The file must start with the specific Dalec frontend syntax.

```yaml
# syntax=ghcr.io/project-dalec/dalec/frontend:latest  
name: go-md2man  
version: 2.0.3  
revision: "1"  
packager: Dalec Example  
vendor: Dalec Example  
license: MIT  
description: A tool to convert markdown into man pages (roff).  
website: https://github.com/cpuguy83/go-md2man  
  
sources:  
  src:  
    generate:  
      - gomod: {}  # Pre-downloads Go modules since network is disabled during build  
    git:  
      url: https://github.com/cpuguy83/go-md2man.git  
      commit: "v2.0.3"  
  
dependencies:  
  build:  
    golang:  
  
build:  
  env:  
    CGO_ENABLED: "0"  
  steps:  
    - command: |  
        cd src  
        go build -o go-md2man .  
  
artifacts:  
  binaries:  
    src/go-md2man:  
  
image:  
  entrypoint: go-md2man  
  cmd: --help  
  
tests:  
  - name: Check bin  
    files:  
      /usr/bin/go-md2man:  
        permissions: 0755  


```

--------------------------------

### Serve Documentation (Make)

Source: https://project-dalec.github.io/dalec/developers

Command to start a local server for viewing and live-previewing documentation. Requires editing files within the website/docs/ directory.

```bash
# Start the documentation server  
make docs-serve  

# Open http://localhost:3000 in your browser  
# Edit files in website/docs/ and see live changes  
```

--------------------------------

### Build RPM Package using Docker

Source: https://project-dalec.github.io/dalec/quickstart

This command uses Docker to build an RPM package for the go-md2man project based on the specified Dalec YAML file. It targets the 'azlinux3/rpm' build stage and outputs the generated RPM and SRPM files to the '_output' directory.

```bash
docker build -t go-md2man:2.0.3 -f docs/examples/go-md2man.yml --target=azlinux3/rpm --output=_output .

```

--------------------------------

### Build and Test Dalec Frontend Image with Docker

Source: https://project-dalec.github.io/dalec/developers

This section provides Docker commands to build and test the Dalec frontend image. It includes examples for building a container image and an RPM package, specifying build arguments like 'BUILDKIT_SYNTAX' and targeting specific distributions and output formats. This is useful for testing custom Dalec build configurations.

```shell
# Build the frontend image  
make frontend  
  
# Build and test with a specific target  
  
# Container example  
docker build -t go-md2man:test \  
  --build-arg BUILDKIT_SYNTAX=local/dalec/frontend \  
  -f docs/examples/go-md2man.yml \  
  --target=azlinux3/container \  
  -t go-md2man:test .  
  
# RPM example  
docker build -t go-md2man:test \  
  --build-arg BUILDKIT_SYNTAX=local/dalec/frontend \  
  -f docs/examples/go-md2man.yml \  
  --target=azlinux3/rpm \  
  --output=_output .  

```

--------------------------------

### Build Container Image using Docker

Source: https://project-dalec.github.io/dalec/quickstart

This command utilizes Docker to build a container image for the go-md2man project using the provided Dalec YAML specification. The resulting image is tagged as 'go-md2man:2.0.3'.

```bash
docker build -t go-md2man:2.0.3 -f docs/examples/go-md2man.yml --target=azlinux3 .

```

--------------------------------

### Complete Package Dependencies Example

Source: https://project-dalec.github.io/dalec/dependencies

An example demonstrating the structure for defining build, runtime, recommends, sysext, test dependencies, and extra repositories for a package within the Dalec build system.

```YAML
dependencies:
  build:
    gcc:
      version: [">=9.0.0"]
      arch: ["amd64"]
  runtime:
    libc6:
      version: [">=2.29"]
  recommends:
    curl:
      version: [">=7.68.0"]
  sysext:
    zstd:
      version: [">=1.5.0"]
  test:
    - bats
  extra_repos:
    - keys:
        mykey:
          http:
            url: "https://example.com/mykey.gpg"
            permissions: 0644
      config:
        myrepo:
          http:
            url: "https://example.com/myrepo.list"
      # this assumes that a build context named `my-local-repo` containing a local repository will be passed
      # to the Dalec build.
      # /opt/repo can now be referenced as a local repository in a repository config imported to dalec
      data:
        - dest: "/opt/repo"
          spec:
            context:
              name: "my-local-repo"
      envs: ["build", "install"]

```

--------------------------------

### Docker Build Command Example

Source: https://project-dalec.github.io/dalec/sources

This example shows a typical Docker build command where the current directory is used as the build context for Dalec.

```bash
$ docker build <some args> .
```

--------------------------------

### Define Systemd Unit Files and Drop-ins

Source: https://project-dalec.github.io/dalec/artifacts

Configures systemd unit files and drop-ins for service management. This allows for enabling, starting, and customizing systemd services as part of the package installation.

```yaml
artifacts:
  systemd:
    units:
      src/contrib/init/my_service.service:
        enable: false
        name: ""
        start: false
    dropins:
      src/contrib/init/customize-a-thing.service:
        enable: false
        name: ""
        start: false

```

--------------------------------

### Run Integration Tests (Make)

Source: https://project-dalec.github.io/dalec/developers

Commands to execute integration tests using the make utility. Supports running all tests or targeting specific distributions. These tests are time-consuming and require Docker with BuildKit.

```bash
# Run all integration tests (45+ minutes)  
make test-integration  

# Or test a specific distribution  
make test-integration SUITE=Mariner2  
make test-integration SUITE=Azlinux3  
make test-integration SUITE=Jammy  
make test-integration SUITE=Bookworm  
```

--------------------------------

### Build Container Image for Windows Cross-Compilation

Source: https://project-dalec.github.io/dalec/targets

Builds binaries and installs them into a Windows base image, facilitating cross-compilation for Windows targets.

```docker
docker buildx build --target windowscross/container .
```

--------------------------------

### PackageDependency Recommends Constraints

Source: https://project-dalec.github.io/dalec/dependencies

Lists packages that are recommended to be installed alongside the generated package. These are optional but enhance the package's functionality or user experience.

```YAML
recommends:
  package_name:
      version: ["<2.0.0", ">=1.0.0"]
      arch: ["amd64", "arm64"]

```

--------------------------------

### Clone and Set Up Dalec Repository

Source: https://project-dalec.github.io/dalec/developers

This snippet shows how to fork the Dalec repository from GitHub, clone your fork locally, and add the upstream repository as a remote for keeping your fork updated. It's a standard Git workflow for contributing to open-source projects.

```shell
# Fork the repository on GitHub, then clone your fork  
git clone https://github.com/<your-username>/dalec.git  
cd dalec  
  
# Add the upstream repository  
git remote add upstream https://github.com/project-dalec/dalec.git  

```

--------------------------------

### Test Specific Components (Go Test)

Source: https://project-dalec.github.io/dalec/developers

Go commands for testing specific components of the project. Includes options for verbose output, filtering tests by name, and enabling race detection for concurrency issues.

```bash
# Test a specific package  
go test -v ./cmd/frontend  

# Test with a filter  
go test -v -run TestSpecLoad ./...  

# Test with race detection  
go test -race ./...  
```

--------------------------------

### Define Users for Package Installation

Source: https://project-dalec.github.io/dalec/artifacts

Defines user accounts to be created during the package installation process. This typically requires a shell to be available on the target system.

```yaml
artifacts:
  users:
    - name: myuser

```

--------------------------------

### Add Azure Linux DNF Repository for Install Dependencies

Source: https://project-dalec.github.io/dalec/repositories

Configures an external DNF repository for Azure Linux cloud-native packages, intended for the 'install' environment. This example assumes necessary GPG keys are already present on Azure Linux systems and focuses on the repository configuration file content.

```yaml
dependencies:
  runtime:
    gatekeeper-manager: {}
  extra_repos:
    - config:
        azl-cloud-native.repo:
          inline:
            file:
              contents: |
                [azurelinux-cloud-native]
                name=Azure Linux Cloud Native $releasever $basearch
                baseurl=https://packages.microsoft.com/azurelinux/$releasever/prod/cloud-native/$basearch
                gpgkey=file:///etc/pki/rpm-gpg/MICROSOFT-RPM-GPG-KEY
                gpgcheck=1
                repo_gpgcheck=1
                enabled=1
                skip_if_unavailable=True
                sslverify=1
      envs:
        - install

```

--------------------------------

### Vim Command to Install LSP Server

Source: https://project-dalec.github.io/dalec/editor-support

A one-time Vim command to install the necessary Language Server Protocol (LSP) server. This command is run within Vim after installing the required LSP plugins.

```vim
:LspInstallServer
```

--------------------------------

### Configure Package Installation Groups in DALEC

Source: https://project-dalec.github.io/dalec/artifacts

This configuration snippet demonstrates how to define groups for package installation. It requires a shell on the target system. The 'name' key specifies the group name.

```yaml
artifacts:
  groups:
    - name: mygroup

```

--------------------------------

### Configure Binary Artifacts in Dalec

Source: https://project-dalec.github.io/dalec/artifacts

Defines binary files to be installed on the target system, typically in '/usr/bin' on Linux. Configuration includes the source path of the binary and optional artifact settings.

```yaml
artifacts:
  binaries:
    src/my_bin:
      subpath: ""
      permissions: 0o755

```

--------------------------------

### Multi-stage Dockerfile Build Example

Source: https://project-dalec.github.io/dalec/testing

This snippet shows a multi-stage Dockerfile. The first stage uses busybox to create a file, and the second stage copies that file from the first stage into a scratch image. This is useful for creating minimal production images.

```dockerfile
FROM busybox
RUN echo hello > /hello

FROM scratch
COPY --from=busybox /hello /hello
```

--------------------------------

### Run Dalec Unit Tests with Go

Source: https://project-dalec.github.io/dalec/developers

This command executes the unit tests for the Dalec project using the Go testing framework. It runs all tests located alongside the source files, marked with the '-test.short' flag for faster execution. Alternatively, 'make test' can be used as a shortcut.

```shell
# Run all unit tests  
go test --test.short ./...  
  
# Or use the Makefile  
make test  

```

--------------------------------

### Configure Libexec Artifacts in Dalec

Source: https://project-dalec.github.io/dalec/artifacts

Installs executable files into '/usr/libexec/' or a subdirectory thereof, intended for use by main package executables. Configuration maps source file paths to artifact settings, with an optional subpath for organization.

```yaml
name: my_package

artifacts:
  libexec:
    src/my_bin:

```

--------------------------------

### Manage Node.js Dependencies from Multiple package.json Files

Source: https://project-dalec.github.io/dalec/sources

This example shows how to use the NodeMod generator's 'paths' field to manage dependencies from multiple 'package.json' files located in different subdirectories of a source. It runs 'npm install' in each specified path, suitable for monorepo structures.

```yaml
sources:
  src:
    path: ./ 
    context: {}
    generate:
      - nodemod:
          paths:
            - frontend
            - backend

```

--------------------------------

### List Available Make Targets for Dalec

Source: https://project-dalec.github.io/dalec/developers

This command displays all available 'make' targets for the Dalec project, categorized by function (Development, Building, Testing, Documentation, Validation). It serves as a quick reference for developers to understand the various tasks they can perform using the Makefile.

```shell
make help  

```

--------------------------------

### PackageDependency Test Packages

Source: https://project-dalec.github.io/dalec/dependencies

Lists additional packages required for running tests. These are installed only for tests that involve executing commands within the built container.

```YAML
test:
  - package_name_1
  - package_name_2

```

--------------------------------

### Run Dalec Integration Tests

Source: https://project-dalec.github.io/dalec/developers

These commands demonstrate how to run integration tests for Dalec. You can specify a particular test suite using the 'SUITE' variable or run all integration tests, which may take a significant amount of time. Integration tests verify the system's behavior as a whole.

```shell
# Run integration tests for a specific distribution  
make test-integration SUITE=Azlinux3  
  
# Run all integration tests (takes 30-60+ minutes)  
make test-integration  

```

--------------------------------

### Configure Manpage Artifacts in Dalec

Source: https://project-dalec.github.io/dalec/artifacts

Specifies manual pages to be installed, typically in '/usr/share/man' on Linux. Configuration involves mapping source file paths (potentially using wildcards) to artifact settings, including permissions.

```yaml
artifacts:
  manpages:
    src/man/*:
      subpath: ""
      permissions: 0o644

```

--------------------------------

### Dalec Development Loop Commands

Source: https://project-dalec.github.io/dalec/developers

This sequence of 'make' commands represents the core development loop for Dalec. It covers generating code, running linters, executing unit tests, and building the frontend binary. This tight feedback loop helps catch issues early and ensures code correctness.

```shell
# 1. Generate any required code (if you modified generators)  
make generate  
  
# 2. Run custom linters to catch issues early  
make lint  
  
# 3. Run unit tests  
make test  
  
# 4. Build the frontend binary to verify compilation  
make build  

```

--------------------------------

### Configure Git Source with Custom Authentication (YAML)

Source: https://project-dalec.github.io/dalec/sources

Example of configuring Git source authentication in YAML, showing how to specify custom secret names for header, token, and SSH authentication. This allows for flexible credential management.

```yaml
  someSource1:
    git:
      # This uses an SSH style git URL.
      url: git@github.com:myOrg/myRepo.git
      commit: 1234567890abcdef
      auth:
        header: GIT_AUTH_HEADER # Default header secret used
        token: GIT_AUTH_TOKEN # Default token secret used
        ssh: default # Default SSH secret used
```

--------------------------------

### Configure Context Source with Includes/Excludes (YAML)

Source: https://project-dalec.github.io/dalec/sources

Example of configuring a 'context' source type in YAML. It specifies the source path, include patterns for '.txt' files, and exclude patterns for 'secret.txt'. This is useful for defining a base set of files for a build.

```yaml
sources:
  someSource:
    path: path/in/source
    includes:
      - "*.txt"
    excludes:
      - "secret.txt"
    context: {}
```

--------------------------------

### Set Entrypoint in DALEC

Source: https://project-dalec.github.io/dalec/image

This snippet shows how to specify the entrypoint for a container image using the 'entrypoint' field in DALEC. The entrypoint defines the executable that will be run when a container starts from this image.

```yaml
image:
  entrypoint: /usr/bin/my-binary
```

--------------------------------

### PackageDependency Runtime Constraints

Source: https://project-dalec.github.io/dalec/dependencies

Specifies the runtime dependencies required for a package to install and execute. This includes package name, version constraints, and target architectures, ensuring the package functions correctly after installation.

```YAML
runtime:
  package_name:
      version: ["<2.0.0", ">=1.0.0"]
      arch: ["amd64", "arm64"]

```

--------------------------------

### Build Docker Image from Inline Source with Custom Dockerfile

Source: https://project-dalec.github.io/dalec/sources

Builds a Docker image from an inline source, allowing a custom Dockerfile path and content. This example defines a multi-stage build where a file is created in one stage and copied to the final image in another.

```yaml
someBuild:
  path: /hello.txt
  build:
    dockerfile_path: other.Dockerfile # [Optional] Change dockerfile path. Default value: "Dockerfile"
    source:
      inline:
        dir:
          uid: 0
          gid: 0
          permissions: 0755
          files:
            Dockerfile:
              contents: |
                FROM alpine:3.14 AS base
                RUN echo "hello world" > /hello.txt

                FROM scratch
                COPY --from=base /hello.txt /hello.txt
```

--------------------------------

### Define Package Header Files

Source: https://project-dalec.github.io/dalec/artifacts

Specifies header files or directories to be included in the package. These are directly installed into the system's include directory, not within a package-specific subdirectory.

```yaml
artifacts:
  headers:
    src/my_header.h:

```

```yaml
artifacts:
  headers:
    src/my_headers/:

```

--------------------------------

### Applying Multiple Patches from a Directory Source in Dalec

Source: https://project-dalec.github.io/dalec/sources

This example shows how to apply multiple patch files from a single directory-based 'context' source to the 'md2man' git source. Each patch file is listed individually in the 'patches' section.

```yaml
sources:
  md2man:
    git:
      url: https://github.com/cpuguy83/go-md2man.git
      commit: v2.0.3
  localPatches:
    context: {}


patches:
  md2man:
    - source: localPatches
      path: patches/some0.patch
    - source: localPatches
      path: patches/some2.patch
```

--------------------------------

### Configure Data Directory Artifacts in Dalec

Source: https://project-dalec.github.io/dalec/artifacts

Defines read-only, architecture-independent data files to be installed, typically in '/usr/share' on Linux. Configuration maps source file paths to artifact settings, with optional subpath and permissions.

```yaml
artifacts:
  data_dirs:
    build_output/my_bin:
      subpath: ""
      permissions: 0o755

```

--------------------------------

### Run Dalec Verification Checks

Source: https://project-dalec.github.io/dalec/developers

This command executes a comprehensive set of verification steps for the Dalec project. It includes generating necessary source files, running custom linters, executing unit tests, and validating that generated files are up-to-date. This is crucial for ensuring code quality and consistency.

```shell
# Run a quick verification  
make verify  

```

--------------------------------

### Customize Pip Generator with Custom Requirements and Index URLs

Source: https://project-dalec.github.io/dalec/sources

This example demonstrates customizing the Pip generator by specifying a custom requirements file name, a primary index URL, and additional index URLs. This allows for more control over where and how Python dependencies are fetched, ensuring reproducible builds.

```yaml
sources:
  python-app:
    git:
        url: https://github.com/example/python-app.git
        commit: v1.0.0
    generate:
        pip:
          requirements_file: "requirements.txt"
          index_url: "https://pypi.org/simple/"
          extra_index_urls:
            - "https://custom-pypi.example.com/simple/"

```

--------------------------------

### Configure Image Settings for Dalec Virtual Package

Source: https://project-dalec.github.io/dalec/virtual-packages

Configures image properties such as entrypoint and command for a Dalec virtual package. These settings define how the container runs after being created from the image.

```yaml
# syntax=ghcr.io/project-dalec/dalec/frontend:latest  
name: my-package  
version: 1.0.0  
revision: "1"  
packager: Contoso  
vendor: Contoso  
license: MIT  
description: A virtual package with custom image settings  
website: http://contoso.com  
  
dependencies:  
  runtime:  
    my-package-foo:  
    my-package-bar:  
  
image:  
  entrypoint: /bin/sh  
  cmd: ["-c"]  


```

--------------------------------

### List Available DALEC Build Targets

Source: https://project-dalec.github.io/dalec/targets

This command demonstrates how to query DALEC for a list of all available build targets and their descriptions. It utilizes `docker buildx build` with specific build arguments to interact with the DALEC frontend.

```bash
$ docker buildx build --call targets --build-arg BUILDKIT_SYNTAX=ghcr.io/project-dalec/dalec/frontend:latest - <<< "null"  
```

--------------------------------

### Build Zip Archive for Windows Cross-Compilation

Source: https://project-dalec.github.io/dalec/targets

Compiles binaries and bundles them into a zip file for Windows targets.

```docker
docker buildx build --target windowscross/zip .
```

--------------------------------

### Build Container Image with Runtime Dependencies for Rocky Linux 9

Source: https://project-dalec.github.io/dalec/targets

Builds a container image for Rocky Linux 9 that includes only the runtime dependencies, optimizing for deployment.

```docker
docker buildx build --target rockylinux9/container/depsonly .
```

--------------------------------

### Test File Content Starts With String in Dalec Spec

Source: https://project-dalec.github.io/dalec/testing

Asserts that a file's content begins with a specified string. Useful for checking headers or initial configurations.

```yaml
name: My Package
# ... other spec fields

tests:
  - name: My Test case
    files:
      /etc/foo.conf:
        starts_with: foo
```

--------------------------------

### Set Working Directory in DALEC

Source: https://project-dalec.github.io/dalec/image

This snippet shows how to define the working directory for a container image using the 'workdir' field in DALEC. This sets the default directory in which commands will be executed when the container starts.

```yaml
image:
  workdir: /my-dir
```

--------------------------------

### Building a Dalec System Extension with Docker

Source: https://project-dalec.github.io/dalec/system-extensions

Builds a system extension container image using Docker and Dalec. The command specifies the YAML definition file, the target build, and the output directory. This process generates a raw image file that can be merged with a systemd-enabled system.

```bash
docker build -f my-sysext.yml --target=azlinux3/testing/sysext --output=. .

```

--------------------------------

### Dalec Build Context Configuration (Empty)

Source: https://project-dalec.github.io/dalec/sources

Configuration snippet demonstrating how an empty build context is represented in Dalec's sources. The empty brackets are a syntax requirement to avoid nil values.

```yaml
sources:
  someSource:
    context: {}
```

--------------------------------

### Update Base Image Reference for azlinux3 using Named Build Context

Source: https://project-dalec.github.io/dalec/targets

Shows how to update the base image reference for the azlinux3 target using a named build context, similar to other distributions.

```docker
--build-context mcr.microsoft.com/azurelinux/base/core:3.0=<new ref>
```

```docker
--build-context dalec-azlinux3-worker=<new ref>
```

--------------------------------

### Dalec System Extension Definition (YAML)

Source: https://project-dalec.github.io/dalec/system-extensions

Defines a system extension using Dalec's YAML syntax. It specifies the extension's name, version, revision, license, description, and its systemd-specific dependencies (sysext). This serves as the configuration file for building the extension.

```yaml
# syntax=ghcr.io/project-dalec/dalec/frontend:latest  
name: my-sysext  
version: 0.1.0  
revision: 1  
license: MIT  
description: A system extension with some useful tools  
  
dependencies:  
  sysext:  
    jq:  
    zsh:  

```

--------------------------------

### Add Microsoft Ubuntu APT Repository for Build Dependencies

Source: https://project-dalec.github.io/dalec/repositories

Configures an external APT repository for Microsoft's Ubuntu packages, specifically for the 'build' environment. It includes GPG key management and the repository list configuration. Ensure the key file is named with the correct extension (.gpg or .asc).

```yaml
dependencies:
  build:
    msft-golang:
  extra_repos:
    - keys:
        msft.asc:
          http:
            url: https://packages.microsoft.com/keys/microsoft.asc
            digest: sha256:2cfd20a306b2fa5e25522d78f2ef50a1f429d35fd30bd983e2ebffc2b80944fa
            permissions: 0o644
      config:
        microsoft-prod.list:
          inline:
            file:
              contents: deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/msft.asc] https://packages.microsoft.com/ubuntu/22.04/prod jammy main
      envs:
        - build

```

--------------------------------

### Applying Patch from Directory Source with Subpath in Dalec

Source: https://project-dalec.github.io/dalec/sources

This example illustrates applying a patch from a directory-based source that has a 'path' defined within the source configuration. Even though the subpath points to a file, the 'path' in the patch spec is still required.

```yaml
sources:
  md2man:
    git:
      url: https://github.com/cpuguy83/go-md2man.git
      commit: v2.0.3
  localPatches:
    context: {}
    path: patches/some0.patch
  
patches:
  md2man:
    - source: localPatches
      path: some0.patch
```

--------------------------------

### Build Container Image with Runtime Dependencies for Rocky Linux 8

Source: https://project-dalec.github.io/dalec/targets

Builds a container image for Rocky Linux 8 that includes only the runtime dependencies, reducing image size for deployment.

```docker
docker buildx build --target rockylinux8/container/depsonly .
```

--------------------------------

### Fetch Docker Image from Registry

Source: https://project-dalec.github.io/dalec/sources

Fetches a Docker image from a specified registry. The output is a directory containing the image's contents. It requires an image reference (e.g., 'docker.io/library/alpine:3.14').

```yaml
sources:
  someDockerImage:
    image:
      ref: docker.io/library/alpine:3.14
```

--------------------------------

### Configure Pip Generator for Python Dependencies

Source: https://project-dalec.github.io/dalec/sources

This configuration sets up the Pip generator to manage Python package dependencies from a Git repository. It automatically fetches and installs dependencies, making them available during the build process. The generator caches these dependencies for efficient builds.

```yaml
sources:
  python-app:
    git:
        url: https://github.com/example/python-app.git
        commit: v1.0.0
    generate:
      - subpath: "" # path inside the source to use as the root for the generator
        pip: {} # Generates a pip cache to cache dependencies

```

--------------------------------

### List Available Build Targets

Source: https://project-dalec.github.io/dalec/targets

Lists all available build targets for a given Dalec spec file. This is useful for understanding the build options for a specific configuration.

```docker
docker buildx build --call targets -f ./path/to/spec .
```

--------------------------------

### Create a Feature Branch in Git

Source: https://project-dalec.github.io/dalec/developers

This command creates a new Git branch for developing a specific feature. It's a fundamental step in the Git workflow for isolating changes and facilitating easier code reviews and merges. Replace 'your-feature-name' with a descriptive name for your feature.

```shell
git checkout -b feature/your-feature-name  

```

--------------------------------

### Vim LSP Settings for YAML Project

Source: https://project-dalec.github.io/dalec/editor-support

Configuration file for the `mattn/vim-lsp-settings` plugin in Vim. It specifies the schema URL and enables validation and completion for YAML files matching specific patterns within the project.

```json
{
	"yaml-language-server": {
		"schemas": [
			{
				"fileMatch": ["test/fixtures/*.yml"],
				"url": "https://raw.githubusercontent.com/project-dalec/dalec/<version>/docs/spec.schema.json"
			}
		],
		"completion": true,
		"validate": true
	}
}
```

--------------------------------

### Configure NodeMod Generator for Node.js Dependencies

Source: https://project-dalec.github.io/dalec/sources

This configuration sets up the NodeMod generator to manage Node.js module dependencies from a Git repository. It automatically fetches and installs dependencies via npm, caching them for efficient builds. The 'subpath' indicates the directory within the source to manage modules.

```yaml
sources:
  my-node-app:
    git:
        url: https://github.com/<fake-org>/my-node-app.git
        commit: v1.0.0
    generate:
      - subpath: "" # path inside the source to use as the root for the generator
        nodemod: {} # Generates node_modules to cache dependencies

```

--------------------------------

### Define Build Steps with Commands

Source: https://project-dalec.github.io/dalec/spec

Details the executable steps required during the build process. Each step can consist of a command to be executed, allowing for complex build logic and custom operations.

```shell
go build -ldflags "-s -w -X github.com/foo/bar/version.Version=${TAG}" -o /out/my-binary ./cmd/my-binary

```

--------------------------------

### Define Replaced Packages in Dalec Spec

Source: https://project-dalec.github.io/dalec/spec

The `replaces` field within the Metadata section lists packages that the current package will supersede. This is beneficial when this package is intended to be used instead of another package with a different name. It can be used in conjunction with `conflicts` to ensure the older package is removed upon installation.

```yaml
replaces:
  foo:
  bar:
    # With version constraints
    version:
      - "< 1.0.0"
```

--------------------------------

### Define Package Conflicts in Dalec Spec

Source: https://project-dalec.github.io/dalec/spec

The `conflicts` field within the Metadata section specifies packages that are incompatible with the current package. This is crucial for ensuring that the package manager prevents the installation of conflicting packages, especially when packages provide the same files. Version constraints can be added to define the scope of the conflict.

```yaml
conflicts:
  foo:
  bar:
    # Add version constraints to the conflicting package
    version:
      - ">=1.0.0"
      - "<2.0.0"
```

--------------------------------

### PackageDependency Extra Repositories Configuration

Source: https://project-dalec.github.io/dalec/dependencies

Configures additional package repositories to satisfy dependencies. This includes GPG keys for repository authentication and the repository configuration details (URL).

```YAML
extra_repos:
  - keys:
      mykey:
        http:
          URL: "https://example.com/mykey.gpg"
          permissions: 0644
    config:
      myrepo:
        http:
          url: "https://example.com/myrepo.list"
    data:
      - dest: "/path/to/dest"
        spec: source
    envs: ["build", "test", "install"]

```

--------------------------------

### Configure Build Environment Variables and Caches

Source: https://project-dalec.github.io/dalec/spec

Sets up the build environment by defining environment variables, build steps, and caching strategies. It allows customization of build processes, including setting Go build flags and managing cache directories.

```yaml
build:
  env:
    TAG: v${VERSION}
    GOPROXY: direct
    CGO_ENABLED: "0"
    GOOS: ${TARGETOS}
  caches:
    - gobuild:
    - dir:
      key: my_key
      dest: /my/cache/dir
  steps:
    - command: |
        go build -ldflags "-s -w -X github.com/foo/bar/version.Version=${TAG}" -o /out/my-binary ./cmd/my-binary

```

--------------------------------

### Run Commands in Docker Image Before Fetching

Source: https://project-dalec.github.io/dalec/sources

Fetches a Docker image and executes specified commands within it before extracting its contents. This is useful for generating content. It allows defining a working directory and environment variables for the commands.

```yaml
sources:
  someDockerImage:
    image:
      ref: docker.io/library/alpine:3.14
      cmd:
        dir: / # Default path that command steps are executed in
        steps:
          - command: echo ${FOO} ${BAR}
            env: # Environment variables to set for the step
              FOO: foo
              BAR: bar
```

--------------------------------

### Dalec Spec for Minimal Image (YAML)

Source: https://project-dalec.github.io/dalec/container-only-builds

A Dalec specification file in YAML format to define a minimal container image. It lists runtime dependencies like 'curl' and 'bash', sets an entrypoint, and includes metadata like name, version, and license. This file is used by Dalec to construct the container image.

```yaml
# syntax=ghcr.io/project-dalec/dalec/frontend:latest
name: my-minimal-image
version: 0.1.0
revision: 1
license: MIT
description: A minimal image with only curl and shell access

dependencies:
  runtime:
    curl:
    bash:

image:
  entrypoint: /bin/bash

```

--------------------------------

### Define Package Metadata in Dalec Spec

Source: https://project-dalec.github.io/dalec/spec

The Metadata section in a Dalec spec YAML defines essential information about the package, including its name, license, description, version, revision, packager, vendor, and website. Fields starting with 'x-' are ignored by Dalec, allowing for custom extensions. Unrecognized fields will result in validation errors.

```yaml
name: My-Package
license: Apache-2.0
description: This is a sample package
version: ${VERSION}
revision: ${REVISION}
packager: Dalec Authors
vendor: Dalec Authors
website: https://github.com/foo/bar
```

--------------------------------

### Build RPM Package for Rocky Linux 8

Source: https://project-dalec.github.io/dalec/targets

Builds an RPM package and its corresponding source RPM (src.rpm) for the Rocky Linux 8 distribution.

```docker
docker buildx build --target rockylinux8/rpm .
```

--------------------------------

### Build Windows Executable (.exe) with Dalec

Source: https://project-dalec.github.io/dalec/targets

This configuration specifies a build step within a Dalec project to compile a Go application, ensuring the output binary has a '.exe' extension suitable for Windows targets. This is a common requirement when using the 'windowscross' target.

```yaml
build:
  steps:
    - command: |
        go build -o _output/bin/dalec_example.exe

```

--------------------------------

### Conditional Build for Windows Executable using TARGETOS in Dalec

Source: https://project-dalec.github.io/dalec/targets

This Dalec build configuration uses the TARGETOS environment variable to conditionally compile the correct binary for Windows or other operating systems. It sets the TARGETOS variable and then executes a Go build command, outputting '.exe' for Windows and a standard binary otherwise.

```yaml
build:
  env:
    TARGETOS: ${TARGETOS}
  steps:
    - command: |
        if [ "$TARGETOS" = "windows" ]; then
          go build -o _output/bin/dalec_example.exe
        else
          go build -o _output/bin/dalec_example
        fi

```

--------------------------------

### Configure Directory Creation Artifacts in Dalec

Source: https://project-dalec.github.io/dalec/artifacts

Creates empty directories on the target system, categorized as 'config' (for configuration files) or 'state' (for persistent data). Each directory is configured with a name and a mode (permissions).

```yaml
artifacts:
  createDirectories:
    state:
      mystate:
        mode: 0o755
    config:
      myconfig:
        mode: 0o755

```

--------------------------------

### Dalec Build Context Configuration (Named)

Source: https://project-dalec.github.io/dalec/sources

This configuration shows how to explicitly name a build context when it's provided by the Docker CLI, such as with the --build-context flag.

```yaml
sources:
  someSource:
    context:
      name: "myContext"
```

--------------------------------

### Configure HTTP Source with Digest and Permissions (YAML)

Source: https://project-dalec.github.io/dalec/sources

YAML configuration for an HTTP source fetching a file from a URL. It includes optional fields for 'digest' to verify file integrity and 'permissions' to set file access rights. This ensures the downloaded file is correct and has the required permissions.

```yaml
sources:
  someSource1:
    http:
      url: https://example.com/someFile.txt
      # optional digest field
      digest: sha256:1234567890abcdef
      # optional permissions field
      permissions: 0644
```

--------------------------------

### Build RPM Package for Rocky Linux 9

Source: https://project-dalec.github.io/dalec/targets

Builds an RPM package and its source RPM (src.rpm) for the Rocky Linux 9 distribution.

```docker
docker buildx build --target rockylinux9/rpm .
```

--------------------------------

### Configure Image Base and Post-Processing Steps

Source: https://project-dalec.github.io/dalec/spec

Defines the base container image and any post-processing actions to be applied. This includes setting the base image, creating symbolic links, and specifying an entrypoint for the image. Useful for customizing the final container image.

```yaml
image:
  base: mcr.microsoft.com/cbl-mariner/distroless/minimal:2.0
  post:
    symlinks:
      /usr/bin/my-binary:
       paths:
         - /my-binary
  entrypoint: /my-binary

```

--------------------------------

### Build Container Image for Rocky Linux 8

Source: https://project-dalec.github.io/dalec/targets

Builds a container image for Rocky Linux 8. This is a default option for the rockylinux8 distribution.

```docker
docker buildx build --target rockylinux8/container .
```

--------------------------------

### Define Symbolic Links for Package

Source: https://project-dalec.github.io/dalec/artifacts

Creates symbolic links within the package. This configuration defines the source target, destination path for the link, and optionally the user and group ownership of the symlink itself.

```yaml
artifacts:
  links:
    - source: /usr/lib/golang/go
      dest: /usr/bin/go
      user: someuser
      group: somegroup

```

--------------------------------

### Build Virtual Package Image with Docker

Source: https://project-dalec.github.io/dalec/virtual-packages

Builds a Docker image for a Dalec virtual package, targeting a specific build environment (azlinux3). This command creates a scratch container containing the virtual package and its declared dependencies.

```bash
docker build -t my-package-image:1.0.0 --target=azlinux3 -f my-package.yml .  

```

--------------------------------

### Quick Build Minimal Image (CLI with JSON input)

Source: https://project-dalec.github.io/dalec/container-only-builds

A Docker build command for a quick, minimal container image creation without a separate spec file. It passes runtime dependencies ('curl', 'bash') and entrypoint directly via build arguments and jq for JSON manipulation. The BUILDKIT_SYNTAX and --target flags configure Dalec for this type of build.

```bash
docker build -t my-minimal-image:0.1.0 --build-arg BUILDKIT_SYNTAX=ghcr.io/project-dalec/dalec/frontend:latest --target=azlinux3/container/depsonly -<<<"$(jq -c '.dependencies.runtime = {"curl": {}, "bash": {}} | .image.entrypoint = "/bin/bash"' <<<"{}" )"

```

--------------------------------

### Build Container Image for Rocky Linux 9

Source: https://project-dalec.github.io/dalec/targets

Builds a container image for Rocky Linux 9. This is a default option for the rockylinux9 distribution.

```docker
docker buildx build --target rockylinux9/container .
```

--------------------------------

### Configure Cargohome Generator for Cargo Dependencies

Source: https://project-dalec.github.io/dalec/sources

This YAML snippet illustrates the configuration for the 'cargohome' generator, which is analogous to 'gomod' but for Rust/Cargo dependencies. It enables the creation of a Cargo home cache for managing and reusing Rust build dependencies, improving build performance and consistency. The syntax is similar to 'gomod', specifying the generator within the 'generate' section.

```yaml
sources:
  md2man:
    git:
        url: https://github.com/cpuguy83/go-md2man.git
        commit: v2.1.0
    generate:
      - subpath: "" # path inside the source to use as the root for the generator
        cargohome: {} # Generates a cargo home cache to cache dependencies

```

--------------------------------

### Define Package Documentation Files

Source: https://project-dalec.github.io/dalec/artifacts

Defines documentation files to be included in the package. Similar to config files, these are mapped by source path to destination path, with options for subpath and permissions.

```yaml
artifacts:
  docs:
    src/doc/info.md:
      subpath: ""
      permissions: 0o644

```

--------------------------------

### Build Minimal Container Image with Docker (CLI)

Source: https://project-dalec.github.io/dalec/container-only-builds

Command to build a minimal container image using Docker. It specifies the Dalec spec file (-f my-minimal-image.yml), the target build stage (--target=azlinux3), and the image tag (-t my-minimal-image:0.1.0). This command leverages Dalec's capabilities to create a lean image.

```bash
docker build -f my-minimal-image.yml --target=azlinux3 -t my-minimal-image:0.1.0 .

```

--------------------------------

### Dalec Spec: Signer with Static Build Arguments

Source: https://project-dalec.github.io/dalec/signing

This YAML snippet shows how to configure a Dalec signer with static build arguments. The 'args' section under 'signer' defines key-value pairs ('SOME_KEY', 'SOME_OTHER_KEY') that are passed directly to the signer's command line during the build for the 'mariner2' target.

```yaml
targets: # Distro specific build requirements
  mariner2:
    package_config:
      signer:
        image: "ref/to/signing:image"
        cmdline: "/signer"
        args:
            SOME_KEY: SOME_VALUE
            SOME_OTHER_KEY: SOME_OTHER_VALUE

```

--------------------------------

### Configure Post-Processing Symlinks in DALEC

Source: https://project-dalec.github.io/dalec/image

This snippet illustrates how to define post-processing steps for a container image using the 'post' field in DALEC. Specifically, it shows the creation of symbolic links, including specifying the target path, the symlink paths, and optionally the user and group for these symlinks.

```yaml
image:
  post:
    symlinks:
      /usr/bin/my-binary:
        paths:
         - /my-binary
        user: someuser
        group: somegroup
```

--------------------------------

### PackageDependency Sysext Constraints

Source: https://project-dalec.github.io/dalec/dependencies

Defines packages to be included in a system extension. All necessary dependencies must be explicitly listed here, as no dependency resolution is performed for system extensions.

```YAML
sysext:
  package_name:
      version: ["<2.0.0", ">=1.0.0"]
      arch: ["amd64", "arm64"]

```