Target Commands

Target commands are executed within the root filesystem which we are just building. This concept is similar to the one of Docker.

The key benefit of using those commands is, that it is very natural. You can automate virtually every command, which you would use to configure the system manually in your terminal.

When you build a system for a foreign architecture, Wharfie uses Qemu to.be able to execute the commands on your x86 host.

FROM

The from directive refers the starting point of your root filesystem. Before you can execute any command inside of your new root filesystem, you obviously need a basic root filesystem. This can be obtained from several sources.

debootstrap

You just need to specify the architecture and the debian version in the following syntax:

debian_<architecture>_<version>

For example:

FROM debian_armel_stretch

archive

You can specify a tar archive. For example, this can be a build artifact from previous build step.

For example:

FROM iotbase.tar

remote archive

Beside tar, wharfie supports a few more archive formats, which can be handy to use external sources as a starting point for your image.

So, the following formats are supported:
* a
* img
* zip

You can pass options for the different formats, separated from the Url by a pipe symbol.

For example:

FROM https://downloads.raspberrypi.org/raspbian_lite_latest|img=p1|format=tar

The format specifies, where to stop with the extract. In the FROM statement this should always be a tar archive. But when this syntax is used in an ADD statement, you might leave this empty and pass an option like "|tar=etc/fstab" to extract a single file.

At first it might be a bit confusing why the extraction of an image results in a tar archive. But wharfie treats every folder as a tar archive. Thats the way how a folder is passed to another build step, including all permissions, attributes and links.

The parameter "img=p1" from the example specifies, that we want to extract partition number 1 from the image file. In this case partition number 0 is the boot partition, and number 1 contains the root filesystem.

RUN

Run gets exactly one argument. This is the command, which should be executed on the targets root filesystem. This command can be multiline.

For example:

RUN apt-get install -y psutils \
    openssh-server ...

The Backslash () at the end of the line indicates, that the command continues in the next line.

Install software with apt-get

If you want to install a new software on your target image, you most likely want to use apt. To avoid apt and dpkg from requesting inputs from the user, you can pass "-y" to apt-get.

For example:

RUN apt-get install -y tzdata

In case you want to deviate from the default, you might want to use dpkg-reconfigure after the installation.

RUN echo Antarctica/Mawson > /etc/timezone && dpkg-reconfigure -f noninteractive tzdata

Add user and set password

An easy, non-interactive way to add a user and set his password is to use the tools "useradd" and "chpasswd".

This example adds the user "wharfie" with the password "secret":

RUN useradd -ms /bin/bash wharfie; echo "wharfie:secret" | chpasswd;

CMD

This command comes from Docker. There it defines the one and only entry point of the docker container. In Wharfie it defines a command that is executed from a systems service unit. So there can be multiple commands, and they are all executed at the end of the boot process.

For example:

CMD ['/run.sh']

LICENSE

This command is creating an archive with all the license texts of all installed packages. Note, that packages which are installed from 3rd party sources are not included in this archive.

For example:

LICENSE all-licenses.tar

SOURCE

This command is creating an archive with all debian source packages, which are currently installed in the system. Like for the license archive, this archive doesn't contain 3rd party packages.

SOURCES all-sources.tar

TOOLCHAIN

This command exports a crosstoolchain, containing the full root filesystem of the target, as well as a cross compiler for an x86 host.

It can be simply exported as a tar archive.

For example:

TOOLCHAIN cross-toolchain.tar

If you need more host tools then just the gcc compiler, you can define those packages in an environment variable.

ENV ADDITIONAL_TOOLCHAIN_PACKAGES libstdc++4.9-dev ...

If you want to execute some commands in the host sysroot, before the toolchain is packed, you can do this by appending this commands to the TOOLCHAIN commad:

TOOLCHAIN cross-toolchain.tar \
    apt-get install -y git; \
    ...

Host commands

RUN HOST

Host commands can be used for virtually every action which don't need to be executed on the target, but where files on the host are involved.

For example:

• prepare a bootable image of the target root filesystem
• download an archive and extract only parts of it
• compile a kernel and add it to the root filesystem
• ...

The syntax is exactly the same as the RUN command. The commands are executed as root from the extracted target folder, which is extracted into a folder directly beside the Wharfile.

ADD

This action can add files, folders and archives into a root filesystem. Even files and archives from URLs are possible.

Every archive will be implicitely extracted into the destination folder.

For example:

ADD etc.tar /etc

COPY

Copy acts very similar to ADD. The only differenxe is, that this command really only copies files and directories. So also archives are treated as standard files, what might be the intention in some cases.

Common Commands

ENV

With this command, you can set global environment variables, which are accessible in every RUN or RUN HOST command. This includes environment variables of sub processes.

For example:

ENV DEBIAN_FRONTEND noninteractive
RUN apt-get install ...

INCLUDE (Draft - not implemented, yet)

The include command can be used to structure your features into different Wharfiles, which can be reused in different Wharfiles. The syntax is simple, as the only parameter to the command is the path to the include file.

ENV ESSID mywifi
ENV PASSWORD mypass
INCLUDE net/wpa.wha
INCLUDE bs/rpi.wha

The included files are searched locally, and only as fallback from an URL. The search URL can be specified with the command INCLUDE_URL.

INCLUDE_URL http://forge.codesys.com/...
INCLUDE bs/rpi.wha

The default URL can be set again by calling INCLUDE_URL without a parameter.

INCLUDE_URL
INCLUDE bs/rpi.wha