### Example Cache Server List Configuration

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_config.md

This example demonstrates how to configure a list of cache servers, specifying types for index and storage services.

```yaml
- url: https://cache-server-1.com/index
  type: index
- url: https://cache-server-1.com/storage
  type: storage
- url: https://cache-server-2.com
  type: all
```

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

### Configure Script Execution

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/junction-includes-build-funky.html

Example of executing the configure script with various standard prefix and directory options. These options control the installation paths of the built software.

```bash
./configure --prefix=/opt \
    --exec-prefix=/opt \
    --bindir=/opt/bin \
    --sbindir=/opt/sbin \
    --sysconfdir=/etc \
    --datadir=/opt/share \
    --includedir=/opt/include \
    --libdir=/opt/lib \
    --libexecdir=/opt/libexec \
    --localstatedir=/var \
    --sharedstatedir=/opt/com \
    --mandir=/opt/share/man \
    --infodir=/opt/share/info   
```

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

### Makefile for hello.c application

Source: https://github.com/apache/buildstream/blob/master/doc/source/handling-files/overlaps.md

This Makefile defines the build and installation process for the hello application, also installing a 'hello.txt' file to the documentation directory, potentially causing an overlap.

```makefile
# Sample makefile for hello.c
#
.PHONY: all install

all: hello

install:
	install -d ${DESTDIR}${PREFIX}/bin
	install -d ${DESTDIR}${PREFIX}/share/doc
	install -m 755 hello ${DESTDIR}${PREFIX}/bin
	install -m 644 hello.txt ${DESTDIR}${PREFIX}/share/doc

hello: hello.c
	$(CC) $< -o $@ -Wall -lhello

```

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

### Run make install command

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/autotools-build.html

Executes the 'make install' command with a specified DESTDIR. This is typically used to install build artifacts into a designated directory.

```shell
make -j1 DESTDIR="/buildstream-install" install
```

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

### Build Documentation with Tox

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/writing_documentation.md

Run this command to build the HTML documentation. Ensure build dependencies are installed first.

```bash
tox -e docs
```

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

### Start lighttpd server

Source: https://github.com/apache/buildstream/blob/master/doc/source/examples/git-mirror.md

Invoke lighttpd with the specified configuration file to start the HTTP server. The `-D` flag keeps lighttpd in the foreground.

```bash
lighttpd -D -f lighttpd.conf
```

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

### Install BuildStream Latest Snapshot in Virtual Environment

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Create a virtual environment named 'venv-bst-latest' and install the latest development snapshot of BuildStream using the --pre flag.

```bash
python3 -m venv venv-bst-latest
virtualenv-bst-latest/bin/pip install --pre BuildStream
```

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

### Install BuildStream Stable in Virtual Environment

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Create a virtual environment named 'venv-bst-stable' and install the stable version of BuildStream within it.

```bash
python3 -m venv venv-bst-stable
venv-bst-stable/bin/pip install BuildStream
```

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

### Makefile for libhello library

Source: https://github.com/apache/buildstream/blob/master/doc/source/handling-files/overlaps.md

This Makefile defines the build and installation process for the libhello library, including installing a 'hello.txt' file to the documentation directory.

```makefile
# Sample makefile for hello library
#
.PHONY: all install

all: libhello.so

install:
	install -d ${DESTDIR}${PREFIX}/lib
	install -d ${DESTDIR}${PREFIX}/include
	install -d ${DESTDIR}${PREFIX}/share/doc
	install -m 644 libhello.so ${DESTDIR}${PREFIX}/lib
	install -m 644 libhello.h ${DESTDIR}${PREFIX}/include
	install -m 644 hello.txt ${DESTDIR}${PREFIX}/share/doc

%.o: %.c %.h
	$(CC) -c $< -o $@ -Wall

libhello.so: libhello.o
	$(CC) -shared -o $@ $<

```

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

### Project.refs File Structure Example

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_project_refs.md

This example demonstrates the structure of a project.refs file, showing how to define source references for elements within the local project and for elements in a dependent junctioned project. Use this format to override source references for elements in your project and its dependencies.

```yaml
projects:

  core:

    base/automake.bst:

    - ref: af6ba39142220687c500f79b4aa2f181d9b24e4...

  bootstrap:

    zlib.bst:
    - ref: 4ff941449631ace0d4d203e3483be9dbc9da4540...
```

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

### Configure Build and Install Commands

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/running-commands.md

Define the commands to be executed during the build and installation phases of an element. These commands are typically used to invoke build systems like 'make'.

```yaml
config:

  build-commands:
  - make PREFIX="%{prefix}"

  install-commands:
  - make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
```

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

### Register a Cython module in setup.py

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/measuring_performance.md

Example of how to register a new Cython module in the `setup.py` file. This ensures the build tool can find and compile your Cython code.

```python
register_cython_module("buildstream._my_module")
```

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

### Autotools Element for Hello World Example

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/autotools.md

This element uses the autotools kind to build a 'hello world' example from the automake tarball. It specifies the tarball source and sets a variable to point to the example's subdirectory.

```yaml
kind: autotools
description: |

    Hello world example from automake

variables:

  # The hello world example lives in the doc/amhello folder.
  #
  # Set the %{command-subdir} variable to that location
  # and just have the autotools element run its commands there.
  #
  command-subdir: doc/amhello

sources:
- kind: tar
  url: gnu:automake-1.16.tar.gz
  ref: 80da43bb5665596ee389e6d8b64b4f122ea4b92a685b1dbd813cd1f0e0c2d83f

depends:
- base.bst

```

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

### Autotools Make Install Command

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/autotools-show-variables.html

Specifies the command used to install the built software. It includes the `make install` command with the `DESTDIR` set for staged installations.

```shell
make-install: make -j1 DESTDIR="/buildstream-install" install
```

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

### Install BuildStream with Pip

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Install BuildStream into your user's home directory using pip. This command also fetches PyPI dependencies.

```bash
pip3 install --user .
```

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

### Makefile for dynamically linked hello application

Source: https://github.com/apache/buildstream/blob/master/doc/source/developing/strict-mode.md

This Makefile builds the 'hello' application, linking it dynamically against the 'libhello' library. It includes build and installation commands.

```makefile
# Sample makefile for hello.c
#
.PHONY: all install

all: hello

install: all
	install -d ${DESTDIR}${PREFIX}/bin
	install -m 755 hello ${DESTDIR}${PREFIX}/bin

hello: hello.c
	$(CC) -Wall -o $@ $< -lhello
```

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

### Install Zsh Completions for Oh My Zsh

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Create a plugin directory for BuildStream, copy the completion script into it, and add 'bst' to your plugins array in .zshrc.

```shell
mkdir $ZSH_CUSTOM/plugins/bst
cp src/buildstream/data/zsh/_bst $ZSH_CUSTOM/plugins/bst/_bst
```

```shell
plugins(
  bst
  ...
)
```

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

### Makefile for hello library

Source: https://github.com/apache/buildstream/blob/master/doc/source/developing/strict-mode.md

This Makefile defines targets for building both dynamic (.so) and static (.a) versions of the hello library, along with installation instructions.

```makefile
# Sample makefile for hello library
#
.PHONY: all install

all: libhello.so libhello.a

install: all
	install -d ${DESTDIR}${PREFIX}/lib
	install -d ${DESTDIR}${PREFIX}/include
	install -m 644 libhello.so ${DESTDIR}${PREFIX}/lib
	install -m 644 libhello.a ${DESTDIR}${PREFIX}/lib
	install -m 644 libhello.h ${DESTDIR}${PREFIX}/include

%.o: %.c %.h
	$(CC) -c $< -o $@ -Wall

libhello.a: libhello.o
	$(AR) rcs $@ $^

libhello.so: libhello.o
	$(CC) -shared -o $@ $<
```

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

### Discover Bash Completion Directory

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Use pkg-config to find the system-wide installation path for bash-completion scripts.

```bash
pkg-config --variable=completionsdir bash-completion
```

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

### Install Build Dependencies (Fedora)

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/using_the_testsuite.md

Installs necessary build dependencies for BuildStream on Fedora-based systems.

```bash
dnf install gcc python3-devel
```

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

### Makefile for Hello World

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/running-commands.md

A Makefile used to compile the 'hello.c' program. It defines rules for building the executable and installing it.

```makefile
# Sample makefile for hello.c
#
.PHONY: all install

all: hello

install:
	install -d ${DESTDIR}${PREFIX}/bin
	install -m 755 hello ${DESTDIR}${PREFIX}/bin

hello: hello.c
	$(CC) -Wall -o $@ $<

```

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

### Install Zsh Completions for Vanilla Zsh

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Copy the completion script to the Zsh functions directory and add the directory to your fpath in .zshrc. Ensure compinit is autoloaded and initialized.

```shell
cp src/buildstream/data/zsh/_bst ~/.zfunc/_bst
```

```shell
fpath+=~/.zfunc
autoload -Uz compinit && compinit
```

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

### Generate Docker image using bst-docker-import

Source: https://github.com/apache/buildstream/blob/master/doc/source/additional_docker.md

Generate a Docker image named 'bst-hello' from a built element 'hello.bst'. Assumes Docker is installed and bst-docker-import is in PATH.

```bash
bst-docker-import -t bst-hello hello.bst
```

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

### BuildStream .run File Example

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/writing_documentation.md

This YAML defines a sequence of BuildStream commands to be executed. It includes fetching a source and capturing the output of a build command into an HTML file.

```yaml
commands:

# Make it fetch first
- directory: ../examples/foo
  command: source fetch hello.bst

# Capture a build output
- directory: ../examples/foo
  output: ../source/sessions/foo-build.html
  command: build hello.bst
```

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

### Install Zsh Completions for Prezto

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Copy the completion script to the Prezto completion modules directory. You may need to reset the zcompdump cache and restart your shell.

```shell
cp src/buildstream/data/zsh/_bst ~/.zprezto/modules/completion/external/src/_bst
```

```shell
rm ~/.zcompdump ${XDG_CACHE_HOME:-$HOME/.cache}/prezto/zcompdump
```

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

### BuildStream Integration Command Output Example

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/integration-commands-shell.html

Observe the detailed output of BuildStream's integration process, including the execution of commands like 'ldconfig' and the custom command 'hello pony'. This shows the lifecycle from loading elements to successful integration.

```shell
ldconfig "/usr/lib"
```

```shell
hello pony
```

```shell
Hello pony
```

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

### Configure Build Commands

Source: https://github.com/apache/buildstream/blob/master/doc/source/developing/strict-mode.md

These commands are used to configure the build process for a project, specifying how to compile and install static elements.

```yaml
config:

  build-commands:
  - make -f Makefile.static PREFIX="%{prefix}"

  install-commands:
  - make -f Makefile.static -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
```

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

### C Code for Hello World Program

Source: https://github.com/apache/buildstream/blob/master/doc/source/developing/workspaces.md

This is the source code for a simple C program that prints 'Hello World'. It serves as an example for demonstrating workspace modifications.

```c
#include <stdio.h>

int main(int argc, char *argv[])
{
  printf("Hello World\n");
  return 0;
}

```

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

### Project Specific Mirror Configuration

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_config.md

Define project-specific mirrors to override default sources. This example shows how to configure multiple aliases for different mirrors.

```yaml
projects:
  project-name:
    mirrors:
    - name: middle-earth
      aliases:
        foo:
        - http://www.middle-earth.com/foo/1
        - http://www.middle-earth.com/foo/2
        bar:
        - http://www.middle-earth.com/bar/1
        - http://www.middle-earth.com/bar/2
    - name: oz
      aliases:
        foo:
        - http://www.oz.com/foo
        bar:
        - http://www.oz.com/bar
```

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

### Declare External Plugins in project.conf

Source: https://github.com/apache/buildstream/blob/master/doc/source/porting_project.md

Specify which plugins from an external junction should be made available in your project. This example makes 'make' and 'meson' available.

```yaml
plugins:
- origin: junction
  junction: buildstream-plugins-junction.bst
  elements:
  - make
  - meson
```

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

### Running Commands During Build

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/strict-mode-build-static-no-strict.html

This snippet shows the commands executed by BuildStream during the integration and build phases for the 'hello-static.bst' element. It includes commands for 'ldconfig', 'make', and 'make install'.

```bash
ldconfig "/usr/lib"
```

```bash
make -f Makefile.staticPREFIX="/usr"
```

```bash
make -f Makefile.static -j1PREFIX="/usr" DESTDIR="/buildstream-install" install
```

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

### Configure Scheduler Controls in YAML

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_config.md

Example of how to configure scheduler controls, such as the number of builders and error handling behavior, within a YAML configuration file.

```yaml
#
# Control the scheduler
#
scheduler:

  # Allow building up to four seperate elements at a time
  builders: 4

  # Continue building as many elements as possible if anything fails
  on-error: continue
```

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

### Configure Interactive Shell Command

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_project.md

Specify the command to be used for running interactive shells with `bst shell`. This example configures it to use `bash` with specific flags.

```yaml
shell:

  # Specify the command to run by default for interactive shells
  command: [ 'bash', '--noprofile', '--norc', '-i' ]
```

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

### BuildStream Build Command Output Example

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/developing-build-after-changes.html

This output shows the detailed progress of a BuildStream build, including timing, element status, and log file information. It helps in monitoring the build process and identifying potential issues.

```text
BuildStream Version 1.93.1+172.g03ccfcd3b
  Session Start: Friday, 17-04-2020 at 20:51:51
  Project:       developing (/home/user/developing)
  Targets:       hello.bst

User Configuration
  Configuration File:      /home/user/.config/buildstream.conf
  Cache Directory:         /home/user/.cache/buildstream
  Log Files:               /home/user/.cache/buildstream/logs
  Source Mirrors:          /home/user/.cache/buildstream/sources
  Build Area:              /home/user/.cache/buildstream/build
  Strict Build Plan:       Yes
  Maximum Fetch Tasks:     10
  Maximum Build Tasks:     4
  Maximum Push Tasks:      4
  Maximum Network Retries: 2

Pipeline
   buildable 179c6ae937e8e2ece3192ab8dc2a55053134a591c9ccd37507b56d11885fae23 base/alpine.bst 
     waiting 125099c65de3a18455f11c5a4a7379df93d5638460906c7f183cfae1b21a651b base.bst 
     waiting ec74614e1f763b990614c97d00ce3494c11b7a0729fc8a914f8e8e4580599949 hello.bst Workspace: /home/user/developing/workspace_hello
===============================================================================
[--:--:--][179c6ae9][   build:base/alpine.bst               ] START  developing/base-alpine/179c6ae9-build.31085.log
[--:--:--][ec74614e][   fetch:hello.bst                     ] START  developing/hello/ec74614e-fetch.31086.log
[--:--:--][179c6ae9][   build:base/alpine.bst               ] START  Staging sources
[00:00:00][ec74614e][   fetch:hello.bst                     ] SUCCESS developing/hello/ec74614e-fetch.31086.log
[00:00:00][179c6ae9][   build:base/alpine.bst               ] SUCCESS Staging sources
[--:--:--][179c6ae9][   build:base/alpine.bst               ] START  Caching artifact
[00:00:00][179c6ae9][   build:base/alpine.bst               ] SUCCESS Caching artifact
[00:00:00][179c6ae9][   build:base/alpine.bst               ] SUCCESS developing/base-alpine/179c6ae9-build.31085.log
[--:--:--][125099c6][   build:base.bst                      ] START  developing/base/125099c6-build.31096.log
[--:--:--][125099c6][   build:base.bst                      ] START  Caching artifact
[00:00:00][125099c6][   build:base.bst                      ] SUCCESS Caching artifact
[00:00:00][125099c6][   build:base.bst                      ] SUCCESS developing/base/125099c6-build.31096.log
[--:--:--][ec74614e][   build:hello.bst                     ] START  developing/hello/ec74614e-build.31100.log
[--:--:--][ec74614e][   build:hello.bst                     ] START  Staging dependencies
[00:00:00][ec74614e][   build:hello.bst                     ] SUCCESS Staging dependencies
[--:--:--][ec74614e][   build:hello.bst                     ] START  Integrating sandbox
[00:00:00][ec74614e][   build:hello.bst                     ] SUCCESS Integrating sandbox
[--:--:--][ec74614e][   build:hello.bst                     ] START  Staging sources
[00:00:00][ec74614e][   build:hello.bst                     ] SUCCESS Staging sources
[--:--:--][ec74614e][   build:hello.bst                     ] START  Running build-commands
[--:--:--][ec74614e][   build:hello.bst                     ] STATUS Running command

    makePREFIX="/usr"

[00:00:00][ec74614e][   build:hello.bst                     ] SUCCESS Running build-commands
[--:--:--][ec74614e][   build:hello.bst                     ] START  Running install-commands
[--:--:--][ec74614e][   build:hello.bst                     ] STATUS Running command

    make -j1PREFIX="/usr" DESTDIR="/buildstream-install" install

[00:00:00][ec74614e][   build:hello.bst                     ] SUCCESS Running install-commands
[--:--:--][ec74614e][   build:hello.bst                     ] START  Running strip-commands
[00:00:00][ec74614e][   build:hello.bst                     ] SUCCESS Running strip-commands
[--:--:--][ec74614e][   build:hello.bst                     ] START  Caching artifact

```

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

### Specify Public Integration Commands

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_declaring.md

Declare public metadata for an element, such as integration commands that should be run after the element is installed. This is useful for setup tasks.

```yaml
public:
  bst:
    integration-commands:
    - "/usr/bin/update-fancy-feature-cache"
```

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

### Build Process Output

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/strict-mode-build-static-no-strict.html

The output shows the BuildStream build process for 'hello-static.bst' when strict mode is disabled. It details the start and success of various stages like loading elements, resolving dependencies, checking sources, and the build commands executed.

```log
BuildStream Version 1.93.1+172.g03ccfcd3b
  Session Start: Friday, 17-04-2020 at 20:52:15
  Project:       strict-mode (/home/user/strict-mode)
  Targets:       hello-static.bst

User Configuration
  Configuration File:      /home/user/.config/buildstream.conf
  Cache Directory:         /home/user/.cache/buildstream
  Log Files:               /home/user/.cache/buildstream/logs
  Source Mirrors:          /home/user/.cache/buildstream/sources
  Build Area:              /home/user/.cache/buildstream/build
  Strict Build Plan:       No
  Maximum Fetch Tasks:     10
  Maximum Build Tasks:     4
  Maximum Push Tasks:      4
  Maximum Network Retries: 2

Pipeline
      cached b795a72d92c05ed0810723f5c3ad40c53bba6e8b568a9d5da22a450a11e03659 base/alpine.bst 
      cached e4a4926893ce660306ca9c812fd8018fa41571c27f37fff4a9e6ab592d0333fe base.bst 
      cached 3ea19fa473f6d9f4a7e67cb3bcafd0306486abdae7e126cd49c13cfb281df882 libhello.bst Workspace: /home/user/strict-mode/workspace_libhello
   buildable 1fe34abbad09b930e86d213b3c21507bf250baecd95effb24fd2223fc6017968 hello-static.bst 
===============================================================================
[::][1fe34abb][   build:hello-static.bst              ] START  strict-mode/hello-static/1fe34abb-build.31821.log
[::][1fe34abb][   build:hello-static.bst              ] START  Staging dependencies
[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Staging dependencies
[::][1fe34abb][   build:hello-static.bst              ] START  Integrating sandbox
[::][1fe34abb][   build:hello-static.bst              ] STATUS Running command

    ldconfig "/usr/lib"

[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Integrating sandbox
[::][1fe34abb][   build:hello-static.bst              ] START  Staging sources
[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Staging sources
[::][1fe34abb][   build:hello-static.bst              ] START  Running build-commands
[::][1fe34abb][   build:hello-static.bst              ] STATUS Running command

    make -f Makefile.staticPREFIX="/usr"

[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Running build-commands
[::][1fe34abb][   build:hello-static.bst              ] START  Running install-commands
[::][1fe34abb][   build:hello-static.bst              ] STATUS Running command

    make -f Makefile.static -j1PREFIX="/usr" DESTDIR="/buildstream-install" install

[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Running install-commands
[::][1fe34abb][   build:hello-static.bst              ] START  Running strip-commands
[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Running strip-commands
[::][1fe34abb][   build:hello-static.bst              ] START  Caching artifact
[00:00:00][1fe34abb][   build:hello-static.bst              ] SUCCESS Caching artifact
[00:00:01][1fe34abb][   build:hello-static.bst              ] SUCCESS strict-mode/hello-static/1fe34abb-build.31821.log
[00:00:01][        ][    main:core activity                 ] SUCCESS Build

Pipeline Summary
  Total:       4
  Session:     1
  Fetch Queue: processed 0, skipped 1, failed 0 
  Build Queue: processed 1, skipped 0, failed 0
```

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

### Docker Compose for BuildGrid Services

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_configuring_remote_execution.md

Defines the services required for a BuildGrid setup: a PostgreSQL database, the BuildGrid controller, and Buildbox workers. Ensure the database is healthy before starting the controller.

```yaml
version: "3.2"

services:
  database:
    image: registry.gitlab.com/buildgrid/buildgrid.hub.docker.com/buildgrid-postgres:nightly
    environment:
      POSTGRES_USER: bgd
      POSTGRES_PASSWORD: insecure
      POSTGRES_DB: bgd
    volumes:
      - type: volume
        source: db
        target: /var/lib/postgresql
    networks:
      - grid
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "bgd"]
      interval: 1s
      timeout: 5s
      retries: 10

  controller:
    image: registry.gitlab.com/buildgrid/buildgrid.hub.docker.com/buildgrid:nightly
    command: [
      "bgd", "server", "start", "-v",
      "/etc/buildgrid/default.yml"]
    ports:
      - 50051:50051
    networks:
      - grid
    depends_on:
      database:
        condition: service_healthy

  bot:
    image: registry.gitlab.com/buildgrid/buildgrid.hub.docker.com/buildbox:nightly
    command: [
      "sh", "-c", "sleep 15 && ( buildbox-casd --cas-remote=http://controller:50051 /var/lib/buildgrid/cache & buildbox-worker --request-timeout=30 --bots-remote=http://controller:50051 --cas-remote=unix:/var/lib/buildgrid/cache/casd.sock --buildbox-run=buildbox-run-bubblewrap --platform OSFamily=linux --platform ISA=x86-64 --verbose )"]
    privileged: true
    volumes:
      - type: volume
        source: cache
        target: /var/lib/buildgrid/cache
    depends_on:
      - controller
    networks:
      - grid

networks:
  grid:
    driver: bridge

volumes:
  cache:
  db:

```

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

### Initialize a new BuildStream project

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/first-project.md

Use the `bst init` command to create a basic project structure. This command generates a `project.conf` file to configure your project.

```bash
bst init
```

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

### Project Configuration with Options

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/directives.md

This project.conf file defines project metadata and a configurable 'flavor' option. The 'flavor' option allows users to select different greeting styles for the hello world program.

```yaml
# Unique project name
name: directives

# Minimum required BuildStream version
min-version: 2.0

# Subdirectory where elements are stored
element-path: elements

# Define an alias for our alpine tarball
alias:
  alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/

# Define an option for this project
#
options:
  flavor:
    type: enum
    description: Flavor of the greeting in the hello world program
    values:
    - normal
    - somber
    - excited
    default: normal

```

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

### Install Commands in Normal Build

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/directives-build-normal.html

After build commands, BuildStream executes 'install-commands' to stage the built artifacts into a temporary installation directory. The `DESTDIR` variable is commonly used here to specify the installation root.

```bash
make -j1 PREFIX="/usr" DESTDIR="/buildstream-install" install
```

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

### Create mirror directory and download tarball

Source: https://github.com/apache/buildstream/blob/master/doc/source/examples/tar-mirror.md

Prepare a directory for your tar mirrors and download a sample tarball. Ensure the directory path matches your lighttpd configuration.

```default
mkdir -p /var/www/tar/gettext
wget -O /var/www/tar/gettext/gettext-0.19.8.1.tar.xz https://ftp.gnu.org/gnu/gettext/gettext-0.19.8.1.tar.xz
```

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

### Download and make bst-docker-import executable

Source: https://github.com/apache/buildstream/blob/master/doc/source/additional_docker.md

Download the bst-docker-import script and make it executable. Ensure ~/.local/bin is in your PATH.

```bash
mkdir -p ~/.local/bin
curl --get https://raw.githubusercontent.com/apache/buildstream/master/contrib/bst-docker-import > ~/.local/bin/bst-docker-import
chmod +x ~/.local/bin/bst-docker-import
```

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

### Install Build Dependencies (Debian)

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/using_the_testsuite.md

Installs necessary build dependencies for BuildStream on Debian-based systems.

```bash
apt install gcc python3-dev
```

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

### bst build dependency options

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_commands.md

Demonstrates the dependency options for the 'bst build' command. Use these to control which dependencies are built along with the specified elements.

```shell
bst build --deps all
```

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

### Run bst --help with cProfile

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/measuring_performance.md

Use cProfile to profile the execution of the `bst --help` command. The output is saved to `bst.cprofile` for later analysis.

```bash
python3 -m cProfile -o bst.cprofile – $(which bst) –help
```

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

### Configure lighttpd for tar mirroring

Source: https://github.com/apache/buildstream/blob/master/doc/source/examples/tar-mirror.md

Set up a basic lighttpd configuration to serve files from a specified directory with directory listing enabled. Adjust 'server.document-root' and 'server.port' as needed.

```default
server.document-root = "/var/www/tar/"
server.port = 3000

dir-listing.activate = "enable"
```

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

### Define Project-Wide Split Rules

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_project.md

Configure default split rules for files installed by elements in the project. This helps in organizing installed files into appropriate directories.

```yaml
split-rules:
  devel:
  - |
    %{includedir}
  - |
    %{includedir}/**
  - |
    %{libdir}/lib*.a
  - |
    %{libdir}/lib*.la
```

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

### Build an Element

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/running-commands.md

Use the 'bst build' command to compile and prepare your project. This command invokes the configured build commands for the specified element.

```bash
bst build
```

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

### BuildStream element with artifact munging

Source: https://github.com/apache/buildstream/blob/master/doc/source/handling-files/overlaps.md

This YAML snippet shows how to modify an element's install commands to remove a conflicting file, '%{install-root}%{docdir}/hello.txt', at install time to resolve overlaps.

```yaml
install-commands:
- make -j1 PREFIX "%%{prefix}" DESTDIR "%%{install-root}" install

- |
  # Rid ourselves of the unwanted file at install time
  rm -f %{install-root}%{docdir}/hello.txt

```

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

### Clone BuildStream Repository

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Clone the BuildStream repository and checkout a specific release tag before installation.

```bash
git clone https://github.com/apache/buildstream.git
cd buildstream
git checkout <desired release tag>
```

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

### Run Pytest Directly

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/using_the_testsuite.md

Execute the test suite using pytest. Ensure all dependencies are installed beforehand.

```bash
pytest
```

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

### Build with Project Option

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/junction-includes-build-funky.html

Example of invoking BuildStream with a project-specific option 'funky'. This option can alter build behavior.

```bash
bst --option funky True build hello.bst
```

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

### Autotools Configure Arguments

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/autotools-show-variables.html

Specifies the arguments passed to the `./configure` script. These arguments define installation paths and other configuration options.

```shell
conf-args: "--prefix=/usr \\\n--exec-prefix=/usr \\\n--bindir=/usr/bin \\\n--sbindir=/usr/sbin\n  \\\n--sysconfdir=/etc \\\n--datadir=/usr/share \\\n--includedir=/usr/include \\\n--libdir=/usr/lib \\\n--libexecdir=/usr/libexec \\\n--localstatedir=/var \\\n\n  --sharedstatedir=/usr/com \\\n--mandir=/usr/share/man \\\n--infodir=/usr/share/info\n    "
```

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

### Configure lighttpd for git mirror

Source: https://github.com/apache/buildstream/blob/master/doc/source/examples/git-mirror.md

This lighttpd configuration sets up an HTTP server to serve git repositories. It maps the /git URL to the git-http-backend CGI script and sets environment variables for git project root and export settings. Adjust `server.document-root` and `GIT_PROJECT_ROOT` if your mirrors are in a different location.

```default
server.document-root = "/var/www/git/"
server.port = 3000
server.modules = (
     "mod_alias",
     "mod_cgi",
     "mod_setenv",
)

alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" )
$HTTP["url"] =~ "^/git" {
     cgi.assign = ("" => "")
     setenv.add-environment = (
             "GIT_PROJECT_ROOT" => "/var/www/git",
             "GIT_HTTP_EXPORT_ALL" => ""
     )
}
```

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

### Running a Normal Build with BuildStream

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/directives-build-normal.html

Execute a BuildStream project using the default 'normal' build flavor. This command initiates the build process for the specified target element.

```bash
user@host:~/directives$ bst build hello.bst
```

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

### Basic bst show command

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_commands.md

Display elements in the pipeline. Specifying no elements shows default targets or all project elements if none are configured. When run from a workspace, it defaults to showing the workspace element.

```shell
bst show [OPTIONS] [ELEMENTS]...
```

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

### Set Default BuildBox Run Implementation

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

After installing BuildBox components, create a symbolic link to set buildbox-run-bubblewrap as the default implementation for buildbox-run.

```bash
ln -sv buildbox-run-bubblewrap /usr/local/bin/buildbox-run
```

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

### Enable Site Packages in Tox

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/using_the_testsuite.md

Allows the use of site packages within the tox environment, bypassing the need to install build dependencies.

```bash
tox -- --sitepackages
```

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

### Make build command

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/junctions-build.html

Standard make command for building a project.

```shell
make
```

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

### Declaring Variables with Interdependencies

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_declaring.md

Variables can be declared in any order, as long as there are no cyclic dependencies and all referenced variables are declared. This example declares 'release-text' and 'version'.

```yaml
variables:
  release-text: This is release version %{version}
  version: 5.5
```

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

### Build Hello Element with Filter Option

Source: https://github.com/apache/buildstream/blob/master/doc/source/handling-files/filtering.md

Build the 'hello.bst' element using the 'bst build' command, controlling the use of the filter via the '--option' flag. This allows testing with both filtered and unfiltered dependencies.

```shell
bst --option use_filter True build hello.bst
bst --option use_filter False build hello.bst
```

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

### Declaring a Variable

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_declaring.md

Declare or override a variable by specifying its value in the 'variables' section. This example declares a 'hello' variable with the value 'Hello World'.

```yaml
variables:
  hello: Hello World
```

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

### Activate and Use Virtual Environment

Source: https://github.com/apache/buildstream/blob/master/doc/source/main_install.md

Activate a virtual environment to use BuildStream. This automatically adds 'bst' to your PATH. Remember to deactivate when done.

```bash
# Use BuildStream stable from venv-bst-stable
source venv-bst-stable/bin/activate
bst --version

# Use BuildStream latest from venv-bst-latest
source venv-bst-latest/bin/activate
bst --version

# Once you are done, remember to deactivate the virtual environment
deactivate
```

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

### bst init command usage

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_commands.md

The general usage for the 'bst init' command, used to initialize a new BuildStream project. It can take an optional target directory.

```shell
bst init [OPTIONS] [TARGET_DIRECTORY]
```

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

### Run Shell Command with Arguments

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/directives-shell-excited.html

Demonstrates executing a shell command with arguments using the 'shell' directive. The command and its arguments are passed directly to the shell.

```bst
shell:
  run: |
    echo "Hello, BuildStream!" > output.txt
```

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

### Run Program with Different Options

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/directives.md

Executes a BuildStream project element using 'bst shell' with different project options. This demonstrates how options affect runtime behavior and output.

```bash
bst shell --option flavor=normal hello.bst -- echo %{greeting}
```

```bash
bst shell --option flavor=somber hello.bst -- echo %{greeting}
```

```bash
bst shell --option flavor=excited hello.bst -- echo %{greeting}
```

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

### Makefile for statically linked hello application

Source: https://github.com/apache/buildstream/blob/master/doc/source/developing/strict-mode.md

This Makefile builds the 'hello' application, linking it statically against the 'libhello.a' library. It specifies the static library path for linking.

```makefile
# Sample makefile for hello.c
#
.PHONY: all install

all: hello

install: all
	install -d ${DESTDIR}${PREFIX}/bin
	install -m 755 hello ${DESTDIR}${PREFIX}/bin

hello: hello.c
	$(CC) -Wall -o $@ $< /usr/lib/libhello.a
```

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

### Evaluate an Enumeration Option

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_project.md

Test an enumeration option using string equality in conditional expressions. This example sets a variable based on the 'loglevel' option.

```yaml
variables:
  enable-debug: False
  (?):
  - loglevel == "debug":
      enable-debug: True
```

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

### Build a Project with BuildStream

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/integration-commands-build.html

Initiates the build process for a specified BuildStream project file. This command triggers the loading, resolving, and building of elements defined in the project.

```bash
user@host:~/integration-commands$ bst build hello.bst
```

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

### Autotools Configure Command with Standard Options

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/autotools-build.html

This command configures an Autotools project with standard installation paths. It sets prefixes for executables, configuration files, and other components.

```bash
./configure --prefix=/usr \
    --exec-prefix=/usr \
    --bindir=/usr/bin \
    --sbindir=/usr/sbin \
    --sysconfdir=/etc \
    --datadir=/usr/share \
    --includedir=/usr/include \
    --libdir=/usr/lib \
    --libexecdir=/usr/libexec \
    --localstatedir=/var \
    --sharedstatedir=/usr/com \
    --mandir=/usr/share/man \
    --infodir=/usr/share/info   
```

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

### Create Source Distribution

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/managing_data_files.md

Run this command to create a source distribution tarball. This helps verify that all intended files are included.

```bash
./setup.py sdist
```

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

### Evaluate a Flags Option

Source: https://github.com/apache/buildstream/blob/master/doc/source/format_project.md

Test a flags option using Pythonic 'in' syntax in conditional expressions. This example checks if 'debug' is present in the 'logmask' option.

```yaml
variables:
  enable-debug: False
  (?):
  - ("debug" in logmask):
      enable-debug: True
```

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

### Running a Build Command in BuildStream

Source: https://github.com/apache/buildstream/blob/master/doc/source/sessions-stored/developing-build-after-changes.html

Execute a build for a specified .bst file. This command initiates the BuildStream process to build the target element defined in the file.

```bash
user@host:~/developing$ bst build hello.bst
```

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

### Makefile for Compiling Hello World

Source: https://github.com/apache/buildstream/blob/master/doc/source/tutorial/directives.md

This Makefile compiles the 'hello.c' program. It includes a mechanism to pass a greeting message via the C preprocessor's '-D' flag, allowing the greeting to be customized.

```makefile
# Sample makefile for hello.c
#
.PHONY: all install

all: hello

install:
	install -d ${DESTDIR}${PREFIX}/bin
	install -m 755 hello ${DESTDIR}${PREFIX}/bin

hello: hello.c
	$(CC) -DGREETING_MESSAGE="\"${GREETING}\"" -Wall -o $@ $<

```

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

### Get Contributors with Git

Source: https://github.com/apache/buildstream/blob/master/doc/source/hacking/making_releases.md

Use git shortlog to summarize authors of commits since the last release tag. Duplicates may need manual removal.

```shell
git shortlog -s 1.1.0...@

```

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

### List open BuildStream workspaces

Source: https://github.com/apache/buildstream/blob/master/doc/source/using_commands.md

Use this command to list all currently open workspaces.

```shell
bst workspace list [OPTIONS]
```