Commit 73b93002 authored by Tristan Van Berkom's avatar Tristan Van Berkom

doc: Adding part 2 of the getting started tutorial

  o doc/examples/running-commands: New example project of a `manual` build element

  o doc/sessions/running-commands.run: New session file to capture bst output

  o doc/source/sessions-stored: Added new generated sessions

  o doc/source/tutorial/running-commands.rst: New tutorial entry describing how
                                              commands are run in the sandbox

  o tests/examples/running-commands.py: Test case validating the tutorial's assertions
parent 3f560378
Pipeline #24032300 passed with stages
in 59 minutes and 9 seconds
kind: stack
description: Base stack
depends:
- base/alpine.bst
kind: import
description: |
Alpine Linux base runtime
sources:
- kind: tar
# This is a post doctored, trimmed down system image
# of the Alpine linux distribution.
#
url: alpine:integration-tests-base.v1.x86_64.tar.xz
ref: 3eb559250ba82b64a68d86d0636a6b127aa5f6d25d3601a79f79214dc9703639
kind: manual
description: |
Building manually
# Depend on the base system
depends:
- base.bst
# Stage the files/src directory for building
sources:
- kind: local
path: files/src
# Now configure the commands to run
config:
build-commands:
- make PREFIX="%{prefix}"
install-commands:
- make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
# 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 $@ $<
/*
* hello.c - Simple hello world program
*/
#include <stdio.h>
int main(int argc, char *argv[])
{
printf("Hello World\n");
return 0;
}
# Unique project name
name: running-commands
# Required BuildStream format version
format-version: 9
# Subdirectory where elements are stored
element-path: elements
# Define an alias for our alpine tarball
aliases:
alpine: https://gnome7.codethink.co.uk/tarballs/
commands:
# Make it fetch first
- directory: ../examples/running-commands
command: fetch hello.bst
# Capture a show output
- directory: ../examples/running-commands
output: ../source/sessions/running-commands-show-before.html
command: show hello.bst
# Capture a build output
- directory: ../examples/running-commands
output: ../source/sessions/running-commands-build.html
command: build hello.bst
# Capture another show output
- directory: ../examples/running-commands
output: ../source/sessions/running-commands-show-after.html
command: show hello.bst
# Capture a shell output
- directory: ../examples/running-commands
output: ../source/sessions/running-commands-shell.html
command: shell hello.bst -- hello
......@@ -23,6 +23,8 @@ General elements
elements/filter
.. _plugins_build_elements:
Build elements
--------------
.. toctree::
......
This diff is collapsed.
<!--
WARNING: This file was generated with bst2html.py
-->
<div class="highlight" style="font-size:x-small"><pre>
<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/running-commands</span>$ bst shell hello.bst -- hello
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging dependencies
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging dependencies
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Integrating sandbox
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Integrating sandbox
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">c50da053</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#06989A"><span style=""><span style="opacity:0.5">STATUS </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Running command
<span style="opacity:0.5"> hello</span>
Hello World
</pre></div>
<!--
WARNING: This file was generated with bst2html.py
-->
<div class="highlight" style="font-size:x-small"><pre>
<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/running-commands</span>$ bst show hello.bst
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
<span style="color:#75507B"> cached</span> <span style="color:#C4A000">a352c93edfc55a41868b4f482758ad3ea1c21571532373542cd20b9135f0718d</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span>
<span style="color:#75507B"> cached</span> <span style="color:#C4A000">a8eeb045115a4a71c18d09fe14b7b4fc3f3e838414a7d23d7c6d4c3027f28743</span> <span style="color:#3465A4"><span style="">base.bst</span></span>
<span style="color:#75507B"> cached</span> <span style="color:#C4A000">c50da0531f050b51a7ddb6f331750642ad222ae6a81a16e091e026aa4d7cc07a</span> <span style="color:#3465A4"><span style="">hello.bst</span></span>
</pre></div>
<!--
WARNING: This file was generated with bst2html.py
-->
<div class="highlight" style="font-size:x-small"><pre>
<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/running-commands</span>$ bst show hello.bst
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
<span style="color:#4E9A06"> buildable</span> <span style="color:#C4A000">a352c93edfc55a41868b4f482758ad3ea1c21571532373542cd20b9135f0718d</span> <span style="color:#3465A4"><span style="">base/alpine.bst</span></span>
<span style="color:#3465A4"> waiting</span> <span style="color:#C4A000">a8eeb045115a4a71c18d09fe14b7b4fc3f3e838414a7d23d7c6d4c3027f28743</span> <span style="color:#3465A4"><span style="">base.bst</span></span>
<span style="color:#3465A4"> waiting</span> <span style="color:#C4A000">c50da0531f050b51a7ddb6f331750642ad222ae6a81a16e091e026aa4d7cc07a</span> <span style="color:#3465A4"><span style="">hello.bst</span></span>
</pre></div>
Running commands
================
In :ref:`the first chapter <tutorial_first_project>` we only imported
a file to create an artifact, this time lets run some commands inside
the :ref:`isolated build sandbox <sandboxing>`.
.. note::
This example is distributed with BuildStream
in the `doc/examples/running-commands
<https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/running-commands>`_
subdirectory.
Overview
--------
In this chapter, we'll be running commands inside the sandboxed
execution environment and producing build output.
We'll be compiling the following simple C file:
``files/src/hello.c``
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/running-commands/files/src/hello.c
:language: c
And we're going to build it using ``make``, using the following Makefile:
``files/src/Makefile``
~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/running-commands/files/src/Makefile
:language: Makefile
We'll be using the most fundamental :ref:`build element <plugins_build_elements>`,
the :mod:`manual <elements.manual>` build element.
The :mod:`manual <elements.manual>` element is the backbone on which all the other
build elements are built, so understanding how it works at this level is helpful.
Project structure
-----------------
In this project we have a ``project.conf``, a directory with some source
code, and 3 element declarations.
Let's first take a peek at what we need to build using :ref:`bst show <invoking_show>`:
.. raw:: html
:file: ../sessions/running-commands-show-before.html
This time we have loaded a pipeline with 3 elements, let's go over what they do
in detail.
``project.conf``
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/running-commands/project.conf
:language: yaml
Our ``project.conf`` is very much like the last one, except that we
have defined a :ref:`source alias <project_source_aliases>` for ``alpine``.
.. tip::
Using :ref:`source aliases <project_source_aliases>` for groups of sources
which are generally hosted together is encouraged. This allows one to globally
change the access scheme or URL for a group of repositories which belong together.
``elements/base/alpine.bst``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/running-commands/elements/base/alpine.bst
:language: yaml
This :mod:`import <elements.import>` element uses a :mod:`tar <sources.tar>`
source to download our Alpine Linux tarball to create our base runtime.
This tarball is a sysroot which provides the C runtime libraries
and some programs - this is what will be providing the programs we're
going to run in this example.
``elements/base.bst``
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/running-commands/elements/base.bst
:language: yaml
This is just a symbolic :mod:`stack <elements.stack>` element which declares that
anything which depends on it, will implicitly depend on ``base/alpine.bst``.
It is typical to use stack elements in places where the implementing logical
software stack could change, but you rather not have your higher level components
carry knowledge about those changing components.
Any element which :ref:`runtime depends <format_dependencies_types>` on
the ``base.bst`` will now be able to execute programs provided by the imported
``base/alpine.bst`` runtime.
``elements/hello.bst``
~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/running-commands/elements/hello.bst
:language: yaml
Finally we have the element which executes commands. Looking at the
:mod:`manual <elements.manual>` element's documentation, we can see that
the element configuration exposes four command lists:
* ``configure-commands``
Commands which are run in preparation of a build. This is where you
would normally call any configure stage build tools to configure
the build how you like and generate some files needed for the build.
* ``build-commands``
Commands to run the build, usually a build system will
invoke the compiler for you here.
* ``install-commands``
Commands to install the build results.
Commands to install the build results into the target system,
these should install files somewhere under ``%{install-root}``.
* ``strip-commands``
Commands to doctor the build results after the install.
Typically this involves stripping binaries of debugging
symbols or stripping timestamps from build results to ensure
reproducibility.
.. tip::
All other :ref:`build elements <plugins_build_elements>`
implement exactly the same command lists too, except that they provide
default commands specific to invoke the build systems they support.
The :mod:`manual <elements.manual>` element however is the most basic
and does not provide any default commands, so we have instructed it
to use ``make`` to build and install our program.
Using the project
-----------------
Build the hello.bst element
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build the project, run :ref:`bst build <invoking_build>` in the
following way:
.. raw:: html
:file: ../sessions/running-commands-build.html
Now we've built our hello world program, using ``make``
and the C compiler provided by the Alpine Linux image.
In the :ref:`first chapter <tutorial_first_project>` we observed that the inputs
and output of an element are *directory trees*. In this example, the directory tree
generated by ``base/alpine.bst`` is consumed by ``hello.bst`` due to the
:ref:`implicit runtime dependency <format_dependencies_types>` introduced by ``base.bst``.
.. tip::
All of the :ref:`dependencies <format_dependencies>` which are required to run for
the sake of a build, are staged at the root of the build sandbox. These comprise the
runtime environment in which the depending element will run commands.
The result is that the ``make`` program and C compiler provided by ``base/alpine.bst``
were already in ``$PATH`` and ready to run when the commands were needed by ``hello.bst``.
Now observe that all of the elements in the loaded pipeline are ``cached``,
the element is *built*:
.. raw:: html
:file: ../sessions/running-commands-show-after.html
Run the hello world program
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now that we've built everything, we can indulge ourselves in running
the hello world program using :ref:`bst shell <invoking_build>`:
.. raw:: html
:file: ../sessions/running-commands-shell.html
Here, :ref:`bst shell <invoking_build>` created a runtime environment for running
the ``hello.bst`` element. This was done by staging all of the dependencies of
``hello.bst`` including the ``hello.bst`` output itself into a directory. Once a directory
with all of the dependencies was staged and ready, we ran the ``hello`` command from
within the build sandbox environment.
......@@ -9,3 +9,4 @@ projects.
:maxdepth: 1
tutorial/first-project
tutorial/running-commands
import os
import pytest
from tests.testutils import cli_integration as cli
from tests.testutils.integration import assert_contains
from tests.testutils.site import IS_LINUX
pytestmark = pytest.mark.integration
DATA_DIR = os.path.join(
os.path.dirname(os.path.realpath(__file__)), '..', '..', 'doc', 'examples', 'running-commands'
)
@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
@pytest.mark.datafiles(DATA_DIR)
def test_running_commands_build(cli, tmpdir, datafiles):
project = os.path.join(datafiles.dirname, datafiles.basename)
checkout = os.path.join(cli.directory, 'checkout')
result = cli.run(project=project, args=['build', 'hello.bst'])
assert result.exit_code == 0
# Test running the executable
@pytest.mark.skipif(not IS_LINUX, reason='Only available on linux')
@pytest.mark.datafiles(DATA_DIR)
def test_running_commands_run(cli, tmpdir, datafiles):
project = os.path.join(datafiles.dirname, datafiles.basename)
result = cli.run(project=project, args=['build', 'hello.bst'])
assert result.exit_code == 0
result = cli.run(project=project, args=['shell', 'hello.bst', '--', 'hello'])
assert result.exit_code == 0
assert result.output == 'Hello World\n'
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment